home / programming / perl / simple comments

Simple Comments

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

Developer News

Microsoft Shows Off Silverlight 4, IE9 Plans

Metasploit Expands Vulnerability Test Framework

HyperCard Reborn?

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

78. Dan Ragle
Admin
06/26/2008 03:51PM

39 total posts | view profile

*sigh* That's another bug.

The way it was supposed to work was that yes, the user could log in prior to confirmation (only if you have require_registration_approval set to 0); but they couldn't actually do anything as both view_profile and comment submissions were supposed to be blocked for the user. In retrospect it looks like view profile is behaving correctly (it just acts like the user doesn't exist) but comment submissions are allowed which is a definite error. I'll get that cleaned up in .960.

In the mean time, if you wanted to prevent comment submissions from unconfirmed users you could just make this mod in Comments.pm:

if (($visitor->status eq 'blocked') ||
         ($visitor->status eq 'deleted')) {
   return 'Sorry, this account has been ' . $visitor->status .
          '. Please contact our administrator for assistance.';
}
elsif ($visitor->status eq 'new') {
   return 'Sorry, this account has not yet been confirmed.';
}

If you wanted to prevent them from logging in entirely, you could make mods to check_login in comments.pl; but you'd have to make several adjustments there.

79. david
06/26/2008 09:07PM

Dan, thanks again. I would suggest, if you are working on this, to disallow logging in if not active. This is because the visitor might not realize the need to activate until much later if they don't immediately comment. They log in just to ensure they are properly registered. By then the email for activation might have been lost. Another possibility is wrongly typed but valid email addresses. Registration goes through (they can log in) but they cannot find the activation email.

Preventing these visitors from commenting is not a big deal - for some reason your program thinks they are not logged in and so the comments need my OK. I have publish on submit=0 and publish visitor comments on submit=1. This was how I caught the bug BTW. My main concern right now is that the system does not weed out wrongly typed but valid/spurious email addresses. Correcting these later is messy.

72. Dan Ragle
Admin
06/20/2008 05:33PM

39 total posts | view profile

Hi nicku,

Do I understand you correctly in that you do not want visitor registrations (per se), you just want to force all submitters to pass through your Apache-based authentication prior to allowing comment submissions?

Short of editing the code I can't think of a graceful solution. You would have to post two separate copies of the script, as you suggest, but if you only do that you would not stop the bad guys from submitting comments (from their own manually crafted forms) to the public copy of comments.pl (and they could probably find where it was easy enough; since various actions--such as RSS feeds--require it to be hit directly).

So you would probably want to additionally make some slight modifications to the public version of the comments.pl, to make sure that only logged in users could submit comments. One idea that comes to mind is to just de-list the add, review, and submit actions; i.e., change this:

my @all_actions      = qw(add display review submit clear rss);

to this:

my @all_actions      = qw(display rss);

That's untested, but it should work. Unfortunately it will also disable user registrations in the public copy of the script; but if I'm reading you right you won't need those, anyways.

The other trick is that you will need to adjust the comment submission form so that it points literally to the private copy of comments.pl; otherwise it will pull the location of the comments script from the config file (which you should have set to the public comments.pl) and therefore won't actually allow any comment submissions!

Good luck!

74. Dan Ragle
Admin
06/23/2008 09:38AM

39 total posts | view profile

Great, nicku, glad it's working for you. And thanks for the heads up on get_article_name, I hadn't considered multi-line titles. I should be able to get that fix added to the next release.

For now, I'd prefer you just link back to this site for the attribution, as opposed to posting your own version, if you don't mind. As you can tell, we haven't really settled on a license scheme for the code yet, so I don't think it would be appropriate to post a GPL version somewhere else. I have nothing against the GPL, but this code belongs to my employer, and as such I cannot make any forward-looking promises pertaining to future licensing.

Of course, if and when there is any change or concrete forward direction on licensing, I'll post it up here so that everybody will have the scoop.

66. Dan Ragle
Admin
05/27/2008 09:51AM

39 total posts | view profile

The RSS file is produced in the same way that the in-page comments are; they're just outputted in a different format (and the content-type is set accordingly). So in terms of the juice it takes to create the file, it should be the same as it would be to display them within a page.

As far as creating a "global" recent comments RSS feed, I can't think of any built-in way to accomplish it, so you're method sounds like a reasonable approach. I think the way I would hack it in, though, is:

- Create a "dummy" page on your site that has a title descriptive of the global comments content (i.e., this title will be used in the resulting RSS file). You can always put this in a password protected area of the site, if you don't want people to find it (they don't have to have access to it, since it's just serving as a locatable container for the comments system).

- Adjust the write_live_comment routine in Comments.pm to write the comment (exactly as is) to both the original target file, and to this dummy file. I.E., right after this code:

      seek $livefile, 0, 0;
      print $livefile $live_comments;
      truncate ($livefile, tell $livefile);
      close $livefile;

add the code to open the dummy file's XML, read in the contents, push the new comment onto the stack, sort the stack, and write the result. All the necessary logic for that is already in write_live_comment, you would just need to piece it together to duplicate the work for the dummy file, instead. You wouldn't need to duplicate all the logic to for duplicate checking, or writing the comment to the user profile, etc. I like putting the adjustment in write_live_comments because that way you should get all of 'em; whether they were moderated, posted directly from the user, or admin replies.

- Adjust the RSS print routine in comments.pl to rewrite the feed link (in the comment loop) such that it is built individually per comment. Currently, it assumes the link to be provided for all comments is the same (differentiated only by comment number), since the current routine assumes that all the comments in a file--and thus an RSS feed--belong to the same article. Without this adjustment, all the links in the global RSS feed would point to the dummy file, instead of to their actual files.

Then you can "publish" the article file by just posting a link to comments.pl passing the action type of rss and the article key of your dummy file (see any existing RSS link on your site for the correct format). I think. From looking through it this morning I believe that's all you would need to do, but of course you'd have to test it out to be sure.

Of course, this will double your disk space; but the alternative of reading the files individually when the RSS file is built isn't pretty response-wise (that WOULD take a lot of time).

There are other issues with this that you might need to address depending on how thorough you want to be; such as tweaking the delete and edit routines in the maintenance screens to delete the matching comments in the dummy XML file, too; and/or somehow automatically cleaning the dummy XML file from time to time (since it will accumulate a copy of all comments in the system).

Good luck!