Open main menu

Extension:QPoll/Terminology and Syntax

General informationEdit

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 definitionEdit

Every poll is defined in the source text of the page enclosed into the <qpoll> tag. One wikipage can embed one or multiple polls in the source text.

<qpoll poll_attributes>
...
</qpoll>
  • poll_attributes : xml list of qpoll element attributes
  • ... : list of questions, see below

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 addressEdit

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 <qpoll id="poll_id">. Poll addresses are currently used as value of address and dependance attributes (see just below) and in qpuserchoice parser function.

Mode definition poll attributesEdit

  • id attribute switches 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 value 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):
<qpoll id="алмаз1">...</qpoll>
  • address attribute switches the poll definition into statistical display mode. The value of attribute specifies 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 different pages will be shown. To display statistics of user voting for <qpoll id="poll2"> declared at Page1 and <qpoll id="poll5"> declared at Page2, one can use the following code (just replace question attributes with real question attributes, or with empty set of attributes {} ):
<qpoll address="Page1#poll2">
{question attributes}
{question attributes}
</qpoll>
<qpoll address="Page2#poll5">
{question attributes}
{question attributes}
</qpoll>

Only common question_attributes can be specified in this poll mode, one question header per line, enclosed into the curly braces.

Declaration / voting modeEdit

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 applicable to any mode, see below.

Every poll may contain an one or multiple question(s):

<qpoll poll_attributes>
{common_question
|question_attributes}
metacategories
categories
...

{common_question
|question_attributes}
metacategories
categories
...

{common_question
|question_attributes}
metacategories
categories
...
</qpoll>
  • 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:
[]()<> 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.

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 #qpuserchoice parser function.

Poll attributesEdit

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.

Common poll attributesEdit

  • Optional perrow attribute specifies to display question tables in cells, similar to MediaWiki's built-in <gallery perrow=number> 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:
showresults value defined style
showresults="0" suppress statistical display (might be useful to selectively disable statistical display for some question(s) of the poll)
showresults="1" display numerical percents in default colors
showresults="1;color:blue;background:yellow;" display numerical percents in blue color on yellow background
showresults="2" display bars in default colors
showresults="2;color:blue;background:yellow;textcolor:#FF0000;textbackground:aquamarine" display bars in blue color on yellow background; percents will have red color on aquamarine background

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 #Statistical display mode.

Declaration/voting mode poll attributesEdit

  • 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 <qpoll id="mypoll" dependance="Another page#my_earlier_poll"> 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.
  • Optional randomize attribute allows to show only some randomly chosen questions from totally defined in poll.

Question attributesEdit

Common question attributesEdit

  • 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:
no layout attribute specified Categories are columns, proposals are rows. Proposal texts are displayed at the right side.
layout="proposals" Categories are columns, proposals are rows. Proposal texts are displayed at the left side.
layout="transpose" Categories are rows, proposals are columns. Proposal texts are displayed at the bottom side.
layout="proposals transpose" Categories are rows, proposals are columns. Proposal texts are displayed at the top side.
layout="tabular" This type of layout is designed to align proposal parts and category inputs of "text" type questions into grid layouts. By default, questions of type "text" have their category definitions mixed in-between common proposal text, not separated as it used to be for earlier types of questions (pre v0.8.0). When layout attribute of poll is not specified at all, that causes inline flow of elements, which is useful let's say for foreign language tests. However, multiline forms (such as personal registration form) and many of another types of forms require their inputs to be vertically aligned to make the output look pretty. Use layout="tabular" in such case to build the grid of proposal parts / category inputs.
  • 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 attributesEdit

  • Mandatory "type" attribute defines the type of user's category selection in the current question. The following values are currently available:
type="unique()" A set of radiobuttons. The selection of these must be unique in both category and proposal axis. This type of category selection represents unique weight choice. Let's say the categories defined are the list of numbers |1|2|3|4|5. Then, the user choices must be an unique weight of the proposal.
type="()" A set of radiobuttons. The selection of these is unique only in category axis. This means, that proposal answer can have only one user's category choice, while different proposals may have the same category choice.
type="[]" A set of checkboxes. The selection of these is non-unique in any axis. One proposal can have as much (but at least one) of user category choice(s).
type="mixed" A set of mixed type user controls (checkboxes, radiobuttons, textfields), defined in the list of proposals (link). Selection of radiobutton clears out every other category selection in the proposal row, if available. Selection of any other control clears out radiobuttons, if available. Radiobuttons and inputs of other types mutually exclude each other. One proposal can have as much (but at least one) of user category choice(s). Since v0.7.0, it is possible to define just one category (choice) for question, when proposal have textfield type. It might be useful for short questions, or for adding the comments.
type="text" Since v0.8.0 it's possible to create more flexible form layouts for polls, combining proposal parts, different types of category inputs mixed together. Because the syntax of "text" type of question is more complex, it's syntax is throughly explained in separate section.
  • Optional "name" attribute (available since v0.8.0) provides name of question to be addressed in the interpretation scripts. In programming environment it is much more convenient to access question by it's name, not just by question index.
  • 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.

"text" type of questionEdit

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.

Category (input) definition Generated html element
<<>> Unrestricted input type=text.
<<:: width="12">> Input type=text with visual width of 12 characters. Note that :: indicates begin of input attribute(s) definition, while width="12" is actual key / value of category attribute.
<<lion|horse|dog|cat>> Select (drop-down list) with default choice "lion".
<<|lion|horse|dog|cat>> Select (drop-down list) with default choice "" (empty string), which usually indicates that there is no _real_ default choice.
<<:: width="auto"|Moscow|Berlin|New York>> Select (drop-down list) with width just enough to hold longest option (New York in this case). Value of width="auto" is meaningful only when there is more than one option given.
<<:: height="4">> Empty textarea with 4 visible rows. Width attribute also can be specified as well.
<<:: height="10"|prefilled text>> Textarea with prefilled text and 10 visible rows.
<<:: height="3"|alpha|beta|gamma|omega|omicron>> Scrollable select with 3 visible values.
<<:: sorting="desc"|a|b|c>> Display options of select in reverse order: c, b, a. "sorting" attribute indicates whether the options of select should be sorted. Possible values: do not sort (by default), 'asc', 'desc'.
<<:: multiple=""|1|2|3>> Select with possible multiple choices. Current category will be able to hold multiple user-submitted values. Note that there is another way to enable multiple choices, by providing the second category of current proposal (see next example), which will create extra field(s).
Ethnic origin<sup>*</sup> <<Russian|Tatar|Ukrainian|Bashkir>> or (''arbitrary'') : <<>> Will create select with 4 options and text field, both are treated as one joint multi-input. Such inputs can be processed via interpretation scripts. Also note that almost arbitrary wiki text of proposal itself can be placed in-between category definitions.
<()> One or more mutially-exclusive radiobuttons can be defined as possible categories of the question's proposal.
<[checked=""]> Checkboxes can be optionally checked (by default they are unchecked).

"text" type of question proposalsEdit

"text" type of question, introduced in v0.8.0, supports multi-line proposals and named proposals. Thus new subform of proposal definition syntax was introduced:

:|proposal_attributes|proposal_and_category_definition
  • :| characters separate multi-line proposals from each other. Old type of single-line definition is also possible, when proposals are separated via new-line, however mixing of multi-line proposals and single-line proposals in one question is not possible and will result in wrong layout or syntax errors.
  • proposal_attributes can be specified to alter the following proposal properties:
Proposal attribute name Purpose
name="my_proposal" Current proposal of question could be addressed via it's name 'my_proposal' in the bound interpretation script.
emptytext="no" Wiether empty text answer is allowed for current proposal's category / categories. Default is "yes".
catreq=1 Minimal number of categories required to be set / checked by voting user. Default value is "all", which means that all categories are required to fill.
  • proposal_and_category_definition Mixed parts of proposal text and definition(s) of category / categories. Eg. Age* <<::width=2>> or Birth place <<>>.

Simple complete example of "text" type question multi-line named proposal definition:

:|name="age" emptytext="no"|Age* <<::width=2>>

More complex complete examples:

:|name="ethnic_origin" emptytext="no" catreq=1|Ethnic origin<sup>*</sup> <<Russian|Tatar|Ukrainian|Bashkir>> or (''arbitrary'') : <<>>
:|name="short_text"|A duck is a type of <<|fish|mammal|bird>>.<br />Hi! My <<|name|country|city>> is Andrew. How are you?<br />Today is Sunday. Tomorrow is <<|Friday|Saturday|Monday>>.