ACS Poll Requirements

I. Introduction

The following is a requirements document for the ACS Poll module.

II. Vision Statement

People like to offer their opinions, and one of the easiest ways to do that is to vote in an opinion poll. The Poll module allows publishers to construct simple one-vote opinion polls. These polls can be used a springboard for discussion (such as Slashdot), construction of a consumer opinion database (such as Deja.com), or just for fun (such as the side bar polls on DrWeil.com).

III. System/Application Overview

The Poll module consists of:

The Polls Themselves
- A Poll name
- A range of dates that the poll is valid (e.g. asking who your favorite presidential candidate is after the election doesn't make much sense)
- The poll's choices
- Whether the poll is limited to registered users
Web-based Administrative Tools for controlling the poll parameters specified above, as well as detecting and correcting ballot-box stuffing
User accessible pages for viewing and voting on polls
User accessible pages for viewing the current poll results
Templated presentation and flexible display API for easy publisher customization of polls and poll result display.

IV. Use-cases and User-scenarios

The Poll module is intended for the following classes of users, which may or may not overlap:

Publishers Use the admin pages to create and update a poll
Designers Modify the page templates and use the display API to customize the poll and poll result presentation
End-users Vote in the polls

Poll Creation

Paulette Publisher, manager of the Apollo Philharmonic web site, decides that an opinion poll is appropriate for their upcoming "Hear Your Favorite Baroque Composer" series. Using the admin pages, Paulette creates a poll named "Baroque Favorites" with a paragraph of HTML that describes the poll's objective in choosing a favorite composer. She also sets a starting and termination date for the poll. A starting date is used because the Baroque Favorites program hasn't been announced yet. A termination date is used because voting in the poll after the concert series content has been decided won't make any difference.

Poll Customization

Debbie Designer is responsible for the graphical look of the Apollo Philharmonic web site. She modifies the Poll module's template files so that they match the look and feel of the rest of the site. Using the Poll display API, she changes the poll's presentation from a list of choices to a fancy table.

Poll Use

Eduardo Enduser is a music enthusiast that lives in the nearby town of Vandergrift. He sees the reference to the poll on the Apollo Philharmonic home page. He views the poll, offers his choice, and sees the results. Seeing that his favorite composer is in the lead, he purchases season tickets online via the E-Commerce module.

V. Related Links

Poll Module Design Document
ACS Styles (ad_return_template etc)
Test Plan (Not available as of 8/29/00)

VI.A Requirements: Data Model

10.10 Polls
(All of these items are entered by the publisher using the administrative UI)
10.10.10 Each poll has a unique identifier
10.10.20 Each poll has a name, which will used in constructing a list of available polls.
10.10.30 Each poll can have an optional description which will be used when displaying the poll.
10.10.40 Each poll can have an optional start date, before which the poll is not available to users
10.10.50 Each poll can have an optional end date, after which the poll is not available to users
10.10.60 Each poll can be designated as being available only to registered users.
10.20 Poll Choices
(All of these items are entered by the publisher using the administrative UI)
10.20.10 Each poll can have an arbitrary number of choices
10.20.20 Each poll choice has a label which is used during poll display
10.20.30 The order of presentation of the choices is controllable by the publisher.
10.30 Poll Votes
(These items are entered by users when they make poll choices. They are viewed by the poll results UI. They can be manipulated using the administrative UI)
10.30.10 Individual votes will be stored
10.30.20 If the voter is a registered user, the user's ID will be stored with the vote
10.30.30 The voters IP address will be recorded. The IP address will be used to detect possible voter abuse.
10.30.40 The date and time of the vote will be recorded.

VI.B Requirements: Administration Interface

The user interface is a set of HTML pages that are used to control all data aspects of Polls. Visual aspects are controlled by templates and the Poll API.

20.10 Poll Creation and Maintenance
20.10.10 Publishers can create polls, set their name and description.
20.10.20 Publishers can set the optional start date and optional ending date
20.10.30 Publishers can change the poll's name, description, starting and ending dates
20.20 Poll Item Creation and Maintenance
20.20.10 Publishers can create poll choices and set the visible label.
20.20.20 Publishers can modify poll choices by changing the visible label.
20.20.30 Publishers can change the order in which poll choices are displayed.
20.30 Abuse detection and correction
20.30.10 Publishers can use UI pages that show possible voter abuse (ballot box stuffing)
20.30.20 Publishers can use UI pages to correct voter abuse by deleting votes

VI.C Requirements: Voting

30.10 Voting
(These items are performed by end-users using HTML pages)
30.10.10 Users can see a list of available polls.
30.10.20 Polls are considered "available" if the current date is between the poll's start and end dates (if they exist), and if the user is a registered user and the poll requires registration.
30.10.30 Users can select an available poll to vote on
30.10.40 If the user has already voted on this poll, they are told that they cannot vote again.
30.10.50 The poll and its choices are presented to the user. The poll choices are ordered according to publisher specification.
30.10.60 The user can select one choice and submit the vote
30.10.80 The user's choice, their IP address, and the date and time of the vote are recorded
30.10.90 The user can then view the current poll results
30.10.100 The user can also view the current poll results without having to vote.

VI.D Requirements: Flexibility of Display

The presentation of available polls, polls and their choices should separated from any procedural / database logic necessary to generate them.

40.10 API

40.10.10 There should be an easy to use, yet flexible API for generating the HTML used for presenting the list of available polls, the polls and their choices, and the poll results
40.10.20 For generating the HTML for the list of available polls (the "front page"), publishers should be able to specify the type of item (e.g. list item vs table row), the style, the style and wording to be used when registration required to vote, and the style and wording used when there are no active polls.
40.10.30 For generating the HTML for the display of a single poll, publishers should be able to specify the type of item (e.g. list item, table row, or simple paragraph breaks between items), the style each choice should be in, as well as the style and wording used when there are no choices for a poll.
40.10.40 For generating the HTML for the display of a single poll's bar-chart results, publishers should be able to specify the color and size of the bars, whether to display numeric values, and whether to display a scale
40.20 Templates
(The Poll module uses the "classic" ACS templating mechanism)
40.20.10 The HTML used for presenting the Poll module's pages will be ADP pages living in the ACS /templates/poll directory
40.20.20 The Poll API and variables passed to the page will be used for generating the dynamic (database-generated) HTML

VII. Implementation Notes

The Poll module can easily become a highly-trafficked part of a site, especially if a controversial question is posed. The poll module should be able to quickly and efficiently handle large number of votes.

VII. Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	08/29/2000	Mark Dalrymple

markd@arsdigita.com

Last modified: $Date: 2001/01/19 21:36:46 $