======== Comments ======== This chapter briefly walks you through installing the comments, trackback, pingback, and CommentAPI plugins. FIXME - September 27th, 2009 - This needs to be updated. Srsly. Summary ======= PyBlosxom does not come with comments functionality built-in. There are several ways you can add comments functionality to your blog. This chapter talks about those. Disqus ====== Disqus is a comments platform web service that allows you to add comments to your blog. Pros: * it's easy to install * it handles spam for you * supports notifications and replies Cons: * it's a web-service that you have no control over * it might be difficult to move your comments over to a new system If this is interesting to you, `sign up for a Disqus account`_. .. _sign up for a Disqus account: http://disqus.com/ Writing your own comments plugin ================================ PyBlosxom allows for plugins allowing you to write a plugin to add comments to your website. This isn't for the feint of heart--there are a lot of bits to think about. Pros: * you're in complete control over how comments work on your site Cons: * not for the feint of heart Comments plugin =============== There's a comments plugin that many PyBlosxom users use and which is sort of supported, but needs a lot of work. Pros: * it's entirely in your control * you can extend and modify it to meet your needs * a lot of PyBlosxom users use it Cons: * many people find it difficult to install * it's missing common comment system features like replies, threads, ... * you have to implement and maintain your own anti-spam measures * it hasn't been well maintained in the last couple of years The comments plugin comes in the ``.tar.gz`` file alongside PyBlosxom as of PyBlosxom 1.5. Prior to that, you can get the latest stable version of the comments plugin from the `contributed plugins pack`_. Alternatively, you can get the latest version `from Git`_, which is even more recent but may be broken. Caveat hacker! .. _contributed plugins pack: http://pyblosxom.bluesock.org/download/ .. _from Git: http://gitorious.org/pyblosxom/pyblosxom/trees/master/plugins/comments .. Note:: The comments plugin also has a `README file`_ that has more information on installing comments, traceback, pingback, and the comment API. .. _README file: http://gitorious.org/pyblosxom/pyblosxom/blobs/master/plugins/comments/README Installing the comments plugin ------------------------------ Requirements: 1. A directory the web-server has writable permissions to. 2. Time and patience. After making sure you have the requirements, do the following: 1. Copy ``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``. For example:: video_audio_podcast_enhancements_in_firefox_3-1244176234.0.cmt 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 PyBlosxom however you have it installed. 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 ``plugins/comments/flavours`` directory to the appropriate places alongside your flavour files. ``comment-story`` template is used to format a single entry that has comments. ``comment`` template is used to format a single comment/trackback/pingback. ``comment-form`` template provides the form used to enter new comments. 4. Edit the ``comment-story``, ``comment``, and ``comment-form`` templates if you need to. 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 ------------------ 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" Writing comments plugin templates --------------------------------- This "diagram" shows which templates are responsible for what for rendering a single entry::