Manual:Hooks/GetPreferences

From MediaWiki.org
Jump to: navigation, search
Translate this page; This page contains changes which are not marked for translation.

Other languages:
Deutsch • ‎English • ‎español • ‎français • ‎日本語 • ‎polski • ‎português do Brasil • ‎中文
GetPreferences
Available from version 1.16.0
Modify user preferences.
Define function:
public static function onGetPreferences( User $user, array &$preferences ) { ... }
Attach hook:
$wgHooks['GetPreferences'][] = 'MyExtensionHooks::onGetPreferences';
Called from: File(s): Preferences.php

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

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


Example[edit]

In extension.json:

"Hooks": {
  "GetPreferences": [ "MediaWiki\\Extension\\ExampleExtension\\Hooks::onGetPreferences" ]
}

In includes/Hooks.php:

namespace MediaWiki\\Extension\\ExampleExtension;

class Hooks {
	static function onGetPreferences( $user, &$preferences ) {
		// A checkbox
		$preferences['mypref'] = array(
			'type' => 'toggle',
			'label-message' => 'tog-mypref', // a system message
			'section' => 'personal/info',
		);

		// 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['mypref2'] = array(
			'type' => 'radio',
			'label-message' => 'tog-mypref2', // a system message
			'section' => 'personal/info',
			// Array of options. Key = text to display. Value = HTML <option> value.
			'options' => array(
				'Pick me please' => 'choice1',
				'No, pick me!' => 'choice2',
				'Seriously, pick me right now' => 'choice3',
			),
			'default' => 'choice1',  // A 'default' key is required!
			'help-message' => 'tog-help-mypref2', // a system message (optional)
		);

		// Required return value of a hook function.
		return true;
	}
}


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 info
rendering Appearance
datetime Date and time
editing Editing
rc Recent changes
watchlist Watchlist
searchoptions Search options
misc Misc

Supported types[edit]

Visible types[edit]

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

API preferences[edit]

API preferences use type 'api'. They are not displayed in Special: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 $wgDefaultUserOptionsManual:$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.