home news download install [how-to] plug-in links contact

. . .

how-to do pollxn

Pointing Blog Entries to Pollxn
Using a Flavor Template
Customizing Pollxn's Flavor Template Files
Alternating Comment Colors
Displaying Comment Counts Per Blog Entry
Displaying Comments in a Popup Window
Archiving and Closing Pollxn Discussions

Pointing Blog Entries to Pollxn
After installing Pollxn, you can create a new discussion for a blog entry by hyperlinking to pollxn.cgi with the storypath parameter. Storypath should supply pollxn.cgi with the URL of the blog entry relative to your webserver:

    <a href="/your_cgi_path/pollxn.cgi?storypath=/path/to/a/blog/entry">discuss</a>

If your blogging software uses templates, you can add the Pollxn hyperlink to the template that displays your blog entries to automatically give users the option to comment on every story you post.

For example, if you're using Blosxom, you could add the following Pollxn hyperlink to your Blosxom story template like this:

    <a href="/your_cgi_path/pollxn.cgi?storypath=$path/$fn.$flavour">discuss</a>

($path, $fn, and $flavour variables are variables used internally by Blosxom).

Using a Flavor Template
Flavor templates change the look and feel of comments. To use a flavor, add the flav parameter to Pollxn.cgi's URL, and set it to the comments template you want to use. Here's an example that will invoke a template called tulip:

    <a href="/your_cgi_path/pollxn.cgi?storypath=/path/to/a/blog/entry&flav=tulip">discuss</a>

Pollxn comes with sample templates in the pollxn_templates folder: pollxn (the default), tulip, daisy, and cactus.

Customizing Pollxn's Flavor Template Files
Pollxn's flavor templates are stored in the pollxn_templates folder. Each template consists of 4 HTML files: a _template file, _comment file, _error file, and _form file. Each file contains HTML, plus a variety of $variables you can move around or format to give your comments a custom look and feel. The chart below shows the different $variables available in each kind of template file.

   Template File Available $Variables
  _template.html $blogtitle - title of your blog
$storytitle - title of blog entry or story
$storytime - blog entry's timestamp
$commentsbody - all posted comments for current page being shown
$storypath - /path/to/this/story
$count - total number of comments
$backlink - link to previous page of comments
$nextlink - link to next page of comments
  _comment.html $number - comment number (1., 2., 3., etc.)
$name - name of person who posted comment
$when - when comment was posted
$email - email address of person who posted
$thecomment - body of the comment or posting
  _error.html $error - the text of the error message
$tryagain - when applicable, text that tells user to try submitting again
$myemail - your email address
$when - time/date when error occurred
  _form.html $storypath, $newkey, $flav - used internally by Pollxn

Alternating Comment Colors
Pollxn can automatically alternate colors when displaying a page of comments, like this:

  comment 1
comment 2
comment 3

The easiest way to achieve this effect is through the use of an HTML table, with each row (<TR>) given an alternating color through the use of a stylesheet. To illustrate how this works, let's take a tour of the default pollxn template.

First, open the pollxn_template.html template file in your favorite text editor.

Find the CSS stylesheet near the top of the file. These two lines define the two colors that will alternate:


Pollxn expects the two alternating colors to be called color1 and color2.

Next, scroll down to this section:

     <table width=100% cellpadding=4 cellspacing=3>

The <table> tag opens the table so the rows produced by $commentsbody will be displayed inside it. Let's take a look at the rows.

Using your text editor, open pollxn_comment.html. This file controls the formatting of each posted Pollxn comment. You'll see that the entire comment is essentially a table row starting with <TR> and ending with a </TR>. Notice the class=$altcolor in the <TR> tag — Pollxn will alternate $altcolor between 'color1' and 'color2' as each successive comment row is displayed, causing the <TR> to change colors.

You don't have to use a table. Since Pollxn alternates between color1 and color2 using a standard CSS stylesheet, you could use this to change text colors, background colors, or any other HTML color setting.

Displaying Comment Counts Per Blog Entry
If you're using version 2.0 or higher of Blosxom as your blog engine, you can use the optional Pollxn plug-in to dynamically display the number of comment posts available for each of your blog entries. The result might look like this:

     Homer Simpson Gets Slow Haircut
In his feature film debut, Krusty the Clown spends 90 minutes
cutting Homer Simpson's hair with rusty toenail clippers.
Link | 43 comments

In the entry above, the "43 comments" link is generated dynamically by the Pollxn plug-in for Blosxom. When visitors click on it, they'll see 43 comments about Homer and can post their own comments.

To add a comments count to your Blosxom blog:

     1. Download and install Blosxom (2.0 or higher)
     2. Download and install Pollxn
     3. Download and install the Pollxn plug-in

Displaying Comments in a Popup Window
To make Pollxn.cgi open in a pop-up window, use the HTML target attribute in your hyperlink. Example:

    <a href="/your_cgi_path/pollxn.cgi?storypath=/path/to/a/blog/entry" target=popup>discuss</a>

If you don't like how the popup window looks, you can always control its size and shape somewhat with Javascript — just Google for some Javascript pop-up window examples.

Archiving and Closing a Pollxn Discussion
Pollxn stores its discussion files in the same folder as the topic being discussed. Each posted comment is stored in its own file with the filename topic.pollxnZ, where Z is a random number. If you have 30 comments about a blog story called /tv/simpsons/homer, you'll end up with 30 Pollxn files, like this:


When a blog story reaches a certain age, people will post fewer and fewer comments about it. At a certain point, you'll probably want to close the discussion completely and archive your Pollxn discussion files so they take up less space on your server's hard drive.

The process of archiving simply takes all of the .pollxn discussion files for a particular story (i.e., /tv/simpsons/homer) and consolidates them into a single file. Once comments have been archived, visitors to your blog can still read the comments, but Pollxn won't allow any additional comments to be posted.

A script called pollxnarchive.cgi is included in the Pollxn download. When you run it, it will spider through your blog's document folders. When an old blog story is found, Pollxn will gather up the story's discussion comment files and consolidate them into a single file called topic.pollxn_archive (e.g., /tv/simpsons/homer.pollxn_archive). The archive script lets you choose how old a blog story must be before its comments will be archived.

To use pollxnarchive.cgi:

  1.    Copy or FTP the script to your web server. You can put the script into any folder where you have rights to execute programs.

  2.    Make sure the script has executable rights. On UNIX you might:

     chmod a+x pollxnarchive.cgi

  3.    Make sure you have rights to write, alter, and remove files in your blog directories. The script will need to be able to consolidate your Pollxn discussion files.

  4.    Load pollxnarchive.cgi into your favorite text editor and set these configuration variables:

      $datadir - the directory where you want the script to begin searching for blog folders

$archiveafter - the age a blog story must reach before its Pollxn comments will be archived. This value is in days.
Example: if you set $archiveafter to 10, a blog story will be archived when it is 10 days old.

$logfile - the location and name of the log file where the script will print the results of its archiving

Save the script when you're done configuring it, then run it.

If you'd like the script to run at regular intervals on your server, set up a cron job or startup script for it. Instructions for doing this vary between servers, operating systems, and ISPs. Consult your ISP if you need directions.

Unless it encounters a fatal error, the script will run quietly and exit, putting all of its archive results into its log file. Here is a sample output from a successful archive of 14 comments about a story called /tv/simpsons:

Petxl archive started at Wed Mar 12 12:57:41 2003
Starting in folder /var/apache/htdocs/docs
Only stories older than 1 day(s) will have their comments archived
Comments found for /var/apache/htdocs/docs/tv/simpsons.txt
Archiving done. 5 directories containing stories were scanned
14 Petxl comment(s) for 1 story was archived
Petxl archive job complete at Wed Mar 12 12:57:41 2003