csPoller Help File and Installation Instructions

1. Stand Alone Installation
2. Module Installation
3. Creating and Managing Polls
4. Poll Configuration
5. Inserting Polls on your Website (using the link wizard)
6. Frequently Asked Questions (FAQ)
7. Troubleshooting


Note: Due to the enhancements and additional features added to csPoller version 2, it is not backwards compatible with previous versions. If you are currently using csPoller on your website, you will either need to recreate the old polls in version2 or install version2 in a different directory.

Stand Alone Installation

Unzip the zip file on your local computer. It should extract to a cgi-script directory with a csPoller directory inside. Inside the csPoller director you will find an images directory, a data directory, and the various files needed for csPoller. Depending on your server's capabilities.. follow either of these 2 sets of instructions.

If you have the ability to run Perl scripts outside your cgi-bin directory:

Make sure your FTP program is set to transfer htm, html, pl, and cgi files in ASCII mode.. the images and other files should be transferred in BINARY mode. With your FTP program.. select the entire cgi-script directory and upload it (and its contents) to the root directory of your website. This would be the same directory where your homepage is located. Next, with your ftp program go to the csPoller directory (which is inside the cgi-script directory) and CHMOD the csPoller.cgi file to 755. Open csPoller.cgi with your web browser to go into setup mode. If your website is http://www.domain.com then the URL should be http://www.domain.com/cgi-script/csPoller/csPoller.cgi. If all goes well.. this will give you a screen with various configuration variables. Change the username and password to your liking and click the save button. This will auto-create a setup.cgi for the script. If you get a permission denied error when you hit the save button, you will need to CHMOD the csPoller directory to 777 and the data subdirectory to 777. Then go back to the setup screen and then you should be able to save the configuration information. That's it. Now you can go to http://www.yourdomain.com/cgi-script/csPoller/csPoller.cgi and enter the username and password you configured for the script to enter the management screen to create and edit your polls.

If you can only run Perl scripts inside your cgi-bin directory:

In your cgi-bin directory, create a directory called csPoller. Inside the csPoller directory, create a directory called 'data'. In your document root directory (same directory where your home page is located), create a cgi-script directory. Inside the cgi-script directory create a directory called csPoller. Then, inside that directory create a directory called images. You should end up with something like:
cgi-bin/csPoller
cgi-bin/csPoller/data
cgi-script/csPoller
cgi-script/csPoller/images

Upload all the files in the cgi-script directory within the zip file to the csPoller directory. Upload the contents of the data directory to the data directory. Upload the images directory to the images directory. CHMOD csPoller.cgi to 755 and then open it with your web browser. If your website is http://www.domain.com then the URL should be http://www.domain.com/cgi-bin/csPoller/csPoller.cgi. If all goes well.. this will give you a screen with various configuration variables. Change the Image URL variable to point to the images directory you created. For example, http://www.yourdomain.com/cgi-script/csPoller/images . Change the Image Path variable to the PATH to the directory where the images are located. If you aren't sure what the path would be, you might have to ask your hosting service. Change the username and password to your liking and click the save button. This will auto-create a setup.cgi for the script. To change the username or password at a later date, simply edit the $username and $password variables in the setup.cgi file. If you get a permission denied error when you hit the save button, you will need to CHMOD the csPoller directory to 777 and the data subdirectory to 777. Then go back to the setup screen and then you should be able to save the configuration information. That's it. Now you can go to http://www.yourdomain.com/cgi-script/csPoller/csPoller.cgi and enter the username and password you configured for the script to enter the management screen to create and edit your polls.


Module Installation Instructions:

A new and exciting technology that CGIScript has developed is the ability to use modules within our csPublisher program. You must have csPublisher in order to use csPoller as a module. Also, in order to use modules you might need to upgrade your version of csPublisher. You can always email contact@cgiscript.net to get the latest version of csPublisher. If you already own the script, updates and replacement copies are free.

With your FTP program, browse to the csPublisher directory. Inside the csPublisher you will see a directory called 'mod'. If you don't see that directory then that means you need to upgrade csPublisher. Upload the csPoller directory from the zip file to the mod directory. If csPublisher was installed in your cgi-bin directory, then you'll need to put the images directory for csPoller outside your cgi-bin directory.. Otherwise you can keep it with the other files so you will end up with the following structure:
mod/csPoller
mod/csPoller/data
mod/csPoller/images
CHMOD csPoller.cgi to 755 and open it with your web browser.. For example, the URL might be: http://www.yourdomain.com/cgi-script/csPublisher/mod/csPoller/csPoller.cgi
Verify the variables, change the username and password variables and hit the save button. If you get a permission denied error, you will need to CHMOD the csPoller directory to 777, along with the data subdirectory. Then go back to the setup screen and you should be able to save it now.

If csPoller is installed successfully, you will be able to enter csPublisher, go to the html editor and in the misc. functions dropdown you should see 2 new items to select. Insert Poll and Manage Polls. Select the Manage Polls function to enter csPoller management.


Creating and Managing Polls

When you enter csPoller, the first thing you will need to do is create a category. Click the 'add category' button and select a name for the category. You can create as many categories as you like. Also, if you are using csPoller as a module for csPublisher, then users will only be able to see and manage their own categories and polls.

Once a category has been created, you can proceed to create your first poll. Click the 'Add Poll' button. Enter a name for the poll and a short description if you like. Then, click the 'add question' button to add the first question. On the add question page, you have a field for entering the question, a dropdown to select what kind of question it is (radio button, checkbox, dropdown, text), and a field to enter the responses. There are 5 different types of questions:
Radio Button Example:
What is your favorite color?
Red
Blue
Green

Checkbox Example:
What are your favorite colors?
Red
Blue
Green

Dropdown Single Example:
What is your favorite color?

Dropdown Multiple Example:
What are your favorite colors?

Text Field Example:
Please Enter your Favorite Color:

The 'Text Field (Don't show on results)" option will allow you to collect information that you don't want included on the poll. For example, you could ask for the persons email address:
What is your email address?

With an example like that, obviously, you wouldn't want the email address to appear on the results page.

Also, with Radio buttons and Checkboxes you have an additional feature for an 'Other' selection that will allow to user to enter free form text in a text field. For example, you could configure a question like:

What is your favorite color?
Red
Blue
Green
Other:

To configure this, in the response text area you enter anything you want to show as an other choice for radio buttons or checkboxes with <> surrounding it. So, for the above example, you would configure the responses as:

Red
Blue
Green
<Other>

You can enter anything you like between the <>. You could configure it like:
Red
Blue
Green
<Other Color>
If you like.


Poll Configuration

On both the main management screen and the poll add/edit screen, there is a Configure button. The configuration lets you set various options for you poll.

The first option is to specify a date for when the poll is active, along with a status of the poll. You can select any poll as being active or on hold. If a poll is on hold, and you are showing the category either by date or randomly.. this poll will not be included in the rotation. If you select the option to use the start and end dates, this will allow you to fill up a category with many polls on different dates or date ranges to show. This would only be applicable if you are showing the category by date (see the section about inserting polls on your web pages).

The next section are the poll options:

Allow Users to View Results without Voting.

If this option is selected, a 'view results' button when appear on the poll form for the users to view the results.

Keep Poll Results Private.

If this option is selected, instead of showing the results of the poll after the person has taken it.. they will see a thank you page only. This is helpful if you want to collect information from people, but don't want them to see what other people are submitting.

Allow Users to View Previous Polls.

If this option is selected, it will provide a link to other polls in the category. If a poll is on 'Hold', then it won't show up in the list. Also, if the poll is configured to show by date and that date hasn't come yet.. then that poll will also not be shown. This option is equivalent to a poll archive. If you would like to manually provide a link to the archive, use the following format: csPoller.cgi?command=sa&cid=[cid] where [cid] is the id for the category. You can get the id for the category by previewing a poll and looking for the cid=xx variable in the URL. If it says cid=1 then you would know the category id would be '1'.


Create Export File.

This option allows you to download a CSV file (compatible with excel) of the submissions. This is helpful if you want to store a copy of the results, are collecting additional information on the poll (name, email address, etc), or want to analyze the results yourself.

Allow Visitor Comments.

This option will display a name a comment field on the poll submission form. On the results page, it will show the comments.. limited by the 'number of comments to show on results page' field. There would also be a link on the results page to view all of the comments. In addition, there is an 'Edit Comments' button that allows you to edit or clear out the comments. Just make your modifications to the text in the text area and hit the save button on the configuration screen.

Note: There is a bad word filter in the script you can configure. Towards the top of csPoller.cgi you will see:

@bad = ('badword1','badword2','badword3','badword3');

Edit the words between the single quotes to be 'filtered' out. You can add as many words as you like, contained in single quotes and comma separated.

 

Poll Style

You can either select to use the default style sheet (default.css located in the images directory for csPoller), or you can configure your own style sheet. If you uncheck the default checkbox, then you will be able to edit and configure a CSS that is unique for this particular poll. There are comments throughout the style sheet that tell you with each section controls. For example, if you wanted to change the color of the questions from black to red, you could change:

<!-- style of question -->
.questionText
{
FONT-SIZE: 8pt;
FONT-FAMILY: Tahoma, sans-serif;
font-weight: bold;
COLOR: black;
BACKGROUND-COLOR: white;
}

to

<!-- style of question -->
.questionText
{
FONT-SIZE: 8pt;
FONT-FAMILY: Tahoma, sans-serif;
font-weight: bold;
COLOR: red;
BACKGROUND-COLOR: white;
}

You can experiment with different settings to get your desired look. In addition to changing the style sheets, you can also modify the global template files. These files are t_poll.htm for the poll submission form and t_poll_results.htm for the results page.

The next section are the voting restrictions.

Users can only vote once.

Self explanatory.. users will only be able to submit once to the poll

Users can vote again after xx days.

You can set this to the number of days to pass before you would allow people to vote on the poll.
Allow multiple voting. Users can vote as many times as they like on the poll.

Security

You can keep track of voters by cookies, IP addresses, or both. This is used for determining if the user has already voted.


Inserting polls on your web pages (Links wizard)

On the main management screen there is a button for Links wizard. This section will automatically generate various codes for you to display the polls on your web pages. The basic process is you select your options.. hit the generate button.. copy and paste the code to the page in the place where you want the poll to appear on your page. If your are using csPoller as a module with csPublisher, its as simple as putting your cursor where you want the poll to appear on the page, go to 'Insert Poll'.. select your options.. click generate.. click the place code button.

The options are as follows:

Select Poll or type to Display

You can either select a single poll to display, or you can have it display a poll randomly or by date as specified by the date in the configuration screen for a particular poll.

Display Call - Code Type

Most of the time you would probably use the JavaScript method.. In order to use the server side include option, you'll need to make sure you have server side includes configured on your server.. In addition, you might have to name the file you are pasting the code on with a particular extension.. shtml for example. The Directory link, allows you to create a standard html link to the poll as opposed to inserting the form on the page.

Results Location

Popup Window

When the poll is submitted, the results appear in a popup window.

New Page

When the poll is submitted.. the results go to a new page, which is actually the t_poll_results.htm page. You can modify that page to your liking to change what the results page looks like.

Same Page

This option will read the page where the original form came from and replace the form with the results of the poll. For example, if you have the poll form on your home page, when someone submits the poll.. they are taken back to your homepage with the poll form replace by the results of the poll.

Direct Link Template

This basically the same option as the 'New Page' option but gives you the ability to specify your own page as opposed to using the default t_poll_results.htm page by itself. Place <!-- Insert Results --> on the page where you want the results to appear. Also, specify the Full URL for the file.

Once you have made your selections. Click the 'Generate' Button. The 'Grab' button with automatically select the text for you so you can then go to copy and then paste the code on your page where you want the poll to appear.

There is also an option on the Links wizard page to just show the results of a particular poll. The Use Template option is identical to the 'Direct Link Template' option in the poll display link wizard section. All the other fields are also identical.


Frequently Asked Questions (FAQ)

Does csPoller require me to have a website?
Yes.. csPoller will only run through a web server. It will not run on your local computer.

My server does not allow me to run Perl scripts.. can I still run csPoller on my site?
No, you can only run csPoller on your site if your hosting service allows you to run Perl scripts.

I am installing on a windows server.. what does CHMOD mean?
CHMOD is a way to change permissions of files on a UNIX based server.. its not applicable for windows servers so you can ignore the instructions where it mentions CHMOD. If you have problems saving files or permission denied errors. Then you will have to contact your hosting service so they can configure the directory so the web server has write access to it.

How do I know what the various paths are on my server?
Usually this is information your hosting service will provide you when you first set up your account with them. You can also look on your hosting service's website to see if they have an FAQ or support section that might tell you how to determine what your path is.

Can I 'brand' the script or remove where is says CGIScript.net.
Yes.. you are welcome to modify the html pages anyway you like as long as you maintain the copyright information in the script itself.

How do I change the look of the poll form or poll results? I have a page with a black background and none of the text is showing up.
Go into the configuration for the poll and uncheck the 'use default' checkbox on style settings. Then go through the style and change instances of 'black' to 'white' or whatever other color you want to use. You can also change the table border colors and table background colors.. in addition to the colors of the bars that represent the different results on the poll results page.

How can I randomly display a group of polls within a specific date range?
Within a category, all various polls with the same start and end date. For example you could add 5 polls with a date range of 01-01-2002 to 02-01-2002 and when you create the code to randomly display polls from the group, it will randomly select one of those 5 polls.

Can I collect other information on the poll such as an email address?
Yes.. you would create a 'Text Field (Don't show on results)" field. This will provide a text field for the user to enter whatever information you are collecting and it won't show that on the results page. To extract the information that people have submitted you'll want to check the box for creating an export file and then download the export file at regular intervals to gather the results.

Is there a limit to the number of responses that I can add?
No, you can add an unlimited number of responses (within reason).

There is no setup.cgi file included in the zip file.
The setup.cgi file is created automatically when you first run the script. It is not included in the zip file. However, there is a setup.cgi.example file that you can rename to setup.cgi if you want to manually configure the variables instead of going through the autosetup procedure.


Troubleshooting

I uploaded the files and when I run csPoller.cgi I get a 500 server error. 
500 Server errors are usually caused by incorrect FTP transfer modes or permissions problems. To make sure the file was uploaded in the correct mode, download the csPoller.cgi file off the server to your computer in BINARY mode and then reupload it back to the server in ASCII mode. Some FTP programs, like WS_FTP for example, will say its transferring in ASCII mode but instead transfers it in binary mode on some occasion. This seems to be most prevalent when your website is controlled by the Plesk web management system.

I forgot my username and password. How do I find out what it is?
FTP in to your server and view the setup.cgi file. The $username and $password variables will tell you the username and password.

I installed the script and everything seems to be working fine but I can't view the images in the script.
This happens when you have the images and CSS files installed in your cgi-bin directory. Cgi-bin directories won't allow you to view normal files in them. They will usually give you either a 500 server error or a forbidden error message if you try to view them directly from your cgi-bin directory. If you are installing in the cgi-bin directory, follow the cgi-bin installation instructions.

I really would like to run the script from on directory outside my cgi-bin directory. How can I set that up?
If you have the apache web server running your site, then sometimes you can use an .htaccess file to configure the directory to run scripts. To do this, open up notepad and type:
AddHandler cgi-script .cgi
Options +ExecCGI

Save that file as .htaccess and upload it to the csPoller directory. Make sure there is a period in from of the name (.htaccess) and make sure there is no 'txt' extension. If there are problems with the name, you should be able to rename it correctly from your FTP program. If you get a forbidden error message instead of it displaying the source of the script, you might be able to just try
Options +ExecCGI in your .htaccess leaving out the AddHandler line. If when you do this you get a 500 server error.. this usually means you are forbidden to use these directives in the .htaccess file. If that is the case you need to delete the .htaccess file to be able to view files in that directory again. It is also more common that not that .htaccess files are hidden by the FTP server. When you upload the .htaccess file.. many times you won't be able to see it in the directory listing. If this is the case, what you can do is create a blank .htaccess file and just reupload that back to the server as opposed to deleting the file.

I get a forbidden error message when I try to run script.
This is usually caused by the script not being set to executable. Make sure the file permissions are set (CHMOD) to 755.

I am running a windows server. I know I can run Perl scripts on my site but when I try to run csPoller.cgi I either get a 500 server error or it displays the source of the script.
Many windows servers are set to only run files with a pl extension. What you can do is rename csPoller.cgi to csPoller.pl and then open csPoller.pl and change the line that says:
$in{'ext'} = "cgi";
to
$in{'ext'} = "pl";
Reupload the file and then try to open csPoller.pl with your web browser.

I have a windows server and when I try to run the script I get a 'can't locate libs.cgi' error message.
Open csPoller.cgi and where it has the line:
$basepath = './';
Change that to the full path to the csPoller program. Example:
$basepath = 'c:/inetpub/wwwroot/cgi-script/csPoller';

Also, make sure you use forward slashes in your path names instead of the normal windows backslashes.

When I try to log in, I get an error messages that says it can't find the page and the URL has in(cgiurl) in it.
That indicates you are trying to open one of the html files directory. You never go directly to any of the html template files. All access to these pages are through the script. Use csPoller.cgi or csPoller.cgi?command=login to log into the script.


If you have any other program or questions, please email contact@cgiscript.net