Расширение:Гаджеты

Справка по расширениям MediaWiki

Gadgets Статус релиза: стабильно
Реализация	MyWiki , Служебная страница , API
Описание	Позволяет пользователям включать на их странице настроек гаджеты на основе JS, предоставляемые другими пользователями
Автор(ы)	Daniel Kinzler (Duesentriebобсуждение)
Политика совместимости	Снэпшоты выходят вместе с MediaWiki. Мастер не имеет обратной совместимости.
MediaWiki	1.19+
Параметры $wgGadgetsDefinitionsUseCodeEditor $wgGadgetsRepo $wgGadgetsDefinitionsUseCodeMirror
Используемые хуки BeforePageDisplay CodeEditorGetPageLanguage CodeMirrorGetMode ContentHandlerDefaultModelFor DeleteUnknownPreferences GetPreferences PreferencesGetIcon PreferencesGetLegend ResourceLoaderRegisterModules UserGetDefaultOptions getUserPermissionsErrors wgQueryPages
License	GNU General Public License 2.0 or later
Скачать	Скачать расширение Git [?]: репозиторий (Phabricator · GitHub) Обзор кода Gerrit журнал Git-коммитов Download source tarball README
Пример	Wikimedia Commons: Gadget overview, user preferences (click "Gadgets"; you need to be logged in of course)
Переведите расширение Gadgets, если оно доступно на translatewiki.net
Проблемы	Открытые задачи · Сообщить об ошибке

Расширение Гаджеты позволяет пользователям возможность выбирать «гаджеты» на основе JavaScript или CSS, предоставленные другими участниками вики.

Гаджеты состоят из JavaScript и/или CSS Сниппеты , расположенных на страницах в пространстве имен MediaWiki. Каждый гаджет определяется строкой в MediaWiki:Gadgets-definition, содержащей название и описание гаджета, а также список используемых им фрагментов JS и CSS (смотрите раздел Использование ниже).

Поскольку гаджеты находятся в пространстве имен MediaWiki (список, определяющий гаджеты, а также фактические фрагменты кода), редактировать код могут только системные администраторы (администраторы интерфейса с версии 1.32). Так и должно быть. Только доверенные участники сообщества вики должны иметь возможность редактирования JavaScript-кода, используемого другими участниками, поскольку JavaScript может быть с лёгкостью использован для угона аккаунтов или слежки за людьми.

Установка

Это расширение поставляется с MediaWiki 1.18 и выше, так что вам не нужно загружать его. Остальные инструкции по настройке всё равно необходимо соблюдать.

• Скачайте и распакуйте файл(ы) в папку с названием Gadgets в вашей папке extensions/.
  Вместо этого разработчикам и соавторам кода следует установить расширение из Git, используя:

  cd extensions/
  git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Gadgets
  

• Добавьте следующий код в конце вашего файла LocalSettings.php :

  wfLoadExtension( 'Gadgets' );
  

• Готово – Перейдите на страницу Special:Version на своей вики, чтобы удостовериться в том, что расширение успешно установлено.

Настройка

$wgGadgetsRepo	Определять гаджеты в MediaWiki:Gadgets-definition или же на страницах по типу MediaWiki:Gadgets/yourGadgetName.json. If json, it will also create the content model GadgetDefinition. "Json" mode is under development and is not ready for use yet.
$wgSpecialGadgetUsageActiveUsers	Configures whether or not to show active user stats on Special:GadgetUsage.	true

Использование

Пример некоторых гаджетов в пользовательских настройках немецкой Википедии.

Как только страница MediaWiki:Gadgets-definition будет создана с как минимум одним верно настроеным гаджетом, у всех участников в Special:Preferences отобразится новый раздел «Гаджеты». Там участники могут включать необходимые им гаджеты. На Special:Gadgets также отображается обзор гаджетов, заданных в MediaWiki:Gadgets-definition, вместе с полезными ссылками на страницы локализации и скриптов/стилей, чтобы их было проще создавать или править. Статистика выбора гаджетов доступна на Special:GadgetUsage.

Формат определения

Чтобы задать гаджет, каждая новая строка на странице MediaWiki:Gadgets-definition должна начинаться с символа «*» (звёздочка). Строка имеет следующий формат:

* mygadget [опции] | названия страниц

Первое поле (в примере — «mygadget») — это внутреннее имя гаджета. Название на странице настроек берётся со страницы системного сообщения интерфейса ($2), где можно указать отображаемое имя и краткое описание, с возможностью использования вики-разметки. The label for the preferences page comes from an interface message page (MediaWiki:Gadget-mygadget) where the proper name and a short description can be written, which also allows wikitext markup to be used.

Внутреннее имя должно начинаться с базовой латинской буквы ([A-Za-z]) и может содержать любое количество букв, цифр ([0-9]), дефисов (-), подчёркиваний (_) и точек (.). Причина этого ограничения в том, что внутреннее имя должно быть допустимым как имя формы в HTML, как ключ системного сообщения интерфейса MediaWiki и как имя модуля ResourceLoader.

Формат опций:

[ResourceLoader | опция1 | опция2 | ... опцияN]

The Загрузчик ресурсов flag is required unless the gadget contains only styles. Options that are "flags" only need to have their name written to be turned on. Options that need a value are followed by an equals sign and a comma-separated list of values. All whitespace is optional and may be omitted.

[ResourceLoader | myflag | mykey = value1, value2, value3 ]

Примеры:

* mygadget[ResourceLoader]|mygadget.js|mygadget.css

или

* mygadget[ResourceLoader|package]| mygadget.js | mygadget-Foo.js | mygadget-data.json | mygadget-template.vue | mygadget.css

или

* mygadget[ ResourceLoader | rights=foo, bar ] | mygadget.js | mygadget.css

Использование пространства имён Gadget Definition

Версия MediaWiki:

≤ 1.41

Есть два способа определения гаджетов, зависящие от значения в $wgGadgetsRepoClass. Если установлено 'MediaWikiGadgetsDefinitionRepo' (по умолчанию), список доступных гаджетов определяется на странице MediaWiki:Gadgets-definition. Альтернативным способом определения гаджетов является использование страниц в пространстве имён Gadget definition, если для $wgGadgetsRepoClass установлено 'GadgetDefinitionNamespaceRepo'. (В MediaWiki 1.39 и позднее вместо этого следует использовать значение '\\MediaWiki\\Extension\\Gadgets\\GadgetDefinitionNamespaceRepo'.)

Перенос существующих определений гаджетов пока не поддерживается, поэтому после изменения этой настройки вы потеряете ранее заданные гаджеты.

Создание страницы Gadget definition:mygadget и добавление в неё приведённого ниже кода в формате JSON даст тот же эффект, что и mygadget[ ResourceLoader | rights=foo, bar ] | mygadget.js | mygadget.css.

{
	"settings": {
		"rights": [ "foo", "bar" ],
		"default": false,
		"package": false,
		"hidden": false,
		"skins": [],
		"actions": [],
		"category": ""
	},
	"module": {
		"scripts": [ "mygadget.js" ],
		"styles": [ "mygadget.css" ],
		"datas": [],
		"peers": [],
		"dependencies": [],
		"codexIcons": [],
		"messages": [],
		"type": ""
	}
}

В примере выше используются Gadget:Mygadget.js и Gadget:mygadget.css.

Опции

Опции

Имя	Параметры	Описание	С версии
ResourceLoader	Нет	Marks gadget's scripts as compatible with Загрузчик ресурсов .	1.17 (r76527)
dependencies	Разделённые запятой названия модулей	These modules will be loaded before the scripts of this gadget execute. См. список модулей по умолчанию.	1.17 (r76639)
rights	Разделённые запятой названия привилегий	Make the gadget available (and visible in preferences) only to users who have the specified privileges.	1.18 (r85268)
hidden	Нет	Скрыть гаджет со страницы Настройки. Это может использоваться в двух случаях: Сделать гаджет включённым по умолчанию без возможности выключения (в качестве модульной альтернативы Common.js). Обратите внимание, что вам нужно будет добавить оба hidden | default для загрузки модуля для всех участников. Гаджеты, которые предназначены не для конечных пользователей, а для загрузки другими гаджетами. Например, чтобы позволить двум гаджетам повторно использовать один и тот же код или зарегистрировать «основную» часть гаджета, которая загружается только на определенных страницах.	1.28
skins	Разделённые запятой названия тем оформления	Make the gadget available (and visible in preferences) only to users who use the specified skins. Before MediaWiki 1.32 it was taking into consideration the skin set in preferences for the user, not the current displayed one (like when adding ?useskin=monobook in the URL, T199478). Since 1.39, the ResourceLoader module is not registered on skins the gadget is unavailable on, so the gadget cannot be loaded on those skins as a dependency or using mw.loader.load() either (T236603). Использование skins — это крайняя мера, которую следует ограничивать специализированным кодом. Например, таким, который зависит от манипуляций с DOM при отсутствии стандартизированных API и не может быть реализован с помощью основных модулей.	1.19 (r100509)
actions	Разделённые запятой названия действий	Сделать гаджет доступным только при указанных действиях со страницей. Например, actions = edit, history загрузит гаджет только при редактировании и просмотре страниц истории. Указание действия edit также будет загружать его при action=submit. Недопустимые действия фактически отключают гаджет, так как его невозможно будет запустить нигде.	1.38 (gerrit:747112)
categories	Разделённые запятой названия категорий	Сделать гаджет доступным только в указанных категориях. Например, categories = Archived, Maintenance загрузит гаджет только на страницах в Category:Archived или Category:Maintenance. См. также: Template gadgets	1.42 (gerrit:1005092)
namespaces	Разделённые запятой числа пространств имён	Сделать гаджет доступным только в указанных пространствах имён. Например, namespaces = 0, 2 загрузит гаджет только в основном пространстве и пространстве Участник.	1.41 (gerrit:624517)
contentModels	Разделённые запятой названия моделей	Сделать гаджет доступным только в указанных контентных моделях. Например, contentModels = wikitext загрузит гаджет только на страницах с викиразметкой.	1.41 (gerrit:922062)
default	Нет	Включить гаджет по умолчанию для всех (включая незарегистрированных пользователей). Зарегистрированные участники всё ещё могут отключить его в своих настройках.	1.18 (r85902)
package	Нет	Пометить этот гаджет упакованным. В этом режиме будет выполнена только первая страница с JavaScript. Остальные можно подключить с помощью функции require(). В этом режиме также становится доступным использование страниц в формате JSON, которые иначе подключить нельзя.	1.38
type	styles (по умолчанию для гаджетов только с CSS) или general (по умолчанию в остальных случаях)	Используйте styles для модулей, которые только изменяют оформление уже находящихся на странице элементов (например, при настройке темы, макета или содержимого статьи). Это приведёт к тому, что CSS-файлы модуля будут подключаться напрямую из HTML страницы, а не загружаться через JavaScript. Подробнее см. ResourceLoader/Migration guide (users)#Gadget type. При использовании styles не будут загружены какие-либо указанные JavaScript-файлы. Для гаджетов, которые изменяют оформление элементов с помощью как JavaScript, так и CSS, требуется два отдельных определения гаджета.	1.28
peers	Разделённые запятой названия гаджетов	Peers are CSS-only gadgets that will be enabled together with your gadget. Peer styles are applied even when JavaScript is disabled. Note that peers are not included when loading a gadget via mw.loader.load([..]) unless you include them in the array yourself, because they are not considered "dependencies". Подробнее см. ResourceLoader/Migration guide (users)#Gadget peers.	1.29
codexIcons	Comma-separated codex icon names	These Codex icons will be loaded with this gadget, see List of all icons. They will be available from an icons.json file generated in the package.	1.45 (gerrit:1108823)
supportsUrlLoad	Нет | true | false	Сделать гаджет доступным для загрузки с помощью параметра URL-запроса ?withgadget.	1.38

Удалённые опции

Имя	Параметры	Описание	С версии	Удалено в версии
top	Нет	Makes the gadget to be top-loaded. This should be used sparingly, but may be needed for some initialization stuff like registering plugins with VisualEditor.	1.22 (gerrit:75506)	1.29
requiresES6	None	Allow use of ES6 syntax (ES2015) in the gadget. Enabling this means server-side syntax validation is skipped for the gadget. Any ES6-requiring gadgets are loaded together in a single web request, which isolates failures due to invalid or unsupported syntax to those gadgets only, without affecting other gadgets and MediaWiki software features. It is recommended to use a tool like ESLint to ensure only valid ES6 syntax is used. Conflicts with default. This option has not actually been removed. See talk page discussion.	1.40 (gerrit:758086)	1.42
targets	desktop (по умолчанию), mobile или desktop, mobile	Set the Загрузчик ресурсов target(s) for the gadget. Do not use targets, instead use skins where absolutely necessary.	1.21 (gerrit:60954)	1.42

You can specify extra dependencies for your gadgets, for example:

* mygadget[ResourceLoader|dependencies=jquery.ui, jquery.effects.clip]|mygadget.js|mygadget.css

Here, we ask ResourceLoader to load modules jquery.ui and jquery.effects.clip with mygadget. Note that gadgets can't depend on scripts from pages, static files, or external URLs, only on modules already registered in ResourceLoader. To make a script from a page depend on another script from a page, each should be a gadget that registers itself as a module in ResourceLoader, then they can be made to have dependencies using the following syntax:

* childgadget[ResourceLoader|dependencies=ext.gadget.parentgadget]|childgadget.js

Чтобы включить гаджет по умолчанию, используйте «default»:

* mygadget[ResourceLoader|default|dependencies=mediawiki.util]|mygadget.js|mygadget.css

To make the gadget available only to users with appropriate permissions, set the rights option, for example:

* ImprovedDeletion [rights=delete] | ImprovedDeletion.js

It makes the gadget available only to users who can delete pages.

Note that restrictions are based on permissions, not user groups like administrators or bureaucrats. Вот несколько реальных примеров:

* modrollback [ResourceLoader |rights=rollback] |modrollback.js
* geonotice [ResourceLoader |default |rights=viewmywatchlist] |geonotice.js
* Ajax_sysop [ResourceLoader |rights=patrol, rollback, markbotedits, delete]|Ajax_sysop.js

Страницы

Оставшиеся поля в строке определения относятся к исходным страницам JavaScript, CSS, JSON (с версии 1.38) и Vue.js (с версии 1.45), из которых состоит модуль гаджета. Они хранятся в пространстве имён MediaWiki как сообщения интерфейса (например, MediaWiki:Gadget-mygadget.js и MediaWiki:Gadget-mygadget.css). Имена страниц должны заканчиваться на .css, .js, .json, .vue, соответственно.

Гаджет может использовать любое количество страниц с кодом, например:

 * frobinator[ResourceLoader]|frob.js|frob.css|pretty.css
 * l33t[ResourceLoader]|l33t.js
 * foobar[ResourceLoader|package]|foo.js|bar.js|foobar-data.json
 * foo[ResourceLoader|package|dependencies=vue,@wikimedia/codex]|codextest.js|codextest-main.vue|codextest-ChangeNameDialog.vue

Обратите внимание, что если в вашем коде есть строки, которые могут быть восприняты как синтаксис викитекста (например, код подписи ~~~~), лучше заключить код в ‎<nowiki>...‎</nowiki> и поместить эти теги в комментарии JavaScript или CSS, чтобы они не интерпретировались при использовании.

Например, см. в 12-й и последней строках MediaWiki:Gadget-formWizard-core.js.

Разделы

Список гаджетов в MediaWiki:Gadgets-definition можно разбить на разделы с помощью строк, которые начинаются и заканчиваются двумя или более символами «=» (равно), заключая в себя имя системного сообщения, задающего название раздела, например:

 == interface-gadgets ==
 ...
 == editing-gadgets ==
 ...

Так будут созданы два новых раздела с названиями, определёнными на страницах MediaWiki:Gadget-section-interface-gadgets и MediaWiki:Gadget-section-editing-gadgets.

Популярные гаджеты

Для гаджетов, популярных в сообществах Викимедиа, см. meta:Gadgets.

См. также

• Special:Gadgets – перечисляет все гаджеты и их краткие описания
• Менеджер гаджетов
• Extension:Widgets
• Сниппеты