Extension:QPoll/Terminology and Syntax

General information
Every page can have one or more of polls. Every poll may contain one or more questions. Every question represents the table with rows and columns counting from zero, where columns are categories (possible user answers) and rows are proposals (poll author's questions). Polls and their questions have xml-style attributes, some of those are mandatory and thus should be properly customized. Question(s) also has a header, which contains a common question, question attributes, optional metacategories line and a mandatory categories line.

Poll address
Poll addresses are similar to addresses of wikipage section: Pagetitle#poll_id. "Title part" before the dash sign can be omitted to specify the address of the poll located at current page. However, the part after the dash sign is not a section. It's an ID of some poll declared at the page Pagetitle, specified as   . Poll addresses are currently used as value of address and dependance attributes (see just below) and in.

Poll attributes
Version 0.6.0 of extension introduces two separate modes of polls: declaration/voting mode and statistical display mode. These modes are selected by choosing appropriate poll attributes:
 * specifying id attribute causes the poll definition to use declaration/voting mode (the only mode available prior to v0.6.0)
 * address attribute causes the poll definition to use statistical display mode, which should be used to display the results of the polls at any wikipage - without the forms used to submit the polls.

The modes are mutually exclusive, so no both id and address attributes can be used together in one poll definition. Also, while some of poll attributes have sense in both modes, many of poll attributes can be used exclusively in one mode. However, nothing prevents the user to define the poll and to show it's statistical results at the same page - just define the poll twice - once with id attribute, another time with address attribute.

Mode definition poll attributes
...
 * id attribute switches the poll definition into declaration/voting mode . It defines string identifier of the poll at the current wikipage. It must be unique on the wikipage. The identifier with the same name might be re-used only at another wikipage. This is because polls cannot be remotely voted at another pages. Please note that id's should be specified without the preceding dash sign, for the very same reason. Non-ASCII id's are possible, just place the value of attribute in quotes (an example in Russian):

... or ...
 * address attribute switches the poll definition into statistical display mode . The value of this attribute specifies a short or full address of the poll, whose statistical data should be displayed. For example, it's very handy to create a page or column of the page, where the results of different polls from the different pages will be shown. For example:

Common poll attributes

 * Optional perrow attribute specifies to display question tables in cells, similar to MediaWiki's built-in   tag attribute). It's very useful when the polls categories and/or proposals are short texts (e.g. lists of numbers, yes/no choice). In such case you may fit more polls on the screen. For example, perrow=3 would setup three question tables per row display layout.


 * Optional showresults attribute specifies to display statistics (percents of user votes for some of the question's category) inside the poll. Originally showresults has only key with no value specified. Starting from v0.5.0 showresults value defines the list of statistical display parameters, separated by semicolons (CSS-like). First element of the list is numerical code of display type: 0 - suppress output (do not show the results), 1 - numerical percents, 2 - simple bars. Next elements define the values of CSS-like attributes: color - the color of bar, background - the background of bar, textcolor - the color of text, textbackground - the background of text. For example:

To enable showresults functionality, an administrator of the wikisite should set "global showresults level" which is specified by value of qp_Setup::$global_showresults property defined in LocalSettings.php after the inclusion of the extension.

Note: you need to set up a page to show the results, see.

Declaration/voting mode poll attributes

 * Optional dependance atttibute defines a relation of the current poll to the successful submission of the poll, address of whose is defined as a value of dependance attribute. For example, poll with the header    will be available for voting only when the user had successfully passed a poll with id="my_earlier_poll", located at Another page. Dependence of the polls can be chained further to the next poll, and the engine would then look for the first unsubmitted poll of the current user.

Common question attributes

 * Optional layout attribute provides various visual layouts of the question. (Note that the question data won't be altered, only the visual representation will be changed). Value of the layout attribute is the list of tokens (words), currently limited to proposals and transpose. Thus, a four possible layouts are available:


 * Optional showresults attribute defines the style of statistical display. The meaning of value is the same as poll's showresults attribute (see above), but it can be applied to every question separately, also the locally-undefined values will be inherited from the top element (poll), like in CSS. Such way, different questions of the same poll may have different values of showresults attribute defined, presenting statistical information in various ways and colors.

Declaration/voting mode question attributes

 * Mandatory type attribute defines the type of user's category selection in the current question. The following values are currently available:

"text" type of question
Since v0.8.0 new "text" type of question was introduced. Similar to "mixed" question type described just above, it allows to mix various input types but in a more flexible and powerful ways. Definition of proposal is not separated from definition of category inputs. Instead, categories are embedded directly into proposal text. Due of that, categories (possible choices) are enclosed into tag-like angle braces <...>. In addition to radiobuttons defined as <> and checkboxes defined as <[]>, it allows to define text inputs of various types.


 * Optional textwidth attribute defines the width of text fields in em's, when the categories of such type were defined in proposal line(s) of the question of "mixed" type.

Poll definition
Every poll is defined in the source text of the page enclosed into the tag. One wikipage can embed one or multiple polls in the source text.  ... Each question contain definition of metacategories and / or categories. Note that neither of them have any relation to MediaWikis categories, nor the Category namespace, unless you deliberately create one by adding such links.
 * poll_attributes : xml list of qpoll element attributes
 * ... : list of questions, see below

Declaration / voting mode
This mode was the only mode available before v0.6.0. Make sure that poll / question attributes are compatible to that mode, otherwise you should get syntax error messages. There are some common attributes which are suitable for any mode, see below.

Every poll may contain an one or multiple question(s):  {common_question metacategories categories ...
 * question_attributes}

{common_question metacategories categories ...
 * question_attributes}

{common_question metacategories categories ... []<> proposal text The above proposal line defines three input fields, the first is a checkbox, the second is a radiobutton, the third is a text field. Proposals are internally numbered from zero.
 * question_attributes}
 * common_question : Common question describes the purpose of the question at whole. It's not mandatory and thus can be blank. Questions are automatically numbered from the number one. Since v0.8.0 questions also may have names defined via question "name" attribute to simplify their usage in interpretation scripts.
 * question_attributes : xml-style list of question attributes.
 * metacategories : optional source line, containing the row of cells, separated by special character ("|" or "!"). Every cell is either a name of metacategory or is an empty one. Empty cell(s) before a cell with the name of metacategory define the count of categories, placed into the group (metacategory). The groups make a "subquestions" in the question of "single" category selections type (see Question attributes). In the source code these are referred as "category spans". Real metacategories are separated with "|". It is also possible to create "fake" metacategories, which serve the purpose as comments to categories and don't create real subquestions. In such case "!" character should be used as a cells separator. Wikilinks and templates can be used in metacategory names (since v0.4.1), though beware of posting non-existing templates, you'll get unexpected category names. Define your templates before submitting the poll.
 * categories : mandatory source line, containing the row of cells, separated by "|" character. Defines the list of categories (columns) in the question table. Categories are the "possible answers", internally numbered from zero. Wikilinks and templates can be used in category names (since v0.4.1), though beware of posting non-existing templates, you'll get unexpected category names. Define your templates before submitting the poll.
 * ... : mandatory list of proposals (one or more source lines). For the types of question "", "unique", "[]" (see Question attributes) these lines contain just the list of proposal texts, one proposal per line. For the type of question "mixed" (since v0.4.0), proposal text is preceeded by list of input types, one element per category defined:

Note that category spans, metacategories, category groups are just a different description of the same logical category grouping. Grouping can be applied only to radiobuttons (for example, a group of two radiobuttons is a logical equivalent of checkbox).

Metacategories (category groups) are unavailable for the types of question "[]", "mixed".

Internal numbering of questions, categories and proposals is important because they might be addressed later as a parameter of the extension's.

Statistical display mode
 {question_attributes} {question_attributes} ... {question_attributes} Only the common question_attributes permitted in statistical display mode can be specified in this poll mode, one per line, enclosed into the curly braces.

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: <qpoll address="Mainpage#almaz1" showresults="1"> {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