Simple Comments: A Basic Perl-Based Comment System for Static Web Pages

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.

Features

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

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.

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:

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:

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.

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

38 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!

100. Jonathan
11/27/2008 10:37PM

Yes, the Akismet API is free to use. I'd personally prefer a locally-installed boolean filter, but since it would take time to learn, using an already-running system such as Akismet is better, I think.

You've a good point about spamming the system with someone else's email address. That's a good idea placing it within the registration form.

And the idea that a forced Review blocks spam came from Textpattern. That system requires a preview before submission, and spam on Textpattern blogs is usually considerably less than on, say, WordPress.

People whose blogs I've read who use the Akismet plugin on both systems have noticed spam volumes coming through the Akismet plugin sometimes many hundreds of times higher on the WordPress system than on the Textpattern system. And the only difference in the comment form is the forced preview. May be fuzzy logic, though.

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

38 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

38 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

38 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

38 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

38 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.

next comments

home / programming / perl / simple comments

Simple Comments

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

Contents:

Features

Requirements

Test Page

Downloads

Setting Up Simple Comments

Release Notes

home / programming / perl / simple comments

Whitepapers and eBooks

Webcasts

Downloads and eKits

Tutorials and Demos