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

. . .

install & configure pollxn

1.   Unzip/Untar
Untar or unzip your Pollxn download. Inside it you'll find 3 files:

  • pollxn.cgi - Pollxn's core engine
  • pollxn_templates folder with the pollxn, tulip, daisy, & cactus template flavors

     and

  • pollxnarchive.cgi - script for archiving Pollxn discussions

Pollxnarchive.cgi is optional — it isn't required to use Pollxn. You can read more about archiving in the How-To section.

 

2.   Transfer Files to Server


Note: If you prefer to edit files on your own computer before uploading them to your web server, do step 5 below before doing this step.

Copy or FTP the items above to your web server. We recommend putting the .cgi files in the same location where your blog software is, or in your blog folder, but your ISP may require you to put it in a /cgi-bin or other applications folder. Some ISPs also require you to use a "wrapper" script in order to run a cgi like pollxn.cgi -- ask your ISP if in doubt.

The pollxn_template folder can go anywhere, as long as pollxn.cgi can access it.

 

3.   Set pollxn.cgi's Rights
Set pollxn.cgi's rights to executable. From a Unix or similar shell command line you might use:

   chmod a+x pollxn.cgi

 

4.   Verify Blog Folders Are Writeable
Check the rights on your folders where your blog files are located (i.e. /myblog/tv, /myblog/simpsons, etc.). These folders should all be writeable by pollxn.cgi. If pollxn.cgi runs as user Bob, then Bob should have rights to write in any of the blog folders, since they are where Pollxn's discussion files will be created. If you're using, try using the chown and chmod commands.

 

5.   Edit pollxn.cgi's Settings
Load pollxn.cgi into a text editor and edit its configuration variables:

$datadir - This is the file system path of the directory or folder where your blog text files are stored.
In my case, for example,
   • All my blog URLs start with /docs (i.e., http://myblog/docs/some_story.html)
   • On my server, 'docs' is at: /Library/WebServer/Documents/blosxom/docs
   • So my blogfolderpath is: /Library/WebServer/Documents/blosxom

If you're using windows, remember \ to \ use \ backslashes instead of forward ones for all paths.

$pollxntemplatefolder - This is the file system path to Pollxn's pollxn_templates folder.
Example: /Library/Webserver/Documents/pollxn_templates

$myemail - This is your email address.

$blogtitle - This is the title of your weblog/blog.

$maxperpage - This is the number of discussion entries that will be shown per page. If you'd like all entries to be shown on a single page, set this to zero (0).

$timezone - Set this to your timezone (PST, EST, etc.)

$fileextension - This is the file extension your blog entries use. For example, if your blog entries are stored on your server as 'blogentry.txt', you would set $fileextension to '.txt'.

$reqname and $reqemail - When a user posts a comment, you can require them to enter their name, email address, both, or none. Set each of these to either one (1) or zero (0).

$maxpostsallowed - This is the maximum number of discussion comments you'll allow to be posted for a blog story. Once this number is reached, no more posts will be allowed, and the comments will be displayed in an 'archived' style -- that is, with no discussion submission form.

$delim, $key, and $maxmult - These are security values that prevent a discussion entry from being accidentally submitted twice. Set $delim to a number between 5 and 10, $key to a number between 2 and 1000, and $maxmult to a number between 5 and 1000.

#!/usr/bin/perl - This is the first line of the cgi file. Verify it correctly refers to your server's Perl interpreter.

When you're done editing, save the pollxn.cgi file.

 

6.   Test the Installation
Open your web browser and run a few tests to make sure Pollxn is O.K.:

Test 1: Hit Pollxn's URL with no parameters
 
Surf to the URL where you installed pollxn.cgi. For example,

       http://yoursite/cgi-bin/pollxn.cgi

You should see:

       The story you referenced wasn't found.

If you see this message, then Pollxn has permission to run on the server -- goto Test 2.

If you don't see the message,

    • is the URL you entered correct?
    • verify pollxn.cgi's executable settings
    • verify the variable settings you made in pollxn.cgi in step 5 above
    • verify your ISP allows CGIs to run in the folder where you put pollxn.cgi
    • verify your ISP doesn't require some kind of CGI wrapper script

 
Test 2: Hit Pollxn and reference one of your blog entries with the 'storypath' parameter
 
Pollxn uses a parameter called storypath to locate a blog entry. Assuming you have a Blosxom story called /docs/tv/simpsons, you would surf to something like:

    http://yoursite/cgi-bin/pollxn.cgi?storypath=/docs/tv/simpsons   or
    http://yoursite/cgi-bin/pollxn.cgi?storypath=/docs/tv/simpsons.txt   or
    http://yoursite/cgi-bin/pollxn.cgi?storypath=/docs/tv/simpsons.html   etc.

Try it. Substitute /docs/tv/simpsons with one of your blog entries. Pollxn should respond with the name of the blog entry, and provide a form allowing you to post some comments for the blog entry. Try entering a comment. Pollxn should accept your post and reload the page, showing you the comment you just entered. If it works, it means Pollxn has rights to run and create comment files in your blog folders. Congratulations! Goto Test 3.

If Pollxn can't find your blog entry,

    • is the URL you entered correct?
    • does the blog entry you supplied actually exist (i.e., /docs/tv/simpsons)?
    • is your blog entry folder (/docs/...) inside the path you supplied for $blogfolderpath in step 5?
    • are you (hopefully) using Blosxom or a Blosxom-compatible blog engine?

If Pollxn can't save your comments,

    • make sure your blog entry's folder (i.e., /docs/tv/) is writeable for the user that pollxn.cgi uses when it runs

 
Test 3: Try a Pollxn flavor with the 'flav' parameter
 
Pollxn's flav parameter determines which set of HTML templates Pollxn uses to format a page of comments. Try running pollxn.cgi like you did in Test 2, but now add the &flav=tulip parameter:

       http://yoursite/cgi-bin/pollxn.cgi?storypath=/docs/tv/simpsons&flav=tulip

Pollxn.cgi should display the comments with a new look and feel. If so, it means Pollxn is able to find its pollxn_templates folder where the HTML template flavor files are stored. Some other flavors to try are cactus and daisy. And of course, you can make your own.

If Pollxn can't find the tulip template or you receive an error message,

    • is the URL you entered correct?
    • did you FTP the pollxn_templates folder to your web server?
    • does the pollxn_templates folder contain its HTML template files?
    • double-check the path you used for $pollxntemplatefolder in step 5 above

 


If you're ready to configure your Pollxn's templates, check out our How To section next.