Extension:QPoll

Purpose
This extension allows to create polls embedded into the wikipages. One page may contain multiple polls. Each poll may contain one or more question of different type. The polls can be "chained" - when the dependent poll will be available for voting only after successful submission of the "dependance" poll. Questions may have various types: with unique, single or multiple category selections and text type (since v0.8.0). Questions contain categories - possible user choices. These can be grouped together as metacategories (also known as category spans) to make "subquestions" inside a question. User choice of category from any of previously voted polls can be retrieved in subsequent polls to change next question proposal text. Since v0.8.0 it is possible to bind and run server-side interpretation scripts to analyze user input. Invalid user input can be refused with exact error message provided by interpretation script. Valid user input can be processed and stored as "structured data" to be further processed by future dependent polls.

Terminology and Syntax
Click at section header to read about logical structure of polls, how these can be defined.

Developing scripts
Click at section header to read about how to process user submitted data via parser function and (since v0.8.0) via server-side interpretation scripts.

Installation and administration
Click at section header to read how to install extension, how to use Special:PollResults special page, which settings in LocalSettings.php may be used.

Example of LocalSettings.php
v0.6.5: require_once( "$IP/extensions/QPoll/qp_user.php" ); qp_Setup::$cache_control = false; qp_Setup::$global_showresults = 1; qp_Setup::$anon_forwarded_for = true;

Declaration/voting mode
Now there's an example of three different polls:  {Please choose the side of conflict: ! Choose a score (I - least important, V - most important) describes my values and ideals describes my personal views the most logically suitable to the current situation explains their arguments in the most logical way gives the most useful idea
 * layout="transpose" type="unique" showresults="0"}
 * I | II | III | IV | V

{When I begin to work on some project as a member of a working group, the most important thing to myself is: understanding the goals and importance of this project to guess the goals and values of the working group members to define, how the project will be performed understanding, which benefits this project can brin to the group members to organize the project in such way that it would be implemented well enough
 * layout="proposals transpose" type="unique" showresults="1"}
 * 1 | 2 | 3 | 4 | 5

{In reality, I am understanding new ideas better and easier, when I can: Did you ever think, which external reasons encourage you to invent something new? Did you ever have trouble because you're too curious? Did you ever have a strong wish to improve the design of the some material thing? Did you ever have trouble due to your own stubbornness?
 * layout="proposals" type="" showresults="1;color:blue;background:yellow"}
 * "Real" myself ||| "Ideal" myself
 * Yes | No | Yes | Maybe | No

{Which picture do you like better? Let's assume the poll above is located at the wikipage Mainpage. It's unique identifier on the mainpage is #almaz1 (id=almaz1 poll attribute). Only a different title can re-use the same identifier. This poll will show it's statistics to everyone who can view and thus vote on the Mainpage, in case wiki admin permitted this by placing  qp_Setup::$global_showresults=1;  in LocalSettings.php (showresults attribute). Questions of this poll will be displayed two per row (perrow=2 poll attribute). Questions of poll will have their statistics displayed in different style, according to their showresults attributes.
 * type="unique" showresults="2;color:blue;background:yellow;textcolor:#FF0000;textbackground:aquamarine"}
 * 1 | 2 | 3 | 4 | 5

 {Checking various types of questions, 1 understanding the goals guessing real goals of the project digging deeply into the problem
 * type=""}
 * Large metacategory for the full list of categories just below
 * Category 1 | Category 2 | Category 3

{Checking various types of questions, 2 understanding the real goals Did you mean choice? guessing true goals of the project digging even more deeply into the problem
 * type=""}
 * Two categories span "A"|| Two categories span "B"
 * 1 | 2 | 3 | 4

{Checking various types of questions, 3 understanding the goals guessing real goals of the project digging deeply into the problem Let's assume the second poll is located at the wikipage Pagename. It will be available for the current user only after the first poll (Mainpage#almaz1) was successfully submitted (dependance="Mainpage#almaz1" poll attribute). It's own id=poll0. It might be addressed in the future with Pagename#poll0 poll address (or, just #poll0 if the another poll or parser function is located on the same page).
 * type="[]"}
 * Metacategory for categories I & II | Metacategory for categories III & IV
 * I | II | III | IV

The question 2, proposal 1 of this poll calls a to display a custom proposal text depending on the user's category choice in the previously voted poll Mainpage#almaz1 question 1, proposal 2 (see "the most logically suitable to the current situation" proposal text line above). The displaying proposal text will be Did you mean ... choice?, where ... will be substituted according to the user choice of categories in Mainpage#almaz1 question 1, proposal 2

Note also, that the metacategory (spans) line of the question number 3 is equivalent to the line second metacategory was filled up with one additional empty cell automatically to include the rest of the categories (IV in this case).
 * Metacategory for categories I & II | Metacategory for categories III & IV
 * Metacategory for categories I & II || Metacategory for categories III & IV

{Your favorite drink [][]<> Winter [][]<> Spring [][]<> Summer [][]<> Autumn The poll of "mixed" type. Choose only the water, or any combination of juice, beer and/or other custom drink, which you would prefer during the proposed seasons of the year.
 * textwidth="20" type="mixed"}
 * Plain water | Juice | Beer | Other drink

{Your favorite drink [][]<> Winter Spring Summer Autumn
 * textwidth="20" type="mixed"}
 * Plain water | Juice | Beer | Other drink

Since the v0.4.3 it's possible to omit repeated declaration of exactly the same category types at the next proposal line. Starting from the second proposal line (Spring), there's only proposal text. Thus, the poll with id=multi2 has the same category types as the previously declared poll with id=multi.

Since the v0.7.0 it's possible to define just one category question when proposal have textfield type: {Please describe your short opinion on newspapers below <> Calgary Herald Edmonton Journal Lethbridge Herald Lethbridge Sun Times Lethbridge Journal Starting with v0.7.0 question's "common question" can be hidden when there is only one category defined and it's name equals to html entity 160 (non-breaking space). This might be useful when defining the fields for question comments and feedbacks. For example, you may replace common question title "Your feedback" to html entity 160 in the poll with id=multi3 to have the question to be hidden.
 * textwidth="20" type="mixed"}
 * Your feedback

Statistical display mode
Please note that this mode is available only since v0.6.0. The following code can be placed at any wiki page where the extension was installed:  {showresults="2;color:green;"} {} {showresults="0"} {showresults="1"} If permitted by value of qp_Setup::$global_showresults property, will show the statistical results of poll with id almaz1 located at Mainpage.
 * first question will have green bars displayed
 * second will inherit showresults="1" from poll's value of showresults attribute, thus showing only numerical percents
 * third will not be displayed at all
 * fourth will have only numerical percents displayed

Technical notes
Parsing and storage of the polls on the wiki pages gives a flexibility. Yet, every kind of flexibility brings technical difficulties. When an existing poll has already been submitted, it's structure and results are stored in database. When some user alters the source text of such poll, troubles might occur. Generally, it's very much recommended to: Few simple precautions are made against of some notorious glitches. Eg, very incompatible stored/altered question headers cause reject of loading previous poll's category choices. Some of these problems can be fixed by developing a visual poll editor, however, this is against wiki idea - processing of source text, and would require too much of efforts.
 * add new categories only at the last column
 * add new proposals only at the last row
 * do not alter existing submitted metacategories
 * do not change the type of the poll

But, do not alter source text of ongoing polls at all, if you can. Setup the wiki so voting users only have a read permission, not an edit permission. Read permission is enough to submit the poll. This is the main reason, why the poll structure is stored only during the first successful submission, not during reading the page source. If you want poll_address to be stored without the poll structure, just submit the unfilled poll. This might be useful for setting up dependence chains without cumbersome answering. Storage of address will happen only if the poll has correct syntax.

Categories of checkbox/radiobutton input types store boolean "true"/"false" values. Categories of text type are considered "true" when the text answer is not empty. Additionally, text input is stored, so the user's answer can be seen on Special:PollResults page. "True" means that category was choosen (answered). That's why the selection of "exclusive" radiobutton in proposal row of "mixed" question type clears out both checkboxes and text fields, and vice versa.

For a technical note on anonymous usernames, read LocalSettings.php section.

Localization
Additional languages can be added into qp_i18n.php file. It is preferable to use http://translatewiki.net/ site interface to update the messages directly at svn server.

Download
To extract tgz archive in Windows, free 7zip program can be used.

Todo

 * 1) Statistical diagrams.
 * 2) Improve "mixed" question type.
 * 3) Make it possible to delete polls.

History
This extension has originally grown out of the exising stable Quiz extension, taking it as the code base. After some revisions, when majority of the code was changed, it has became apparent that Quiz compatibility should be dropped, because the purposes of both extensions are quite different - the storage scheme can't easily be made unified, and there's not much of demands to store Quiz results. Besides that, nested and rotating tables layout require html class renderer which uses arrays and objects to interpret the tags - with simple strings output tags nesting errors and general code bloat were arising.