======== Comments ======== :Author: PyBlosxom Development Team :Version: $Id: 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. Summary ======= 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! .. _contributed plugins pack: http://sourceforge.net/project/showfiles.php?group_id=67445&package_id=145140 .. _from SVN: http://pyblosxom.svn.sourceforge.net/viewvc/pyblosxom/trunk/contrib/plugins/comments/ The comments plugin also has a `README file`_ that has more information on installing comments, traceback, pingback, and the comment API. .. _README file: http://pyblosxom.svn.sourceforge.net/viewvc/*checkout*/pyblosxom/trunk/contrib/plugins/comments/README Installing the comments plugin ============================== Requirements: * A directory the web-server has writable permissions to. After making sure you have the requirements, do the following: 1. Copy ``contrib/plugins/comments/plugins/comments.py`` to your plugins directory. Then add ``"comments"`` to the ``load_plugins`` property in your ``config.py`` 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 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 ============================ =============================================================== 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 ``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" Problems you might have ----------------------- FIXME Writing comments plugin templates ================================= This "diagram" shows which templates are responsible for what for rendering a single entry::
<- story.html

$title

|
| ... |
| links |
<-
<- comment-story.html
<- comment.html Posted by $blah at $blah | $blah |
<-
<- comment.html Posted by $blah at $blah | $blah |
<-
<- comment-form.html form stuff here. |
|
<- 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: http://en.wikipedia.org/wiki/Ajax_(programming) 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. Enabling -------- 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::

Add an ``onsubmit`` handler to the ``form`` tag::

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. ) .. _cgiwrap: http://cgiwrap.sourceforge.net/ Next, add ``onclick`` handlers to the button ``input`` tags:: Finally, include this ``script`` tag somewhere after the ``form`` closing tag:: The separate closing ``</script>`` tag is necessary for IE. Without it, IE won't actually run the code in ``comments.js``. Disabling --------- 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: http://akismet.com/ akismetcomments --------------- `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". .. _WordPress: http://wordpress.com/ .. _Automattic: http://automattic.com/ 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 Wordpress.com API key`_. .. _sign up for a Wordpress.com API key: http://faq.wordpress.com/2005/10/19/api-key/ After you have your API key, copy ``akismetcomments.py`` and ``akismet.py`` to your plugin directory. Add an ``akismet_api_key`` config variable with to your API key to your ``config.py``. Also, make sure the ``baseurl`` config variable is defined:: py['baseurl'] = "joe.com" 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 ``api-key.rest.akismet.com``. 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`_. .. _Benjamin 'Mako' Hill: http://mako.cc/ .. _Blake Winton: http://bwinton.latte.ca/ check_javascript ---------------- 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:: ...
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`_. .. _Ryan Barrett: http://snarfed.org/ 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/trackback.py`` to your plugins directory. Then add ``"trackback"`` to the ``load_plugins`` property in your ``config.py`` file. .. _trackbacks: http://www.sixapart.com/pronet/docs/trackback_spec 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:: TB The ``/trackback`` URL prefix is configurable with the ``trackback_urltrigger`` config variable. You can supply an embedded RDF description of the trackback ping:: 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/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. .. _pingbacks: http://www.hixie.ch/specs/pingback/pingback You'll need to advertise a pingback link in your ``head`` template. Add the following tag to the ``meta`` section:: Replace ``joe.com`` with your ``baseurl``. Installing the CommentAPI ========================= 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. .. _CommentAPI: http://wellformedweb.org/story/9 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:: ###commentAPI###/$file_path 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