VotePlugin
Simple way to count votes
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
- rate: give something a rating (a number of stars)
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,
%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)
and
%VOTE{id="Jazzers" stars1="Herbie Mann" stars2="Horace Silver" stars3="Thelonious Monk"}%
displays as
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
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.
%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]]."}%
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
- Syntax:
%VOTE{ id="..." select1="..., ..., ..." }%
- Parameters:
Parameter | Description | Example |
id | The identifier of the poll. You can have multiple independent votes in the same topic. | id="Dining" |
selectN | Defines the name of a select vote, where you select one from a ranges of options. N is a number that identifies this item within the poll e.g. select1 , select2 etc. You must number all select and stars parameters uniquely and sequentially (e.g. select1 stars2 select3 | select1="Drink" |
optionsN | Each selectN must have a corresponding optionsN that defines a comma-separated list of the options that can be selected between. | options1="Beer,Wine,Milk" |
starsN | Defines the name of a rate vote, where you rate something by giving it a number of stars. N is a number that identifies this item within the poll e.g. select1 , stars2 etc. You must number all select and stars parameters uniquely and sequentially (e.g. select1 stars2 select3 | stars2="Usability" |
widthN | Each starsN must have a corresponding widthN . This gives the number of stars to show e.g. width1="5" will show 5 stars. | width2="10" |
formatN | Defines the format of the results display. See formatting results, below. | format="$large" |
chartN | Defines the format of a single bar in the results bar chart generated for the corresponding select (for select type only). See formatting results, below. | chart="<p>$option $score</p>" |
separator | Defines the string to be used to separate each row in the result. | separator="<br/>" |
global | If set to "off" , this makes the id local to this topic (the default). If set to "on" it will be a global poll that can be accessed from many topics. | global="on" |
open | If set to "off" this is a closed vote. If set to "on" it is open (the default) | open="on" |
secret | If set to "off" , then the database will record who voted. If set to "on" , votes are secret (the default) | secret="on" |
saveto | If set to the name of a topic, the poll results will be appended to the end of that topic. The results are formatted as a TWiki table for easy post-processing. | saveto="Main.VoteResults" |
bayesian | If set to "on" , rating averages will be computed using the Bayesian average of this item against all the other items that have the same item in their stars field. This requires all the participating %VOTEs to be global , or to save their results to the same place using saveto . See http://www.thebroth.com/blog/118/bayesian-rating for more information about Bayesian rating. | bayesian="off" |
submit | If set to "off" , this makes the %VOTE display the results of the vote without prompting for any input. This is useful when - for example - you want to show the results of a global vote, without permitting more voting. |
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
TWikiVariable VOTEPLUGIN_DEFAULTS
to be a parameter string e.g.
* Set VOTEPLUGIN_DEFAULTS = open="on" global="on" bayesian="on"
You can do this in an individual topic, for an entire web (in WebPreferences), or for the whole TWiki (in Public.TWikiPreferences).
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 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(N) |
Expands to the coloured bar used to show the popularity of this option. N 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 <div>$bar(300) $option $perc% ($score)</div>
- The default
format
for stars
is: | $key | $small<br /><small>Score: $score, My vote: $mylast, Total votes: $sum</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 %VOTE{ ... }% will generate the selection box(es) and the poll results.
Weighting the vote
You can weight the vote results by setting the TWikiPreference
%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,
| *Name* | *Weight* |
| AlbertCamus | 100 |
| SunTszu | 50 |
| NiccoloMachiavelli | 1000 |
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
%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
WebPreferences
topic you can write
* Set VOTEPLUGIN_RESETTERS = GeorgeWBush(*);RobertMugabe(zimbabwe);SimonCowell(*Idol, XFactor)
* Set FINALPREFERENCES = VOTEPLUGIN_RESETTERS
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 configure script and follow "Find More Extensions" in the in the Extensions section.
- Or, follow these manual installation steps:
- Download the ZIP file from the extension home on twiki.org (see below).
- Unzip
VotePlugin.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 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.
IMPORTANT If you don't want anyone to be able to reset votes on your site, then make sure you:
* Set VOTEPLUGIN_RESETTERS = none
in Main.TWikiPreferences, and add
VOTEPLUGIN_RESETTERS
to
FINALPREFERENCES
.
Plugin Info
- Set SHORTDESCRIPTION = Simple way to count votes
Plugin Author: |
TWiki:Main/MichaelDaum |
Copyright: |
© 2005-2007 Michael Daum http://wikiring.de, © 2005-2012 TWiki:TWiki.TWikiContributor |
License: |
GPL (GNU General Public License) |
Plugin Version: |
2012-12-01 |
Change History: |
|
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 <package> |
7 Mar 2005: |
Initial version |
Dependencies: |
Name | Version | Description |
---|
TWiki::Contrib::RatingContrib | >=0 | Lines-of-stars rating module | |
Plugin Home: |
TWiki:Plugins/VotePlugin |
Feedback: |
TWiki:Plugins/VotePluginDev |
Appraisal: |
TWiki:Plugins/VotePluginAppraisal |
Related Topics: VarVOTE,
TWikiPlugins,
DeveloperDocumentationCategory,
UserDocumentationCategory