Simple Comments Release Notes: v.960 (1/3)

[next]

Simple Comments Release Notes: v.960

By Dan Ragle

Digg This Add to del.icio.us

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

Chock full of new features and fixes--many requested by readers--my Simple Comments script returns for a major release. As always, I'll review the new features of the script in this and the forthcoming release bulletin, with a special emphasis on the development-related issues that surfaced during its creation. And so, without further ado...

Simple Comments Supports OpenID

By far, the number one change in this release of Simple Comments is support for OpenID. We'll examine this topic extensively in the pages that follow (the majority of this release bulletin will focus on OpenID related topics), but for now note that v.960 of Simple Comments allows users to login and create a visitor account using an OpenID identifier, as well as associate an OpenID with an existing (already registered) visitor account (so they can login using their OpenID on future visits). Our OpenID implementation follows the OpenID 2.0 specs (for the most part; I'll detail the differences I know of in Part II of these release notes), and also supports white/black lists for OpenID providers (so you can allow only those OpenID providers you know, or block known bad guy providers). As is the case with most Simple Comments features, you can enable or disable OpenID support by toggling a single configuration parameter.

Article Locking and Other Enhancements

While OpenID was the biggest change to Simple Comments (both in terms of new functionality and the size of the raw code), it wasn't the only one. Other enhancements in this new version of the script include:

• HTML Header/Footer Templates. The default set of templates provided with Simple Comments now includes header and footer templates, allowing you to implement major changes to the look and feel of the system by tweaking just a few templates. In fact, three include-templates are now provided: The HTML Header (html_header.tmpl) includes everything up to the <title>...</title> of the page; the Page Header (page_header.tmpl) includes everything from beneath the <title>...</title> to where you want the script results to be displayed and the HTML Footer (html_footer.tmpl) includes everything from the end of the script results through the bottom of the page. By using three includes, you're still free to set the title of each page per your liking, and insert page-specific code both in the head and the body of the resulting document.

  The base templates provided with the Simple Comments script have been modified to use these includes, at least those that display full HTML pages as a result. (Some templates--such as the comment display itself--are intended to be included within another HTML page; these "snippet" templates do not, of course, use the header/footer includes.) For example, here's a look at the new add_error.tmpl:

  <TMPL_INCLUDE NAME="html_header.tmpl">
     <title>Oops! Can't submit comment for: <TMPL_VAR NAME="article_name"></title>
  <TMPL_INCLUDE NAME="page_header.tmpl">
     <h1>Error in Comment Processing</h1>
     <p>We're sorry, but due to unforseen circumstances, we are unable to 
        process your comment. The problem may be temporary; you may wish 
        to just try again.</p>
     <p>If the problem persists, please bring the error message below to our 
        comment administrator's attention: <TMPL_VAR NAME="admin_name">, 
       (<TMPL_VAR NAME="from_email">)</p>
     <p class="error"><TMPL_VAR NAME="error_message"></p>
     <p>For your records, here's the comment you were trying to post. You 
        should keep your own copy of it (we don't have a copy at this point)
        so you can resubmit it once we get the bug worked out.</p>
     <TMPL_INCLUDE NAME="submit_form.tmpl">
  <TMPL_INCLUDE NAME="html_footer.tmpl">

  As you can see, the included header and footer includes enable you to change the look and feel of each page in a major way by just adjusting the html_header, page_header and html_footer templates, all of which are accessible in the administration script. Have a look at our visitor registration page to see how we crafted the headers and footers here on WebRef.

• 
  Articles can now be locked from comment submissions.

  Article Locking. Articles can now be locked on an individual basis; i.e., Simple Comments will not allow comment submissions on locked articles. Articles can be locked manually (one at a time as needed), or automatically after an administrator-defined number of days has passed.

  A new configuration parameter, article_lock_days, controls whether or not articles are locked automatically. If it's set to 0, then articles are never locked automatically. If set to a positive number, the script will check the date-time modified of the page the comments will appear on, and will automatically lock the page when it becomes older than the days specified. Note that once an article is locked or unlocked, no further automatic processing will occur on that article (even if the article is refreshed). In this way, the system will never re-lock (or unlock) an article that an administrator has explicitly set.

• Support for Unique Display Names. Display names for registered users can now be forced to be unique, and if they are, can also be used to login to the system. At the heart of this enhancement is the new xref file, which, if the new unique_display_names parameter is set to 1, stores each of the identifiers an individual may use to gain access to their account (with the exception of E-mail addresses, which the system continues to recognize natively) cross referenced with their system user IDs. Note that if OpenID's are enabled, then unique display names will also be automatically enabled, since the two identifiers both stash the IDs in the xref file for quick lookups..

  Using the xref file provides two advantages to Simple Comments. Firstly, it provides a single lookup point where we can translate a user's display name (or OpenID, if necessary) into their unique visitor ID. Without this single file, Simple Comments would literally have to read every visitor record on the system every time someone logged in an attempt to match the login ID with the visitor record. Obviously that would be terribly inefficient.

  Secondly, the xref file itself provides us with a primitive form of locking control; when we want to store a new display name (or check to make sure a selected name does not exist), we can lock the xref file for exclusive processing--ensuring that another instance of the script cannot perform its own check until we're finished with it. This capability is critical: if we cannot lock the file, then we might give two different people the same display name if they happened to request it at the same time. With locking in place, the second user couldn't check for the existence of the name until after the first visitor finished their registration; at which time the second user's request would simply be denied. In Perl, the primary means for locking up files is via the flock command and its various parameters. For further information, see the File Locking section of perlopentut (and if you're unfamiliar with Perl's built-in documentation system, see my earlier primer on the subject.)

  If you decide to use unique display names on your existing Simple Comments deployment, it's necessary to build the initial cross reference file from data in your existing visitor records (i.e., the current display names will be checked for duplicates and stored in the xref file). A new option in the administration script provides this capability. If the initial build of the file finds any duplicate display names in your existing accounts, you will be prompted with the details so you can manually adjust the accounts as necessary to remove the duplication. Simple Comments will not automatically change existing accounts to remove duplicates; so you're free to implement your own duplicate policy as necessary.

• Visitor CAPTCHA Bypass. A new configuration flag--visitor_captcha_bypass--allows you to bypass CAPTCHA checks for registered and logged in visitors. If this flag is set in the configuration file, logged in visitors will not need to perform CAPTCHA verifications when they submit comments or profile changes.

• User E-mails in Comments. The storing of user E-mail addresses within the comments is now optional, and is turned off by default. See the CHANGES.txt file for more information regarding this change.

Other minor enhancements include a streamlined administration menu, reorganized documentation and various template-related improvements.

The utf8 Gaff and Other Fixes

As is nearly always the case, several bugs were fixed in this release of Simple Comments; many of which were pointed out by WebRef readers. Some of the more prominent bugs include:

• In an earlier article, I detailed the specifics of a bug I discovered in my use of the utf8 pragma. In brief: the utf8 pragma wasn't actually being used in the Simple Comments code at all--even though I had intended it to be. To learn the details of the faulty code as well as why it didn't work the way I thought it did, I refer you to my Perl Pragmas Primer.

  Having implemented the fix described in that article, a new error quickly surfaced: Namely, the HTML::Template module doesn't always work properly when older Perls (i.e., 5.6) run with the utf8 pragma enabled. To counter this problem, I found it necessary to localize my use of utf8 to only that code within which it was absolutely necessary; i.e.:

  BEGIN {
     if ($] import();
     }
  }
  # ...
  # Code that requires utf8 processing goes here
  # ...
  no utf8;

  You may or may not be able to get away with that in your own projects; if not, a direct patch to HTML::Template or a Perl upgrade may be your only alternatives.

• Late in the development cycle for this release it was brought to my attention by one of our WebRef readers that Simple Comments was incorrectly allowing users to login to the system before they had confirmed their E-mail address. While it effected only those who did not require registration approval, (i.e., those who let all user registrations go straight through without administrator review), the bug was serious in that it enabled a user to create an account with virtually any E-mail address they could think of (so long as it was syntactically valid). This bug is now fixed; accounts can no longer log into the system unless their status is active. As I mentioned in my original reply to the bug report, I can't think of any legitimate reason that a non-active account should be allowed to login. If you can, let me know. In the meantime, I apologize for any problems this bug may have caused you.

• Hyphens and underscores are now allowed in reCAPTCHA public/private keys.

• When saving a user profile in the administration script (i.e., when approving a submitted profile), be sure to copy over the current user comment list and their post count; since they may have changed since the user provided the profile update.

And for a full listing of changes made in this version, be sure to check the CHANGES.txt file included with the distribution package.

So much for the warm-up act; let's turn our attention to the main feature. What exactly is OpenID? And how can it used beneficially in your own login-based projects? Go to the next page to learn more about this authentication method that allows users to use a single identifier to sign on to multiple--and unrelated--Web sites...

[next]

Created: July 8, 2008
Revised: July 8, 2008

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