flag of the United Kingdom
URBAN
Mainframe

The Ultimate Comments Handler (Beta)

Date:  Wed, 9th-Jun-2004prevnext

Tags: CMS, Open Source, Perl, Programming, Urban Mainframe, Website Development

I've listened to your feedback and scratched my own itches. The result is a collection of routines that, for myself at least, represents the ultimate comments handler and I am proud to present it for testing...

Before we go in to the details, I'd just like to take a moment to draw your attention to the title of this page, "The Ultimate Comments Handler (Beta)". There has been a considerable amount of discussion recently about the use of the "beta" label as used within the software industry. I have chosen that label because it accurately describes the comment handler at the time of writing: I've added a plethora of new features consisting of several hundred lines of code. I have tested those features locally, but I'm certain that I can't have covered all possible permutations. Rest assured, when I'm happy that the handler works, I'll gladly rescind the label. But, for now, it stands.

Background

I had already put together a pretty sweet and feature-packed comments handler for the Urban Mainframe. Despite my efforts, contemporary weblog comment systems had one major advantage over my own - most of them have a parser which allows the user to add some form of SGML "markup" in order to control the presentation of their comments.

I chose not to allow markup in order to prevent users invalidating my pages with erroneous code. Unfortunately my decision was not without consequence, hence the new handler.

Markup with Markdown

One of the most significant new features of the handler is the availability of a markup parser. This is provided via the integration of John Gruber's "Markdown". Markdown is a "text-to-HTML conversion tool for web writers." The Markdown plug-in was designed to work with popular weblog software like Movable Type. It is commonly used by weblog authors for the production of their content. However, I have never seen it used within a comments handler other than my own (am I the first?).

There were three key factors that influenced my decision to implement Markdown:

  • elegance - Markdown's syntax is uncomplicated and elegant. It's also readable by non-techies in its unparsed form
  • validation - as far as I can ascertain, Markdown's output is 100% compliant with the XHTML Transitional ruleset
  • GPL / Open Source / Perl - Markdown is written in Perl, the same language as my CMS

I had to make a few modifications to the Markdown script in order to get it to work with my CMS, but the process was relatively painless and the benefits more than justified the effort.

Markdown's strength is its ease-of-use. Adding formatting to comments is almost child's play. Let's look at the syntax for a couple of the most frequently required formatting tasks.


Example 1 - Hyperlink some text:

[text to hyperlink](URI "link title (optional)")


e.g: [Daring Fireball](http://daringfireball.net/ "go to: Daring Fireball")

Result:

Daring Fireball


Example 2 - Create an unordered list:

* IBM
* SUN
* Apple
* SGI

Result:

  • IBM
  • SUN
  • Apple
  • SGI

Example 3 - Create a blockquote:

> Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Quisque hendrerit...

Result:

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Quisque hendrerit...


Could it be any easier?

I have had to tweak the Markdown script to in order for it to integrate seamlessly with the comments handler, but most of the original functionality is available. The missing features are:

  • Markdown provides a syntax for italicizing text. However, italic text has a special significance in my handler - it is used to indicate text that has been added to a comment during a post-publish edit (see: Editing Blog Comments)
  • Markdown provides a pass-through for existing (X)HTML markup. I have disabled this facility in order to protect against poorly-formed and incorrect code.

It is worth pointing out that the parsing facilities of the previous comment handler still apply. Plain text URIs are automatically converted to hyperlinks, paragraphs are produced without markup. Thus, even if you choose to ignore the many options provided by Markdown, your comments will still be presented in the correct manner.

Comment Preview

Despite the simplicity of Markdown's syntax, errors will inevitably occur when authoring comments. Even without the added complication of markup, being able to preview comments before submitting them is virtually a necessity for a user-centric website.

A couple of readers bemoaned the lack of a preview option for their comments. I missed it myself on many an occasion. However, we've always managed to get along just fine without it - so it was way down at the bottom of my "to do" list.

However, the introduction of a markup parser without the means to preview the resulting output is like a party without the verve - a credibility killer! So I did the decent thing and added one.

The preview engine is quite clever (in my humble opinion). Once you've written your comment, a click of the "preview my comments" button will present your comment in situ - inline with the existing comments (if any) and presented exactly as it would be if it were "live".

That's not all... Once you've gone into preview mode, your draft comment becomes persistent. The preview has a unique URL that you can bookmark and return to at any time (providing the comment has not been published), so there's no reason not to prepare detailed essays in response to the articles I publish here!

Why the "Ultimate" Comments Handler?

What, you mean you're not impressed yet? Oh come on - markup and preview are just two features of this multi-faceted handler:

  • 100% valid XHTML Transitional output (in theory)
  • each comment is directly addressable
  • each published comment has a 15-minute "editable" window after publication
  • edited comments are displayed with "diffs" to maintain thread integrity
  • handler has an integrated Captcha system to defend against comment spam
  • registered users can publish private annotations along with public comments
  • handler prevents duplicate posts
  • comment threads can be subscribed to (and unsubscribed from)
  • Gruber's "SmartyPants" enhances typography

To Do

  • There is no preview facility when editing a published comment. There should be.
  • Make the comments searchable
  • Unicode support is still not 100% reliable

Beta Testing

Now back to that "beta" bit. As I wrote above, this handler should be considered "beta" at the moment. It is not thoroughly tested and I would like to solicit your help for that (that's right, this whole thing is a feeble, transparent attempt to tease some comments out of the lurkers among you - come on, you know you want to).

I am particular keen to see the Markdown engine tested. So please, comment away (remember: a comprehensive guide to Markdown's syntax is available at Daring Fireball).

You can comment on this entry, or read what others have written (24 comments).


W3C VALIDATE XHTML
W3C VALIDATE CSS