home / programming / perl / simple comments

Simple Comments

A basic, Perl-based comment system for static Web pages

Developer News

Mandrake Linux Founder Back, Virtually

Amazon: We're a Technology Company

Sun Expands MySQL With Closed Source

By Dan Ragle

Current release: v.962
Release date: July 29, 2008
Download

On this page is a collection of information pertaining to WebRef's Simple Comments Perl script that allows you to implement a basic comment posting system on the static pages of your Web site. Here you'll find the latest Simple Comments zipped distribution file, a link to the latest changelog (included in the distribution), basic features and requirements of the system, links to the individual release notes, and whatever else I can think of. To get started with Simple Comments, I recommend that you read this page in its entirety. While not mandatory, the release notes for the versions also provide some potentially helpful bits of information--especially from a developer's perspective--and may be beneficial both from an implementation and an educational perspective, i.e., even if you aren't interested in using the Simple Comments script, you may be interested in reading some of the developmental issues I've encountered while developing it; points that are elaborated upon in the release notes.

Contents:: Features; Requirements; Test Page; Downloads; Setup; Release Notes

Features

The key features and capabilities of the most recent version of Simple Comments include:

Template-based design: You can craft the HTML output by the scripts by adjusting template files separately from the Perl code.
Optional Visitor Registration: At the discrection of the administrator, visitors can register on the site and fill in basic information to be displayed on their profile pages. Administrators can force all visitors to register in order to submit comments, elect to simultaneously accept comments from both registered and unregistered visitors, or disable the visitor registration system entirely via configuration parameters. The administrator can also configure the system to force all display names to be unique; in which case visitors can login with their display names, as well (default is to login using their E-mail address).
OpenID Support: For those implementations that do support visitor registrations, site visitors can login using their OpenIDs. This feature can be enabled or disabled when deploying the script (default is enabled).
Basic HTML support: A few unadorned HTML tags are supported in comments; including bold text (<b></b>), italicized text (<i></i>),
```
pre-formatted text
```
(<pre></pre>), and links (<a href="blah"></a>). All other HTML tags will be converted to a literal representation. This feature can also be disabled so that no HTML tags are allowed.
Separate administration: By default, Simple Comments requires that all comments submitted by users must be approved by an administrator before they're displayed on the site; the approval process itself is performed by a separate script from the display script, so it can be snugly tucked behind a password and SSL protected area of your site. You may also configure Simple Comments to allow user submitted comments to be displayed on the site immediately, without requiring administrator approval (but be warned: Simple Comments doesn't perform any automated content filtering on submitted comments). The administration script also allows you to search for and edit existing comments and visitor profiles (if the system is configured to accept visitor registrations).
Article locking: Articles can be locked (I.E., comment submissions blocked) either automatically based on the age of the article in days, or as needed by the administrator.
Simple inclusion: Once the system is set up, you can enable comments on a Web page by adding a single Server Side Include directive to the page.
Comments-per-page option: Support for an administrator-defined number of comments displayed on each page (the display template can include "next" and "previous" links - allows the user to redisplay the selected Web page with the next or previous comments in the list).
Support for Site Sections: You can configure separate areas of your site to be maintained by separate administrators; each site section can also have its own look and feel.
Granular Administration Rights: Individual administrators can have separate access rights to the administration script. For example, one administrator might only be able to modify templates, while another can only approve and edit comments.
Reply to capabilities and threaded displays: You can display your comments via a threaded display, in which replies are displayed beneath the original comment that triggered the reply. Each level of reply receives an identifier so you can apply separate template-based styling to each level of reply.
Support for CAPTCHA authentication: via integration with the captchas.net or reCAPTCHA system (administrator configurable)
Support for RSS formatted comment feeds
Flat File Data Storage: A separate database application setup is unnecessary; approved (published) comments and visitor profiles are stored in XML files.
Support for mod_perl: Simple Comments can be run in a mod_perl environment.

Requirements

To set up and use this system, you'll need Perl 5.6 or later installed on your server, the Apache Web Server with executable includes enabled (the ability to execute a Perl script when called in the HTML file as an include, see the setup instructions) access rights to create a directory outside the Web server's document root on your server, and access to place scripts into your cgi-bin. Basic Perl savvy and comfort in tossing files around on your Web server (as well as setting their access rights) will also be needed.

Though optional (beginning with .910), access to a password protected area (via Apache access controls) within your cgi-bin is also recommended; preferably reachable via an SSL server.

You will also need the following Perl modules installed on your system:

CGI
XML::Simple (and XML::Parser)
HTML::Entities
HTML::Template
POSIX
URI
URI::Escape
Fcntl
LWP::UserAgent
Digest::MD5
Time::Local
MIME::Base64

All but the HTML::Template module are typically installed with your Perl distribution; HTML::Template (and any others that may be missing) you can pick up from CPAN. XML::Simple is sometimes missing; if so, you may need to install both XML::Simple and XML::Parser (which XML::Simple relies on).

The following modules are recommended for use with OpenIDs (i.e., if openid_enabled is set to 1), and may in fact be required for use with some OpenID providers:

Math::BigInt
Math::BigInt::GMP
Digest::SHA

To use CAPTCHAs in your comment submission form, you need to decide whether you prefer to use the captchas.net system (see http://captchas.net) or the recaptcha system from Carnegie Mellon University (see http://recaptcha.net). If you select the captchas.net system, then you must first register with and receive a user-id and shared secret from http://captchas.net. If you select the recpatcha system, then register on the http://recaptcha.net site. Registration for both systems is free as of this writing; though both request that you warn them if your usage will be somewhat high (50k+ hits a day for captchas.net, or 100k+ hits a day for recaptcha.net). Once you've registered, you can then enable CAPTCHAS by including the appropriate _captcha and/or recaptcha_ parameter settings in the config.xml file.

To enable administrator notifications (the notify_admin_on_submit and notify_admin_on_visitor_confirm options) the Web user account (the account used by the Web server to perform system operations) must have access to sendmail. Additionally, sendmail access is required to enable the visitor registration system, since non-OpenID visitors are required to confirm their E-mail addresses as part of the registration process.

The comments script will work in both a standard and mod_perl enabled Web server.

Test Page

Want to submit a test comment? On most pages of our site (including this one) we'll only publish comments that actually pertain to the article, so you can't enter stuff like test comment or hello world. On our Test Page, however, we'll let you get away with those types of comments.

The test page also shows you what the comment display templates look like "out-of-the-box," i.e., the comments are displayed on the test page with the same templates in the Simple Comments distribution file (for the comments that appear on other pages of our site, we've modified the templates to match the WebRef look and feel). You can access the test page by clicking on the following link:

Simple Comments Test Page

Downloads

You can download the latest version of Simple Comments by clicking this link: comments.zip. The download is provided as a zipped file; use your favorite extractor to unzip it.

To view a list of changes from version to version, read the CHANGES.txt file.

Setting Up Simple Comments

Refer to the Readme.txt, included in the Zip distribution, for setup instructions.

Release Notes

These articles contain notes pertaining to each individual release of Simple Comments. Developers who are learning Perl may find these release notes of interest. The first release article (v.902) includes much of the information on this page, and also discusses the basic architecture of the scripts. Later release articles focus on new features, documentation of fixed bugs, and/or technical points of interest within the new release itself.

User Comments

Submit | Register | Login

99. Dan Ragle
Admin
11/20/2008 01:22PM

36 total posts | view profile

Hi Jonathan,

Feature requests are welcome, though admittedly slow going these days as I haven't had an abundance of time to work on this project. Akismet has been mentioned before (as has mollum.com) and probably deserves another look. Do you know if Akismet offers any free-level of service for their product? As I recall that was the main reason I shyed away from them initially, I don't remember seeing any free service levels. I think E-mails have also been suggested in the past; but one of the potential problems there is spam-abuse (i.e., a person could submit using their "buddy's" E-mail and then subscribe them to all posts from the article). So, I would probably have to tie the E-mail subscription into the user-registration features (at least that way the user has to confirm their E-mail address before they can subscribe). Worth looking into, but again, I don't foresee any quick implementations.

As far as forcing a preview, I'm not sure what you're getting at there. You could theoretically just remove the "Add" button from the submission form, and then alter the Review template to include a copy of the submission form WITH the "Add" button. But ultimately, that won't stop bots; which are smart enough to figure those types of things out, anyway. Or perhaps I've mis-understood your request?

Cheers!

95. Dan Ragle
09/26/2008 09:43AM

36 total posts | view profile

Hi Vladas,

That's probably coming from the CGI module; i.e., the CGI header function will default to ISO-8859-1 unless told otherwise.

If you're having this trouble with Simple Comments, you should be able to rectify it by finding the header calls and adding the optional charset parameter to them; i.e.,

$cgi->header(-charset => 'utf-8');

$cgi->header(-cookie => $cookie_data,
             -charset => 'utf-8');

etc. Unfortunately, there are many of them to change; since I had to add in multiple potential exit points in the OpenID logic. I'll look at making that a configuration option in a future version of the script.

Theoretically, you should also be able to add a META HTTP-EQUIV in your page output; but I think I would personally rather see it directly in the header, too.

And if you're having trouble in one of your own projects, I can only recommend finding the header() function for your CGI output and adjusting accordingly.

Best of luck!

97. Dan Ragle
Admin
09/29/2008 10:34AM

36 total posts | view profile

utf-8 support

Hi Vladas,

The script is admittedly lacking when it comes to utf-8 support. Part of that is the result of my own shortcomings in regards to utf-8 knowledge; the other is knowing that Perl 5.6--which I wanted to make sure I supported--was itself not completely solid in regards to utf-8 support. So, I have no doubt you will run into utf-8 related problems. I would like to go back through and add in more thorough support for utf-8 at some point in the future, but can't say for certain when that will be.

In the mean time, the problem you mention with the article names is most likely the result of some HTML entity encoding that in retrospect probably isn't necessary. At least the angle brackets need to be encoded, but other things probably do not. In Comments.pm, find the get_article_name function, and change this:

HTML::Entities::encode_entities($title,"\200-\377<>");

to this:

HTML::Entities::encode_entities($title,"<>");

If that doesn't work, and you're running perl 5.8 or later, you might also try forcing the HTML file found to be read in as utf-8; i.e.:

open (my $fh, '<:utf8', $config->{'webroot'} . $title)

This, of course, assumes that the file is originally encoded in utf-8; if not, you may need to force the encoding to be whatever the file actually is. If you're running Perl 5.8, then I believe Perl will internally translate the read-in input to utf-8; but it still needs to know for certain what the file was encoded in in the first place to know how to perform the translation.

Good luck!

93. Dan Ragle
09/22/2008 05:02PM

36 total posts | view profile

Hi david,

1.) Yes, display names can now be forced to be unique. See the new unique_display_names parameter in the config file. So you should no longer need the custom code.

Also note that when you upgrade, you'll need to create the initial xref file--there's an option to do that in the admin script.

See the "Support for Unique Display Names" section in the release notes.

2.) The catch-all hack you're using should still work, I can't think of any reason it wouldn't (but I never actually tried it myself, so....)

3.) Most if not all the templates changed; but many of the changes were the result of adding standard includes for the headers/footers of pages (actually three includes are used). Again, see the release notes for more.

The CHANGES.txt file lists all the files that changed, and it differentiates between those that were changed only to support the new header/footer construct vs. those that were changed to support new functionality. I know it's a pain, but you'd pretty much have to compare what's there to what you have to determine if a change is necessary to your templates.

And of course the CHANGES.txt also lists all the config parameter additions and new template additions as well.

Good luck!

83. thomas
08/28/2008 01:43AM

issue installing

Hi Dan,

I'm having a bit of difficulty installing your perl script. perhaps you have come across this already and know the answer.

The comments script comes up and apears to work. I can Review what I've entered. however when I use the Add, button the page goes blank. teh status indicator at the bottom of the page indicates 'done'.

Bringing up the admin page seems to come up. however there are no comments to approve.

I'd assumed I had a file permission error or something but a double check seemed to indiate all is well.

also... the instructiosn indicate the "waiting_file.xml" should have a permision of RW, however this is not one of the files copied across from the zip file. I simply "touched" the file and set it up as indcated.

Thank you
Thomas

84. Dan Ragle
Admin
08/28/2008 11:26AM

36 total posts | view profile

Hi Thomas, thanks for giving the script a try, and sorry it's giving you trouble.

Do you have access to your server's error log? There's more than likely an indication there of the source of the problem. I just downloaded the .962 distribution and did a fresh install to make sure it's kosher, and it seems fine. Note the "waiting_file.xml" is a typo; it should be "waiting_comments.xml" (it's referred to correctly elsewhere in the docs; but is incorrect in the rights section). The system doesn't actually use "waiting_file.xml" (unless you've directly specified it as such in the config file). But note that that should not be the ultimate cause of the problem; since Simple Comments will actually create that file if it's missing, anyways.

Is it just the add button that's a problem? I.E., are all the other screens working fine (for example, can you review the comment prior to adding it)? If so, then the template mechanism itself must be fine. And since you're not getting the comment actually written to the file (it's not showing on the article or in the admin screen), that narrows the problem down even further.

Are you using the templates as shipped in the distribution (i.e., have you made any mods to the .tmpl files)?

My knee-jerk guess would be a problem with the submit log. Check the submit_log setting in your config file, and make sure it points either to an existing file that the Web user has read/write access to; or to a directory that the Web user has read/write access to (so that it can create the file if necessary). As a test, you could also just turn off the submit threshold entirely by setting submit_threshold to 0 in the config file (or clearing the submit_log setting entirely).

If you're still having trouble, then the easiest way to troubleshoot is to get access to that Web server error log. Let me know if you can get to it, and what error is being displayed.

Good luck!

87. Dan Ragle
Admin
08/29/2008 11:38AM

36 total posts | view profile

Hmmmmm... both problems would seem to be access related; i.e., the script is fine as long as it only needs to read data, but as soon as it tries to write something you get errors. Once you set the submit_threshold to 0 you bypassed the first file write, but the promptly received an error with the next write (which would have been to waiting_comments.xml).

Are you sure the Web server's effective UID is what you think it is? Try dropping this script in your cgi-bin and then hitting it through your server:

#!/usr/bin/perl -T

use strict;
use warnings;
use CGI ();

my $cgi = CGI->new();
print $cgi->header();

print '<h2>Real User: ', (getpwuid($<))[0], '</h2>', "\n";
print '<h2>Real Group ID(s): ', $(, '</h2>', "\n";
my $groupnames = join(', ', map { (getgrgid($_))[0] } (split(' ', $()));
print '<h2>Real Group(s): ', $groupnames, '</h2>', "\n";

print '<h2>Effective User: ', (getpwuid($>))[0], '</h2>', "\n";
print '<h2>Effective Group ID(s): ', $), '</h2>', "\n";
$groupnames = join(', ', map { (getgrgid($_))[0] } (split(' ', $))));
print '<h2>Effective Group(s): ', $groupnames, '</h2>', "\n";

Be sure to adjust the Perl path and executable rights, of course.

One other thing to try: On one of my systems here I seemed to be unable to access files in directories unless the directories were both readable and executable by everybody. So, you may need to mark your individual directories read/executable by owner, group, and others to be able to get to their files. You can always mark the individual files within the directories more strictly as necessary. Something else to try.