%META:TOPICINFO{author="wmertens" date="1216776193" format="1.1" version="1.3"}%
<!--
This topic is part of the documentation for VotePlugin and is
automatically generated from Subversion. Do not edit it! Your edits
will be lost the next time the topic is uploaded!

If you want to report an error in the topic, please raise a report at
http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/VotePlugin
-->

<!--

   PLEASE DO NOT EDIT THIS TOPIC

   It is automatically generated from the subversion repository, and any changes
   you make will simply be overwritten the next time a release is generated.

   Instead, you could check your fix in, raise a bug in the Bugs web, or mail the author.
-->
---+!! <nop>%TOPIC%
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 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,

=%<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"}%

---++ Syntax Rules

---++ Syntax
#StandardAttrs
Write =%<nop>VOTE{ ... }%= in the text of a a TWiki topic to define a poll
%STARTSECTION{"vote_attributes"}%
   * 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"= |
   | =select<i>N</i>= | \
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"= |
   | =options<i>N</i>= | \
Each =select<i>N</i>= must have a corresponding =options<i>N</i>= that \
defines a comma-separated list of the options that can be selected between. | =options1="Beer,Wine,Milk"= |
   | =stars<i>N</i>= | \
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"= |
   | =width<i>N</i>= | \
Each =stars<i>N</i>= must have a corresponding =width<i>N</i>=. This gives the number of \
stars to show e.g. =width1="5"= will show 5 stars. | =width2="10"= |
   | =enabled<i>N</i>= | \
This is a [[%TWIKIWEB%.IfStatements][logical expression]] that determines if this field is available. | =enabled2="$ WIKINAME='TWikiGuest'"= |
   | =text<i>N</i>= | \
Free-form line of text. Use the width<i>N</i> parameter to determine the length. | =text3="Remark"= |
   | =textbox<i>N</i>= | \
Free-form block of text. Use the width<i>N</i> and height<i>N</i> parameters to determine the size | =textbox4="Remarks"= |
   | =height<i>N</i>= | \
Only for textbox<i>N</i>, number of lines in the textbox | =height4=5= |
   | =desc<i>N</i>= | \
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"= |
   | =format<i>N</i>= | \
Defines the format of the results display. See [[VotePlugin#FormattingResults][formatting results]], below. | =format="$large"= |
   | =chart<i>N</i>= | \
Defines the format of a single bar in the results bar chart generated for the corresponding  =select= (for =select= type only). See [[VotePlugin#FormattingResults][formatting results]], below. | =chart="&lt;p>$option $score&lt;/p>"= |
   | ={select,stars,text,chart}format= | \
Defines the default format for fields of the given type | =selectformat="&#124; $desc &#124; $prompt &#124; $bars &#124;"= |
   | =separator= | Defines the string to be used to separate each row in the result. | =separator="&lt;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.<nop>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. |
%ENDSECTION{"vote_attributes"}%

%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 %MAINWEB%.<nop>TWikiPreferences).

#FormattingResults
---+++ 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(<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'
   * !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 =%<nop>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 Build<nop>Contrib.
   * If you have TWiki 4.2 or later, you can install from the =configure= interface (Go to Plugins->Find More Extensions)
      * See the [[http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement][installation supplement]] on TWiki.org for more information.
   * If you have any problems, then you can still install manually from the command-line:
      1 Download one of the =.zip= or =.tgz= archives
      1 Unpack the archive in the root directory of your TWiki installation.
      1 Run the installer script ( =perl &lt;module&gt;_installer= )
      1 Run =configure= and enable the module, if it is a plugin.
      1 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.
      1 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)
      1 Manually edit !LocalSite.cfg to set any configuration variables.

%IF{"defined 'SYSTEMWEB'" else="<div class='twikiAlert'>%X% WARNING: SYSTEMWEB is not defined in this TWiki. Please add these definitions to your %MAINWEB%.TWikiPreferences, if they are not already there:<br><pre>   * <nop>Set SYSTEMWEB = %<nop>TWIKIWEB%<br>   * <nop>Set USERSWEB = %<nop>MAINWEB%</pre></div>"}%


---++ Plugin Info
<!-- provided for compatibility only
   * Set SHORTDESCRIPTION = Simple way to count votes
-->
|  Plugin Author: | TWiki:Main/MichaelDaum |
|  Copyright &copy;: | 2005-2007, Michael Daum http://wikiring.de |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | post-15571 (not in SVN yet) |
|  Change History: | &nbsp; | 
|  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 &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 |


-- TWiki:Main.MichaelDaum - 31 Aug 2006

%META:FILEATTACHMENT{name="rightbar.gif" attr="" autoattached="1" comment="" date="1213617432" path="rightbar.gif" size="196" user="UnknownUser" version=""}%
%META:FILEATTACHMENT{name="example_stars.gif" attr="h" autoattached="1" comment="" date="1213617432" path="example_stars.gif" size="2576" user="UnknownUser" version="1"}%
%META:FILEATTACHMENT{name="example_select.gif" attr="h" autoattached="1" comment="" date="1213617432" path="example_select.gif" size="4989" user="UnknownUser" version="1"}%
%META:FILEATTACHMENT{name="leftbar.gif" attr="" autoattached="1" comment="" date="1213617432" path="leftbar.gif" size="196" user="UnknownUser" version=""}%
%META:FILEATTACHMENT{name="mainbar.gif" attr="" autoattached="1" comment="" date="1213617432" path="mainbar.gif" size="148" user="UnknownUser" version=""}%
