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

Simple Comments Release Notes: v.910

[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:

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:

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.

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.

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.

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.

Date Time Formatting

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

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.

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