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.23, download the master version from github.
 * Add the following line to LocalSettings.php:
 * Setup optional parameters in LocalSettings.php, when 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. It's also possible to install from cli via usual php update.php shell script. Alternatively, you may import qpoll.sql to MySql database manually, but remember that $wgDBprefix for the table names won't be used in such case thus such way of installation is not recommended.
 * If there are any glitches, make sure you've installed successfully and MediaWiki version is compatible to 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 administrative rights, provides various statistical information about polls currently running at 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 complete user votes in XLS-format for more complex ways of analysis (eg. spreadsheet scripts).

LocalSettings.php
There are 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;  (= 0 when uninitialized) provides default value of showresults attributes of poll / question.

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

Boolean values are kept for the compatibility to pre v0.6.0. By default when no value is specified in LocalSettings.php / poll header / question header, polls statistics is available only to the users with administrative rights at 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' chain to the anonymous username (in form of "proxy_IP/client_IP"). Such username will be represented as a subpage of anonymous user page in the 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, when 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' feature 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 &lt;qpoll&gt; tag is presented, which reduces site 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.

Prior to v0.6.5, user settings were defined via global variables $qp_enable_showresults and $qp_AnonForwardedFor before the require_once( "$IP/extensions/QPoll/qp_user.php" ) line. Since v0.6.5, these are set up as the 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 are discouraged to use.

General MediaWiki settings recommended to use
Sometimes only registered users should be allowed to vote polls. Possible reasons are:
 * To diminish the IP address spoofing.
 * To engage anonymous to actively participate as site editors.
 * For anonymous editing wiki it's still advisable to disable anonymous poll source editing to prevent voting manipulation and due to fragile link between poll definitions and it's database schema.

In such case separate custom namespace should be used for polls. define("NS_POLL", 500); define("NS_POLL_TALK", 501); $wgExtraNamespaces[NS_POLL] = "Poll"; $wgExtraNamespaces[NS_POLL_TALK] = "Poll_talk"; $wgNamespaceProtection[NS_POLL] = array( 'edit_poll' ); $wgNamespacesWithSubpages[NS_POLL] = true; $wgNonincludableNamespaces[] = NS_POLL; To disable users from editing polls: $wgGroupPermissions['sysop']['edit_poll'] = true; To disable anonymous from viewing polls, install Extension:Lockdown then use the following settings: $wgNamespacePermissionLockdown[NS_POLL]['read'] = array('user');

Since v0.8.0 separate Interpretation namespace (NS_QP_INTERPRETATION / NS_QP_INTERPRETATION_TALK) is introduced to store poll interpretation scripts, currently written in subset of PHP language. All efforts were made to make the scripts less vulnerable to malicious editing attempts. Such as most of dangerous functions / classes are disabled from execution via php built-in tokenizer. However, it's still possible to perform some DDOS attacks via for loops. Thus, it's advisable to disallow editing the sources of interpretation scripts to anyone but sysops and bureaucrats: $wgNamespaceProtection[NS_QP_INTERPRETATION] = array( 'edit_interpretation' ); $wgGroupPermissions['sysop']['edit_interpretation'] = true; Because interpretation scripts can be used in school entivonment to check the knowledge of students, even viewing of them should be disabled, otherwise the pupil will be able to find the correct answer by studying the source of the script. Install Extension:Lockdown then add the following line: $wgNamespacePermissionLockdown[NS_QP_INTERPRETATION]['read'] = array('sysop', 'bureaucrat'); $wgNonincludableNamespaces[] = NS_QP_INTERPRETATION;

Do not forget to add poll's custom namespace to $wgNamespacesToBeSearchedDefault in case you want text parts of the polls to be searchable. For further information look at:
 * Manual:Using_custom_namespaces

If you are using qp_debug function to log intermediate values of interpretation scripts, it is advisable to change default log file name to different one which might be harder to guess: $wgDebugLogGroups['qpoll'] = 'my_arbitrary_qpoll_debug_file.txt'; However, in production environment it's better to comment out all qp_debug calls in the scripts so they will not slow-down the server.

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

for v0.8.0 and above also add: $wgNamespaceProtection[NS_QP_INTERPRETATION] = array( 'edit_interpretation' ); $wgGroupPermissions['sysop']['edit_interpretation'] = true;

Technical notes
Defining polls at wiki pages provides improved flexibility of content layout, which is desirable for education environment. For example image thumbnails or TeX formulas can be used in the questions. 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 some notorious glitches. Eg, major incompatibility between re-defined question headers to previously stored question headers cause rejection of loading previously submitted category choices. Some of these problems can be fixed by developing a visual poll editor. However, that is against wiki idea - processing of source text, and would require too much efforts, which I am as sole developer of this project cannot handle.
 * 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.

So, 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. That is the primary reason, why the poll structure is stored only during the first successful submission, not during viewing of 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 at Special:PollResults page. "True" means that category was chosen (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 or translation corrections can be applied into qp.i18n.php file. Until the extension is hosted at github, the preferable way of updating localization file is to create a pull request. http://translatewiki.net/ site interface requires to use Wikimedia git repository.

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