|
Installation
- 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:
require_once( "$IP/extensions/QPoll/qp_user.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):
| qp_Setup::$global_showresults value | defined style |
|---|---|
| undefined, 0, false | Completely suppress statistical display. |
| true, 1 | Shows the statistics of some poll only to users who successfully submitted (passed) that poll; this helps to reduce voting bias influenced by previous voters. |
| 2 | Shows the statistics to everyone. |
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 <qpoll> 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=purgequery, 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.
| global variable, v < 0.6.5, before require_once(...) | v >= 0.6.5, after require_once(...) |
|---|---|
| $qp_enable_showresults | qp_Setup::$global_showresults |
| $qp_AnonForwardedFor | qp_Setup::$anon_forwarded_for |
| not available, use 0.6.3 w/o cache control, 0.6.4 with cache control | qp_Setup::$cache_control |
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:
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:
- 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.
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.
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
| Release | Notes |
|---|---|
| 0.3.0 tgz | First public release |
| 0.4.0 outdated, security vulnerabilities | Basic support for text fields. New "mixed" type of the question, which allows to combine different types of fields in one proposal row. Database scheme changed to store text answers, not just checkbox / radio as before. |
| 0.4.1 outdated, security vulnerabilities | Minor fixes. Http redirect finally works in Opera. Nested wikilinks and templates should work in names of categories. Tiny change of metacategories format storage in DB. |
| 0.4.2 outdated, security vulnerabilities | Minor fixes. PLURAL should properly work in messages. qpuserchoice parser function introduced new value of default_answer parameter. Minor UI improvements in Special:PollResults. Database scheme slightly changed to improve performance. |
| 0.4.3 outdated, security vulnerabilities | Small JS fix. Shortened syntax of question type "mixed". |
| 0.5.0 outdated, security vulnerabilities | Internal changes of questions parsing. Few code fixes. showresults attribute can be defined in question header, which supports different styles of statistical display. |
| 0.5.1 outdated, security vulnerabilities | Few bugfixes. Improved compatibility of extension with PHP 5.3 (qp_user.php, XLS generation class). |
| 0.6.0 tgz | Significant cleanup and refactoring of the code. Statistical mode of poll output, which can optionally be restricted to display the results of the poll only to the users who already voted the poll. Administrator can browse text answers for the selected poll, question, proposal category at Special:PollResults page (for mixed question fields of type "<>"). |
| 0.6.1 tgz | Small improvements in displaying of header parsing error messages. {{#iferror}} check now should work for {{#qpuserchoice}} function. |
| 0.6.2 tgz | Througly checked escaping of the output to minimize the risk of XSS. |
| 0.6.3 tgz | Fixed bug that happened due to missing $wgDBprefix in one of SQL operators. Including updated translations from http://translatewiki.net/ (many thanks to contributors). This version is recommended for MediaWiki 1.14, 1.15. |
| 0.6.4 tgz | Parser and Article caches control for better performance (experimental feature: need a review or more testing under various versions / setups of MediaWiki). Fixed issue with non-UTF locales in htmlentities() (reported for PHP 5.3.1). |
| 0.6.5 tgz | Parser and Article caches control by default is off (can be switched on by setting the value of qp_Setup::$cache_control property in LocalSettings.php). Fixed bugs and incompatibilities that prevented the extension from working in MediaWiki 1.16 with Vector skin / UsabilityInitiative enhanced preview mode. This version is recommended for MediaWiki 1.16 and will NOT work with 1.15. |
| 0.7.0 tgz | Compatibility to 1.15, 1.16, 1.17. Updated Spreadsheet writer PEAR classes to the latest versions available. Fixed some additional PHP 5.3 deprecations. Enable to define questions of mixed type with just one category defined when the proposal type is textfield. Optionally hide (don't display) common question of such questions, which is useful for adding the fields for feedbacks / comments. Now uses recursiveTagParse() with PPFrame to enable parser functions in tag body (MW 1.16+). Also uses ResourceLoader (MW 1.17+). Export of user votes (voices) in XLS format from Special:Pollresults page, not just averages / totals as before. |
| 0.8.1 zip | Compatibility to 1.23. New "tabular" layout of polls. New "text" type of question. Interpretation scripts can be used to process user-submitted poll data. Actually was developed back in early 2012 but postponed to release and previously left without documentation due to major family troubles. |
To extract tgz archive in Windows, free 7zip program can be used.