| Author: | PyBlosxom Development Team |
|---|---|
| Version: | comments.txt 1029 2007-06-07 02:33:12Z willhelm |
| Copyright: | This document is distributed under the MIT license. |
Contents
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.
Requirements:
After making sure you have the requirements, do the following:
Copy contrib/plugins/comments/plugins/comments.py to your plugins directory. Then add "comments" to the load_plugins property in your config.py file.
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.
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.
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 comments.py available in story and comment-story |
|
|---|---|
variable name |
description |
num_comments |
contains an integer count of the number of comments associated withthis entry |
Available in the comment template:
Template variables from comments.py |
|
|---|---|
variable name |
description |
cmt_title |
the title of the comment |
cmt_description |
the content of the comment or excerpt of the trackback/pingback |
cmt_link |
the pingback link referring to this entry |
cmt_author |
the author of the comment or trackback |
cmt_optionally_linked_author |
the author, wrapped in an <a href> tag to $cmt_link if it was provided |
cmt_pubDate |
the date and time of the comment/trackback/pingback |
cmt_source |
the source of the trackback |
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 config.py file:
py['comment_smtp_server'] - your SMTP server OR py['comment_mta_cmd'] - alternatively, the path to your MTA AND THEN 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'] = "joe@joe.com" py['comment_smtp_to'] = "joe@joe.com"
This sends email through your MTA via the command /usr/bin/mail:
py['comment_mta_cmd'] = "/usr/bin/mail" py['comment_smtp_from'] = "joe@joe.com" py['comment_smtp_to'] = "joe@joe.com"
FIXME
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> <-
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 </script> 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.
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.)
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 check_javascript.py 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" />
</form>
<script type="text/javascript">
// used by check_javascript.py. this is almost entirely backwards compatible,
// back to 4.x browsers.
document.getElementById("secretTokenInput").value = "$blog_title";
</script>
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.
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.
If you want to support trackbacks, copy contrib/plugins/comments/plugins/trackback.py to your plugins directory. Then add "trackback" to the load_plugins property in your config.py 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="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:trackback="http://madskills.com/public/xml/rss/module/trackback/">
<rdf:Description
about="$base_url/$file_path"
dc:title="$title"
dc:identifier="$base_url/$file_path"
trackback:ping="$base_url/trackback/$file_path"
/>
</rdf: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.
If you want to support pingbacks, copy contrib/plugins/comments/plugins/xmlrpc_pingback.py and contrib/xmlrpc_plugins/xmlrpc.py to your plugins directory. Make sure you have the base_url property defined in your config.py file. Then add "xmlrpc_pingback" to the load_plugins property in your config.py 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="http://joe.com/RPC" />
Replace joe.com with your baseurl.
FIXME - this text probably needs fixing.
If you want to support CommentAPI, copy contrib/plugins/comments/plugins/commentAPI.py 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 comments.py 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:
xmlns:wfw="http://wellformedweb.org/CommentAPI"
Then inside your RSS items you need to add a wfw:comment element:
<wfw:comment>###commentAPI###/$file_path</wfw:comment>
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