Manual:Hooks/GetPreferences

GetPreferences
Erhältlich ab Version 1.16.0 Verändere Benutzereinstellungen.
Funktion definieren:	public static function onGetPreferences( User $user, array &$preferences ) { ... }
Haken anbringen:	In extension.json: { "Hooks": { "GetPreferences": "MediaWiki\\Extension\\MyExtension\\Hooks::onGetPreferences" } }
Angerufen von:	Datei(en): preferences/DefaultPreferencesFactory.php
Interface:	GetPreferencesHook.php

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

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

Verwendung

Parameter

Parameter/Option	Beschreibung
$user	Benutzer, dessen Einstellungen geändert werden sollen
&$preferences	Array mit der Beschreibung der Präferenzen, das an ein HTMLForm-Objekt übergeben wird

Register und Teilabschnitte

Der Array-Schlüssel section gibt an, welche Registerkarte und welcher Abschnitt von Preferences die Einstellungen enthält. Wenn der section-Wert foo/bar ist, bedeutet dies, dass die Einstellung auf der Registerkarte foo (benannt durch die Systemnachricht prefs-foo) innerhalb der Sektion bar (benannt durch die Systemnachricht prefs-bar) erscheinen wird. Falls keine solche Registerkarte oder Sektion existiert, wird sie automatisch erstellt.

Liste der Standard-Register

Kennung	Zeigt an als
personal	Benutzerdaten
rendering	Aussehen
editing	Bearbeiten
rc	Letzte Änderungen
watchlist	Beobachtungsliste
misc	Verschiedenes

Unterstützte Typen

Sichtbare Typen

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

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

API-Einstellungen

API-Einstellungen verwenden den Typ api. Sie werden in Special:Preferences nicht angezeigt. 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).

Voreinstellungen

Um den Standardwert für eine Präferenz festzulegen (d.h. den Wert, der für einen neuen Benutzer festgelegt ist, der noch nicht seine Präferenzen angepasst hat), ist die Einstellung zur globalen Variable $wgDefaultUserOptions hinzu zu fügen. Der gleiche Schlüsselname wie bei $preferenzen im Haken ist zu verwenden.

Alternativ, wenn eine Erweiterung erstellt wird, kann dies dem DefaultUserOptions-Abschnitt der Datei extensions.json hinzugefügt werden.

Beispiel seit REL1_35

See: Handling hooks in MediaWiki 1.35 and later

extension.json

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

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

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

extension.json

In extension.json:

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

Hooks.json

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

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",
}