Author: PyBlosxom Development Team
Version: comments.txt 1029 2007-06-07 02:33:12Z willhelm
Copyright: This document is distributed under the MIT license.


This chapter briefly walks you through installing the comments, trackback, pingback, and CommentAPI plugins.


PyBlosxom does not come with comments functionality built-in. Instead, comments are implemented as a plugin which people who are interested in in having comments can install and everyone else can ignore.

You can get the latest stable version of the comments plugin from the contributed plugins pack. Alternatively, you can get the latest version from SVN, which is even more recent but may be broken. Caveat hacker!

The comments plugin also has a README file that has more information on installing comments, traceback, pingback, and the comment API.

Installing the comments plugin


After making sure you have the requirements, do the following:

  1. Copy contrib/plugins/comments/plugins/ to your plugins directory. Then add "comments" to the load_plugins property in your file.

  2. Comments are stored in a directory tree which will parallel the data directory tree. The comments themselves are stored as XML files named entryname-datetime.suffix. The comment system allows you to specify the directory where the comment directory tree will stored, and the suffix used for comment files. You need to make sure that this directory is writable by the pyblosxom CGI scripts.

    Set comment_dir to the directory (in your data directory) where you want the comments to be stored. The default value is a directory named comments in your data directory.

    Set comment_ext to the change comment file extension. The default file extension is cmt.

  3. Copy the flavour files from the contrib/plugins/comments/flavours directory. There are flavours for html and rss. You should copy all the files to your data directory.

    The comment-story template is used to format a single entry that has comments. The comment template is used to format a single comment/trackback/pingback. The comment-form template provides the form used to enter new comments.

  4. Edit the comment-story, comment, and comment-form templates. Variables that are available are:

    Available in the story and comment-story templates:

    Template variables from available in story and comment-story

    variable name



    contains an integer count of the number of comments associated withthis entry

    Available in the comment template:

    Template variables from

    variable name



    the title of the comment


    the content of the comment or excerpt of the trackback/pingback


    the pingback link referring to this entry


    the author of the comment or trackback


    the author, wrapped in an <a href> tag to $cmt_link if it was provided


    the date and time of the comment/trackback/pingback


    the source of the trackback

Email notification

Enabling email notification

The comment system can notify you via e-mail when new comments/trackbacks/pingbacks are posted. There are two ways to configure this feature. The first is to have email notifications sent through your MTA via SMTP and the second is to have email notifications sent through your MTA via a local command.

If you want to enable this feature, add the following properties to your file:

py['comment_smtp_server'] - your SMTP server


py['comment_mta_cmd']     - alternatively, the path to your MTA


py['comment_smtp_from']   - the address sending the notification
py['comment_smtp_to']     - the address receiving the notification

For example, this sends email through your MTA via SMTP connecting to localhost:

py['comment_smtp_server'] = "localhost"
py['comment_smtp_from']   = ""
py['comment_smtp_to']     = ""

This sends email through your MTA via the command /usr/bin/mail:

py['comment_mta_cmd']     = "/usr/bin/mail"
py['comment_smtp_from']   = ""
py['comment_smtp_to']     = ""

Writing comments plugin templates

This "diagram" shows which templates are responsible for what for rendering a single entry:

<div class="news">           <- story.html
<h2>$title</h2>               |
<div class="content">         |
...                           |
</div>                        |
links                         |
</div>                       <-
<div class="comments">       <- comment-story.html
<div class="comment">        <- comment.html
Posted by $blah at $blah      |
$blah                         |
</div>                       <-
<div class="comment">        <- comment.html
Posted by $blah at $blah      |
$blah                         |
</div>                       <-
<div class="commentform">    <- comment-form.html
form stuff here.              |
</div>                        |
</div>                       <-

AJAX commenting

Comment previewing and posting can optionally use AJAX, as opposed to full HTTP POST requests. This avoids a full-size roundtrip and re-render, so commenting feels faster and more lightweight.

AJAX commenting degrades gracefully in older browsers. If the user's browser doesn't support JavaScript or XmlHttpRequest, or if the user has turned JavaScript off, comment posting and preview will use normal HTTP POST.


To enable AJAX commenting in your pyblosxom installation, just copy comments.js to your plugin directory and add the following JavaScript to your comment-form template. (It's already included in the comment-form.html template that comes with the comments plugin.)

First, add a comment-anchor tag to the beginning of the template:

<p id="comment-anchor" />

Add an onsubmit handler to the form tag:

<form method="post" action="$base_url/$file_path#comment-anchor"
      name="comments_form" id="comments_form" onsubmit="return false;">

If you run pyblosxom inside cgiwrap, remove #comment-anchor from the URL in the action attribute, since it confuses cgiwrap. (If AJAX comment previewing and posting don't work, try removing #comment-anchor first. Your hosting provider may be using cgiwrap without your knowledge. )

Next, add onclick handlers to the button input tags:

<input value="Preview" name="preview" type="button" id="preview"
       onclick="send_comment('preview');" />
<input value="Submit" name="submit" type="button" id="post"
       onclick="send_comment('post');" />

Finally, include this script tag somewhere after the form closing tag:

<script type="text/javascript" src="/comments.js"></script>

The separate closing &lt;/script&gt; tag is necessary for IE. Without it, IE won't actually run the code in comments.js.


To disable AJAX support, simply remove the JavaScript onsubmit and onclick handlers from your comment-form template. The comments plugin will fall back to traditional HTTP POST commenting.

Dealing with comment spam

Expect it to happen. Some folks get comment spam trickling in and others get a torrential downpour. It's best to deal with it from the start. It's also something you're going to have to deal with every few months as spam techniques change and your needs change.

If this doesn't sound like something you want to actively maintain on your blog, then you should encourage people to email comments to you and rely upon your email spam-prevention.

As of contributed plugins pack 1.2 (March 27, 2005), the comments plugin has a comment_reject callback which allows plugins to examine each comment and reject it according to the plugin's heuristics. Because this is done in a callback, you can have multiple comment rejection plugins that handle different situations. A comment won't be accepted until it has been looked at by each comment rejection plugin you have running on your blog.

The recommended comment spam solution is akismetcomments and check_javascript, in parallel. akismetcomments uses Akismet, a centralized comment spam database and filter, and check_javascript simply checks that the client's user agent supports Javascript. (Spam bots almost never do.)


Akismet is a spam filter service developed and operated by Automattic, the people behind WordPress. Akismet maintains an up-to-date blacklist, Bayesian filter, and other tools to determine whether blog comments are spam or valid, ie "ham".

The akismetcomments plugin passes every comment on your blog to Akismet, which decides whether the comment is spam or ham. If spam, the comment is logged and discarded; if ham, it is accepted to your blog.

To use akismetcomments, you'll need to sign up for a API key.

After you have your API key, copy and to your plugin directory. Add an akismet_api_key config variable with to your API key to your Also, make sure the baseurl config variable is defined:

py['baseurl']        = ""
py['akismet_api_key] = "ABQIAAAAg88GzFz..."

Finally, your blog's web server will need to be able to make outbound HTTP connections on port 80 to Some hosting providers and firewalls may prevent this. If you're not sure about this, check with your webmaster or hosting provider.

akismetcomments was written by Benjamin 'Mako' Hill and Blake Winton.


Comment spam is usually sent by automated spam bots, which blindly send HTTP POSTs to a large, static list of blog addresses. These spam bots have very little in common with web browsers. In particular, they rarely parse or render HTML, and even more rarely run Javascript.

Given this, Javascript can be an effective way to determine whether a comment was submitted by a spam bot or a web browser. check_javascript uses a small piece of Javascript on the client side to set the value of an input element in the comment form, which it checks for on the server.

To use check_javascript, first copy to your plugins directory. Then include this hidden input element and Javascript in your flavour's comment-form template:

<input type="hidden" name="secretToken" id="secretTokenInput"
  value="pleaseDontSpam" />

<script type="text/javascript">
// used by this is almost entirely backwards compatible,
// back to 4.x browsers.
document.getElementById("secretTokenInput").value = "$blog_title";

It's included in the comment-form.html template in the contrib/plugins/comments/flavours/, so if you use that template, you're good to go.

check_javascript was written by Ryan Barrett.

rolling your own

It's not hard to roll your own comment rejection plugin. First figure out what the heuristics involved would be. Then write a plugin with a cb_comment_reject function in it. In that function, look at the data provided and reject the plugin if it seems appropriate to do so.

A basic template for writing a plugin to reject comments is as follows.

Example: Template for plugin for rejecting comments

FIXME - Documentation for what your plugin does and how to set it up
goes here.

FIXME - License information goes here.

FIXME - Copyright information goes here.
__author__      = "FIXME - your name and email address"
__version__     = "FIXME - version number and date released"
__url__         = "FIXME - url where this plugin can be found"
__description__ = "FIXME - one-line description of plugin"

def verify_installation(request):
    # FIXME - code to verify that this plugin is installed correctly
    # here.

    return 1

def cb_comment_reject(args):
    req = args["request"]
    comment = args["comment"]

    blog_config = req.getConfiguration()

    # FIXME - code for figuring out whether this comment should
    # be rejected or not goes here.  If you want to reject the
    # comment, return 1.  Otherwise return 0.

Installing trackback

If you want to support trackbacks, copy contrib/plugins/comments/plugins/ to your plugins directory. Then add "trackback" to the load_plugins property in your file.

If you want trackbacks you need to advertise the trackback ping URL for a particular entry.

You advertise a manual trackback ping link. You can do this by inserting the following HTML in story.html and comment-story.html files:

<a href="$base_url/trackback/$file_path" title="Trackback">TB</a>

The /trackback URL prefix is configurable with the trackback_urltrigger config variable.

You can supply an embedded RDF description of the trackback ping:

  <rdf:RDF xmlns:rdf=""

This RDF should also be inserted in story.html and comment-story.html. Since it is in an HTML comment, it doesn't matter where you put it.

Installing pingback

If you want to support pingbacks, copy contrib/plugins/comments/plugins/ and contrib/xmlrpc_plugins/ to your plugins directory. Make sure you have the base_url property defined in your file. Then add "xmlrpc_pingback" to the load_plugins property in your file.

You'll need to advertise a pingback link in your head template. Add the following tag to the meta section:

<link rel="pingback" href="" />

Replace with your baseurl.

Installing the CommentAPI

FIXME - this text probably needs fixing.

If you want to support CommentAPI, copy contrib/plugins/comments/plugins/ to your plugins directory. If you enable CommentAPI in your RSS feed (see below), some RSS aggregator programs will provide an interface that can post a comment to a blog entry.

You need to have installed in order for this to work.

Then you must add the CommentAPI tags to your RSS 2.0 feed. The best way to do this is to add an XML namespace declaration to the rss element:


Then inside your RSS items you need to add a wfw:comment element:


where ###commentAPI### is replaced by the URI that you mapped your CommentAPI.cgi to At the moment, you need to map to a URI one level below the $base_url of the blog