Poll Module Designby Mark DalrympleI. Essentials
II. IntroductionPeople like to offer their opinions, and one of the easiest ways to do that is to vote in an opinion poll. The Poll module lets you construct polls that are active for a range of dates, specify the choices the users can make, whether to require the voter to be a registered user, and display the current results. Since site designers like to change things, all of the user-accessible portions of the polls use the ACS style mechanism along with an API for controlling the display.Polls are for multi-item, single-choice, single-vote opinion polls. They're not designed to do anything else e.g. M items to choose from and the user can choose N of them. Site Publishers have a set of tools at their disposal for creating and modifying the polls, as well as a set of anti-abuse tools for removing votes made by ballot-box stuffers. III. Historical ConsiderationsThe Poll Module was originally a client-driven project which was integrated into ACS. The flexibility of display as well as the anti abuse tools were driven by client needs.VI. Data Model DiscussionThree tables are used. One to hold the polls, one to hold the choices the user can make for each pool, and the actual set of votes users have made.
create table polls (
poll_id integer not null primary key,
name varchar(100) not null,
description varchar(4000),
start_date date,
end_date date,
require_registration_p char(1) default 'f' check (require_registration_p in ('t','f'))
);
Any number of polls can be active at a time. Whether a poll is active
depends on the start_date and end_date. To disable a poll, use the
admin pages to set the end_date into the past or the start_date into
the future. Name is a short name used to label pages and links, while
description is a longer description that is displayed with the votes
and results.
require_registration_p indicates whether a user has to be a registered user (have an entry in the users table) before they can vote. Making registration required implies that the user can only vote once for each poll. If registration is not required, we can't distinguish one vote from another, so users can vote any number of times for each poll. Why not use the IP address to control whether someone can vote more than once, even if they're not a registered user? Unfortunately there's not a 1-to-1 mapping of IP addresses to people. IP masquerading hides many people behind one IP address (meaning we would prevent legal votes), and users behind massive proxy systems (such as AOL users) can get a random IP address on each request, (meaning obnoxious folks can vote multiple times).
create table poll_choices (
choice_id integer not null primary key,
poll_id references polls not null,
label varchar(500) not null,
sort_order integer
);
This holds the choices that users can vote on. The sort_order column
controls the order of presentation for the choices associated with a
given poll.
create table poll_user_choices (
poll_id references polls not null,
choice_id references poll_choices not null,
-- user_id can be NULL if we're not requiring registration
user_id references users,
ip_address varchar(50) not null,
choice_date date not null
);
Each user vote is recorded here. If there is no user ID (meaning that
the voter is not a registered user), the user_id in this table is
NULL. Even though we don't use the IP address to control user
voting, we keep it around in case some obnoxious person stuffs
the ballot box. We can go into SQL*Plus and undo the damage, or
use some of the admin pages to clean up after the evildoer.
There are also sequences for poll identifiers and poll choice identifiers. There are three indices used to speed up queries: create index poll_choices_index on poll_choices(poll_id, choice_id); create index poll_user_choice_index on poll_user_choices(poll_id); create index poll_user_choices_choice_index on poll_user_choices(choice_id); VII. Legal TransactionsThe Poll tables have referential integrity (foreign key constraints), thereby preventing situations where a poll item doesn't have an owning poll or a vote doesn't have a corresponding poll or item.Administrative TransactionsThe administrative pages have complete control over the data in the database.Creating a new poll:
insert into polls
(poll_id, name, description,
start_date, end_date, require_registration_p)
values
(...)
Editing an existing poll:
update polls set
name = :name,
description = :description,
start_date = :start_date,
end_date = :end_date,
require_registration_p = :require_registration_p
where
poll_id = :poll_id
Deleting a poll: delete from poll_user_choices where poll_id = :poll_id delete from poll_choices where poll_id = :poll_id delete from polls where poll_id = :poll_idCreating a new poll choice:
insert into poll_choices
(choice_id, poll_id, label, sort_order)
values
(...)
Changing poll item sort order:
foreach i [array names choice_order] {
...
update poll_choices
set sort_order = :choice_order
where choice_id = :i
}
Deleting a poll choice: delete from poll_choices where choice_id = :choice_idDeleting anonymous duplicate votes (based on IP address):
delete from poll_user_choices
where poll_id = :poll_id
and user_id is null
and (choice_id, ip_address) in
(select choice_id, ip_address
from poll_user_choices
where user_id is null
group by choice_id, ip_address
having count(*) >= :deletion_threshold)
End User TransactionRecording a Vote:
set insert_sql "insert into poll_user_choices
(poll_id, choice_id, user_id, choice_date, ip_address)
values
(...)
VIII. Templates and CustomizationThe templates for the user-accessible pages are stored in /template/poll. The templates are named "template-name.plain.adp" and "template-name.fancy.adp". The ACS style mechanisms choose which template to use.There are two categories of templates in use: those that display the polls, the choices, and the results; and those that say "you did something wrong".
Customization FunctionsTo fully customize Poll template, designers need to know how to invoke functions as well as how to put variables into<%= $variable > units. There are three
functions provided that take the database-driven output (e.g. the currently
active polls) and some customization information and then return a blob of
html for inclusion. Designers would do something like
<%= [poll_display -item_start "<tr><td>" -item_end "</tr>" -style_start "<font color=white><i>" -style_end "</i></font>" $choices] %>
So why not use
To allow customization of each line of database-driven output, say whether to
arrange the available choices in an Instead, three functions are provided. Each takes optional parameterized arguments and a required blob of data which is passed to the template ADP by the Tcl pages in /poll.
Use this function to control the display on the "index" page (the top-level page you get when going to /poll). If invoked without optional arguments, the polls are arranged in an unordered list. The "polls" variable is provided to the index template. poll_display ?optional arguments? choices
Use this function to control the display of an individual poll. If invoked without optional arguments, the poll choices are arranged in an unordered list. The "choices" variable is provided to the one-poll template. This code:<ul> </ul>results in this:While this:<table border=3 text=white bgcolor=black> <%= [poll_display -item_start "<tr><td>" -item_end "</tr>" -style_start "<font color=white><i>" -style_end "</i></font>" $choices] %> </table>results in this: poll_results ?optional arguments? results
Use this function to control the display on the "results" page. This function is a wrapper around gr_sideways_bar_chart which simplifies the API. This coderesults in this:While this: IX. Configuration/ParametersThere are no additional configuration parametersX. Acceptance TestsProbably should just include the existing acceptance for the Poll Module. I don't know where that's kept these daysXI. AuthorsThe initial creation of the Poll module was by Ben Adida. Mark Dalrymple extended Ben's work and added the templating facilities. Philip Greenspun added the voting abuse clean-up features.markd@arsdigita.com.com |
|
40