Bloge

Summary: A bundle of blogging
Version: 2009-08-28
Prerequisites: PmWiki 2.2.x, PmForm, EditAttributes
Status: beta
Maintainer: Eemeli Aro
Categories: Blog
Discussion: Bloge-Talk

Test site: http://aut-web.hut.fi/bloge/

Description

Bloge is a full-featured bundle of recipes for using PmWiki as a blogging engine. Its structure is as modular as possible, so you may pick and choose what to use, or just grab the whole lot.

The basic requirements of what makes up a blog aren't the same for everyone; the discussion here on pmwiki.org has been active since at least 2004 with quite a few recipes and bundles. Bloge is an attempt to fulfill any reasonable set of these requirements in an easy-to-use manner (Not a lofty goal at all, no...).

The philosophy behind Bloge is to be as non-intrusive as possible and to rely as much as possible on standard (but powerful!) PmWiki features such as templated page lists and a few commonly used recipes (PmForm, Captcha and EditAttributes). However, getting all of that to play nicely with each other and other recipes makes the initial installation a bit more complex than usual. After that, though, all you need to add to your config file is a single line.

For a more in-depth introduction to Bloge, you're best off taking a look at and playing with the test site at http://aut-web.hut.fi/bloge/ — to add blog posts use the username Poster and password test.

Download

Since this is a bundle, you can either download bloge-bundle.zipΔ or get its contents individually:

Installation

NOTE: If you would like to use this bundle but find these instructions too complex or difficult to understand, please leave a comment on the talk page, and I'll see what I can do.

If you've downloaded the files separately, each of the recipes has their own installation instructions that mostly consist of just putting the .php file in your cookbook/ directory. PmForm also includes a template file that isn't used by Bloge.

For the coreΔ and the bundle packageΔ, once you unpack it you should have files in four different directories: (files in italics are not included in bloge-core.zipΔ)

cookbook/
bloge.php
bloge-feeds.php
bloge-linkback-client.php
bloge-linkback-server.php
bloge-ping.php
bloge-shorturl.php
bloge-tags.php
bloge-urlapprove.php
captcha.php
editattr.php
pmform.php
local/
Blog.NewPost.php
Blog.php
Comments.php
pub/
bloge.css
bloge.js
wikilib.d/
Blog.Blog
Blog.EditForm
Blog.GroupFooter
Blog.GroupHeader
Blog.SideBar
Blog.Templates
Comments.GroupFooter
Site.PmFormTemplates

Each needs to go to the corresponding directory in your PmWiki installation. If you're using a wiki farm, you may need to copy the files to the corresponding directory of each wiki, depending of course on your setup.

If you'd prefer to use some other groups than Blog and Comments, please see below for the instructions.

Once that's done, just add the following line to your config file:

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

Usage

On first visit, the page Blog.Blog will be rather empty. However, provided that you have edit access the sidebar should provide a link "New blog post" that'll take you to Blog.NewPost?action=edit, which will present a blog post edit form that has a few more text fields than the commonly used one:

  • Title, Description and Keywords correspond to the similarly-named page directives. With Bloge-Tags, the keywords are also used as tags and shown at the bottom of the blog post as well as in the tag cloud in the sidebar.
  • Time is the publication time for the blog post. You can use a variety of expressions here, such as "now", "+2 hours", "last Monday", or an exact time ina format such as year-mm-dd hh:mm. Leaving this blank will use the current time. Blog posts that have a future time won't be published until that time, requiring edit access to view before then.
  • Hide comments and lock comments control what's shown at the bottom of a blog post and in post listings.

Now, once you've made your blog post and published it, it'll get named using the time value and the title, with a name such as Blog.2009-08-16-my-first-blog-post or Blog.2009-08-16 if you didn't provide a title. Multiple post on the same day with the same title will have names postfixed -2, -3 and so on.

If you've enabled $EnableDrafts, Bloge will support that as well: draft blog posts won't get listed or otherwise shown unless you have edit access. Unfortunately there's still a small bug in publishing drafts: the page name will be generated when you first save the draft, not when you publish it. This means that if you change the time value the page name won't change to suit. Internally, though, the blog post will get listed and shown with the proper publication time.

The only special markup that's added for use on blog posts is the optional [[#jump]], which signifies the end of page contents to include in listings and feeds. If it is used, it'll get replaced with a link "Continue reading..." to the full blog post. A GuiEdit button is also added for this.

Configuration

The Bloge bundle can be configured and controlled via an array $Bloge, has the following structure:

KeyDefault
value
Explanation
'group''Blog'The page group for blog entries and archives.
'comment-group''Comments'The page group for comments; set empty to disable commenting.
'comment-edittime'30*60Comment editing time after posting, in seconds; set to zero or a negative number to disable editing after posting.
'comment-blocklist'10The value for $EnableBlocklist when processing comments
'comment-feeds'array('atom','rss')Comment feed types.
'email-to'''Address where to email notifications about new comments. Use a comma-separated list for multiple addresses.
'email-from'"Bloge comment ...""From:" address to use in comment emails. See source for full default value.
'email-subject''{$Title}'Title of comment emails.
'editformpage''Blog.EditForm'Page where the blog post edit form is found; set empty to use the default edit form.
'templatepage''Blog.Templates'Page where the required templates are found
'newpostpage''Blog.NewPost'Page to use for new blog posts; the page in question shouldn't actually exist but its per-page customization should.
'css-url'"$PubDirUrl/bloge.css"Where to find the default CSS file; set empty if not using.
'javascript-url'"$PubDirUrl/bloge.js"Where to find the default Javascript file; set empty if not using. This transforms the blog post and comment times into relative terms, as in "2 hours ago".
'feeds'
array('atom' => ...,
'rss' => ...)
An array of feedType => feedURL for blog post feeds.

So to set Bloge to email you when a new comment is received, you could use:

$Bloge['email-to'] = 'yourname@example.com';

Additionally you can enable or disable different parts of Bloge by setting the following:

VariableDefault valueExplanation
$EnableBlogeCaptcha0Require valid captcha for posting anonymous comments. Also requires $EnableBlogeComments.
$EnableBlogeComments1Posting new comments. If disabled, Blog.GroupFooter should probably also have the comment posting form removed.
$EnableBlogeFeeds1Bloge-Feeds: blog post and comment feeds. To just disable the comment feeds, set $Bloge['comment-feeds'] = FALSE;.
$EnableBlogeLinkbackClient0Bloge-LinkbackClient. Note: requires cURL.
$EnableBlogeLinkbackServer0Bloge-LinkbackServer. Note: requires cURL. If enabled, Bloge will also by default set $EnableLinkbackBlocklist = 10;.
$EnableBlogePing0Bloge-Ping.
$EnableBlogeShortUrl0Bloge-ShortUrl.
$EnableBlogeTags1Bloge-Tags.
$EnableBlogeUrlApprove1Bloge-UrlApprove.

How to rename Blog and Comments groups

Using different group names than "Blog" and "Comments" is possible, but requires renaming things in a few places to match.

  • The contents of the PHP files shouldn't need any modifications once you've set $Bloge['group'] = 'YourNewBlogGroup'; as well as set the values of $Bloge['editformpage'], $Bloge['templatepage'] and $Bloge['newpostpage'] if you're moving them as well to new locations.
  • Rename or copy the contents of Blog.GroupHeader, Blog.GroupFooter and Blog.SideBar to the respective pages in your new group
  • Rename the per-page and per-group customization files in the local/ directory (Blog.NewPost.php, Blog.php and Comments.php)
  • Fix the hardcoded references to the group names in Blog.GroupFooter, Blog.Templates and Comments.GroupFooter.

Blog pages

Here's a listing of what specific pages do under Bloge.

Blog.Blog
The main blog page, with full posts or extracts of the 8 latest blog posts. This number 8 is configurable as the page text variable itemcount on Blog.Blog, and also controls the number of blog posts in the paged archives.
Blog.EditForm
The edit form used for blog posts, based on the default Site.EditForm. To use a single edit form for all pages on your wiki you should add to it the fields used on Blog.EditForm inside a conditional such as (:if ( group Blog && ( name NewPost || name ????-??-* ) ) :).
Blog.GroupFooter
Handles archive page contents and the blog post footer, which includes post tags, author, permalink, short URL, trackback link, and comments.
Blog.GroupHeader
Adds a timestamp to the top of blog posts.
Blog.NewPage
The location used for creating new blog posts. The page doesn't actually exist, but its per-page customization file (local/Blog.NewPage.php) does, which is used to generate the page name for new blog posts.
Blog.SideBar
A sample sidebar to use with Bloge, featuring most of the pagelists and other additions you might have in your sidebar
Blog.Templates
Page list templates and PmForm templates used by Bloge.
Blog.2, Blog.3, etc.
A continuation of the main blog page's list of blog posts.
Blog.2009, Blog.2010, etc.
All blog posts from the specified year.
Blog.2009-08, Blog.2010-01, etc.
All blog posts from the specified month.
Blog.2009-08-16-first-post, Blog.2009-08-20, etc.
Individual blog posts
Comments.GroupFooter
Redirects viewing comment pages to their context on blog posts.
Comments.2009-08-16-first-post-012, Comments.2009-08-20-003, etc.
Individual comments are kept as separate wiki pages, each named after its parent blog post's name postfixed with an auto-incremented three-digit number (eg. -003, -012)

A note about archive index pages (eg. Blog.2, Blog.2009, Blog.2009-08): These pages don't actually exist, instead their contents are generated by Blog.GroupFooter and hence need to be linked to as eg. {$BlogRoot}/2009-08 instead of Blog/2009-08. {$BlogRoot} is the URL root of the blog group, and hence links using it won't check whether the target page exists or not. Unfortunately these links also won't be added to the link targets, and hence you can't do a search for eg. link=Blog.2.

Notes

I'll be adding to and fixing this documentation as I get the chance. The scope of the bundle is such that it requires a few words to explain everything.

The strict rules on page naming that Bloge imposes are a feature, not a bug. This forces a clear distinction between blog and wiki content while imposing no artificial rules that prevent using information either way. If you would like to post a wiki page as a blog post, you can for example (:include:) it in a new blog post. Similarly, each blog post is just a wiki page that you may refer to and use as you see fit. And if you really want to, you could modify the pagelist rules to fix this.

The recipe includes and uses a couple of MarkupExpressions that may be useful outside the context of the recipe as well: {(math)} and {(atomic)}

Comment author names can't include spaces. This is due to integration with AuthUser, which prevents anonymous commenters from using the name of a registered user. At the moment this only checks users mentioned on the page SiteAdmin.AuthUser. Authenticated users' comments also receive a different CSS class ("authuser") than anonymous ones ("anon").

Bloge adds a wrapper around $AuthFunction in order to make the comment editing and future post blocking possible. If you're using a non-standard authentication function it should work all right provided that you've set it up before including bloge.php and that your function matches PmWikiAuth in its external functionality.

The bundle is intentionally light on styling, so as to make it easily modifiable for any PmWiki skins. Some CSS rules are included as pub/bloge.css, but including that is completely optional. The pagelist templates and header/footer files do however set a number of classes that your own CSS rules may use.

The relative dates are generated using javascript, pub/bloge.js, which relies on the browser's clock not being too far out of sync.

Release notes

Please see the individual recipe pages for their release notes. The following only refers to the Bloge core and bundle, which are released via this page.

  • 2009-08-28 coreΔ bundleΔ — component recipe updates + added captcha + bugfixes: anonymous comment author check, disabled comment drafts
  • 2009-08-16 coreΔ bundleΔ — first release
  • 2009-08-10 — this page first published (incomplete)

Contributors

See also

  • Cookbook.Blog — List of recipes in Blog category
  • Cookbook.BlogIt — Provides a complete blogging system, using in-built PmWiki features -- additional features are supported through existing cookbooks.

Comments

See discussion at Bloge-Talk

User notes +3: 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.