Simple Comments Release Notes: v.910 (1/2)

[next]

Simple Comments Release Notes: v.910

By Dan Ragle

[This is a release bulletin for the Simple Comments script. For general information pertaining to the script, including the latest release download, system requirements, etc., visit the Simple Comments main page.]

Version .910 of Simple Comments adds a few new features to the system, as well as squashing several bugs. In true WebReference fashion, we'll briefly examine these new changes to the script and then provide a bit of detail as to some of the more interesting technical shenanigans that went into the creation of this version.

New Features

The biggest single new feature is the implementation of site section support--or the ability to divide your site into sections such that each section can have its own unique look and feel and be administrated by a separate person. To accomplish this, we've added support for a <section> element in the configuration file; within which you can define <prefix> elements that specify what areas of the site this section encompasses (by the URL prefix). For example, the following block defines a Programming section, which will be represented by all pages beneath the top level programming, coding, and scripting directories:

<section name="Programming">
   <prefix>/programming/</prefix>
   <prefix>/coding/</prefix>
   <prefix>/scripting/</prefix>
</section>

In addition, with a few exceptions you can also add any of the other configuration parameters within a section definition, and those parameters will take precedence whenever you work with (or the user views) comments on pages within that section. This allows you to set templates (including the template directory, so you can point to a whole new collection of templates in each section - if you like), administrators (via admin_user settings), and other parameter assignments on a per-section basis. More detail on the new section capabilities can be found in the readme.txt that is in the download distribution file.

Other key new features in this release include:

1. Direct Support for Administrator Authentication

   It's no longer required (though it is still recommended) that you place the administrator script within a password protected area of your Web site. If you place the administrator script within a public area of your site, the script will implement a direct user authentication scheme (the script itself will prompt you for your user name and password, which you can initially define and set up in the new users.xml, described in the readme.txt). This scheme requires that you have cookies enabled in your browser; and once you initially authenticate to the script, a cookie is created that stores an MD5 hashed version of your password so that later accesses to the script are automatically authenticated using it.

   Please note, however, that unless you access the administrator script via an SSL protected server, your initial password and the MD5 hashed version will be transmitted back and forth between your server and browser in plain text; anyone with access to the data stream between you and the server and a packet sniffer will be able to detect it. If you can place your administration script on an SSL secured server, that would be the best solution; but if not, be aware that your password and/or its encoded version may be readable by bad guys (so don't use the same password that you use to access your bank account or corporate servers, for example).

   On a side note, Basic Apache Authentication is not much, if any, better than this scheme; since the password itself is provided by the browser in plain text when sent to any Apache page that is protected via Basic Authentication. This password is encoded so it can be safely transported via TCP even if it has unusual characters; but it's not encrypted--the plain text password can therefore be easily decoded and read from the HTTP headers. This is why we recommend that you use an SSL server for the administration script, if at all possible (and for that matter, any application that requires the confidential transmission of information). If an SSL server isn't available, then be sure to select passwords for use in the administration script that are not the same as those that you may be using for other, more sensitive applications.

   The required steps to setup Simple Comments for user authentication are provided in the readme.txt file within the comments.zip distribution.

2. Administrator Rights Assignments by Function

   You can now assign specific rights to each administrator based on the available functions of the administrator script. For example, one administrator may be assigned the right to review and edit comments, while another can only modify the system's HTML templates.

3. Immediate Publishing

   Submitted comments can now be set to be published to the page immediately, without requiring administrator approval. If you elect to use this option, be forewarned that Simple Comments does not yet have any type of content filtering (i.e., for profanity or vulgarities, for example), so users will be able to post whatever they wish to your site! The script will still default to requiring administrator approval for submitted comments before they will be allowed to be displayed on pages.

4. Reverse Comment Sorting

   An option is now available allowing comments to be displayed on each page in standard (oldest to newest) or reverse (newest to oldest) order.

5. Date Time Formatting

   You now have basic control over how the date and time of the comments are displayed on your pages.

6. Additional Display Parameters

   The comment display template now includes the edit date, edited by, published date, and approved by parameters; these can therefore now be incorporated within your comment displays.

Bug Fixes

Several bugs were corrected in this version of Simple Comments. For a full list view the CHANGES.txt file in the zipped distribution; but some of the more critical fixes include:

• Allow multiple admin users to be defined in the configuration file. Though documented as such, the initial Simple Comments release won't allow you to do this.

• Allow deletion of comments after they've been approved. Previously, you could only delete a comment while it was waiting to be published, but not after.

• When entering comments with included <pre> blocks, the user's intended white-space formatting within the code was not always honored; some white space would inadvertantly be stripped from within the <pre>...</pre> tags.

• Force use of XML::Parser in XML::Simple to avoid mis-encoded attributes.

That last bug deserves a little more attention. You may recall from our initial release notes that I use the XML::Simple Perl module to both read in our configuration data and read and store the actual user comments themselves. XML::Simple will hand off the actual XML parsing tasks to either XML::Parser or the XML::SAX designated parser, giving preference to XML::SAX if it's available. What was not immediately apparent, however, is that (at least in some configurations) XML::SAX will not return exactly the same data as XML::Parser does where attribute values and character entities are concerned. You can force XML::Simple to use XML::Parser if you want; but since I didn't realize they might report different results, I didn't think this was necessary.

As an example of the problem, consider the following code:

use strict;
use XML::Simple;
# first read: Force XML::Parser
$XML::Simple::PREFERRED_PARSER = 'XML::Parser';
my $config = XMLin('<opt thetag="Beth &amp; Dan" />');
print $config->{'thetag'}, "\n";  # prints Beth & Dan
# now allow XML::SAX
$XML::Simple::PREFERRED_PARSER = undef;
$config = XMLin('<opt thetag="Beth &amp; Dan" />');
print $config->{'thetag'}, "\n";  # prints Beth &amp; Dan

When run on one of our servers with XML::SAX installed, the two print outs were as displayed above--they were not identical even though the XML input was. Since, in one case the entities are being replaced with their corresponding characters and in the other case they aren't, the Simple Comments script would make the wrong assumptions concerning character entities whenever XML::SAX was actually used on the servers. None of the servers I initially tested on had XML::SAX installed, so I never saw the problem in the first Simple Comments release! i.e., the sample code above produces the same output for both print statements on a server that doesn't have XML::SAX installed. Therefore, for the most consistent results with whatever parser you may actually have on your system, I now force XML::Simple to use XML::Parser, or nothing.

Besides this XML parsing problem that made it through to our first release, I also encountered several interesting developmental issues when working on the newer features for this version of the script. Continue to the next page to hear more about configuration file caching for mod_perl scenarios and the magical--and seemingly unpredictable--appearance of SWASHNEW errors...

[next]

Created: September 13, 2006
Revised: September 13, 2006

URL: https://webreference.com/programming/perl/comments/v.910/index.html