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
| &lt;pollId> | &lt;date> | &lt;userId> | item1 | item2 | ... |
  • the topic collecting the votes should follow the syntax:
here goes the topic normal text
here goes the vote definition
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


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:

  • lineformat is:
|  $i{0}  |  $c{0} ($p{0})  |
  • header is:
| *The winners are* | *Votes* |

Format arguments

The itemformat parameters can contain the following arguments:
  • $item: the item voted
The countformat parameters can contain the following arguments:
  • $count: the number of votes
The itemformat parameters can contain the following arguments:
  • $perc: the percentage
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


  • Install the module CPAN:Digest::MD5
  • Unzip in your twiki installation dir.
  • 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
  • (Dakar) Visit configure in your TWiki installation, and enable the plugin in the {Plugins} section.

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


See: PollExample or SmiliesPoll


  • add a deadline (only votes before date X are valid) or a CLOSED parameter

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
    • Set LIMIT = 3
  • How each voted item is formatted
    • Set ITEMFORMAT = $item
  • How each count is formatted
    • Set COUNTFORMAT = $count
  • How each percentage is formatted
    • Set PERCFORMAT = $perc%
  • 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)
    • Set JOIN = on
  • How do we separate the ex-aequo values?
      * Set EXAEQUOSEP =  <br/> 

-- TWiki:Main.AndreaSterbini - 20 Sep 2003

This topic: TWiki > PollPlugin
Topic revision: r2 - 2009-12-23 - 14:11:33 - TWikiAdminUser
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding NTP? Send feedback
Note: Please contribute updates to this topic on at TWiki:TWiki.PollPlugin