Manuel:Accroches/GetPreferences

This page is a translated version of the page Manual:Hooks/GetPreferences and the translation is 100% complete.

GetPreferences
Disponible depuis version 1.16.0 Modification des préférences utilisateur.
Fonction à définir :	public static function onGetPreferences( User $user, array &$preferences ) { ... }
Attacher l'accroche :	Dans extension.json : { "Hooks": { "GetPreferences": "MediaWiki\\Extension\\MyExtension\\Hooks::onGetPreferences" } }
Appelé de :	Fichier(s) : preferences/DefaultPreferencesFactory.php
Interface :	GetPreferencesHook.php

Pour plus d'information sur l'ajout des accroches (hooks), voir Manuel:Accroches .
Pour des exemples d'extensions utilisant cette accroche, voir Category:GetPreferences extensions/fr .

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

Utilisation

Paramètres

Paramètre/Option	Description
$user	Utilisateur dont les préférences vont être modifiées.
&$preferences	Tableau de description des préférences, à transmettre à un objet HTMLForm

Onglets et sections

La clé de tableau section spécifie quelles onglets et sections de Preferences contiennent vos préférences. Si la valeur de votre section est foo/bar, cela signifie que votre préférence apparaîtra dans l'onglet foo (sous le nom de message système prefs-foo) dans la section bar (sous le nom de message système prefs-bar). Si l'onglet ou la section correspondante n'existent pas, ils sont créés automatiquement.

Liste des onglets par défaut

Indicatif	Présenter comme
personal	Informations personnelles
rendering	Apparence
editing	Modification
rc	Modifications récentes
watchlist	Liste de suivi
misc	Préférences diverses

Types supportés

Types apparents

Le type peut prendre diverses valeurs trouvées dans le tableau HTMLForm::$typeMappings du fichier includes/htmlform/HTMLForm.php, incluant info, multiselect, radio, etc.

La plupart des préférences sont stockées dans le même format que celui utilisé par HTMLFormField, mais dans le cas où une transformation 'type' => 'usersmultiselect' devrait être effectuée à partir d'une liste de noms d'utilisateurs séparés par des passages à la ligne (c'est ce qu'utilise le widget du formulaire) et d'une liste d'Id d'utilisateurs séparés par des passages à la ligne (c'est ce que l'on range en base de données). Voir le traitement de email-blacklist (dans le noyau) ou echo-notifications-blacklist (dans Echo ) pour les exemples d'appplication.

Floats

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

Préférences d'API

Les préférences API utilisent le type api. Elles ne sont pas affichées dans 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).

Préférences par défaut

Pour définir la valeur par défaut d'une préférence (c'est-à-dire la valeur qui est définie pour un nouvel utilisateur qui n'a pas encore personnalisé ses préférences), ajoutez la définition à la variable globale $wgDefaultUserOptions . Utilisez le même nom clé utilisé pour les $preferences dans l'accroche.

Par ailleurs, si vous écrivez une extension, vous pouvez ajouter à la section DefaultUserOptions du fichier extensions.json.

Exemple depuis la 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