Bloge
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:
- bloge-core.zipΔ — The Bloge core files which tie together all the rest and provide basic blogging and commenting functionality
- PmForm — pmform.zipΔ — Form processing engine for PmWiki (
Site.PmFormTemplatesis not used by Bloge) - Captcha — captcha.phpΔ — Use captchas to prevent automated systems from modifying pages
- EditAttributes — editattr.phpΔ — Edit a page's title, description and other attributes using separate EditForm fields (version 2009-07-30 or later is required)
- Bloge-Feeds — bloge-feeds.phpΔ — Blog-like Atom & RSS feeds
- Bloge-Linkback — bloge-linkback-client.phpΔ and bloge-linkback-server.phpΔ — Automatically send and receive Pingbacks and Trackbacks
- Bloge-Ping — bloge-ping.phpΔ — Notify search engines when a page is modified (not enabled by default by Bloge-core)
- Bloge-ShortUrl — bloge-shorturl.phpΔ — Get short URLs on your own site (not enabled by default by Bloge-core)
- Bloge-Tags — bloge-tags.phpΔ — Use page keywords and categories as tags
- Bloge-UrlApprove — bloge-urlapprove.phpΔ — Approve links one at a time
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Δ)
|
|
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:
| Key | Default 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*60 | Comment editing time after posting, in seconds; set to zero or a negative number to disable editing after posting. |
'comment-blocklist' | 10 | The 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:
| Variable | Default value | Explanation |
|---|---|---|
$EnableBlogeCaptcha | 0 | Require valid captcha for posting anonymous comments. Also requires $EnableBlogeComments. |
$EnableBlogeComments | 1 | Posting new comments. If disabled, Blog.GroupFooter should probably also have the comment posting form removed. |
$EnableBlogeFeeds | 1 | Bloge-Feeds: blog post and comment feeds. To just disable the comment feeds, set $Bloge['comment-feeds'] = FALSE;. |
$EnableBlogeLinkbackClient | 0 | Bloge-LinkbackClient. Note: requires cURL. |
$EnableBlogeLinkbackServer | 0 | Bloge-LinkbackServer. Note: requires cURL. If enabled, Bloge will also by default set $EnableLinkbackBlocklist = 10;. |
$EnableBlogePing | 0 | Bloge-Ping. |
$EnableBlogeShortUrl | 0 | Bloge-ShortUrl. |
$EnableBlogeTags | 1 | Bloge-Tags. |
$EnableBlogeUrlApprove | 1 | Bloge-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.GroupFooterandBlog.SideBarto the respective pages in your new group - Rename the per-page and per-group customization files in the
local/directory (Blog.NewPost.php,Blog.phpandComments.php) - Fix the hardcoded references to the group names in
Blog.GroupFooter,Blog.TemplatesandComments.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
itemcountonBlog.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 onBlog.EditForminside 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
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.