HTML::Ballot::Trusting - HTML-template-based insercure multiple-choice ballot
# Create the poll
use HTML::Ballot::Trusting; $HTML::Ballot::Trusting::CHAT = 3; my $p = new HTML::Ballot::Trusting { ARTICLE_ROOT => 'E:/www/leegoddard_com', URL_ROOT => 'http://localhost/leegoddard_com', RPATH => 'E:/www/leegoddard_com/vote/results.html', TPATH => 'E:/www/leegoddard_com/vote/template.html', QPATH => 'E:/www/leegoddard_com/vote/vote.html', CPATH => 'E:/www/leegoddard_com/CGI_BIN/vote.pl', ASKNAMES => 1, QUESTIONS => [ 'Why?', 'Why not?', 'Only for £300.' ] }; $p->create();
A simple module for inseucre web ballots.
This is a very beta version that will mature over the next week or so. Please let me know how it breaks.
Features:
no test is made of who is voting, so users may vote any number of times, or may even vote (and surely will) thousands of times using a "LWP" hack.
a HTML page of voting options and one of the results of votes so far is generated from a single HTML template, and it is in these pages that ballot status is maintained, so no additional file access is required.
HTML output into the template is minimal, but all unique entities are given a "class" attribute for easy CSS re-definitions.
simple bar charts of results are generated using HTML.
users may submit a comment with thier vote, though no connection between the value of the vote and the user is recorded
users' IP addresses may be recorded, and displayed, and a chart of the IP addresses from which communication has been received the most may be displayed.
In future these features may be added:
A more secure version is being considered, which uses simple e-mail authentication of users, sending ony one voting password to any e-mail address: this may appear as "HTML::Ballot::MoreCynical".
This may be extended to include a ballot `time out'.
Options to have graphs based on single-pixels, or using the "GD" interface will arrive some time in the future.
Construct an HTML template that can be used to generate the question and answer pages. Where you wish the questions and answers to appear, insert the following element:
<TEMPLATEITEM name='QUESTIONS'></TEMPLATEITEM>
The template should at least define the CSS representation for votehighscorebar and votebar as having a coloured background, or you will not be able to view the results' bar graph. See "CSS SPECIFICATION" for more details on other CSS classes employed.
votehighscorebar
votebar
Other functions may be included as below. Note that TEMPLATEITEMs may require some minimal content of at least a space character, I'm not sure, I'd better check.
TEMPLATEITEM
If you wish to allow a user to submit a comment with their vote, include the following element:
<TEMPLATEITEM name='COMMENT'> This is what voter's have said: </TEMPLATEITEM>
Unlike the QUESTIONS TEMPLATEITEM, any text you include in this block will be reatained at the top of a list of users' comments.
QUESTIONS TEMPLATEITEM
If you wish to have the result page display a list of the names entered by voters, also include:
<TEMPLATEITEM name='VOTERLIST'> Here is the voterlist... </TEMPLATEITEM>
This acts in the manner of the COMMENT TEMPLATEITEM, above.
COMMENT TEMPLATEITEM
If you wish to have the result page display a list of the most frequently-posting IP addresses, include:
<TEMPLATEITEM name='IPCHART'> <H2>Top IP Addresses To Post To This Ballot</H2> </TEMPLATEITEM>
To this, the module will add a SPAN of HTML that lists the top posters. Anything before that span (in this example, the H2 element) will remain.
SPAN
H2
Initiate the ballot by constructnig an HTML::Ballot::Trusting object and calling create method upon it in a manner simillar to that described in "SYNOPSIS".
create
In response, you should receive a list of the locations of files used and dynamically created by the process.
Several global variables exist as system defaults. Most may be over-riden using the constructor (see the sections ARTICLE_ROOT, URL_ROOT, STARTGRAPHIC, SHEBANG in "CONSTRUCTOR (new)".>
ARTICLE_ROOT
URL_ROOT
STARTGRAPHIC
SHEBANG
THe number of items to include in the IP chart of frequent posters
Requires a reference to the class into which to bless, as well as a hash (or reference to such) with the following key/value content:
the root, in the filesystem, where these HTML pages begin - can over-ride the global constant of the same name;
the root, on the internet, where these HTML pages begin - can over-ride the global constant of the same name;
an array of questions to use in the ballot
Path at which the HTML Template may be found
Path at which to save the HTML ballot Questions' page
Path at which to save the HTML Results page
If you do not use the SUBMITTO attribute (below), you must use this: Path at which to save a dynamically-generated perl script that processes form submissions. Obviously must be CGI accessible and CHMOD appropriately.
SUBMITTO
If you do not use the CPATH attribute (above), you must use this: Path to the script that processes submission of the CGI voting form
CPATH
Represents the Shebang line you place at the start of your perl scrpts: set this to over-ride the default value taken from the global constant scalar of the same name. Could adjust this to suss the path from Config.pm or even MakeMaker, if it came to it, but time....
Config.pm
MakeMaker
Maximum acceptable length of text comments.
Set if users should supply their name when voting.
If ASKNAMES (above) is defined, this value may be set to limit the possible length of a name.
ASKNAMES
Creates the HTML voting page.
Accepts: just the calling object: all properties used should be set during construction (see "CONSTRUCTOR (new)").
If the page contains a COMMENT TEMPLATEITEM, will include a text box in the voting page, to allow users to submit comments. Setting COMMENTLENGTH to a value when calling the constructor will restrict the length of acceptable comments.
COMMENTLENGTH
If the page contains a <VOTERLIST TEMPLATEITEM>, this will be updated with the name supplied by the user.
Returns: the path to the saved HTML question document.
See also "USE" and "CSS SPECIFICATION".
The action attribute of the FORM element is set to the CGI environment variable, SCRIPT_NAME (that is, the location of this script).
action
FORM
SCRIPT_NAME
Form elements are simply seperated by linebreaks (BR): use CSS to control the layout: the radio-button HTML elements are set to be class voteoption; the SUBMIT button element is set to be class votesubmit.
BR
voteoption
SUBMIT
votesubmit
HTML is used to create bar charts, but this should be easy to replace with a GD image, or a stretched single-pixel. Each question is given a TEMPLATEITEM element, and results will be placed within by the vote method (see "METHOD vote").
GD
vote
See also "CSS SPECIFICATION".
Casts a vote and updates the results file.
Accepts:
1. the question voted for, as defined in the HTML vote form's INPUT/value.
INPUT
value
2. optionally, a user-submitted comment.
3. optionally, a user-submitted name.
The following CSS classes are employed (and expected) in the HTML:
the TD within the chart (above) that represent volume of votes cast. These must be defined for results to be visable, though if the NOHTML flag is set in the constructor, a red background will be used as well.
TD
NOHTML
<style type="text/css"> <!-- .votebar { background-color: #990000} .votebar { background-color: red} --> </style>
chart
the right-most TD, containg the chart TABLE
TABLE
voteresults
the layer of the whole results section;
votequestion
the left-most TD, containing the text representing the questions;
votescore
the centre-left TD, containing the text representing the number of votes recieved by the item;
votepc
the centre-right TD, containing the text representing the percentage of vote obtained
voteoptionradio
The radio button in the question-asking phase.
voteoptiontext
The text associated with radio buttons, as above.
voteoptionsubmit
The submit button as above.
votecommenttextbox
The text box used to accept comments.
votecommenttext
Text associated with the textbox (above).
votecommentdate
The date SPAN of a comment.
voteusrname
The SPAN that covers a user-entered name in the report.
listvoteusrname
The SPAN that covers user-entered names and IP address in list context
The SPAN that covers the user name within listvoteusrname.
voteusrip
As above, but for IP address.
ipchartitem
An item in the IP chart.
HTML::EasyTemplate.
Lee Goddard (LGoddard@CPAN.org)
This module and all associated code is Copyright (C) Lee Goddard 2001. All rights reserved.
This is free software and may be used under the same terms as Perl itself with the added condition that it not be used in a commercial setting, to make money, either directly or indirectly, without the advanced and explicit prior signed permission of the author.
5 POD Errors
The following errors were encountered while parsing the POD:
Non-ASCII character seen before =encoding in '£300.''. Assuming CP1252
'=item' outside of any '=over'
You forgot a '=back' before '=head1'
You forgot a '=back' before '=head2'
To install HTML::Ballot::Trusting, copy and paste the appropriate command in to your terminal.
cpanm
cpanm HTML::Ballot::Trusting
CPAN shell
perl -MCPAN -e shell install HTML::Ballot::Trusting
For more information on module installation, please visit the detailed CPAN module installation guide.