Extension:QuickSurveys

From MediaWiki.org
Jump to navigation Jump to search
MediaWiki extensions manualManual:Extensions
Crystal Clear action run.svg
QuickSurveys

Release status:Extension status stable

DescriptionTemplate:Extension#description In article quick surveys or external surveys. Polling readers for opinion.
Author(s)Template:Extension#username Jon Robson, Joaquin Hernandez, Rob Moen, Bahodir Mansurov, Sam Smith
Latest versionTemplate:Extension#version 0.6.0
MediaWikiTemplate:Extension#mediawiki 1.26+
LicenseTemplate:Extension#license GNU General Public License 2.0 or later
Download

Translate the QuickSurveys extension if it is available at translatewiki.net

Check usage and version matrix.

IssuesPhabricator

Open tasks · Report a bug

The QuickSurveys extension allows for showing in-article banners, in order to ask users so that we can gather opinions and feedback on different matters.

Documentation[edit]

Prerequisites[edit]

QuickSurveys depends on EventLogging and won't work without it.

Installation[edit]

  • Download and place the file(s) in a directory called QuickSurveys in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php:
    wfLoadExtension( 'QuickSurveys' );
    
  • Run the update script which will automatically create the necessary database tables that this extension needs.
  • YesY Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

To users running MediaWiki 1.24 or earlier:

The instructions above describe the new way of installing this extension using wfLoadExtension() If you need to install this extension on these earlier versions (MediaWiki 1.24 and earlier), instead of wfLoadExtension( 'QuickSurveys' );, you need to use:

require_once "$IP/extensions/QuickSurveys/QuickSurveys.php";

Configuration[edit]

Here is a configuration for two kinds of surveys: internal and external. The external surveys are required to point to an `https://` URL.

{
	"@QuickSurveysRequireHttps": "Whether to require links to external surveys to be secure",
	"QuickSurveysRequireHttps": true,
	"QuickSurveysConfig": [
		{
		"@name": "survey name",
		"name": "internal example survey",
		"@type": "internal or external link survey",
		"type": "internal",
		"@question": "survey question message key",
		"question": "ext-quicksurveys-example-internal-survey-question",
		"@description": "The message key of the description of the survey. Displayed immediately below the survey question.",
		"description": "ext-quicksurveys-example-internal-survey-description",
		"@answers": "possible answer message keys for positive, neutral, and negative",
		"answers": [
			"ext-quicksurveys-example-internal-survey-answer-positive",
			"ext-quicksurveys-example-internal-survey-answer-neutral",
			"ext-quicksurveys-example-internal-survey-answer-negative"
		],
		"@enabled": "whether the survey is enabled",
		"enabled": true,
		"@coverage": "percentage of users that will see the survey",
		"coverage": 0.5,
		"@platforms": "for each platform (desktop, mobile), which version of it is targeted (stable, beta)",
		"platforms": {
			"desktop": ["stable"],
			"mobile": ["stable", "beta"]
		}
		},
		{
		"name": "external example survey",
		"@type": "internal or external link survey",
		"type": "external",
		"@question": "survey question message key",
		"question": "ext-quicksurveys-example-external-survey-question",
		"@description": "the i18n key of the description of the survey",
		"description": "ext-quicksurveys-example-external-survey-description",
		"@link": "external link to the survey",
		"link": "ext-quicksurveys-example-external-survey-link",
		"@instanceTokenParameterName": "parameter to add to link",
		"instanceTokenParameterName": "parameterName",
		"@privacyPolicy": "The i18n key of the privacy policy text.",
		"privacyPolicy": "ext-quicksurveys-example-external-survey-privacy-policy",
		"@enabled": "whether the survey is enabled",
		"enabled": true,
		"@coverage": "percentage of users that will see the survey",
		"coverage": 0.5,
		"@platforms": "for each platform (desktop, mobile), which version of it is targeted (stable, beta)",
		"platforms": {
			"desktop": ["stable"],
			"mobile": ["stable", "beta"]
		}
		}
	]
}

Adding message keys[edit]

Messages can be defined as part of an extension e.g. WikimediaMessages or by wiki page. For example the message "ext-quicksurveys-example-internal-survey-answer-positive" can be defined by editing the wiki page MediaWiki:ext-quicksurveys-example-internal-survey-answer-positive

For editing messages ensure you have the right permissions. You will need edit-interface right.

How to load a specific survey[edit]

You can bypass the sampling and load a survey using one of the methods below. Please note that the survey you want to load needs to be enabled and passed to the front end.

  • To load a random survey append ?quicksurvey=true to the URL;
  • To load an internal survey whose name is 'internal example survey' append ?quicksurvey=internal-survey-internal example survey to the URL;
  • To load an external survey whose name is 'external example survey' append ?quicksurvey=external-survey-external example survey to the URL.

Notes[edit]

Note that a survey won't show up:

  • on the Main Page;
  • on non-article page;
  • on non-existent article page;
  • when the browser's "Do Not Track" feature is turned on;
  • on skin Minerva when the beta opt in panel is shown;
  • if a survey is an external one and points to non-https location when the config variable `wgQuickSurveysRequireHttps` is set to `true`.