Easy Poll - Website Poll Manager

Program:	Easy Poll 3.4
Cost:	US$29	Demo - New Window
Platform:	Unix, Linux, Mac, Windows	Users Guide
Requires:	Perl	F.A.Q.
Rating:

1. Requirements
2. Configuration
3. Installation
   1. Linux/Unix/Mac Servers
   2. Common Installation Problems on Linux/Unix/Mac Servers
   3. Windows Servers
   4. Common Installation Problems on Windows Servers
4. License and Disclaimer
5. Getting Started / Creating Polls
   1. Traditional Code
   2. Compact XML Code
6. Editing Polls
7. Deleting Polls
8. Displaying Poll Results
9. Changing your password

1. Setting the Path to Perl. Open all CGI Scripts (except [script]_key.cgi) in a Plain Text Editor and make sure the first line of the CGI Script is the Path Perl for your server. Most Users can skip this step being the default Path to Perl shipped in the CGI Script is very common.
   
   NB: if you do not you a Plain Text editor such as Windows NotePad or Mac Textedit (in Plain Text Mode), your Text/HTML editor will add extraneous code to the CGI Script when you save it which will result in a server 500 Error.
   
   
2. Upload all CGI Scripts to your cgi-bin or any cgi enabled directory and CHMOD all the CGI Scripts to 755. It is imperative that you upload (transfer) all CGI Scripts to your server in ASCII mode.
   
   If you forget to CHMOD all CGI Scripts to 755, Step 3 will yield a Server 500 Error.
   
   If you do NOT upload (transfer) all CGI Scripts to your server in ASCII mode, Step 3 will yield a Server 500 Error.
   
   
3. Load your Browser, point it to the [script]_setup.cgi file and follow the on-screen instructions for installation. For example, in your browser, type :
   
   http://www.yourdomainname.com/cgi-bin/[script]_setup.cgi
   
   
4. Enter a Username and Password. This will be your Username and Password for the Administration Section. If the Setup Routine is successfully processed a link to the Administration Section will appear on the resulting page. Click the link to access the Administration Section with the Username and Password you just entered in the Setup Script.
   
   Should you encounter any Permission problems with the Setup Routine follow the instructions returned by the Script.

1. Server 500 Error. This most often occurs because Step 2 was not followed precisely. Make sure the CGI Scripts you are uploaded are CHMOD to 755, the folder the CGI Scripts reside in is also CHMOD to 755, and the CGI Scripts were transferred in ASCII Mode. Auto-Detect only detects the extensions you specify in your FTP client's Settings.
   
   
2. I can initially load the Setup Script and punch in my Username and Password, but when I submit the Form, I receive 404 Error Page or an alternate Error Page stating "Page Cannot be found".
   
   This suggests your Server is operated by a very nervous System Administrator employing strict security measures, you're using a Shared Secure Server which dynamically sets your domain name to something other than the a standard Top Level Domain (www.yourdomainname.com) or sbox is employed by your server.
   
   In any case, open [script]_key.cgi in Plain Text Editor (not a WYSIWYG Text Editor, nor a Rich HTML Editor) and enter the URL to the folder you uploaded the CGI Scripts to in the $SecureServer Variable. If you uploaded the CGI Scripts to your cgi-bin, then you'd set the following:
   
   $SecureServer = "http://www.yourdomainname.com/cgi-bin";
   
   Do NOT enter the CGI Script name, do NOT enter a trailing slash. After setting the Variable refresh the Setup Routine's Page that asks you to enter your Username and Password. Unless you refresh the initial Setup Page, the Form's URL will not be updated to reflect your Variable value.
   
   
3. I cannot find the correct path to my WebSpace or the required Data Directories and/or Password file cannot be created.
   
   You need to find that Path. Ask your host, or Download a copy of our free E-Vars CGI Script and install it on your server. CHMOD it to 755 then load it in your Web Browser which will print your Server's environment variables and other useful information. Determine your Server's Document_ROOT or Absolute Server Path to the folder your home page (index.html) resides in. You may need to append "/www" or "/httpdocs" to your Document_ROOT or Absolute Server Path to complete the path to your Writable WebSpace.
   
   Once you've determined your Absolute Server Path, open [script]_key.cgi in Plain Text Editor (not a WYSIWYG Text Editor, nor a Rich HTML Editor) and set the $DefaultData Variable. For example:
   
   $DefaultData = "/var/username/www/htdocs";
   
   Finally, on some Server's it's necessary to CHMOD the folder just above your WebSpace to 777 granting permission to the CGI Script to create the Required Directories at WebSpace Level. In the example above, the "htdocs" folder would need to have it's permissions set to 777.
   
   
4. We offer a very reasonably priced Custom Installation Service. We'll Setup the CGI Script for you and send you the Log in details which you can update at your own leisure. If we cannot successfully Setup the CGI Script we will refund both the Installation fee and the purchase price of the CGI Script. To Order Custom Installation, please fill in our Secure Installation Order Form.

1. Your Windows Server may not execute CGI scripts even if Perl is Supported. Many Server Administrators do not modify the Registry to accommodate Scripts with a .cgi extension. In this case, contact us for a copy PL Version.
   
   
2. Setting the Path to Perl. Your Server may or may not require the Path to Perl. It's highly likely you don't need it, and you can ignore this Step. However you may want to check with your Host if you can not load the Setup Script in your web Browser.
   
   NB: if you do not you a Plain Text editor such as Windows NotePad or Mac Textedit (in Plain Text Mode), your Text/HTML editor will add extraneous code to the CGI Script when you save it which will result in a server 500 Error.
   
   
3. Upload all CGI Scripts to your cgi-bin or any cgi enabled directory. It is imperative that you upload (transfer) all CGI Scripts to your server in ASCII mode.
   
   If you do NOT upload (transfer) all CGI Scripts to your server in ASCII mode, Step 3 will yield a Server 500 Error.
   
   
4. Load your Browser, point it to the [script]_setup.cgi file and follow the on-screen instructions for installation. For example, in your browser, type :
   
   http://www.yourdomainname.com/cgi-bin/[script]_setup.cgi
   
   
5. Enter a Username and Password. This will be your Username and Password for the Administration Section. If the Setup Routine is successfully processed a link to the Administration Section will appear on the resulting page. Click the link to access the Administration Section with the Username and Password you just entered in the Setup Script.
   
   Should you encounter any Permission problems during the Setup Routine, you need to contact your Host and request "Full Read/Write Permissions" be applied to at least one folder on your Server. Many Servers have at least one writable folder, often named "database". See Common Installation Problems below for more information.

1. Server 500 Errors are usually misleading on Windows Servers. It seems to be the default error page for just about every error. Make sure you typed in the correct Website Address (URL) to the CGI Scripts on your server. Make sure the CGI Scripts were transferred in ASCII Mode. Auto-Detect only detects the extensions you specify in your FTP client's Settings.
   
   
2. I can initially load the Setup Script and punch in my Username and Password, but when I submit the Form, I receive 404 Error Page or an alternate Error Page stating "Page Cannot be found".
   
   This suggests your Server is operated by a very nervous System Administrator employing strict security measures, you're using a Shared Secure Server which dynamically sets your domain name to something other than the a standard Top Level Domain (www.yourdomainname.com) or sbox is employed by your server.
   
   In any case, open [script]_key.cgi in Plain Text Editor (not a WYSIWYG Text Editor, nor a Rich HTML Editor) and enter the URL to the folder you uploaded the CGI Scripts to in the $SecureServer Variable. If you uploaded the CGI Scripts to your cgi-bin, then you'd set the following:
   
   $SecureServer = "http://www.yourdomainname.com/cgi-bin";
   
   Do NOT enter the CGI Script name, do NOT enter a trailing slash. After setting the Variable refresh the Setup Routine's Page that asks you to enter your Username and Password. Unless you refresh the initial Setup Page, the Form's URL will not be updated to reflect your Variable value.
   
   
3. I cannot find the correct path to my WebSpace or the required Data Directories and/or Password file cannot be created.
   
   You need to find that Path. Ask your host, or Download a copy of our free E-Vars CGI Script and install it on your server. You will need to rename the E-Vars CGI Script to "myserver.pl" if your Server only executes Scripts with .pl extensions. Upload it to your cgi-bin or any cgi executable folder then load it in your Web Browser which will print your Server's environment variables and other useful information. Determine your Server's Document_ROOT or Absolute Server Path to the folder your home page (index.html) resides in. You may need to append "\\www" or "\\httpdocs" to your Document_ROOT or Absolute Server Path to complete the path to your Writable WebSpace.
   
   Once you've determined your Absolute Server Path, open [script]_key.cgi in Plain Text Editor (not a WYSIWYG Text Editor, nor a Rich HTML Editor) and set the $DefaultData Variable. Be sure to separate folder names with two backslashes, not one slash. For example:
   
   $DefaultData = "C:\\html\\username\\htdocs";
   
   
4. We offer a very reasonably priced Custom Installation Service. We'll Setup the CGI Script for you and send you the Log in details which you can update at your own leisure. If we cannot successfully Setup the CGI Script we will refund both the Installation fee and the purchase price of the CGI Script. To Order Custom Installation, please fill in our Secure Installation Order Form.

The only required fields are :

Reference Name
Poll Question
Answers

Click on each of the gray colored links for instant information about each available option. Once you have entered your Question, answers and preferred settings for this Poll, scroll to the very bottom of the page and press the large button labelled "Create Poll". These Settings apply to dynamic polls which can be viewed or linked to from your website.

The Public List of your website Polls can be accessed by clicking the link in Easy Poll's control panel. Easy Poll prints a list of currently available Polls on demand. Your Public List of Polls can be located at :

http://www.YOURDMNE.com/cgi-bin/epoll/vote.cgi?list

assuming you installed Easy Poll in a directory named /cgi-bin/epoll. As soon as you paste the code in to a web page and upload it to your server, the Polling booth is live and ready for use. Alternatively you can link to your copy of the Public List from your Home Page and let your visitors cast their Votes in their chosen Polls. The Public List renders it's look based on your Settings.

Each website poll can be directly accessed from the Public List or you can place a direct link to your poll on any web page by grabbing it from the Public List. Easy Poll's Settings page also has an option to ""Link to Results from Public List. If set to "Yes" the "Results" column will be printed on the Public List page.

The page will reload and your Poll's Settings will have been stored to the server. You can now copy and paste the generated code into any of your web documents and begin taking votes.

To fetch the code for an existing Poll, from the Summary page, click the poll's name in the Name - Get Code column.

The generated code for your Poll form may be modified to change the visible appearance of your Polling station, however you MUST retain all form field names and values as generated. There are types of polling forms generated.

1. Traditional Code
   
   This poll form is a conventional form which when submitted by your visitors will either pop the poll results in a new window (see FAQ for details on how to do this) or by default, redirect the user to the results page or your chosen redirect URL.
   
   
2. Compact XML Code
   
   This poll form uses an XML HTTP request supported by all modern major browsers. Should a browser not support it, the form will act as described in the "Traditional Code" section. The purpose of this form is to show the visitor the results of the poll without them leaving the page they're currently on (your poll form's page). A <div> tag is used, which acts like a web page in it's own right. The Voting form is displayed within the <div> tag and when submitted, the results are also displayed within the same <div> tag.
   
   Because of the nature of what is essentially a down-sized web page, you will want to keep the content (poll results) to a size which can be accommodated. To do this, you can include configuration settings inside the poll form. That is, each of your poll forms, can dictate the size and content of the results shown. The available options are as follows, examples for each are shown below :
   
   
   1. id - this is a required field and must be in each Voting form. The generated code will always include this field.
      
      
   2. xml - this field indicates the poll form is a compact form and as such the results should not print the Header and Footer defined in Easy Poll's "Settings".
      
      
   3. question - The poll's question can be redefined or shortened so that it does not use up much space in the results.
      
      
   4. shownums - can be set to no or 0 (zero) so only percentages are printed rather than the number of votes and percentages.
      
      
   5. redirect - can be used to fetch an existing website page into the results <div>, must begin with http:// or https://
      
      
   6. rTab - set the results table's background color, can be a color name such as red or a hex code such as #ff0000
      
      
   7. rHead - set the results table's background color for the first row (where the question is displayed), can be a color name such as red or a hex code such as #ff0000
      
      
   8. rTabWidth - set the width of the results table, can either be an integer or percentage. It populates the table's width attribute, not the style.
      
      
   9. barcolors - set the colors for each bar as a comma separated list for the poll results table, can be color names such as red, blue, green or hex codes such as #ff0000, #0000ff, #008800
      
      
   10. face - set the font type or family for the poll results table, populates the font's style attribute
       
       
   11. fsize - set the font size for the poll results table, populates the font's style attribute
       
       
   12. color1 - set the font color for the poll results table, can be a color name such as red or a hex code such as #ff0000, populates the font's style attribute
       
       
   All of the above poll configuration settings will take precedence over the settings defined when you created the form. This enables you to display the same poll results with different settings in different pages or <div> tags. Here's an example of how to over-ride the server defined poll settings using your poll form.
   
   <form action="..../vote.cgi?cast=1171862184" method="post" onsubmit="return castVote_1171862184(this);">
   <input type="Hidden" name="id" value="1171862184">
   <input type="Hidden" name="xml" value="1">
   <input type="Hidden" name="shownums" value="No">
   <input type="Hidden" name="rTabWidth" value="150">
   <input type="Hidden" name="rTab" value="#06FF00">
   <input type="Hidden" name="barcolors" value="red, blue, #06FF00">
   <input type="Hidden" name="face" value="Arial">
   <input type="Hidden" name="fsize" value="11px">
   <input type="Hidden" name="color1" value="black">
   .....
   </form>
   
   The same can be applied to the JavaScript tag used to display poll results on any web page. The tag generated for displaying results may look like the following :
   
   <script language="JavaScript" src="..../vote.cgi?view=1052073423&js=1"></script>
   
   But can be modified to display your poll results with a different look, as such :
   
   <script language="JavaScript" src="..../vote.cgi?view=1052073423&js=1&xml=1&shownums=no&rTabWidth=300&fsize=11px"></script>
   
   Note how each setting and it's definition (key/value pair) is separated with an & and an = sign. As in &xml=1