VotePlugin < TWiki

Tags: view all tags
---+!! <nop>%TOPIC%
<!--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/VotePlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/VotePluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
<sticky>
<div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div>
</sticky>
%SHORTDESCRIPTION%

---++ Introduction

This plugin can be used to build an online-voting system, or _poll_. There are two ways to vote for an item:

   * *select*: vote for a given choice from a selection  <br /><img src="%ATTACHURLPATH%/example_select.gif" />
   * *rate*: give something a rating (a number of stars) <br /><img src="%ATTACHURLPATH%/example_stars.gif" />
A single poll can mix and match the different vote types.

Polls can be _open_ or _closed_. You don't have to log in to vote in an open poll, but you are restricted to one vote per poll per user per calendar date. You have to log in to vote on a closed vote, but you are restricted toone vote per user. You can change your vote in either open or closed votes, though if you do that on a different date in an open vote, it will count as a new vote. Polls are _open_ by default.

The results of a poll can be held in _secret_. If a poll is secret, no records are kept of who voted for what. Polls are _secret_ by default.

You can choose whether to save the resuts of the vote in a _topic_ or in a _secret place_. If you choose to save the results in a topic, you can protect that topic using the normal TWiki access control mechanisms, and the vote will still work. Saving in a topic has the advantage that you can easily post-process the results in TWiki, but it's a bit more work to set up so polls are saved in a _secret place_ by default.

Polls are either _local_ to the topic they are defined in, or are _global_ to the entire TWiki. Each poll has an _ID_ which distinguishes it from other polls. These IDs are local to the topic for local polls, but can be shared between topics if the poll is made _global_.

The result of a poll is displayed in the polling form.

Vote plguin can covert old result file to a compatible format automatically. If you don't have old vote result files, you can turn off this feature by setting "$TWiki::cfg{Plugins}{VotePlugin}{OldVoteFileAutoConvert} = 0" to save some performance.

---++ Example

You create a poll using the %VOTE twiki variable. For example,

=%<nop>VOTE{id="FavouriteMeal" select1="Drink" options1="Beer,Wine,Milk,Water" select2="Food" options2="Steak,Bread,Pasta,Pizza"}%=

displays as (if the plugin is installed and enabled)

%VOTE{id="FavouriteMeal" select1="Drink" options1="Beer,Wine,Milk,Water" select2="Food" options2="Steak,Bread,Pasta,Pizza"}%

and

=%<nop>VOTE{id="Jazzers" stars1="Herbie Mann" stars2="Horace Silver" stars3="Thelonious Monk"}%=

displays as

%VOTE{id="Jazzers" stars1="Herbie Mann" stars2="Horace Silver" stars3="Thelonious Monk"}%

---++ How it behaves on a mirror web and read-only web
If you don't know what is a mirror web and read-only web, please read [[http://twiki.org/cgi-bin/view/Codev/ReadOnlyAndMirrorWebs][this]].
 
This page is on a read-only web.
As you can see above, selections for polls are disabled.
And you don't see the "OK" buttons to submit your votes.
This is the case on a mirror web as well.

In short, you can view vote results on a mirror web, but cannot vote.
This is primarily because vote parameters might be changed on the primary web.
If so, voting based on a mirrored page would cause unexpected voting - e.g. voting to non existing candidate.

So you may find it useful to have the following lines on a vote page.
The message is displayed on on mirror webs.
<verbatim>
%IF{"'%CONTENTMODE%' = 'slave'"
 then="You are on a read-only mirror of this web and you cannot vote here.
 To vote, please go to [[%MASTERWEBSCRIPTURL%.%TOPIC%][here]]."}%
</verbatim>

---++ Who can vote
If the =saveto= parameter is specified, only users who can change the topic specified by the parameter can vote.
Otherwise, anybody who can read the page having a vote can vote.

---++ Syntax Rules

---+++ Vote Form

#StandardAttrs
%INCLUDE{ "VarVOTE" section="syntax" }%

%X% The =style= parameter has been _deprecated_ and should not be used
(though it still works). The =color= and =bgcolor= parameters have been removed.

You can change the defaults for any or all of the above parameters by defining
the [[TWikiVariables][TWikiVariable]] =VOTEPLUGIN_DEFAULTS= to be a parameter string e.g.
<pre>
   *<nop> Set VOTEPLUGIN_DEFAULTS = open="on" global="on" bayesian="on"
</pre>
 You can do this in an individual topic, for an entire web (in !WebPreferences), or for the whole TWiki (in %USERSWEB%.<nop>TWikiPreferences).

#FormattingResults
---+++ Formatting the Results of a Poll

Each item in the poll has a results display next to it (are as part of it in the case of stars). The =format= parameter is used to control how this is displayed. It is usually used to define a row in a TWiki table, and is expands once for each =stars= and once for each option in a =select=.

The =format= parameter is a string that can include the following formatting tokens:

| =$key= | Expands to the name of the item (e.g. the value of =select1=). |
| =$prompt= | Expands to a drop-down selector that allows the user to pick the option they want to vote for (for =select= items only) |
| =$bars= | Expands to a sorted list of bar charts showing the number of votes for this option. Each bar in the chart is formatted according to the format defined in the corresponding =chart= parameter. |
| =$sum= | Expands to the total number of votes cast |
| =$score= | Expands to the mean of all the ratings (for =stars=) |
| =$perc= | Expands to =100*$score/$sum= |
| =$mylast= | Expands to my last rating (for =stars= items only) |
| =$small= | Expands to the star rating bar, using small stars (mutually exclusive with =$large=) |
| =$large= | Expands to the star rating bar, using large stars (mutually exclusive with =$small=) |
| =$reset= | Expands to a reset button, if the viewer has reset rights (see [[#Reset][Resetting a Poll]], below). Without reset rights, expands to nothing. |

The =chart= parameter defines the format of each bar in the bar chart that is generated for each option in the corresponding =select=.

| =$bar(<i>N</i>)= | Expands to the coloured bar used to show the popularity of this option. <i>N</i> is the required total width of the bar in pixels. |
| =$option= | Expands to the name of the option that this bar is for |
| =$perc= | Expands to =100*$score/$sum= |
| =$score= | Expands to the total number of votes cast for this option |

   * The default =format= for a =select= is: =| $key | $prompt | $bars |=
   * The default =chart= is =&lt;div>$bar(300) $option $perc% ($score)&lt;/div>=
   * The default =format= for =stars= is: =| $key | $small&lt;br />&lt;small>Score: $score, My vote: $mylast, Total votes: $sum&lt;/small> ||=

The default =separator= is a newline.

=select=, =option=, =format= and =chart= can all use the standard formatting tokens =$percnt=, =$dollar=, =$quot= and =$n= to render the respective characters.

The %<nop>VOTE{ ... }% will generate the selection box(es) and the poll results.

---+++ Weighting the vote

You can weight the vote results by setting the !TWikiPreference =%<nop>VOTEPLUGIN_WEIGHTINGS%= to the name of a topic that is used to weight the votes of certain members of the community in the final result. For example,
<verbatim>
| *Name* | *Weight* |
| AlbertCamus | 100 |
| SunTszu | 50 |
| NiccoloMachiavelli | 1000 |
</verbatim>

The numbers are percentages. A user who isn't otherwise weighted has a weighting of 100. A weighting lower that 100 reduces their influence on the vote, and a weighting higher than 100 increases it. In the example above,

   * !AlbertCamus has a weight of 100, as does !AdamSmith (who gets the default)
   * !SunTszu's votes only count for half as much as !AlbertCamus'
   * !NiccoloMachiavelli has ten times as much influence as !AlbertCamus and !AdamSmith, and twenty times as much as !SunTszu.

The weighting topic applies to all votes in the scope of the =%<nop>VOTEPLUGIN_WEIGHTINGS%= setting.

#Reset
---+++ Resetting a Poll

Sometimes you want to be able to clear the results of a poll. Access to this feature is controlled using the =VOTEPLUGIN_RESETTERS= TWiki variable. This variable defines a (semicolon-separated) list of wiki names and a (comma-separated) list of the IDs of votes they are allowed to reset. You can use =*= as a wildcard in the vote IDs. For example, in a =Web<nop>Preferences= topic you can write
<verbatim>
   * Set VOTEPLUGIN_RESETTERS = GeorgeWBush(*);RobertMugabe(zimbabwe);SimonCowell(*Idol, XFactor)
   * Set FINALPREFERENCES = VOTEPLUGIN_RESETTERS
</verbatim>
to allow
   * !GeorgeWBush to reset any vote he likes,
   * !RobertMugabe to reset the results of any vote with the id =zimbabwe=,
   * !SimonCowell to reset the results of all votes with an ID ending in =Idol= and any vote with the ID =XFactor=.
If a user has sufficient rights to reset a vote, then a button will be generated in the vote prompt which, when clicked, will reset the results for that vote to initial conditions. If you have used a =format= parameters for the vote, then =$reset= will expand to the reset button.

Note that it is important to finalise the setting, otherwise it can be overridden in individual topics by anyone with =CHANGE= access. If you don't define =VOTEPLUGIN_RESETTERS= no-one can reset _any_ votes.

---++ Plugin Installation Instructions

__Note:__ You do not need to install anything on the browser to use this extension. The following instructions are for the administrator who installs the extension on the TWiki server.

   * For an __automated installation__, run the [[%SCRIPTURL{configure}%][configure]] script and follow "Find More Extensions" in the in the __Extensions__ section.
      * See the [[http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement][installation supplement]] on TWiki.org for more information.

   * Or, follow these __manual installation__ steps:
      * Download the ZIP file from the extension home on twiki.org (see below).
      * Unzip ==%TOPIC%.zip== in your twiki installation directory.
      * Set the ownership of the extracted directories and files to the webserver user.
      * Install the dependencies (if any).

   * Plugin __configuration and testing__: 
      * Run the [[%SCRIPTURL{configure}%][configure]] script and enable the plugin in the __Plugins__ section.
      * Configure additional plugin settings in the __Extensions__ section if needed.
      * Test if the installation was successful using the examples provided.


%X% *IMPORTANT* If you don't want anyone to be able to reset votes on your site, then make sure you:
<verbatim>
   * Set VOTEPLUGIN_RESETTERS = none
</verbatim>
in Main.<nop>TWikiPreferences, and add =VOTEPLUGIN_RESETTERS= to =FINALPREFERENCES=.
</verbatim>

---++ Plugin Info

   * Set SHORTDESCRIPTION = Simple way to count votes

|  Plugin Author: | TWiki:Main/MichaelDaum |
|  Copyright: | &copy; 2005-2007 Michael Daum http://wikiring.de, %BR% &copy; 2005-2012 TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 2012-12-01 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  2012-12-10: | TWikibug:Item7072: VotePlugin doesn't support multiple disks. |
|  2012-12-01: | TWikibug:Item7020: Categorize TWiki Variable VOTE |
|  2012-10-10: | TWikibug:Item6974: Introduce a new configure $TWiki::cfg{Plugins}{VotePlugin}{OldVoteFileAutoConvert} |
|  2012-10-10: | TWikibug:Item6973: Disable submit button when current site mode is read-only or slave. |
|  2011-03-01: | TWikibug:Item6638: Fix 0% bug -- TWiki:Main.UlfJastrow |
|  2010-07-30: | TWikibug:Item6530: Doc fixes -- TWiki:Main.PeterThoeny |
|  14 Oct 2008 | TWikibug:Item6070 works for hierarchical webs now.  - TWiki:Main/ColasNahaboo |
|  10 Aug 2008 | TWikibug:Item5768 suppress submission of individual ratings in a multi-row vote TWikibug:Item5769 correct default handling of transcluded rates TWikibug:Item5766 $large is once again large TWikibug:Item5771 support for resetting votes. |
|  1 Jul 2007: | TWikibug:Item4310 : abstracted out TWiki:Plugins.RatingContrib, and modified the code to be tolerant of forms within forms - TWiki:Main/CrawfordCurrie |
|  24 Jun 2007: | TWikibug:ItemItem4298: fixed secret switch. Item4200: added VarVOTE. - TWiki:Main/CrawfordCurrie |
|  11 Jun 2007: | TWikibug:Item4235 - removed excess newlines, fixed separator - TWiki:Main/CrawfordCurrie |
|   8 Jun 2007: | Added =submit= - TWiki:Main/CrawfordCurrie |
|   6 Jun 2007: | Added =global=, =open=, =secret=, =format=, =chart=, =saveto=, =VOTEPLUGIN_WEIGHTINGS=, bayesian averaging - TWiki:Main/CrawfordCurrie |
|  31 Aug 2006: | added NO_PREFS_IN_TOPIC |
|  15 Aug 2006: | added "use strict" and fixed revealing errors |
|  27 Apr 2006: | added lazy compilation |
|   7 Dec 2005: | added gif bar; removed debug flag |
|   9 Oct 2005: | fixed invocation of normalizeFileName |
|   8 Oct 2005: | added added a little more style flexibility |
|   7 Oct 2005: | storing votes into =_Vote*.txt= now (was =Vote*.txt= before) ;\
                fixed error messaging on empty argument lists |
|  14 Sep 2005: | fixes for dakar |
|  14 Apr 2005: | incorporated =getLocaldate()= function |
|  16 Mar 2005: | use Cache API only if its there; delayed =use &lt;package&gt;= | 
|   7 Mar 2005: | Initial version |
|  Dependencies: | <table border="1"><tr><th>Name</th><th>Version</th><th>Description</th></tr><tr><td align="left">TWiki::Contrib::RatingContrib</td><td align="left">&gt;=0</td><td align="left">Lines-of-stars rating module</td></tr></table> |
|  Plugin Home: | TWiki:Plugins/%TOPIC% |
|  Feedback: | TWiki:Plugins/%TOPIC%Dev |
|  Appraisal: | TWiki:Plugins/%TOPIC%Appraisal |

__Related Topics:__ VarVOTE, %SYSTEMWEB%.TWikiPlugins, %SYSTEMWEB%.DeveloperDocumentationCategory, %SYSTEMWEB%.UserDocumentationCategory
Attachments
Topic attachments
I	Attachment	History	Action	Size	Date	Who	Comment
gif	example_select.gif	r1	manage	4.9 K	2012-12-10 - 08:29	TWikiAdminUser	Saved by install script
gif	example_stars.gif	r1	manage	2.5 K	2012-12-10 - 08:29	TWikiAdminUser	Saved by install script
gif	leftbar.gif	r1	manage	0.2 K	2012-12-10 - 08:29	TWikiAdminUser	Saved by install script
gif	mainbar.gif	r1	manage	0.1 K	2012-12-10 - 08:29	TWikiAdminUser	Saved by install script
gif	rightbar.gif	r1	manage	0.2 K	2012-12-10 - 08:29	TWikiAdminUser	Saved by install script
Topic revision: r2 - 2020-07-17 - TWikiAdminUser
Account
- Log In
- Register User
Edit
Attach
Copyright © 1999-2025 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.VotePlugin.