Documentation Voting Script

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

Function   Configuration   Upload   The Log File   Include The Script   HTML Templates   Support   License Information

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 <title> tag and as headline of the page. Example:

$vote_title = 'Favorite Color';

$vote_text     Like the voting title you can define a text that appears on the page (i.e. a question or a description). Example:

$vote_text = 'What is your favorite color?';

$vote_option[]     In this variable you can enter the vote options, which are selectable by the visitors. Each vote option gets an own variable. Example:

$vote_option[] = 'Red';
$vote_option[] = 'Green';
$vote_option[] = 'Blue';

Instead of text you can display images as options. For example:

$vote_option[] = './templates/smilies/1.gif'; $vote_option[] = './templates/smilies/2.gif'; $vote_option[] = './templates/smilies/3.gif';

Beside the paths you need to define "radio_image" as field type ($form_field_type).

$intern_vote_name     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:

$intern_vote_name = 'favorite_color';

$form_field_type     It is possible to display two different types of option menus. To get a list of radio buttons enter "radio". Example:

$form_field_type = 'radio';

Result:  Text

Instead of text next to the radio buttons you can display images. Set "radio_image" as field type.

$form_field_type = 'radio_image';

Result:  

To get a select menu (drop down/pull down menu) enter "select". Example:

$form_field_type = 'select';

Result:

$bar_image_name     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:

$bar_image_name = 'black.gif';

You are free to create your own bar images and place them into the above mentioned folder.

$max_bar_width     The value of this variable will be used as maximum length of a bar (in pixels).

$check_ip_address     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.

$check_cookie     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.

$language     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).

$path['templates']     This variable contains the path to the HTML template folder.

$path['logfiles']     Enter here the path to folder that contains the log files. Please make sure that the folder is writable (chmod 777).

$tmpl['layout']     This variable contains the file name of the HTML templates which contain the layout.

$log['logfile']     This variables contain the name of the log file. Please make sure the file is writable (chmod 777).

$show_error_messages     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.

$add_text     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 }.

If you want to add your own values to the variable $add_text please follow the pattern from the example entries. 

$add_text = array(

                    'txt_additional' => 'Additional',
                    'txt_more'       => 'More'

                  );

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 _ .
   

Top

Upload script files

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):

/voting_script/
/voting_script/inc/
/voting_script/languages/
/voting_script/logfiles/
/voting_script/templates/

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).

Please note: The folder "templates" contains a folder with images.

Top

The Log File - logfiles/log.txt

The folder "logfiles" and the file "log.txt" need to be writable (chmod 777).

Top

Implementing The Voting Script

You can implement the script in different ways.

Direct Linking

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.

I-Frame (HTML)

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:

<iframe name="voting" src="./voting.php" width="400" height="300" frameborder="0"></iframe>

SSI Include

In case your server supports SSI (Server Side Includes) you can include the script with following line:

<!--#include virtual="./voting.php?$QUERY_STRING" -->

Replace "./voting.php" with the correct path to your script. It is important to leave the parameter "?QUERY_STRING".

If that doesn't work please rename your HTML file into .shtml. Please ask also your webspace provider, whether your server supports SSI.

Important: In order to get back after voting to the site where the vote is included, you need to put a hidden form field into the HTML template:

<input type="hidden" name="vote_redirect" value="http://www.your-server.com/seite.shtml" />

The line needs to be directly below the form tag:

<form name="vote" action="{script_self}" method="post">
  <input type="hidden" name="vote_redirect" value="http://www.your-server.com/seite.shtml" />

Replace the "http://www.your-server.com/seite.shtml" with the URL to your page.

PHP Include

You can include the script in an existing PHP file by using the include() instruction:

<?php

include('./voting.php');

?>

Replace "./voting.php" with the correct path to your script.

Top

HTML template customization

The directory "templates" contains the files for the layout. You can use HTML and CSS to customize the layout as you wish.

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.

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.

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.

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.

Top

Support

You will find answers to your questions and solutions for your problems with the script in our support forum.

Top

License Information

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.

  1. You may re-distribute the script license to a third party.
  2. You may make your own pricing.
  3. A script license applies to a single domain.

More scripts at STADTAUS.com:

  1. Online Appointment Planner
  2. Image Gallery Script
  3. Formmail Script
  4. Tell A Friend Script
  5. Google Dance Tool
  6. Download Center Lite
  7. Guestbook Script

Please also visit our project MetaCollection, a guide for webmasters and developers who are in search of CGI, Perl, or PHP script archives.

http://www.metacollection.com/

Top