PmWiki | Cookbook / BlogIt (original) (raw)

Summary: Provides a complete blogging system, using in-built PmWiki features -- additional features are supported through existing cookbooks.

Version: 2024-09-14

Prerequisites: PmWiki 2.3.36 or later, PmForm, JavaScript enabled on browser for Admin and Blog entry functions.

Status: Active

Project Blog: https://solidgone.org/tags/blogit

Download: ZIP

License: Dual licensed under the MIT and GPL licenses.

Table of Contents

Update Summary 2024-09-14

Many updates for PHP 8.2, diffs and downloads merged with origin, released as 1.9.6. (also available at https://github.com/5ko/BlogIt). Requires PmWiki 2.3.36 or more recent.

I do not use this recipe, if you uncover any problems I haven't noticed, please post on the BlogIt-Talk page or via email. Someone who regularly uses the recipe will be most welcome to take over the maintenance. --Petko

For more information refer to the full release details.

Description

BlogIt provides an easy to setup blogging system, based on PmWiki, providing similar functionality to other major blogging platforms. BlogIt includes blog entry, blog management, comment entry and approval, and comment management, and comes with pagelists providing most features provided in other blog systems. Additional features like ping-backs, notifications, and tag-clouds, can be added using existing cookbooks.

BlogIt works with all existing skins. Some skins provide an additional features when used with BlogIt, like Blix, Equilibrium, DropShadow, GlossyHue, and others. Simply install and activate the skin and BlogIt will put blog entry elements like Title, date, author, tags in the right locations for the skin design. All other skins will work with BlogIt -- but you won't get the automatic styling of some blog elements, unless the skin accommodates that.

Feature Summary

Writing

Commenting

Administration

Other Features

Demo

A demo sandbox is available at solidgone.org. Admin password is "blogadmin", and the Edit password is "blogedit" -- no user name is needed. Feel free to add new blog entries, add comments, login as admin and approve a few comments.

You can also see BlogIt in action at my personal journal and my tech journal. BlogIt has now replaced my use of Drupal.

Comments

Show your support and leave a rating, or help out and let me know if you have a suggestion or a problem.

Download and Install

  1. Download ZIP
    1. For PHP 8.2, get this version instead (requires PmWiki 2.3.36 or more recent).
    2. Extract the contents of the cookbook folder into your cookbook directory, usually pmwiki/cookbook/.
      This will create a 'blogit' directory inside cookbook: pmwiki/cookbook/blogit/.
      ## Extract the contents of the pub folder into your pub directory, usually pmwiki/pub.
      This will create a 'blogit' directory inside pub: pmwiki/pub/blogit/.
  2. Security:
    1. Make sure you assign Edit and Admin passwords in config.php. If you don't anyone will be able to create blog entries, and to post comments.
      $DefaultPasswords['admin'] = pmcrypt('your_admin_password');
      $DefaultPasswords['edit'] = pmcrypt('your_edit_password');
    2. If you are using the standard PmWiki security (not AuthUser, etc), then ensure Edit permissions are set on the page "Blog.Main".
    3. If you are using AuthUser based security the set $bi_AuthPage Permissions, and add additional configuration for roles.
  3. Config:
    1. Ensure that $EnableRelativePageVars = 1; is set. This is normally set by default.
    2. Add the following to your local configuration file, usually pmwiki/local/config.php. You need to put this towards the end of config.php, after password definitions, and also after any of the optional configuration steps:
      Note: You do not need to add an include_once pmforms.php from config.php -- BlogIt will automatically do the include for you.

(:div class="indent" style="overflow:auto;width:800px;border:1px dashed lightgray":)

$HandleAuth['source'] = 'edit'; #Prevents non authorized users from viewing comment source email address $HandleAuth['diff'] = 'edit'; #Prevents non authorized users from viewing comment source email address $MaxIncludes=500; #BlogIt makes heavy use of includes, so this needs to be increased. include_once("$FarmD/cookbook/blogit/blogit.php");

Optional Setup

These steps need to come before the BlogIt include statement.

  1. Captcha: (optional) If you want to use Captcha or ReCaptcha to prevent comment spam, then refer to the Stop Spam section.
  2. Caching: (optional) Caching speeds up PmWiki generally, and therefore BlogIt. But it can delay the appearance of new comments and blog entries in pagelists.
    1. Create a work.d directory at the same level as your wiki.d directory, usually pmwiki/work.d/.
    2. These settings enable caching:
      $WorkDir = dirname(FILE).'/../work.d';
      PageListCacheDir=PageListCacheDir = PageListCacheDir=WorkDir .'/';
      $EnablePageIndex=1;
  3. Skins: (optional) If the skin you use does not provide support for BlogIt, it will still work. However, the elements on the page generated by BlogIt will have a default styling. If the skin does not provide explicit BlogIt support, check the skinning section to see if there is a stylesheet, which will improve the appearance of your blog. If the skin you use does not provide specific styling and you need something, then log an issue on the talk page.
  4. Groups: Define a default group for blog entries -- used as the default in the "Page URL" field when creating a new blog entry (purely for convenience, not required):
    $bi_DefaultGroup='Blog';
    1. Specify which groups to look for blog entries (may make things quicker on large sites). If you want blog entries to exist in any group, then set this parameter to an empty string. If you require blog entries to exist in specific groups use a pipe separated list of group names.
      $bi_BlogGroups='JoesBlog|ZaksBlog|SusansBlog';

Also refer to site-wide modifications that can be made to BlogIt.

Setup Sequencing in config.php

It's important to get the sequencing of the config.php configuration correct. Problems will occur if you don't, particularly if you put password config settings after including authuser. Here's the recommended ordering:

  1. Define passwords, password groups, and authuser configs.
  2. Include authuser
  3. BlogIt configs
  4. Include blogit

Setting up your Blog

Main Blog Summary Page

Your main page (in this example Blog.Main) is going to be a basic page list, which will include blog summaries, the part upto the "Read more..." link. By default you'll want to include all blog entries in the blog1 blog, of status Publish. For example, create a page Blog.Main:

(:notitle:) (:includesection "#blog-summary-pagelist blogid=blog1 status=publish":)

If you want to display Sticky entries before Published entries then add another pagelist:

(:notitle:) (:includesection "#blog-summary-pagelist blogid=blog1 status=sticky":) (:includesection "#blog-summary-pagelist blogid=blog1 status=publish":)

Blog SideBar

The BlogIt sidebar includes a admin control panel (visible to administrators), the list of recent articles, and comments, and the tag-list, ensure your Site.SideBar includes BlogIt-SideBar. Basically wrap the original sidebar in an if condition. (Don't forget the closing (:ifend:) at the end.)

(:if equal {$bi_BlogIt_Enabled} 1:)(:include Site.BlogIt-SideBar:) (:else:) <> (:ifend:)

If you are using multiple blogs, then pass the blogid as a parameter (replacing MY_BLOG_ID):

(:if equal {$bi_BlogIt_Enabled} 1:)(:include Site.BlogIt-SideBar blogid=MY_BLOG_ID:) (:else:) <> (:ifend:)

In order to view the control panel on the sidebar, users need to have 'sidebar' action assigned. Refer to security setup for more details.

Start using your Blog

Create New Blog Entries

Now you're ready to create a new blog entry -- simply click on the "New Entry" link in the sidebar. If you're not using the BlogIt sidebar, then simply visit the page Site.BlogIt-NewEntry. If you see a blank page, then make sure you have appropriate privileges.

Note: All BlogIt releases on GitHub seem to be missing the page Site.BlogIt-NewEntry. --Petko September 06, 2024, at 04:01 PM

Complete the blog entry form. Typically you will enter a Blog Title, Tags, select a Status, and then enter the blog entry text -- you usually don't need to touch the other fields.

Click to Enlarge

Comment Administration

Whenever you see a comment, and if you are logged in with the appropriate privileges, you will see a set of admin links, allowing you to either Approve/Unapprove, Delete, Edit, and Block a comment. Some actions require appropriate privileges. On the blog single-entry administrators can click on any number of comments, and use the menu on the 'Comment' heading to perform bulk actions.

By default comments will automatically be approved if you have captcha enabled. You can change this behavior by setting $bi_DefaultCommentStatus.

Security

Most blogs are not public, so at the very least you probably want to lock things down, by adding edit and admin passwords to config.php:

$DefaultPasswords['admin'] = crypt('secret'); $DefaultPasswords['edit'] = crypt('secret');

BlogIt Roles and Actions

By default BlogIt defines a single 'role' with all 'actions' assigned to the role. Currently valid actions are:

Using Standard PmWiki Security (not using AuthUser)

By default anyone with Edit permissions is able to perform all actions. You can change this behavior by over-riding $bi_Auth. The array takes this format:

By default the array is:

$bi_Auth = array( 'edit'=>array('comment-edit', 'comment-approve', 'blog-edit', 'blog-new', 'sidebar', 'blogit-admin') );

You might want to change that so only Admins can edit and approve comments:

$bi_Auth = array( 'edit'=>array('blog-edit', 'blog-new', 'sidebar', 'blogit-admin'), 'admin'=>array('comment-edit', 'comment-approve') );

Using AuthUser

You can use AuthUser to provide fine grained access to the blog and its features.

Here's an example where we use two BlogIt roles, one for blogs and one for comments. We then setup two users, 'step' who can create/edit blog-entries, and 'daveg' who can approve comments.

[1] Define BlogIt roles, and associated actions

Actions: 'comment-edit', 'comment-approve', 'blog-edit', 'blog-new', 'sidebar', 'blogit-admin'

$bi_Auth = array( 'blogs'=>array('comment-edit','blog-edit', 'blog-new', 'sidebar','blogit-admin'), 'comments'=>array('comment-approve', 'sidebar','blogit-admin') );

[2] Define users passwords

$AuthUser['daveg'] = crypt('daveg'); #set daveg password $AuthUser['step'] = crypt('step'); #set daveg password

[3] Add users to the roles

$AuthUser['@blogs'] = array('step'); $AuthUser['@comments'] = array('daveg');

[4] Assign roles to security groups

$DefaultPasswords['blogs'] = array('@blogs'); $DefaultPasswords['comments'] = array('@comments');

[5] Assign roles to pmwiki actions

$DefaultPasswords['edit'] = array('@blogs', '@comments');

include_once("$FarmD/scripts/authuser.php");

Alternately you can simply store passwords [2] and users/role assignments [3] in Site.AuthUser or SiteAdmin.AuthUser, in the normal way. In this case simply assign some users to a group (for example @blogs):

Then in config.php:

[1] Define BlogIt roles, and associated actions

Actions: 'comment-edit', 'comment-approve', 'blog-edit', 'blog-new', 'sidebar', 'blogit-admin'

$bi_Auth['blogs'] = array('comment-edit', 'comment-approve', 'blog-edit', 'blog-new', 'sidebar', 'blogit-admin');

[5] Assign roles to pmwiki actions

$DefaultPasswords['blogs'] = array('@blogs');

Internationalization

If you create a new translation, please post it for others to use!

Language Translations

BlogIt utilizes PmWikis built in internationalization mechanism. All text strings are stored in Site.XLPage-BlogIt.

  1. Either create a new language translation page, or use an existing one. To create a new page, copy the content of Site.XLPage-BlogIt to a new page, ie, Site.XLPage-BlogIt-LANGUAGE, and enter the translations within the empty quotes. For example, replace the empty quotes below:
    'more' => ''
    With the language translation:
    'more' => 'plus'
  2. Load the page in config.php:
    XLPage('ABBR','Site.XLPage-BlogIt-LANGUAGE');

You can also use this method to rename any of the labels that BlogIt uses. So if you prefer to have the "more" link in the sidebar read "archive" just create a new XLPage and load it in config.php, using the preferred term rather than a 'true' translation. For example:

English XLPage: 'more' => 'archive' Other Language XLPage: 'more' => 'more-translated'

Changing Date Display and Entry Formats

These date formats are defined by BlogIt. Note that a skin may define additional formats, so check in Site.XLPage-skinname.

You typically want to change date formats when you use PmWiki in a non-English language. BlogIt date formats are stored in Site.XLPage-BlogIt -- so simply make a copy of that page, and load it as you would when adding internationalization support.

Alternately, if you want to change the date formats and not make any other language alterations, add this to config.php, using the original format in the list above as the string used in the array. In this case the 'long-date' is being redefined to %d %B, %y, at or around %H:%M:

$XLLangs[]='blogit'; $XL['blogit']['%B %d, %Y, at %I:%M %p'] = '%d %B, %y, at or around %H:%M';

If you want to use European date entry formats like 'dd/mm/yyyy' which might be confussed with 'mm/dd/yyyy' set $bi_DateStyle.

Changing the Character Set

BlogIt automatically uses UTF-8 character set for page names. You can change this behavior in the using the basic PmWiki configuration, by changing $MakePageNamePatterns, for example Cookbook.ISO8859PageNameConversionPatterns. For example to use ISO-8859:

$Charset='ISO-8859-1';

additonal character conversion patterns for ISO 8859-1 character set

SDV($PageNameChars, '-[:alnum:]'); SDV($MakePageNamePatterns, array( "/'/" => '', "/[^$PageNameChars]+/" => ' ', '/((^|[^-\w])\w)/e' => "strtoupper('$1')", '/ /' => '' ));

additonal character conversion patterns for ISO 8859-1 character set

SDV($ISO88591MakePageNamePatterns, array( '/Á/' => 'A', '/Â/' => 'A', '/Ă/' => 'A', '/Ä/' => 'Ae', '/Ĺ/' => 'Ao', '/Ć/' => 'Ae', '/Ç/' => 'C', '/Č/' => 'E', '/É/' => 'E', '/Ę/' => 'E', '/Ë/' => 'E', '/Ě/' => 'I', '/Í/' => 'I', '/Î/' => 'I', '/Ď/' => 'I', '/Đ/' => 'D', '/Ń/' => 'N', '/Ú/' => 'U', '/Ó/' => 'O', '/Ô/' => 'O', '/Ő/' => 'O', '/Ö/' => 'Oe', '/Ř/' => 'Oe', '/Ů/' => 'U', '/Ú/' => 'U', '/Ű/' => 'U', '/Ü/' => 'Ue', '/Ý/' => 'Y', '/Ţ/' => 'Th', '/ß/' => 'ss', '/ŕ/' => 'a', '/á/' => 'a', '/â/' => 'a', '/ă/' => 'a', '/ä/' => 'ae', '/ĺ/' => 'ao', '/ć/' => 'ae', '/ç/' => 'c', '/č/' => 'e', '/é/' => 'e', '/ę/' => 'e', '/ë/' => 'e', '/ě/' => 'i', '/í/' => 'i', '/î/' => 'i', '/ď/' => 'i', '/đ/' => 'd', '/ń/' => 'n', '/ň/' => 'o', '/ó/' => 'o', '/ô/' => 'o', '/ő/' => 'o', '/ö/' => 'oe', '/ř/' => 'oe', '/ů/' => 'u', '/ú/' => 'u', '/ű/' => 'u', '/ü/' => 'ue', '/ý/' => 'y', '/ţ/' => 'th', '/˙/' => 'y' ));

join to standard patterns MakePageNamePatterns=arraymerge(MakePageNamePatterns = array_merge(MakePageNamePatterns=arraym​erge(ISO88591MakePageNamePatterns, $MakePageNamePatterns);

Charset Conversion Routines

BlogIt will use which ever Charset you defined within PmWiki, except when using Ajax functionality, which must use UTF8. By default BlogIt will transparently convert from UTF8, back into the Charset you have specified in Charset,usingaPHProutine′iconv′.Insomecases,web−hostsdonotprovideaccesstothisroutine.InthesecasesyoucanoverridetheroutingBlogItusesbysetting‘Charset, using a PHP routine 'iconv'. In some cases, web-hosts do not provide access to this routine. In these cases you can override the routing BlogIt uses by setting </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.9463em;vertical-align:-0.1944em;"></span><span class="mord mathnormal" style="margin-right:0.07153em;">C</span><span class="mord mathnormal">ha</span><span class="mord mathnormal">rse</span><span class="mord mathnormal">t</span><span class="mpunct">,</span><span class="mspace" style="margin-right:0.1667em;"></span><span class="mord mathnormal">u</span><span class="mord mathnormal">s</span><span class="mord mathnormal">in</span><span class="mord mathnormal" style="margin-right:0.03588em;">g</span><span class="mord mathnormal">a</span><span class="mord mathnormal" style="margin-right:0.13889em;">P</span><span class="mord mathnormal" style="margin-right:0.08125em;">H</span><span class="mord mathnormal" style="margin-right:0.13889em;">P</span><span class="mord mathnormal">ro</span><span class="mord mathnormal">u</span><span class="mord mathnormal">t</span><span class="mord mathnormal">in</span><span class="mord"><span class="mord mathnormal">e</span><span class="msupsub"><span class="vlist-t"><span class="vlist-r"><span class="vlist" style="height:0.7519em;"><span style="top:-3.063em;margin-right:0.05em;"><span class="pstrut" style="height:2.7em;"></span><span class="sizing reset-size6 size3 mtight"><span class="mord mtight"><span class="mord mtight">′</span></span></span></span></span></span></span></span></span><span class="mord mathnormal">i</span><span class="mord mathnormal">co</span><span class="mord mathnormal">n</span><span class="mord"><span class="mord mathnormal" style="margin-right:0.03588em;">v</span><span class="msupsub"><span class="vlist-t"><span class="vlist-r"><span class="vlist" style="height:0.7519em;"><span style="top:-3.063em;margin-right:0.05em;"><span class="pstrut" style="height:2.7em;"></span><span class="sizing reset-size6 size3 mtight"><span class="mord mtight"><span class="mord mtight">′</span></span></span></span></span></span></span></span></span><span class="mord">.</span><span class="mord mathnormal" style="margin-right:0.07847em;">I</span><span class="mord mathnormal">n</span><span class="mord mathnormal">so</span><span class="mord mathnormal">m</span><span class="mord mathnormal">ec</span><span class="mord mathnormal">a</span><span class="mord mathnormal">ses</span><span class="mpunct">,</span><span class="mspace" style="margin-right:0.1667em;"></span><span class="mord mathnormal" style="margin-right:0.02691em;">w</span><span class="mord mathnormal">e</span><span class="mord mathnormal">b</span><span class="mspace" style="margin-right:0.2222em;"></span><span class="mbin">−</span><span class="mspace" style="margin-right:0.2222em;"></span></span><span class="base"><span class="strut" style="height:0.8889em;vertical-align:-0.1944em;"></span><span class="mord mathnormal">h</span><span class="mord mathnormal">os</span><span class="mord mathnormal">t</span><span class="mord mathnormal">s</span><span class="mord mathnormal">d</span><span class="mord mathnormal">o</span><span class="mord mathnormal">n</span><span class="mord mathnormal">o</span><span class="mord mathnormal">tp</span><span class="mord mathnormal">ro</span><span class="mord mathnormal" style="margin-right:0.03588em;">v</span><span class="mord mathnormal">i</span><span class="mord mathnormal">d</span><span class="mord mathnormal">e</span><span class="mord mathnormal">a</span><span class="mord mathnormal">ccess</span><span class="mord mathnormal">t</span><span class="mord mathnormal">o</span><span class="mord mathnormal">t</span><span class="mord mathnormal">hi</span><span class="mord mathnormal">sro</span><span class="mord mathnormal">u</span><span class="mord mathnormal">t</span><span class="mord mathnormal">in</span><span class="mord mathnormal">e</span><span class="mord">.</span><span class="mord mathnormal" style="margin-right:0.07847em;">I</span><span class="mord mathnormal">n</span><span class="mord mathnormal">t</span><span class="mord mathnormal">h</span><span class="mord mathnormal">esec</span><span class="mord mathnormal">a</span><span class="mord mathnormal">sesyo</span><span class="mord mathnormal">u</span><span class="mord mathnormal">c</span><span class="mord mathnormal">an</span><span class="mord mathnormal">o</span><span class="mord mathnormal" style="margin-right:0.03588em;">v</span><span class="mord mathnormal" style="margin-right:0.02778em;">err</span><span class="mord mathnormal">i</span><span class="mord mathnormal">d</span><span class="mord mathnormal">e</span><span class="mord mathnormal">t</span><span class="mord mathnormal">h</span><span class="mord mathnormal">ero</span><span class="mord mathnormal">u</span><span class="mord mathnormal">t</span><span class="mord mathnormal">in</span><span class="mord mathnormal" style="margin-right:0.03588em;">g</span><span class="mord mathnormal" style="margin-right:0.01968em;">Bl</span><span class="mord mathnormal">o</span><span class="mord mathnormal" style="margin-right:0.03588em;">g</span><span class="mord mathnormal" style="margin-right:0.07847em;">I</span><span class="mord mathnormal">t</span><span class="mord mathnormal">u</span><span class="mord mathnormal">ses</span><span class="mord mathnormal">b</span><span class="mord mathnormal">yse</span><span class="mord mathnormal">tt</span><span class="mord mathnormal">in</span><span class="mord mathnormal" style="margin-right:0.03588em;">g</span><span class="mord">‘</span></span></span></span>bi_CharsetFn to the name of a function that converts from UTF8 to a specified charset. The function must take the form ($val, <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>s</mi><mi>r</mi><mi>c</mi><msup><mo>=</mo><mrow><mo mathvariant="normal">′</mo><mo mathvariant="normal">′</mo></mrow></msup><mo separator="true">,</mo></mrow><annotation encoding="application/x-tex">src=&#x27;&#x27;, </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.7519em;"></span><span class="mord mathnormal">src</span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mrel"><span class="mrel">=</span><span class="msupsub"><span class="vlist-t"><span class="vlist-r"><span class="vlist" style="height:0.7519em;"><span style="top:-3.063em;margin-right:0.05em;"><span class="pstrut" style="height:2.7em;"></span><span class="sizing reset-size6 size3 mtight"><span class="mord mtight"><span class="mord mtight">′′</span></span></span></span></span></span></span></span></span></span><span class="base"><span class="strut" style="height:0.3em;vertical-align:-0.1944em;"></span><span class="mpunct">,</span></span></span></span>tgt='UTF-8') where:

Skin Support

Some skins provide additional support for BlogIt, allowing page elements to be repositioned and syled specifically for that skin. In cases where the skin does not provide this built-in support you have a few options for improving the standard appearance. The standard PmWiki skin is an example of a skin that will work with BlogIt, but whose appearance can be improved by using an additional stylesheet.

Skin Settings

Skin Stylesheets

Listed below are some CSS stylesheets for skins that don't natively support BlogIt. These skins can still be used with BlogIt, with or without the stylesheets -- the stylesheets simply improve the styling for the page elements that BlogIt adds.

If the skin you use is not listed below, try using the PmWiki stylesheet -- it provides some basic styling to BlogIt elements that should work on most skins.

Feel free to add your own stylesheets for your favorite skins.

  1. Save the stylesheet in a publicly accessible directory, usually pmwiki/pub/css/.
  2. Add this to config.php, replacing 'blogit-SKINNAME.css' with the name of the skin file you saved. PageCSSListFmt[′pub/css/blogit−pmwiki.css′]=′PageCSSListFmt['pub/css/blogit-pmwiki.css'] = 'PageCSSListFmt[′pub/css/blogit−pmwiki.css′]=′PubDirUrl/css/blogit-SKINNAME.css'; #Replace SKINNAME with the name of the skin

You can use the blogit-pmwiki.css file as a starting point for providing BlogIt support to other skins.

Validate XHTML Strict

In order to ensure strict XHTML validation with skins which are written to that specification add this to config.php:

For strict validation

SDV($InputTags['end'][':html'], ''); SDVA($InputTags['pmform'][':html'], "<form action='{$PageUrl}' $InputFormArgs>

");

Adding More Features to your Blog

BlogIt provides basic blog support, but relies on other cookbooks to add functionality. Below are some cookbooks that work well with BlogIt, and some suggested settings. Of course, there are always options -- you don't have to use these cookbooks, others will likely work with no issues.

Stop Comment Spam

Comment captcha will only work if you assign Edit and Admin passwords.

Three days after I posted the link to the demo site on the PmWiki mailing list I was getting comment spam. Stop it dead, with some form of captcha cookbook:

$EnableCaptchaImage=1; if (!CondAuth($pagename,'edit')) $EnablePostCaptchaRequired = 1; include_once("$FarmD/cookbook/captcha.php");

Captcha will now be active for comments. Captcha is automatically deactivated when creating or editing blog entries, since you need to be logged in under the Edit or Admin password in order to edit.

If you don't see the captcha enabled for comments, make sure you have assigned edit and admin passwords on your wiki. If you don't assign passwords, then everyone has Edit and Admin access, which causes BlogIt to disable the captcha. The implication of this is that you can't currently use BlogIt in a completely open wiki (no edit or admin passwords), and also enable Captcha -- if there is strong demand for this type of blog then let me know.

Improved Edit Toolbar Icons

Use EditToolbar for an improved toolbar while you edit. You need to enable buttons BEFORE you include blogit.php, otherwise the buttons will not be displayed correctly.

$EnableGUIButtons = 1; include_once("$FarmD/cookbook/edittoolbar.php");

Page Counters

_Note: Full integration with TotalCounter is not currently implemented, as TotalCounter does not display page counts correctly within pagelists._BlogIt will display page counts set by cookbooks using the {$PageCount} variable, like TotalCounter.

include_once("$FarmD/cookbook/totalcounter.php");

Show YouTube and other videos

Use Ape. Easy, lightweight and unobtrusive embedding of maps, videos and more in wiki pages.

Google Sitemaps

One way to make sure your site is found by search engines is to submit a sitemap to the search engine. Use Google Sitemaps. In order to prevent search engines seeing pages they don't have access to, include some additional search patterns to exclude SiteAdmin, and the comment group.

if ($action=='sitemap'){ $EnablePageListProtect = 1; $SitemapSearchPatterns[] = '!^SiteAdmin.!'; $SitemapSearchPatterns[] = '!^Comments.!'; include_once("$FarmD/cookbook/sitemap.php"); }

Page Conversion (to BlogIt, and away from BlogIt)

BlogIt uses Page Text Variables to store blog entry attributes. BlogIt pages look like regular PmWiki pages when viewed with BlogIt disabled -- because they are regular PmWiki pages. If you do a 'normal' PmWiki edit on a blog entry you'll see the variables BlogIt uses.

In order to either add or remove the attributes, simply use the converter utility. The utility can only be run by an Admin. All actions are controlled using URL parameters. Available parameters are:

Conversion Process

This process will add PTV values to the PmWiki page. When you run the utility leave out the writetofile parameter until you've checked the results in the browser.

  1. Make a backup of wiki.d. This process has been rigorously tested -- but caution should prevail.
  2. Append ?action=blogitupgrade&pattern=Blog\. to your URL (for instance the homepage). This step makes no changes -- it outputs all changes that will be made. The pattern 'Blog\.' will process all pages in the Blog group. If you have a huge number of pages (more than a few hundred for instance) you might want to use a different pattern. Verify that the correct pages are being converted, and that things look right.
  3. Append ?action=blogitupgrade&mode=convert&pattern=Blog\.&writetofile=true to your URL (for instance the homepage). This step will write the changes to all matched pages, updating to the new format.

When you run without the writetofile parameter you should see something like:

Main.Main [[#blogit_pmmarkup]](:title 12341:)[[#blogit_pmmarkupend]] (:blogid:blog1:) (:entrytype:blog:) (:entrydate:1239246060:) (:entryauthor:DaveG:) (:entrytitle:12341:) (:entrystatus:draft:) (:entrycomments:open:) (:entrytags::) [[#blogit_entrybody]]2131[[#blogit_entrybodyend]]

Pattern Samples

Converting a Single Page

Convert the page "Blog.Main":

?action=blogitupgrade&mode=convert&pattern=Blog.Main$

Converting All Pages in a Group

Convert all blog entries in the "Blog" group:

?action=blogitupgrade&mode=convert&pattern=Blog.

Converting a number of pages

In this case we match all entries in groups Blog, and Main, the page MyGroup.MyPage, and all pages in the group MyGroup starting with 'A'. Patterns are inclusive by default, which is why the final pattern matches all pages starting with 'A'. Also note that the dot delimiter is prefixed with a '\' -- otherwise it means 'any character'.

?action=blogitupgrade&mode=convert&pattern=Blog.,Main.,MyGroup.MyPage,MyGroup.A

Use a '$' at the end of each pattern to ensure a direct match.

?action=blogitupgrade&mode=convert&pattern=Blog.,Main.,MyGroup.MyPage$,MyGroup.A$

Converting all pages

You can convert all pages at once, using the '.' wildcard. Use this with extreme caution, as it will convert all PmWiki documentation pages, and possibly other system related pages:

?action=blogitupgrade&mode=convert&pattern=.

Converting from BlogIt format to normal PmWiki pages

This function removes the PTV fields added by BlogIt, leaving basic PmWiki pages. You can do the same thing manually, by using the normal PmWiki 'edit' function, and removing the PTV fields.

?action=blogitupgrade&mode=revert

If everything looks okay, then commit the changes:

?action=blogitupgrade&mode=revert&writetopage=true

Advanced Changes to BlogIt

The following setting are also available, and can be made in a config.php file:

SDVA($bi_Ajax, array('bi_ce'=>'ajax', 'bi_ca'=>'ajax', 'bi_cua'=>'ajax', 'bi_be'=>'normal-ajax', 'bi_ne'=>'normal-ajax', 'bi_del'=>'ajax')); #key: action; value: ajax style

$bi_BlogList = array('blog1','blog2','blog3');

array('pmform'=>"$FarmD/cookbook/pmform.php", 'guiedit'=>"$FarmD/scripts/guiedit.php", 'convert'=>"$FarmD/cookbook/blogit/blogit_upgrade.php")

Changing Blog Status Values

You can add new status values to the pull-down list available on the new entry form. You might do this if you want additional groups of blog-entries.

$bi_StatusType['new status']='new status';

Custom Page Titles, and Changing Default Processing

The variable $bi_Hooks allows administrators to specify functions for each page-type, either blog or comment, that will be executed at a specific processing stage either pre-entry, pre-save, or post-save. This allows administrators to change the default behavior of BlogIt, for instance, by specify different default values for fields, or altering the format of page names.

$bi_Hooks['blog']['pre-entry']='processBlogsPreEntry'; $bi_Hooks['comment']['post-save']='processCommentsPostSave';

More than one function can be specified for each page-type/stage combination, using an array. In the example below two functions will get called pre-entry for blogs.

$bi_Hooks['blog']['pre-entry'][]='processBlogsPreEntry1'; $bi_Hooks['blog']['pre-entry'][]='processBlogsPreEntry2'; $bi_Hooks['comment']['post-save']='processCommentsPostSave';

Changing the default status for new blog-entries

In this case specify a hook for blog page-types during pre-entry. Then check that the current action is for new blogs $action=='bi_ne', and set the entrystatus.

$bi_Hooks['blog']['pre-entry'][]='processBlogsPreEntry'; function processBlogsPreEntry($src, $auth){ global POST,_POST,P​OST,action; if ($action=='bi_ne') $_POST['ptv_entrystatus']='sticky'; }

Changing the pagename format

To add the date to the name of the wiki page, hook into the blog post-save processing.

$bi_Hooks['blog']['post-save'][]='renameNewEntryUrl'; function renameNewEntryUrl($src, $auth) { global $_POST; POST[′ptventryurl′]=MakePageName(_POST['ptv_entryurl'] = MakePageName(P​OST[′ptve​ntryurl′]=MakePageName(src, POST[′ptventryurl′].′−′.strftime(′_POST['ptv_entryurl'].'-'.strftime('%Y%m%d',P​OST[′ptve​ntryurl′].′−′.strftime(′_POST['ptv_entrydate'])); }

Another example from Farvardin, "For my needs, I found that I wanted to create a default page name for my entries, based on today's date. Therefore I added this to my local/config.php:"

$bi_Hooks['blog']['pre-entry'][]='processBlogsPrePagename'; function processBlogsPrePagename($src, $auth){ global POST,_POST,P​OST,action; $today = date("Y-m-d"); if ($action=='bi_ne') POST[′ptventryurl′]=′Blog.′._POST['ptv_entryurl']='Blog.'.P​OST[′ptve​ntryurl′]=′Blog.′.today; }

FAQ

Edit the BlogIt FAQ page to add or edit FAQs. Also refer to the Talk pages -- someone may have had a similar problem or question.

Blog entries are not shown

If you're readers (usually non-authenticated) cannot see the content of your blog entries, and only see the title, make sure you have set the status of the entry to something other than Draft. Draft entries are not shown unless you are logged in with Edit or Admin privs.

Changing Tag Used for Breaking Entry

You can change both the tag used to determine the end of the entry introduction (by default [[#break]], and also the text used to display the link to the full entry (by default Read more...). As with date formats you can either change the entries in the XLPage, or make a change in config.php:

$XLLangs[]='blogit'; $XL['blogit']['break']='split'; $XL['blogit']['Read more...']='Continue reading...';

Note: If you change the break tag, then entries using the old break tag will no longer break. You'll need to manually update entries which use the older break tag.

How to hide the standard Action menu

You can hide the action menu (containing View, Edit, History, Backlinks) on an individual page by adding this markup to the page:

Or for the whole wiki with:

SetTmplDisplay('PageActionFmt',0);

The notitle directive does not remove title from blog summary list

This is really down to how the summary list was designed to work -- without the title there would be no deliniation between blog entries. However, you can override this functionality by overriding the blog summary pagelist, or creating a new pagelist. To override the default pagelist, which is in Site.BlogIt-CoreTemplate:

  1. Create a PmWiki page called Site.BlogIt-SkinTemplate-SKINNAME, or edit the page if it already exists -- replace the word SKINNAME with the name of the skin you are using.
  2. The exact markup you see will depend on the skin you are using. Use this sample as a template for creating the list as you want to see it. For instance remove the heading line (2nd line) to remove the page title:

!!! #common-blog-head %h3% Parameters: title, listformat (show header or not), entrydate, entrytags, fullname, entryauthor, showcount [==[==]@ (:if false:)[#common-blog-head] (:if equal "" "true":)!! [ | ] (:div9999 class="blogit-meta-data-head":) (:blogit-skin author pre_text='!!!!!$[By] ' post_text=', $[on] ':)(:blogit-skinend:)
%blogit-date%(:blogit-skin date fmt='long':)(:blogit-skinend:)%%(:if:)
(:blogit-skin edit pre_text='%blogit-edit-link%%item accesskey="$[ak_edit]"%' post_text='%%' page='':)$edit (:div9999end:) [[#common-blog-headend]] @[==]==]

How can I create a list of only the last (newest) n entries?

Simply add count=n (replace the 'n' with a number) to the includesection statement or for a global setting set $bi_EntriesPerPage in config.php.

bi_EntriesPerPage = 15; #default is 10

How to Display Future Dated Entries?

BlogIt will not display entries which are dated beyond the current date. This way you can future date an entry, and it will automatically be displayed once that date is reached, if it is in "Publish" status.

If you want to always display future dated entries:

$bi_DisplayFuture = 'false';

Does BlogIt use cookies?

If you login as a user with BlogIt privs, BlogIt will use cookies to keep track of the page history trail (last two pages). It does this to make the Admin workflow smoother. So when you cancel a blog edit, or when you approve a comment, BlogIt will return to the page you were on previously. The cookie is only maintained for the current session, and is removed when you close the browser.

Cookies are not used for blog readers.

Admin is Redirected to Incorrect Page

If you are consistently being redirected to the same wrong page after performing an Admin function (comment edit, comment delete, comment approve, cancel from a blog edit, etc), and you were using BlogIt prior to version 1.2.0 delete all cookies associated with blogit:

If you see multiple cookies with the same cookie name (blogit-back-1 and blogit-back-2), delete them all.

Change the default BlogIt styling

You can change the styling of BlogIt elements by using a stylesheet. Some skins come packaged with styling for BlogIt-specific elements. For skins that don't include specific styling for BlogIt you the PmWiki BlogIt stylesheet might work, or might be a good basis to create a new stylesheet for your skin.

Prevent Formatting in Comment when displayed in sidebar

BlogIt displays the first sentence (or until the first newline) of each comment in the Sidebar. Sometimes user use basic PmWiki formatting within comment, and this can adversely affect the look of the sidebar. For instance, if the comment text starts with %red% then the comment in the sidebar will be red. You have a couple of options in these cases:

  1. Edit comments either removing the offending formatting, or add a summary first sentence with no formatting.
  2. Use a recipe like MarkupToUnstyled to strip sidebar comments of formatting, and then tell BlogIt to use the function with $bi_UnstyleFn:
    include_once("$FarmD/cookbook/markuptounstyled.php");
    $bi_UnstyleFn = 'MarkupToUnstyled';
  3. Define a style to override the most common comment sidebar styling:
    $HTMLStylesFmt['bi-pmwiki'] .= '.blogit-comment-summary-list li span {font-size: 100% !important;} ';
  4. Define a style to override the most common comment sidebar styling, and then apply the style to the offending sentence in the comment, Thus, when the first line of a comment needs sanitizing, the reviewer can simply surround the offending sentence with the new class %sidebaronly%sanitized title%%.
    $HTMLStylesFmt['bi-pmwiki'] .= '.sidebaronly { display:none; } #sidebar .sidebaronly { display:inline; }';

Problems with Passwords

BlogIt needs to be able to access text within pages -- that means it needs to be able to access pages. Thus BlogIt has to be included:

Automatically Approve all Comments

By default comments DO NOT need to be approved by an admin. If you have a captcha enabled, then that's usually enough to stop spam. However, if you need a level of admin approval set this in config.php:

$bi_DefaultCommentStatus = 'false';

Unapproved comments don't show in control panel

If you override $bi_DefaultCommentStatus make sure you provide a string value, not a 'boolean' value:

$bi_DefaultCommentStatus='false';

The browser title bar title shows the title from a blog-entry

You have manually included a (:title TBD:) markup in the body of one of your blog entries. Currently PmWiki gives precedence to titles that occur last in a page. Since the blog list page includes the first part of the blog entry, which includes the title markup, it overrides any prior title markups on the blog list page. You can work around this by setting a (:title TBD:) at the very bottom of the blog list page, after all the pagelists. Alternately refer to the one line fix on PITS 00779.

No entries listed in Recent Entries section

If you see no entries listed under the sidebar "Recent Entries" heading, and you do have entries that you would expect to see listed, ensure you have set the following in config.php. More info is on the Talk Page:

$EnableRelativePageVars = 1;

Cookbook Compatibility

Some extensions may adversly onteract with BlogIt settings, such as MultiLanguage. You have to edit multilanguage.php, and change the "$title" variable to something else.

Setting up an RSS feed

By default BlogIt will display an RSS feed icon in the browser bar. You can turn this feature off by:

You can add an RSS link to a page with this markup:

[[{$SiteGroup}.BlogIt-Admin?action=rss | RSS Feed]]

You can change the page through which the RSS feed is accessed; the page does not need to exist. For example through the page Blog.RSS:

$bi_Pages['rss']='Blog.RSS';

BlogIt will display 10 entries on your RSS feed. Change this by setting:

Using the Drafts Recipe and BlogIt

If you are logged in as an Edit user, and have enabled both the Drafts recipe and BlogIt, and try to perform an ?action=edit on a non-BlogIt page, then the Publish button will not be enabled. In this scenario you will need to ensure that you include the Drafts recipe from config.php, rather than relying on PmWiki to automatically include Drafts.

$EnableDrafts=1; include_once("$FarmD/scripts/draft.php"); include_once("$FarmD/cookbook/blogit/blogit.php");

Some background: Drafts are enabled in PmWiki using $EnableDrafts=1, which provides a mechanism for saving pages a separate draft pages, with a "-Draft" suffix, and then later publishing the draft to the final page, basically changing the page name removing the "-Draft" suffix. This workflow doesn't really align with the way in which typical blogs operate, and so BlogIt implements it's own draft mechanism. In addition even if you were to enable Drafts, BlogIt doesn't use the normal PmWiki edit action, and so you would not see the Publish/Draft buttons.

How (:includesection ...:) works

Blog-it makes extensive use of pagelists and other markup, but this markup is rarely found in the source of the page you are viewing. Usually the markup is included ("brought into the page") via the (:includesection ...:) markup. Includesection simply goes to a defined set of pages and searches for the specified section -- the first section it finds (as named in the includesection markup) as it goes through the pages is then placed in the current page. The pages which are searched by default are these:

This bit of code defines the precedence of the pages as blogit looks for the relevant section:

SDV($bi_TemplateList, (isset($bi_Skin)?$SiteGroup.'.BlogIt-SkinTemplate-'.$bi_Skin.' ' : '') .$SiteGroup .'.BlogIt-CoreTemplate');

The Power Behind the Code

BlogIt is brought to you with help from:

Known Issues

Edit the BlogIt Known Issues page to add or edit issues.

List is grouped by issue type, and within that group is in approximate level of urgency, so items near the top of each issue type are likely to get implemented first. Issues are formatted as described below:

The list serves as a roadmap and outlines the likely areas of focus for future releases of BlogIt, and provides guidance on how known issues will be addressed.

  1. Stability: Remove known bugs. Ensure coding approaches leverage the PmWiki framework appropriately. Security shake-down.
  2. Functionality Alignment: Verify co-existance with existing blog-related recipes. Bring the blog features up to par with traditional blogging platforms.
  3. User Interface: Create templates for existing skins, ajax ui, control panel.
  4. Scale Up: Ensure performance scales to blogs with thousands of pages, and comments.
  5. Importing: Provide a means of importing pages from existing systems (Blogger, WordPress, etc).

Bugs

New

Changes

Documentation

Development Release

These issues are only found in the current development release.

Issues that need additional verification

If you are able to repeat any of these issues, please let me know how you did it!

Change Log

The most recent changes are listed below. A full archive can be found in the BlogIt release history.

1.9.6 (2024-09-14)

Contributors: Petko. Requested and tested by Fabien Vignes-Tourneret.

Release Summary

Many updates for PHP 8.2, diffs and downloads merged with origin, released as 1.9.6. (also available at https://github.com/5ko/BlogIt). Requires PmWiki 2.3.36 or more recent.

I do not use this recipe, if you uncover any problems I haven't noticed, please post on the BlogIt-Talk page or via email. Someone who regularly uses the recipe will be most welcome to take over the maintenance. --Petko

1.9.5 (1-Apr-2016)

Contributors: DaveG

Release Summary

Ensure tags are spaced correctly on single-entry -- ensure you update to the latest version of your skin. Some changes to internationalization. Locks down diff and source by default. Minor fixes and clean up.

Release Details

1.9.4 (28-Mar-2016)

Contributors: DaveG

Release Summary

Fixed problem saving ajax mode.

Release Details

1.9.3 (28-Mar-2016)

Contributors: DaveG

Release Summary

Fixed a bug when using $bi_CommentsAutoClose. Works with ReCaptcha.

Release Details

1.9.2 (26-Mar-2016)

1.9.1 (26-Mar-2016)

Cleaned up code using pretty print. No other changes. (http://jsbeautifier.org/, http://beta.phpformatter.com/)

1.9.0 (26-Mar-2016)

Contributors: DaveG, SteP, circusmachina
Issue Reports: SteP, Blonder, circusmachina, Farvardin, John Rankin, Peter Bowers

Release Summary

Big bug fix release, and a few new features for bulk administration of comments.

Release Details

1.8.0 (24-Feb-2016)

Contributors: DaveG, Jr, Tiger!P

Release Summary

Added PHP5.x compatibility. Ensure you download and install the latest PmForm, as it's no longer included as part of the BlogIt package.

Release Details

The most recent changes are listed above. A full archive can be found in the BlogIt release history.

User notes +18: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.