VOTE.PL Version 2.1.2 Released 13/07/2002 WWW: http://home.datacomm.ch/atair/perlscript/index.html Email: atair@datacomm.ch Copyright (c) 2002 A. Schnyder. All Rights Reserved. ########################################################################## VOTE.PL README (for version 2.1.2) ########################################################################## TABLE OF CONTENTS 1. Licensing 2. Description 3. Requirements 4. Setup Instructions 5. Changing Poll Interface Files 6. Changing Poll Result Files 7. Logfiles 8. Updates History 9. Known Issues 10. Contact and Support Information ########################################################################## 1. LICENSING ########################################################################## Vote.pl is free software. You can redistribute and modify it freely without any consent of the developer (A. Schnyder), if and only if the following conditions are met: (a) The copyright info in the headers remains intact. (b) The purpose of distribution or modification is non commercial. Commercial distribution of this product without a written permission from A. Schnyder is strictly prohibited. This script is provided without any warranty. The author does not take any responsibility for any damage this script may cause. 2. DESCRIPTION ########################################################################## Vote.pl is a web voting CGI script, that is highly adjustable to your likings. The look of polling interfaces as well as of result pages can be modified by use of html code, to integrate the poll smoothly into the look and feel of your personal site. Vote.pl can handle an unlimited number of polls on different pages. IP number tracking and cookies prevent multiple votes from a single user. Main Features: * Highly configurable look * View results graphically and/or numerically * User tracking by IP no. and/or cookie prevents multiple votes. * Provides a maximum number of 23 questions per poll and 999 choices per question * Handles several votings on different pages 3. REQUIREMENTS ########################################################################## This version of Vote.pl is intended to work with Perl 5. It is assumed that voters use cookie-enabled browsers, otherwise the cookie tracking won't work. When properly installed Vote.pl should run on UNIX and Windows NT/2000. However the author has only tested it on a UNIX system. Of course a cgi-bin directory, a web server, a computer, an internet connection, etc. are required as well. ;-) 4. SETUP INSTRUCTIONS ########################################################################## Steve Imhof has written a comprehensive guide to Vote.pl. (Thanks fly out to him). If you are unexperienced with CGI, HTML and Perl, I recommend you to read his guide instead of the below instructions, since these are quite short and not intended for newbies. The guide can be found at: http://home.datacomm.ch/atair/perlscript/vote.pl_guide.html It follows an instruction how to set up two sample polls, called Example and Test, which come with this script. Afterwards you should be able to adjust these examples to your own polls or questionnaires. 1. After unzipping vote.zip, you should have the following files: vote.pl - the Vote.pl script config.txt - the configurations file examp_ip.txt - the Example IP logfile examp_logfile.txt - the Example logfile examp_out.html - the Example result file examp_after.html - the Example after voting file examp_voted.html - the Example already voted file example.html - the Example interface file readme.txt - this file test.html - the Test interface file test_ip.txt - the Test IP logfile test_logfile.txt - the Test logfile test_out.html - the Test result file test_after.html - the Test after voting file vote.jpg - jpg file result.jpg - jpg file black.gif blue.gif . . yellow.gif - gif files 2. Make sure the path to the Perl interpreter is correct at the first line in vote.pl. Initially it is set to #!/usr/bin/perl If it is different on your server, you need to change it accordingly. 3. Open the configurations file 'config.txt' using a text editor. "***Example***" This is the name of the first poll (here simply called 'Example'). Needs not to be change. The name of the polls must be between three asterisks. "html_file: example.html" ... ... "already_voted_file: examp_voted.html" These lines specify the paths to the corresponding files. You need not to change these either. "vote_url": xxx Specify the URL for vote.pl. This is the URL you must use to execute the script. "checkIP": false Enable or disable IP tracking by setting this flag true or false. Initially it is set to false. "checkCookie": false Enable or disable cookie tracking. The initial value is false. "expiration": 200 Specify the cookie expiration time in days. Initially the cookie expires 200 days after it has been sent to the user. This means, after 200 days it is possible to vote a second time. "replace_form_after": true Enable or disable this feature with 'true' or 'false'. If it is enabled, the voting form will be replaced by a results table after casting a vote. Otherwise the results will be displayed on a new page. "replace_form_result": false Enable or disable this feature with 'true' or 'false'. If it is enabled, the voting form will be replaced by a results table when viewing the results. Otherwise the results will be displayed in a blank page. "***Test***" Name of second poll. (In this case 'Test') It follows the same configurations for the poll 'Test'. Make same changes as above. Similarly it would be possible to add a third poll, or even a fourth, fifth, etc.... Simply write the name of a new poll on a new line (between three asterisks) and add its configurations underneath. 4. Edit interface files using a text editor. Open 'example.html', which belongs to the poll Example. <form action="xxx" method="get"> Replace "xxx" with the URL for vote.pl. (E.g.: http://mydomain.com/cgi-bin/vote.pl). This is the URL you have specified in Step 3. <input type="hidden" name="name" value="Example"> This sends the name of the poll (in this case "Example") to vote.pl. Needs not to be changed. <a href="http://xxx?name=Example&action=view"> Replace "xxx" with the URL for vote.pl. Now open 'test.html' and modify it as above. 5. Edit result files. Open 'examp_out.html' and 'test_out.html' and replace all 'yyy' with the URL of the corresponding pictures. E.g.:src="yyy/green.gif" -> src="http://mydomain.com/green.gif" Now do the same with 'examp_after.html' and 'test_after.html'. 6. Place following files in your cgi-bin directory with the corresponding permissions: file permission ----------------------------------- vote.pl 755 config.txt 644 examp_ip.txt 666 examp_logfile.txt 666 examp_out.html 644 examp_after.html 644 examp_voted.html 644 example.html 644 test.html 644 test_ip.txt 666 test_logfile.txt 666 test_out.html 644 test_after.html 644 Place (a copy) of following files into the public area (that is, the area that is accessible from typing an URL directly into a browser) file permission ----------------------------------- example.html 644 test.html 644 vote.jpg 644 result.jpg 644 black.gif 644 blue.gif 644 . . yellow.gif 644 Note a copy of 'example.html' and 'test.html' must be in the cgi-bin directory AND in the public area. 7. That's it. You can access the polls simply by typing the URL of 'example.html' or 'test.html' into a browser. To view the poll results use the URL: http://www.mydomain.com/cgi-bin/vote.pl?name=nnn&action=view 5. CHANGING POLL INTERFACE FILES ########################################################################## When changing interface files you should observe the following rules: - The maximum number of questions is 23. Per question you can provide up to 999 answers. - Each line ought to contain only one input tag. - There must be a hidden input tag with name='name' and value='name_of_poll'. - Questions are labelled using the lowercase alphabet (a to w), which are in total 23 letters. Provided choices are labelled using numbers in raising order. 6. CHANGING POLL RESULT FILES ########################################################################## There are two different files, where you can specify the way the results are displayed. In our Example poll, 'examp_after.html' describes the result page that is shown after a vote is cast. Where as 'examp_out.html' defines the page that appears when the 'Result' button is pressed. In poll result files you can use the following variables, which will be replaced by the corresponding values, when viewing the results: - $a1; : no. of votes for the first choice of question 'a' - $%a1;: no. of votes in percent for the first choice of Q 'a' - $a2; : no. of votes for the second choice of Q 'a' - $%a2;: no. of votes in percent for the second choice of Q 'a' - $b1; : no. of votes for the first choice of Q 'b' - ... - ... - etc. - $tot;: total votes 7. LOGFILES ########################################################################## Each voting has its own logfile, where the voting data is saved. If the logfile does not exist the first time vote.pl is executed, it will be created automatically. Every time you add a new question or choice to your poll you have to delete the old logfile, so that vote.pl can create a new logfile, which corresponds to the new questions. The format of the logfile looks as follows: Total votes:0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 Each line represents a new question and each column stands for a different choice. 8. UPDATES HISTORY ########################################################################## - Version 2.1.1 released (18/10/2000) - Version 2.1.2 released (13/07/2002) * Newly added feature: different config-files for the result file that apears after casting a vote and the file that is shown after pressing the results button. 9. KNOWN ISSUES ########################################################################## - User tracking by cookies is not perfect. The user can easily delete cookie files or disable cookies and vote a second time. So don't use this feature if your doing anything important, and cannot simply laugh at those who cheat. 10. CONTACT AND SUPPORT INFORMATION ########################################################################## Since Vote.pl is freeware, I do not provide much user support. Please try to find a solution to your problem by yourself by reading the readme.txt very carefully. But if you can't find the answer after doing so , or if you have found a bug, you should contact the developer. ########################################################################## END OF README.TXT