Extension:QPoll/Installation and administration

Installation
require_once( "$IP/extensions/QPoll/qp_user.php" );
 * download the latest available version and extract it to your wiki extension directory. Note: if you have MediaWiki 1.18, download the trunk version, not 1.18 (see talk page).
 * add the following line to LocalSettings.php
 * setup additional variables in LocalSettings.php, if needed
 * check out Special:Version page to verify the installation
 * login as the user with administrative rights, go to Special:PollResults page. Database tables will be set up. Alternatively, you may import qpoll.sql to mysql database manually (remember that $wgDBprefix for the tables won't be used!).
 * if there are any glitches, make sure you've installed successfully and MediaWiki version is compatible with the extension. Please report the bugs at the talk page. Also you may try using previous version (if available).

Special:PollResults
Special:PollResults special page, available to users with the administrative rights, provides various statistical information about polls currently running on the wiki site. You may browse polls and users, check which users had (/not) participated in the polls, view user choices as well as total's statistics (percents of the category selections). Precise total's statistics can also be exported into the XLS-format, to further analyze the data in OpenOffice / LibreOffice Calc or Excel. Since v0.7.0 it is also possible to export user votes in XLS-format.

LocalSettings.php
Among general user settings (such as setting up 'read', 'edit' and other rights for registered and anonymous users), there are three built-in qp_Setup class properties and some related wikiglobal variables which affect the extension's operation: qp_Setup::$global_showresults = value;
 *  qp_Setup::$global_showresults = 0;  (default value is 0) controls "global showresults level" of showresults poll / question attributes.

Following table shows all of currently available global showresults level values (which are applied to all polls of the wiki):

Boolean values are kept for the compatibility with pre v0.6.0. By default, without the value specified, showresults does nothing and the polls statistics is available only to users with administrative rights on the Special:PollResults page.

qp_Setup::$anon_forwarded_for = value;
 *  qp_Setup::$anon_forwarded_for = true;  (default is false) enables appending of X-Forwarded-For client address to the anonymous username (in form of "proxy_IP/client_IP"). Such username will be represented as a subpage of anonymous user page in NS_USER namespace.

Voting of anonymous users behind the proxy brings the technical difficulties, because anonymous username in MediaWiki is represented with it's IP address:
 * private subnets aren't appended to IP chain by default. To do so, place a $wgUsePrivateIPs = true; line into LocalSettings.php. Otherwise, qp_Setup::$anon_forwarded_for has a very little sense.
 * even if website admin enables $wgSquidServers[] in LocalSettings.php to resolve X-Forwarded-For proxy http header, many clients behind different proxies use the same private subnets (eg. 10.0.0.0/8). In such case, two users with the same private IP under different proxies can vote as the single user. That's why qp_Setup::$anon_forwarded_for is needed.
 * even, when $wgUsePrivateIPs and qp_Setup::$anon_forwarded_for are true, proxy headers can be spoofed. Some proxies have X-Forwarded-For turned off. In such case, use authorization. Consider adding a namespace for polls, which would be readable only to registered users. Try using available LDAP authorization extension.

qp_Setup::$cache_control = value;
 *  qp_Setup::$cache_control = true;  (default is false) makes the extension to flush Article and Parser caches only when the user actually submits the page. By default, extension always uses Parser::disableCache at every page where qpoll tag is presented, which reduces the performance. However, cache control feature is not completely tested so use it at your own risk! Also, after changing the value of this property, don't forget to run  ?Title=Page_where_the_poll_is_located&action=purge  query, to make sure the cache is purged.

Before v0.6.5, user settings were made by definition of global variables $qp_enable_showresults and $qp_AnonForwardedFor before the require_once( "$IP/extensions/QPoll/qp_user.php" ) line. Since v0.6.5, these settings are made by values of qp_Setup class properties qp_Setup::$global_showresults and qp_Setup::$anon_forwarded_for, after the require_once("$IP/extensions/QPoll/qp_user.php"). $qp_enable_showresults and $qp_AnonForwardedFor still can be defined for backward compatibility but discouraged to use.

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;

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. Until the extension is hosted at github, the preferrable way of updating localization file is to create a pull request. http://translatewiki.net/ site interface requires to use Wikimedia git repository.