[ move all comments to PollPluginDev ]
This is a plugin that handles Polls:
- multiple polls (each one has its id)
- the users are "anonymous" (their vote is stored with an MD5 id)
- all votes are attached at the end of a topic (the same or a different one)
- you can vote several issues together
- you can show the cumulative rank (e.g. you can have 3 preferences counted together)
- only last vote of each user's is counted
- each user can change his/her mind and vote again
- or even cancel his/her vote (by doing an empty vote, if allowed)
- you can select the allowed voters with (ALLOW/DENY)TOPICVOTE
- all the ex-aequo winners can be
- collected together (I like it this way )
- or listed separately
How to set-up a Poll
- Define an html FORM with
action=".../poll/<web>/<topic>"
- the
web
and topic
parameters sets where the votes should be accumulated
- if you want to collect votes at the end of the same topic use
action=".../poll/%WEB%/%TOPIC%"
- each value of the form is appended to the topic as a table row (a "vote"):
- the first 3 columns are FIXED, the remaining ones contain the vote values
| <pollId> | <date> | <userId> | item1 | item2 | ... |
- the topic collecting the votes should follow the syntax:
here goes the topic normal text
<!--TWikiPoll-->
here goes the vote definition
<!--TWikiPoll-->
here go all the votes
- a vote definition is written this way:
- BEWARE: this is the only valid syntax for multidimensional polls
| <pollId/> | <pollDate/> | <pollUserId/> | <pollItem1/> | <pollItem2/> | <pollItem3/> |<pollItem4/> | ... |
- if you are interested only in collective results (i.e. rank all the values together) you can use the shorter notation (note the missing final "|")
| <pollId/> | <pollDate/> | <pollUserId/> | <pollItems/>
How you show the results
When you type |
You get |
%POLLRESULTS% |
a table of counts, sorted in decreasing count order |
%POLLRESULTS{<args>}% |
a table of counts, sorted in decreasing count order |
Parameters
The POLLRESULTS tag accepts the following parameters:
Parameter |
Default value |
Description |
id |
'id0' |
needed to vote different issues in the same page |
web |
%WEB% |
web containing the topic collecting the votes |
topic |
%TOPIC% |
topic collecting the votes |
limit |
5 |
number of "winners" shown |
itemformat |
'$item' |
how the item voted is formatted |
countformat |
'$count' |
how the count is formatted |
percformat |
'$perc%' |
how the percentage is formatted |
lineformat |
see below |
how a line is formatted |
exaequosep |
', ' |
separator of ex-aequo (same-count) votes |
header |
see below |
header of the result table |
join |
'on' |
if 'on' then all ex-aequo are collected in a single row |
The default value of:
| $i{0} | $c{0} ($p{0}) |
| *The winners are* | *Votes* |
Format arguments
The
itemformat
parameters can contain the following arguments:
The
countformat
parameters can contain the following arguments:
-
$count
: the number of votes
The
itemformat
parameters can contain the following arguments:
The
lineformat
parameters can contain the following arguments:
-
$i{n}
: item of column n
-
$c{n}
: count of column n
-
$p{n}
: percentage of column n
- columns indexes:
- columns start with index
n=1
- column
n=0
is special, and contains the cumulative count over all columns
- this way you allow more than one preference
Installation
- Install the module CPAN:Digest::MD5
- Unzip PollPlugin.zip in your twiki installation dir.
- If you like, move the PollPlugin topic from the Plugins to the TWiki web
- in the bin directory, add poll among the protected scripts (i.e. modify the
.htaccess
file so that poll is protected the same way save is)
<Files poll>
require valid-user
</Files>
Tips and Tricks
- DO NOT use the short line syntax for multidimensional polls!
- DO NOT write
$p{0}%
inside the lineformat
argument in the tag, else you close the tag wrongly
- use the PERCFORMAT parameter
Examples
See:
PollExample or
SmiliesPoll
TODO
- add a deadline (only votes before date X are valid) or a CLOSED parameter
Version history
- 1.010 now uses only TWiki::Func functions, a lot of features added, POLLVOTERS removed
- 1.000 original version
Plugin Settings
- Short description of this plugin
- Set SHORTDESCRIPTION = A plugin to collect votes (Polls)
- This is the pattern recognized and transformed by the PollPlugin
* Set SYNTAX = %POLLRESULTS%|%POLLRESULTS{.*?}%|<!--TWikiPoll-->
- Number of winners shown
- How each voted item is formatted
- How each count is formatted
- How each percentage is formatted
- How is the header formatted
- Set HEADER = | Winners! | Votes | Perc. |
- How each line of the resulting table is formatted
- Set LINEFORMAT = | $i{0} | $c{0} | $p{0} |
- Do we want all the ex-aequo items collected together? (on/off)
- How do we separate the ex-aequo values?
* Set EXAEQUOSEP = <br/>
--
TWiki:Main.AndreaSterbini - 20 Sep 2003