NAME

Poll - Perl extension to build web polls

DESCRIPTION

        Perl module to build and run web polls with built-in administrative capabilities.

SYNOPSIS

        use Poll;
        my $poll = new Poll;
        $poll->path('/system/path/to/data/directory');

# Voting and returning poll results

        $poll->vote($ans_key);
        $html = $poll->get_html();
        print "Content-type: text/html\n\n";
        print $html;

#- Create a new Poll -#

        $poll->question('Should Trent Lott change his barber?');
        $poll->add_answers( "Yes", "No", "Who's Trent Lott?", etc );
        $poll->create();

USAGE

        $poll->path($directory);

Above system directory must me chmod'ed 666. Also, it needs to contain the files qid.dat & questions.dat as world writable. The graphic to create the default percentage graph also goes in this directory.

#- Retrieving Poll Data -#

        $html = $poll->get_html(<pollid>);

Returns default html of specific poll results. With no parameter the script returns the latest poll.

-OR-

        $poll_id = $poll->get(<pollid>);

This command retrieve the specified poll but returns the poll id rather than html. Using this method the poll objects can be accessed for customized formatting of output. Example below:

        $poll_id = $poll->get(<pollid>);
        print $poll->question();
        foreach ($poll->rkeys) { 
                print $poll->answers->{$_}." = ".$poll->votes->{$_}."<BR>";
        }

#- Voting on Latest Poll -#

        $poll->vote($ans_key);

Takes hash key for appropriate $poll->answers. Keys can be gotten via $poll->akeys. Example below:

        foreach ($poll->akeys) {
                print "Answer = ".$poll->answers->{$_}."\n";
                print "Key = ".$_."\n";
        }

#- Create a new Poll -#

        $poll->question('Should Trent Lott change his barber?');
        $poll->add_answers( "Yes", "No", "Who's Trent Lott?", etc );
        $poll->create();

This is pretty straight-forward. There can be an infinite amount of answers for any giver question but be aware of how it may look when outputted to html. The create() command builds the appropriate poll files in the $poll->path() directory.

#- To get a hash array of all polls to date -#

        my %all_polls = $poll->list();
        foreach (keys %polls) {
                print qq|<A HREF="$ENV{SCRIPT_NAME}?poll_id=$_">$all_polls{$_}</A><BR>|;
        }

This would print out a list of polls with links that could be followed to view the results of that poll.

DOCUMENTATION

Documentation and code examples for Poll.pm can be located at http://www.straphanger.org/~mgammon/poll

The code examples located at the above url handle both administrative and standard polling routines. There are currently no manpages for this module but I will be working on them and post a revision when available.

PREREQUISITES

Perl 5.004

May work with earlier versions but hasn't been tested. Feel free to email me if you find it does.

AUTHOR

Mike Gammon <mgammon@straphanger.org>

perl(1).

cpanm WWW::Poll

perl -MCPAN -e shell
install WWW::Poll