Manual:Hooks/GetPreferences

Languages:

GetPreferences
Available from version 1.16.0 Modify user preferences.
Define function:	public static function onGetPreferences( User $user, array &$preferences ) { ... }
Attach hook:	In extension.json: { "Hooks":{ "GetPreferences":"MediaWiki\\Extension\\MyExtension\\Hooks::onGetPreferences" } }
Called from:	File(s): preferences/DefaultPreferencesFactory.php
Interface:	GetPreferencesHook.php

For more information about attaching hooks, see Manual:Hooks .
For examples of extensions using this hook, see Category:GetPreferences extensions.

Since REL1_35:

Define function:	public function onGetPreferences( $user, &$preferences ) { ... }
Attach hook:	In extension.json:
{ "Hooks":{ "GetPreferences":"example_tag" }, "HookHandlers":{ "example_tag":{ "class":"MediaWiki\\Extension\\ExampleExtension\\Hooks", "services":[ "MainConfig", "UserOptionsLookup" ] } } }
Interface:	GetPreferencesHook.php

Usage

[edit ]

Parameters

[edit ]

Parameter/Option	Description
$user	User whose preferences are being modified
&$preferences	Preferences description array, to be fed to an HTMLForm object

Tabs and sections

[edit ]

The section array key specifies which tab and section of Preferences contains your preferences. If your section value is foo/bar, this means your preference will appear on the foo tab (named by system message prefs-foo) within the bar section (named by system message prefs-bar). If no such tab or section exists, it is created automatically.

List of default tabs

[edit ]

Identifier	Displays as
personal	User profile
rendering	Appearance
editing	Editing
rc	Recent changes
watchlist	Watchlist
misc	Misc

Supported types

[edit ]

Visible types

[edit ]

The type can take on various values found in the HTMLForm::$typeMappings array in the file includes/htmlform/HTMLForm.php, including info, multiselect, radio, etc.

Most preferences are stored in the same format as is used by the HTMLFormField, but in the case of 'type' => 'usersmultiselect ' a transformation should be carried out from a newline-separated list of usernames (which is what the form widget works with) and a newline-separated list of user IDs (which is what gets stored in the database). See the treatment of email-blacklist (in core) or echo-notifications-blacklist (in Echo ) for examples of this.

Floats

[edit ]

For float types, you can set min and max, which will be validated on save.

API preferences

[edit ]

API preferences use type api. They are not displayed in Special:Preferences. They are usually set via custom front-end interfaces that call the API.

Note that you should not use 'type' => 'hidden ' for API preferences (that type exists for HTML forms, not preferences).

Default preferences

[edit ]

To set the default value for a preference (i.e. the value that is set for a new user that hasn't customized their preferences yet), add the setting to the $wgDefaultUserOptions global variable. Use the same key name as you use for $preferences in the hook.

Alternatively, if you're writing an extension, you can add to the DefaultUserOptions section of the file extensions.json.

Example since REL1_35

[edit ]

See: Handling hooks in MediaWiki 1.35 and later

extension.json

[edit ]

In extension.json:

"Hooks":{
"GetPreferences":"main"
},
"HookHandlers":{
"main":{
"class":"MediaWiki\\Extension\\ExampleExtension\\Hooks",
"services":[
"MainConfig",
"UserOptionsLookup"
]
}
},
"AutoloadClasses":{
"MediaWiki\\Extension\\ExampleExtension\\Hooks":"includes/Hooks.php",
},
"config":{
"PersonalSettingsEnabledPageId":{
"type":"boolean",
"value":false
},
"PersonalSettingsNumberOfMostViewedPages":{
"type":"int",
"value":50
},
"PersonalSettingsPeriodForLastViewedPages":{
"type":"string",
"value":"year"
}
},
"manifest_version":2

Hooks.json

[edit ]

In includes/Hooks.php:

namespace MediaWiki\Extension\ExampleExtension;
use MediaWiki\Preferences\Hook\GetPreferencesHook;
use GlobalVarConfig;
use MediaWiki\MediaWikiServices;
use MediaWiki\User\UserOptionsLookup;
class Hooks implements GetPreferencesHook {
	private GlobalVarConfig $config;
	private UserOptionsLookup $userOptionsLookup;
	public function __construct(
		GlobalVarConfig $config,
		UserOptionsLookup $userOptionsLookup
	) {
		$this->config = $config;
		$this->userOptionsLookup = $userOptionsLookup;
	}
	public function onGetPreferences( $user, &$preferences ) {
		$your_new_extensions_section = 'exampleextension';
		// A checkbox
		$preferences_key = 'hitcounters-pageid';
		$preferences_default = $this->userOptionsLookup->getOption(
						$user,
						$preferences_key,
						$this->config->get( 'PersonalSettingsEnabledPageId' ) );
		$preferences[$preferences_key] = [
			'type' => 'toggle',
			'label-message' => 'hitcounters-pageid-label',
			'default' => $preferences_default,
			'section' => $your_new_extensions_section
		];
		// An int input box
		$preferences_key = 'hitcounters-numberofmostviewedpages';
		$preferences_default = $this->userOptionsLookup->getOption(
						$user,
						$preferences_key,
						$this->config->get( 'PersonalSettingsNumberOfMostViewedPages' ) );
		$preferences[$preferences_key] = [
			'type' => 'int',
			'help-message' => 'hitcounters-numberofmostviewedpages-help',
			'label-message' => 'hitcounters-numberofmostviewedpages-label',
			'maxLength' => 4,
			'default' => $preferences_default,
			'section' => $your_new_extensions_section
		];
		// A select box
		$ctx = RequestContext::getMain();
		$preferences_key = 'hitcounters-periodforlastviewedpages';
		$key_base = 'hitcounters-statistics-mostpopular';
		// Ensure that 'default' is always the 1st array item
		$preferences_default = $period = $this->config->get( 'PersonalSettingsPeriodForLastViewedPages' );
		$itemDisplayName = $ctx->msg( "$key_base-$period" )->text();
		$itemArray = [ $itemDisplayName => $period ];
		$period = 'week';
		$itemDisplayName = $ctx->msg( "$key_base-$period" )->text();
		$itemArray[$itemDisplayName] = $period;
		$period = 'month';
		$itemDisplayName = $ctx->msg( "$key_base-$period" )->text();
		$itemArray[$itemDisplayName] = $period;
		$period = 'year';
		$itemDisplayName = $ctx->msg( "$key_base-$period" )->text();
		$itemArray[$itemDisplayName] = $period;
		$usersItem = $this->userOptionsLookup->getOption(
						$user,
						$preferences_key,
						$preferences_default );
		$preferences[$preferences_key] = [
			'type' => 'select',
			'options' => $itemArray,
			'default' => $usersItem,
			'label-message' => "$preferences_key-label",
			'section' => $your_new_extensions_section
		];
		// A set of radio buttons. Notice that in the 'options' array,
		// the keys are the text (not system messages), and the values are the HTML values.
		// They keys/values might be the opposite of what you expect. PHP's array_flip()
		// can be helpful here.
		$preferences_key = 'exampleextension-exampleselect';
		$key_base = 'exampleextension-select';
		$itemKey1 = 'choice1';
		$itemName1 = $ctx->msg( "$key_base-$itemKey1" )->text();
		$itemKey2 = 'choice2';
		$itemName2 = $ctx->msg( "$key_base-$itemKey2" )->text();
		$itemKey3 = 'choice3';
		$itemName3 = $ctx->msg( "$key_base-$itemKey3" )->text();
		// A 'default' key is required, ...
		$preferences_default = $itemKey1;
		// ..., but respect user's choice!
		$usersItem = $this->userOptionsLookup->getOption(
						$user,
						$preferences_key,
						$preferences_default );
		$preferences[$preferences_key] = [
			'type' => 'radio',
			'help-message' => 'exampleextension-exampleselect-help', // a system message (optional)
			'label-message' => 'exampleextension-exampleselect-label', // a system message
			// Array of options. Key = text to display. Value = HTML <option> value.
			'options' => [
				$itemName1 => $itemKey1,
				$itemName2 => $itemKey2,
				$itemName3 => $itemKey3
			],
			'default' => $usersItem, // A 'default' key is required!
			'section' => $your_new_extensions_section
		];
	}
<!-- [...] -->
}

i18n

[edit ]

In i18n/en.json:

{
	"exampleextension-select-help": "Put a help message here!",
	"exampleextension-select-label": "Select an item:",
	"exampleextension-select-choice1": "Pick me please",
	"exampleextension-select-choice2": "No, pick me!",
	"exampleextension-select-choice3": "Seriously, pick me right now",
	"hitcounters-pageid-label": "Show page ID",
	"hitcounters-numberofmostviewedpages-label": "Number of most viewed pages",
	"hitcounters-periodforlastviewedpages-label": "Period for last viewed pages:",
	"hitcounters-statistics-mostpopular-week": "Most viewed pages in the current week",
	"hitcounters-statistics-mostpopular-month": "Most viewed pages in the current month",
	"hitcounters-statistics-mostpopular-year": "Most viewed pages in the current year",
}

Example Old School

[edit ]

extension.json

[edit ]

In extension.json:

"Hooks":{
"GetPreferences":"ExampleExtensionHooks::onGetPreferences",
},
"AutoloadClasses":{
"ExampleExtensionHooks":"includes/Hooks.php",
},
"config":{
"PersonalSettingsEnabledPageId":false,
"PersonalSettingsNumberOfMostViewedPages":50,
"PersonalSettingsPeriodForLastViewedPages":"year"
},
"manifest_version":1

Hooks.json

[edit ]

In includes/Hooks.php:

class ExampleExtensionHooks extends Hooks {
	public static function onGetPreferences( $user, &$preferences ) {
		global $wgPersonalSettingsEnabledPageId, $PersonalSettingsNumberOfMostViewedPages, $PersonalSettingsPeriodForLastViewedPages;
		$your_new_extensions_section = 'exampleextension';
		// A checkbox
		$preferences_key = 'hitcounters-pageid';
		$preferences_default = $this->userOptionsLookup->getOption(
						$user,
						$preferences_key,
						$wgPersonalSettingsEnabledPageId );
		$preferences[$preferences_key] = [
			'type' => 'toggle',
			'label-message' => 'hitcounters-pageid-label',
			'default' => $preferences_default,
			'section' => $your_new_extensions_section
		];
		// An int input box
		$preferences_key = 'hitcounters-numberofmostviewedpages';
		$preferences_default = $this->userOptionsLookup->getOption(
						$user,
						$preferences_key,
						$PersonalSettingsNumberOfMostViewedPages );
		$preferences[$preferences_key] = [
			'type' => 'int',
			'help-message' => 'hitcounters-numberofmostviewedpages-help',
			'label-message' => 'hitcounters-numberofmostviewedpages-label',
			'maxLength' => 4,
			'default' => $preferences_default,
			'section' => $your_new_extensions_section
		];
		// A select box
		$ctx = RequestContext::getMain();
		$preferences_key = 'hitcounters-periodforlastviewedpages';
		$key_base = 'hitcounters-statistics-mostpopular';
		// Ensure that 'default' is always the 1st array item
		$preferences_default = $period = $PersonalSettingsPeriodForLastViewedPages;
		$itemDisplayName = $ctx->msg( "$key_base-$period" )->text();
		$itemArray = [ $itemDisplayName => $period ];
		$period = 'week';
		$itemDisplayName = $ctx->msg( "$key_base-$period" )->text();
		$itemArray[$itemDisplayName] = $period;
		$period = 'month';
		$itemDisplayName = $ctx->msg( "$key_base-$period" )->text();
		$itemArray[$itemDisplayName] = $period;
		$period = 'year';
		$itemDisplayName = $ctx->msg( "$key_base-$period" )->text();
		$itemArray[$itemDisplayName] = $period;
		$usersItem = $this->userOptionsLookup->getOption(
						$user,
						$preferences_key,
						$preferences_default );
		$preferences[$preferences_key] = [
			'type' => 'select',
			'options' => $itemArray,
			'default' => $usersItem,
			'label-message' => "$preferences_key-label",
			'section' => $your_new_extensions_section
		];
		// A set of radio buttons. Notice that in the 'options' array,
		// the keys are the text (not system messages), and the values are the HTML values.
		// They keys/values might be the opposite of what you expect. PHP's array_flip()
		// can be helpful here.
		$preferences_key = 'exampleextension-exampleselect';
		$key_base = 'exampleextension-select';
		$itemKey1 = 'choice1';
		$itemName1 = $ctx->msg( "$key_base-$itemKey1" )->text();
		$itemKey2 = 'choice2';
		$itemName2 = $ctx->msg( "$key_base-$itemKey2" )->text();
		$itemKey3 = 'choice3';
		$itemName3 = $ctx->msg( "$key_base-$itemKey3" )->text();
		// A 'default' key is required, ...
		$preferences_default = $itemKey1;
		// ..., but respect user's choice!
		$usersItem = $this->userOptionsLookup->getOption(
						$user,
						$preferences_key,
						$preferences_default );
		$preferences[$preferences_key] = [
			'type' => 'radio',
			'help-message' => 'exampleextension-exampleselect-help', // a system message (optional)
			'label-message' => 'exampleextension-exampleselect-label', // a system message
			// Array of options. Key = text to display. Value = HTML <option> value.
			'options' => [
				$itemName1 => $itemKey1,
				$itemName2 => $itemKey2,
				$itemName3 => $itemKey3
			],
			'default' => $usersItem, // A 'default' key is required!
			'section' => $your_new_extensions_section
		];
	}
<!-- [...] -->
}

i18n

[edit ]

In i18n/en.json:

{
	"exampleextension-select-help": "Put a help message here!",
	"exampleextension-select-label": "Select an item:",
	"exampleextension-select-choice1": "Pick me please",
	"exampleextension-select-choice2": "No, pick me!",
	"exampleextension-select-choice3": "Seriously, pick me right now",
	"hitcounters-pageid-label": "Show page ID",
	"hitcounters-numberofmostviewedpages-label": "Number of most viewed pages",
	"hitcounters-periodforlastviewedpages-label": "Period for last viewed pages:",
	"hitcounters-statistics-mostpopular-week": "Most viewed pages in the current week",
	"hitcounters-statistics-mostpopular-month": "Most viewed pages in the current month",
	"hitcounters-statistics-mostpopular-year": "Most viewed pages in the current year",
}

Retrieved from "https://www.mediawiki.org/w/index.php?title=Manual:Hooks/GetPreferences&oldid=7592433"