手册:钩子/GetPreferences
GetPreferences | |
---|---|
自version 1.16.0 版可用 修改用户参数设置。 | |
定义函数: | public static function onGetPreferences( User $user, array &$preferences ) { ... }
|
附加钩子: | 在extension.json中:
{
"Hooks": {
"GetPreferences": "MediaWiki\\Extension\\MyExtension\\Hooks::onGetPreferences"
}
}
|
调用自: | 文件: preferences/DefaultPreferencesFactory.php |
介面: | GetPreferencesHook.php |
更多有关附加钩子的信息,请参见Manual:Hooks 。
有关使用此钩子的扩展示例,请参见Category:GetPreferences extensions/zh。
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 |
用法
参数
参数/选项 | 描述 |
---|---|
$user | 正在修改其首选项的用户 |
&$preferences | 要提供给HTMLForm对象的首选项描述数组 |
选项卡和节
section
数组键指定Preferences的哪个选项卡和部分包含您的首选项。
如果您的section
值是foo/bar,这意味着您的首选项将出现在foo选项卡上(由系统消息prefs-foo
命名)的bar部分(由系统消息prefs-bar
命名)。
如果不存在这样的选项卡或部分,则会自动创建。
默认标签列表
标识符 | 显示为 |
---|---|
personal | 用户资料 |
rendering | 外观 |
editing | 编辑 |
rc | 最近更改 |
watchlist | 监视列表 |
misc | 其他 |
支持的类型
可见类型
type可以采用在文件includes/htmlform/HTMLForm.php的HTMLForm::$typeMappings
数组中找到的各种值,包括信息
、多选
、单选
等。
大多数首选项以与HTMLFormField相同的格式存储,但在'type' => 'usersmultiselect'
的情况下,应该从换行符分隔的用户名列表(表单小部件使用该列表)和换行符分隔的用户ID列表(存储在数据库中)执行转换。
有关这方面的例子,请参阅email-blacklist
(核心)或echo-notifications-blacklist
(Echo )的处理。
Floats
For float
types, you can set min
and max
, which will be validated on save.
API参数设置
API首选项使用类型api
。它们不会显示在Special:Preferences中。
They are usually set via custom front-end interfaces that call the API.
'type' => 'hidden'
for API preferences (that type exists for HTML forms, not preferences).
默认首选项
要设置首选项的默认值(即为尚未自定义其首选项的新用户设置的值),请将该设置添加到$wgDefaultUserOptions 全局变量。使用与钩子中的$preferences相同的键名。
或者,如果您正在编写扩展,可以将其添加到文件extension.json的DefaultUserOptions部分。
示例
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",
}