Documentation Voting Script

Thank you for your interest in our Voting Script. We recommend to read this documentation carefully.

Introduction

The script has been configured in a way that makes it ready to use. You only need to upload all script files to your web server. When you intent to edit the script you should do it step by step. After each change you should run the script to monitor the effects. Doing so enables you to know what change eventually causes an error.

Please make sure that the folder "logfiles" is writable (chmod 777).

The HTML templates of the script have been generated by the specifications of XHTML 1.0. HTML tags like <br> or <input> contain an ending slash (<br /> or <input type="text" name="field" />).

Functions and features

With this script you provide votes and polls on your website. Your visitors select one option and click the submit button to vote. The results will be displayed as graphical bars. The option can be displayed as radio buttons with text or images aside and as select menus.

To prevent manipulations the script uses the IP address of the user and/or Cookies. That is to make sure, every visitor votes only once. Please note that these two features can only try to prevent fraudulent votes.

Features at a glance

Top

Set up and configuration

The file "index.php" can be viewed as the configuration file of the script. It is possible to duplicate the file and set it up in a different manner. That enables you to run several scripts with the same script core. Because of that you need to install and - if required - license the script only once.

Besides the "index.php" the additional file "voting_image_options.php" has been set up. The poll's options are image paths instead of text. The visitors can choose between images instead of text options. Although, a unique name ($intern_vote_name) and "radio_image" as field type ($form_field_type) has been defined.

The following variables can be edited:

$vote_title     You can define an own title for each voting. The title will be displayed within the tag and as headline of the page. Example: <br /><br /> <span class="code">$vote_title = 'Favorite Color';</span> <br /><br /> </td> </tr> <tr valign="top"> <td class="codebold">$vote_text</td> <td>   </td> <td> Like the voting title you can define a text that appears on the page (i.e. a question or a description). Example: <br /><br /> <span class="code">$vote_text = 'What is your favorite color?';</span> <br /><br /> </td> </tr> <tr valign="top"> <td class="codebold">$vote_option[]</td> <td>   </td> <td> In this variable you can enter the vote options, which are selectable by the visitors. Each vote option gets an own variable. Example: <br /><br /> <span class="code"> $vote_option[] = 'Red';<br /> $vote_option[] = 'Green';<br /> $vote_option[] = 'Blue'; </span> <br /><br /> Instead of text you can display images as options. For example: <br /><br /> <span class="code"> $vote_option[] = './templates/smilies/1.gif'; $vote_option[] = './templates/smilies/2.gif'; $vote_option[] = './templates/smilies/3.gif'; </span> <br /><br /> Beside the paths you need to define "radio_image" as field type ($form_field_type). <br /><br /> </td> </tr> <tr valign="top"> <td class="codebold">$intern_vote_name</td> <td>   </td> <td> Enter here the intern vote name that will be used by the script. Please avoid white spaces and special characters. The intern name must be defined because the script uses a single log file for all votes. To separate all votes and results, the intern vote name has to be unique. Example: <br /><br /> <span class="code">$intern_vote_name = 'favorite_color';</span> <br /><br /> </td> </tr> <tr valign="top"> <td class="codebold">$form_field_type</td> <td>   </td> <td> It is possible to display two different types of option menus. To get a list of radio buttons enter "radio". Example: <br /><br /> <span class="code">$form_field_type = 'radio';</span> <br /><br /> Result: <input type="Radio" name="ddd" value="v"> Text <br /><br /> Instead of text next to the radio buttons you can display images. Set "radio_image" as field type. <br /><br /> <span class="code">$form_field_type = 'radio_image';</span> <br /><br /> Result: <input type="Radio" name="ddd" value="v"> <img src="./images/3.gif" border="0" alt="" align="middle" /> <br /><br /> To get a select menu (drop down/pull down menu) enter "select". Example: <br /><br /> <span class="code">$form_field_type = 'select';</span> <br /><br /> Result:<select name="name" size="1"> <option value="Red">Red</option> <option value="Green">Green</option> </select> <br /><br /> </td> </tr> <tr valign="top"> <td class="codebold">$bar_image_name</td> <td>   </td> <td> The results are displayed as graphical bars. This variable contains the name of the image that you want to use. All available bar images can be found in the folder "templates/images_voting". Example: <br /><br /> <span class="code">$bar_image_name = 'black.gif';</span> <br /><br /> You are free to create your own bar images and place them into the above mentioned folder. <br /><br /> </td> </tr> <tr valign="top"> <td class="codebold">$max_bar_width</td> <td>   </td> <td> The value of this variable will be used as maximum length of a bar (in pixels). <br /><br /> </td> </tr> <tr valign="top"> <td class="codebold">$check_ip_address</td> <td>   </td> <td> With this option you can define, whether the visitors are allowed to vote once or as much as they want. If you set this variable to "yes" the script reads the visitors IP address and checks the log file for that IP. In case it matches the visitor will be unable to vote. <br /><br /> </td> </tr> <tr valign="top"> <td class="codebold">$check_cookie</td> <td>   </td> <td> With this option you can define, whether the visitors are allowed to vote once or as much as they want. If you set this variable to "yes" the script sets a cookie after the user has voted. The script checks the cookie and prevents the visitor from voting. <br /><br /> </td> </tr> <tr valign="top"> <td class="codebold">$language</td> <td>   </td> <td> You can set here the language. Enter the abbreviation that also is used in the name of the language file in the directory "languages" (en in languages.en.inc.php and de in languages.de.inc.php). <br /><br /> </td> </tr> <tr valign="top"> <td class="codebold">$path['templates']</td> <td>   </td> <td> This variable contains the path to the HTML template folder. <br /><br /> </td> </tr> <tr valign="top"> <td class="codebold">$path['logfiles']</td> <td>   </td> <td> Enter here the path to folder that contains the log files. Please make sure that the folder is writable (chmod 777). <br /><br /> </td> </tr> <tr valign="top"> <td class="codebold">$tmpl['layout']</td> <td>   </td> <td> This variable contains the file name of the HTML templates which contain the layout. <br /><br /> </td> </tr> <tr valign="top"> <td class="codebold">$log['logfile']</td> <td>   </td> <td> This variables contain the name of the log file. Please make sure the file is writable (chmod 777). <br /><br /> </td> </tr> <tr valign="top"> <td class="codebold">$show_error_messages</td> <td>   </td> <td> The default value of this variable is "yes" so during the configuration process you will get error messages and hints that help you to install the script. Once the script configuration has been finished you can set these system messages off because it is not necessary to give extern visitors a view into the system. <br /><br /> </td> </tr> <tr valign="top"> <td class="codebold">$add_text</td> <td>   </td> <td> You can add further values, text, variables or other content to this variable. That content can be displayed in the HTML templates by using markers/placeholders within curly brackets { and }. <br /><br /> If you want to add your own values to the variable $add_text please follow the pattern from the example entries. <br /><br /> <pre> $add_text = array( 'txt_additional' => 'Additional', 'txt_more' => 'More' ); </pre> <p>The first part of each entry is the name of the placeholder. In case you want to use the value of txt_addition in your template enter the name of the entry with curly brackets - {txt_addition}. The name must not contain white spaces or special characters. Only allowed is the _ .</p> </td> </tr> <tr valign="top"> <td class="codebold"></td> <td>   </td> <td> <br /><br /> </td> </tr> </table> <p align="right"><a href="#top">Top</a></p> </div> <div class="chapter"> <a name="upload"></a> <h4>Upload script files</h4> <p>Create the following folder on your web server (with the most FTP clients you are able just to copy the hole script with all folders in one go):</p> <p class="code"> /voting_script/<br /> /voting_script/inc/<br /> /voting_script/languages/<br /> /voting_script/logfiles/<br /> /voting_script/templates/ </p> <p>Copy all files to their corresponding folder. Image files (.gif, .jpg, .png) have to be uploaded in binary mode. Every other files have to be uploaded in ASCII mode (text mode).</p> <p>Please note: The folder "templates" contains a folder with images.</p> <p align="right"><a href="#top">Top</a></p> </div> <div class="chapter"> <a name="logfiles"></a> <h4>The Log File - logfiles/log.txt</h4> <p>The folder "logfiles" and the file "log.txt" need to be writable (chmod 777).</p> <p align="right"><a href="#top">Top</a></p> </div> <div class="chapter"> <a name="include"></a> <h4>Implementing The Voting Script</h4> <p>You can implement the script in two different ways.</p> <h4>Direct Linking</h4> <p>You can set a direct link to the script and use it as an independent page. You can customize the HTML template to fit in your website layout.</p> <h4>I-Frame (HTML)</h4> <p>With the HTML tag <iframe> you can include the script in an existing page. Place the <iframe> tag where you want it to appear within the page: Example:</p> <p class="code"><iframe name="voting" src="./voting.php" width="400" height="300" frameborder="0"></iframe></p> <p align="right"><a href="#top">Top</a></p> </div> <div class="chapter"> <a name="html"></a> <h4>HTML template customization </h4> <p>The directory "templates" contains the files for the layout. You can use HTML and CSS to customize the layout as you wish.</p> <p>In case you are using a WYSIWYG editor like Dreamweaver, Frontpage or NetObjects please make sure that the software does not make any changes by itself.</p> <p>The template files contain markers with { and } like: {txt_script_name}. These markers will be replaced by its counterparts from the language file "languages/language.en.inc.php". You are free to edit that file and change the words and phrases. You are also free to replace the markers within the template files by real words or put those markers to other positions within the template file. And you are also able to enhance the language file by using the given pattern. </p> <p>Amongst those word markers exist the so called Loops. Similar to HTML tags the two parts (<LOOP …>…</LOOP>) must not be separated. If you want to alter the position within the template you move the hole block.</p> <p>The template "voting_image_options.tpl.html" has been created to display images as options. It contains image tags with the placeholder {label} as file name and path within the LOOP block.</p> <p align="right"><a href="#top">Top</a></p> </div> <div class="chapter"> <a name="support"></a> <h4>Support</h4> <p>You will find answers to your questions and solutions for your problems with the script in our <a href="http://www.stadtaus.com/forum/" target="_blank">support forum</a>.</p> <p align="right"><a href="#top">Top</a></p> </div> <div class="chapter"> <a name="license"></a> <h4>License Information</h4> <p>You can download the script without registration und use it for free. If you want to use the script without the reference to STADTAUS.com, you can purchase the script online.</p> <ol start="1" type="1"> <li>You may re-distribute the script license to a third party.</li> <li>You may make your own pricing.</li> <li>A script license applies to a single domain.</li> </ol> <p>More scripts at STADTAUS.com:</p> <ol> <li>Online Appointment Planner</li> <li>Image Gallery Script</li> <li>Formmail Script</li> <li>Tell A Friend Script</li> <li>Google Dance Tool</li> <li>Download Center Lite</li> <li>Guestbook Script</li> </ol> <p>Please also visit our project MetaCollection, a guide for webmasters and developers who are in search of CGI, Perl, or PHP script archives.</p> <p><a href="http://www.metacollection.com/">http://www.metacollection.com/</a></p> <p align="right"><a href="#top">Top</a></p> </div> </form> </body> </html>