how-to do pollxn

Contents:
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
	etc.

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:

     .color1{background-color:#eeeeee}
     .color2{background-color:#ffffff}

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>
     $commentsbody
     </table>

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:

     /tv/simpsons/homer.pollxn34893
     /tv/simpsons/homer.pollxn8100234
     ...etc.

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: