VotePlugin

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 to one 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.

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)

Drink  
Food  

and

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

displays as

Herbie Mann Score: 0, My vote: 0, Total votes: 0
Horace Silver Score: 0, My vote: 0, Total votes: 0
Thelonious Monk Score: 0, My vote: 0, Total votes: 0

Syntax Rules

Syntax

Write %VOTE{ ... }% in the text of a a TWiki topic to define a poll

  • The following standard attributes are recognized
    Name 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"
    enabledN This is a logical expression that determines if this field is available. enabled2="$ WIKINAME='TWikiGuest'"
    textN Free-form line of text. Use the widthN parameter to determine the length. text3="Remark"
    textboxN Free-form block of text. Use the widthN and heightN parameters to determine the size textbox4="Remarks"
    heightN Only for textboxN, number of lines in the textbox height4=5
    descN Longer free-form description of the form field. Use this to describe the fields in a more prosaic way, or because you want to change a fieldname halfway through a survey. desc4="Please leave any remarks you might have"
    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>"
    {select,stars,text,chart}format Defines the default format for fields of the given type selectformat="| $desc | $prompt | $bars |"
    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.

ALERT! 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 Main.TWikiPreferences).

Formatting the Results

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).
$desc Expands to the longer description of the item or to $key if that is not given.
$vote Chosen value, not for stars
$prompt Expands to the active formfield (e.g. select box, textfield. Not for stars)
$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)

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'
  • NiccolaMachiavelli 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.

Plugin Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.

Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.

  • If you have TWiki 4.2 or later, you can install from the configure interface (Go to Plugins->Find More Extensions)
  • If you have any problems, then you can still install manually from the command-line:
    1. Download one of the .zip or .tgz archives
    2. Unpack the archive in the root directory of your TWiki installation.
    3. Run the installer script ( perl <module>_installer )
    4. Run configure and enable the module, if it is a plugin.
    5. Repeat for any missing dependencies.
  • If you are still having problems, then instead of running the installer script:
    1. Make sure that the file permissions allow the webserver user to access all files.
    2. Check in any installed files that have existing ,v files in your existing install (take care not to lock the files when you check in)
    3. Manually edit LocalSite.cfg to set any configuration variables.

Plugin Info

Plugin Author: TWiki:Main/MichaelDaum
Copyright ©: 2005-2007, Michael Daum http://wikiring.de
License: GPL (GNU General Public License)
Plugin Version: post-15571 (not in SVN yet)
Change History:  
23 Jul 2008: Added enabled, xxxformat, text, textbox and supporting infrastructure including properly encoding vote results - TWiki:Main/WoutMertens
1 Jul 2007: Bugs:Item4310 : abstracted out TWiki:Plugins.RatingContrib, and modified the code to be tolerant of forms within forms - TWiki:Main/CrawfordCurrie
24 Jun 2007: Bugs:ItemItem4298: fixed secret switch. Item4200: added VarVOTE. - TWiki:Main/CrawfordCurrie
11 Jun 2007: Bugs: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:
NameVersionDescription
TWiki::Contrib::RatingContrib>=0Lines-of-stars rating module
Plugin Home: TWiki:Plugins/VotePlugin
Feedback: TWiki:Plugins/VotePluginDev
Appraisal: TWiki:Plugins/VotePluginAppraisal

-- TWiki:Main.MichaelDaum - 31 Aug 2006

Topic attachments
I Attachment History Action Size Date Who Comment
GIFgif leftbar.gif   manage 0.2 K 2008-06-16 - 11:57 UnknownUser  
GIFgif mainbar.gif   manage 0.1 K 2008-06-16 - 11:57 UnknownUser  
GIFgif rightbar.gif   manage 0.2 K 2008-06-16 - 11:57 UnknownUser  
Edit | Attach | Watch | Print version | History: r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r3 - 2008-07-23 - wmertens
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2020 by the contributing authors. All material on this collaboration platform is the property of the contributing authors. <br /> Ideas, requests, problems regarding lt;nopgt;TWiki? lt;a href='mailto:twiki-admin@kcl.ac.uk?subject=TWiki%20Feedback%20on%20TWiki.VotePlugin'gt;Send feedbacklt;/agt; <br /> Note: Please contribute updates to this topic on TWiki.org at <a href="http://twiki.org/cgi-bin/view/TWiki/VotePlugin" target="twiki.org">TWiki:TWiki.VotePlugin</a>.