v0.05

Documentation and Release Notes




Contents

What is "iVote?"
Features in Current Release
Features to be Implemented
The Voting System
Installation of iVote
Configuration Options
Further Information
Release History

What is "iVote?"

In a nutshell, iVote is a very high-performance image voting/polling system.

It was designed from the ground up to take advantage of persistant database connections and the benefits of mod_perl under the Apache Web server. It should work anywhere Apache and Perl can; Unix or Windows. It works with MySQL currently as the RDBMS back-end, although changes to other databases is trivial, thanks to the use of DBI::DBD methods.

What you see above is the database administration screen to a new image voting system that I'm working on called "iVote." It came from the primordial ooze on March 10th, 2000 and has been steadily developed since that time. On March 19th, 2000 - a live demonstration version was made available for previewing (see below).

It all started when I wanted to create some simple CGI applications to make a "best desktop contest" feature for this Web site. As I started coding it, I realized that it could equally apply to photos for a photo competition as much as desktops - or any other image(s) where you wish to have people select, vote or choose their favorite. Think of it as a visual poll.

Features in Current Release

In short, it works and works well. In the year that it's been up and running so far, it has not crashed or lost data once. It has proving to be tamper-proof via the Web as well thus far. Database connectivity worked smoothly and quickly and the system in general required no hand holding.

Features to be Implemented

There are still many features that are either missing or on a sort of "wish list" of things to add to it. As it is released now, it is fully functioning - but may not have all the bells and whistles, or "creature comforts" as it were. Below is a list of things that are currently on this list of things to implement in future versions.

Watch for the announcements here and on Freshmeat .

The Voting System

So far, the rated voting system is in place and working nicely up to a +/- of two vote values. That is, if you set $vote_limit to 0, it functions as a normal one vote increment as in previous versions. If you set $vote_limit to 1, then you get a -1 or +1 vote and if you set $vote_limit to 2, then you get a range of -2, -1, +1 or +2 vote. Depending on what $vote_limit is set to (0, 1 or 2) the vote buttons on the voting page are automatically generated. Support for higher ranges is built-in, but you don't get the automatic button generation. To see this in action, try the current developmental version of iVote. You'll notice that rather than a simple option to "VOTE!" you get instead a "- / +" display for either decrementing the vote or incrementing it!

As it is, pre-v0.05 and in development, the new voting system has one major drawback. I just have to tackle a flaw introduced by this system in the vote counting and voting page to handle "negative votes." The problem is that in counting the "number of votes" the early code simply tallied up the total votes for a given entry. I had not planned for this new style of voting, so there's no field for "total votes" just one for the actual "score." So, if an entry gets a negative vote, not only does the score go down, but so does the "total number of votes" on an entry. This may be fine for your particular situation, but you need to be aware of it.

Unfortunately, this requires a fair bit of hacking to the v0.04 code, necessitating an additional field in the table - thereby making v0.05 on upwards probably incompatible with previous versions.

Installation of iVote

iVote currently connects to an MySQL database as "root" with no password. This should be changed to "nobody" with a password later on, which requires a user entry in the MySQL authentication/grant table. This will be part of an install script. For now, here's how to install it manually:

  1. Run the included "install_tables.sh" script to create db & tables
  2. Change the parameters at the top of the "iVote.pl" file accordingly
  3. Then just go to the normal URL and follow from there:
    http://localhost/cgi-bin/iVote.pl

From here, you can add your entries via the Web interface. Don't forget to populate the $images directory with two images for each entry of type $image_type. They must be in the form of "t_XX.YYY" and "f_XX.YYY" where "XX" is the entry ID and "YYY" is the same as specified by $image_type, like "jpg" for example.

Configuration Options

If you look at the iVote.pl script, near the top -- you'll see a section that looks similar to the piece included below. Each line represents an option that controls a feature of function of iVote. Below the sample you will find a a run-down of each variable; what it does, what the values are accepted and so on.

# Begin Configuration Section
#
my $home            = "/iVote";
my $images          = "$home/images";
my $buttons         = "$home/buttons";
my $cgi_base        = "/perl";
my $cgi_url         = "$cgi_base/iVote.pl";
my $file_path       = "/www/my.documentroot.com/docs/iVote";
my $db_name         = "ivote";
my $db_votes        = "voted";
my $db_entry        = "entries";
my $header_doc      = "$file_path/header.html";
my $footer_doc      = "$file_path/footer.html";
my $dump_page_title = "Welcome to iVote! ($version)";
my $dump_page_attrs = 'BGCOLOR = "#FFFFFF" TEXT="#000000"';
my $image_type      = "jpg";
my $rank_next       = "my.documentroot.com/somefile.html";
#
# Options, limits and toggles
#
my $singlevote      = 0;  # 0 = multiple, 1 = single
my $allowdelete     = 0;  # 0 = no, 1 = yes
my $cutoff          = 0;  # 0 = allow, 1 = disallow, "2000-7-24" would set date
my $vote_limit      = 1;  # Max change in vote value (0 = normal, 1 = +/-, 2 = --/++)
my $ivote_down      = 0;  # 0 = up, 1 = down
my $mailto_name     = 1;  # 0 = no link, 1 = link
my $blurb           = 1;  # 0 = no blurb shown, 1 = show blurb
my $max_rank        = 5;  # Max number of listings in ranking display
my $rank_head       = 1;  # 0 = no header, 1 = show header file
my $vote_style      = 0;  # 0 = default, 1 = clean (with "rankings" finish)
#
# End Configuration Section

$home ="text"

The directory in your Web filesystem that contains the included iVote resources and assets, such as interface buttons, header and footer files and graphics. It is specified as if in a URL, and not a full filesystem path.

$images ="$/home/text"

The sub-directory of $home where the images for the entries are stored. It is based on the root directory of $home as-is, but you can change that if you wish.

$buttons ="$home/buttons"

This specifies the sub-directory of $home where the interface buttons are stored. It is based on the root directory of $home as-is, but you can change that if you wish.

$cgi_base ="text"

The directory from which you're running iVote as a CGI, based on a URL and not a filesystem path. Sometimes this is "cgi-bin" but if you have mod_perl installed You might have a "perl" directory, which mod_perl utilizes as-is the default.

cgi_url$ ="$cgi_base/text"

Based on the $cgi_base above, this variable specifies the name of the iVote script. You can change this for multiple simultaneous polls, each having different options. It must be set so that if you have multiple polls, the various interface functions will return to the proper script instance.

file_path$ ="text"

The full filesystem path to where your document root points to for iVote's home.

$db_name ="text"

The name of the table in your database for this script instance that holds the data for the entries and votes. By creating more tables with different names and running multiple instances of iVote, you can change this variable and have multiple polls.

$db_votes ="text"

The name of the table in your database for this script instance that holds the data for the visitors that have voted. By creating more tables with different names and running multiple instances of iVote, you can change this variable and have multiple polls. This table should be cleared out to enable wide-open voting. As your visitors vote, this table gets populated with IP addresses to prevent voting multiple times on a particular poll if the $singlevote variable is set. See below.

$db_entry ="text"

The name of the table in your database for this script instance that holds the data for the entries. By creating more tables with different names and running multiple instances of iVote, you can change this variable and have multiple polls.

header_doc$ ="$file_path/header.html"

Built on the $file_path as the root, this specifies the HTML code to be used as a header for the voting page. This way you can customize what your visitors will see at the top of the page. A header graphic and a description of the page is included, but you may wish to explain how the vote works or include your own Website or company logo and formatting - or a navigation bar.

$footer_doc ="$file_path/footer.html"

As with the header above, this is built on the $file_path as the root, and specifies the HTML code to be used as the footer of every page. You can add your own navigation or copyright controls or your standard Web site footer.

The software itself inserts a copyright notice and a link back to the iVote Web site. You must not disable this function, or you will be breaking the license under which this software is distributed. You may, at your discretion change the font size to make it smaller, but it must be clearly legible when viewed in a browser.

$dump_page_title ="text ($version)"

The text that you wish to appear as the title of any iVote generated pages, including the voting page seen by your visitors. By default the version of iVote you're running is displayed, but you may wish to remove this for production use to increase security.

$dump_page_attr ='text'

This defines the page attributes of any iVote generated pages, including the voting page seen by your visitors. You can use standard HTML tags as you would use within a BODY tag. For example, BGCOLOR = "#FFFFFF" TEXT="#000000" Be careful with the quotes, as it could break the script. The variable is enclosed in single quotes, so you don't need to escape the double quotes.

$image_type ="text"

Through $image_type you can specify "gif" or "jpg" as the file types, among others. Currently, having mixed image file types is NOT supported.

$rank_next ="text"

If this variable is defined and you display the "rankings" then you will automatically get an "okay" button that points to the URL specified here. You should ONLY include the fully qualified URL and no HTML tags, etc.

$singlevote =0 | 1

This toggles the standard one-vote per visitor controls, preventing a visitor from voting more than once in a poll. It relies on the table $db_votes to exist for each iVote instance. See above $db_votes.

$allowdelete =0 | 1

Toggles whether or not deleting entries from the administration screen is allowed. Once a poll is set up, you should probably disable this to prevent accidental and irreversable deletions of entries and their vote counts.

$cutoff =0 | 1 | date

This multi-function variable controls the voting behavior of your poll. If it is set to "0" then voting is allowed on the voting page. Setting it to "1" will disable voting by not generating voting buttons on the voting page. Similarly, if you set the variable to a date in the format of "yyyy-mm-dd" then you can set a cutoff date for your poll, automatically. As of this date, the buttons for casting votes on the voting page are no longer generated, effectively emulating the "1" setting as above.

$vote_limit =0 | 1 | 2 | #

This controls the voting behavior of your poll in a major way. If left at it's default setting of "0" then your visitors may cast a vote for an entry, incrementing that entry's vote count by one. This is the most common form of voting, e.g. "pick your favorite." For this you should have $singlevote turned on, otherwise visitors could just vote for any entry multiple times, or multiple entries repeatedly, causing havoc.

If you set this variable to "1" then your visitors can cast a "down vote" or "up vote" for a particular entry (or set of entries, depending on $singlevote) by plus or minus one. If you disable multiple votes through $singlevote, then your visitors get one shot at promoting or demoting a single entry. If you allow multiple votes, then your visitors can adjust the entries at will, even multiple times. In future versions of iVote, this will probably controlled through the $db_votes table to allow only one "adjustment" per entry per user.

If this is set to "2" then you have the same functionality as for "1" above, but the range is extended to two votes per entry. That is, a range of -2, -1, +1 or +2. This allows your visitors more fine-grained control of "rating" and entry.

You may set this value higher, but iVote currently will only automatically generate voting buttons for the voting page up to "2" and not beyond! This will break your voting page. It is allowed so that you may manually hack up your own voting page instead of relying on the automatically generated one by iVote. Just added flexibility.

$ivote_down =0 | 1

Also added is the option to set $ivote_down so that when the script is run, you're told that the system is "temporarily unavailable" which is good if you have some unforseen issues with the database or system in general. It alerts your visitors, but effectively shuts down the system completely. It exits before anything else happens within the script, like database connections, etc. If you wish to disable voting, but allow yourself the option of adding or deleting entries (as you would when first setting up iVote) set "$cutoff = 1" instead.

$mailto_name =0 | 1

Toggles the hyperlinking via a "mailto:" of the entry's name. This is useful if you wish to hide people's Email addresses, cut down on clutter on the vote page or have a simple name based on an object like color, style or whatever - rather than a person's name.

$blurb =0 | 1

Toggles the displaying the the blurb on the voting page.

$max_rank =#

Another neat feature is the embeddable rankings display, which will show up to the top $max_rank entries, sorting by score in a descending manner. That is, the entry with the highest number of votes will be up top. This is useful if you want to embed this information within a Web page of your site.

$max_head =#

Enable the inclusion of your normal $header_doc file by setting this variable to "1" or turn it off (making rankings cleaner for embedding) by setting it to "0."

$vote_style =0 | 1

If this is set to "0" then you get the table version of the voting page, which has been the default/classic style. This shows the number of votes, the name w/link if enabled, voting buttons depending on your $vote_limit and a blurb if enabled through $blurb.

If this is set to "1" then you are presented with a very "clean" and stripped down version of the voting page, showing just the thumbnail version of the images -- which are linked so that clicking on them implies a casting a vote on that entry. Once your visitor clicks on the image, they are thanked for their vote and then the rankings display is called. If you are using this style, you should enable $rank_next with a URL so that your visitor can "move on" after casting their vote. You may or may not want to enable $rank_head to show your normal header in the rankings display and consider making $max_rank equal to the number of entries so that your visitors can see the rankings for all entries, rather than just the "top five" for example. If you have a lot of entries though, this may be inappropriate.

Further Information

See also the CHANGES file for additional information.

Release History

Here is the history of releases for this software.


All images are (C) 1994-2005 by Michael Holve