Jump to content

Extension:Gadgets

From mediawiki.org
This page is a translated version of the page Extension:Gadgets and the translation is 47% complete.
この拡張機能は MediaWiki 1.18 以降に同梱されています。 そのため再度ダウンロードする必要はありません。 しかし、提供されているその他の手順に従う必要はあります。
MediaWiki 拡張機能マニュアル
Gadgets
リリースの状態: 安定
実装 自分のウィキ , 特別ページ , API
説明 環境設定画面からJSベースのユーザー提供型ガジェットを有効にできるようにしました。
作者 Daniel Kinzler (Duesentriebトーク)
互換性の方針 MediaWiki とともにリリースされるスナップショット。 master には後方互換性がありません。
MediaWiki 1.19+
ライセンス GNU 一般公衆利用許諾書 2.0 以降
ダウンロード
README
ウィキメディア・コモンズ ガジェットの概要、, 個人設定。 (「ガジェット」をクリック。もちろんログインする必要があります)
  • $wgGadgetsRepo
  • $wgSpecialGadgetUsageActiveUsers
四半期ごとのダウンロード数 107 (Ranked 53rd)
使用中の公開ウィキ 4,529 (Ranked 177th)
translatewiki.net で翻訳を利用できる場合は、Gadgets 拡張機能の翻訳にご協力ください
問題点 未解決のタスク · バグを報告

ガジェット拡張機能は他の利用者にJavaScriptやCSSベースのガジェットを提供することを可能にします。

ガジェットは MediaWiki 名前空間のページにある JavaScript と CSS スニペット で構成されています。 各ガジェットは MediaWiki:Gadgets-definition の1行で定義され、名前と説明、使用するJSとCSSスニペットのリストで構成されます(Usageセクションを参照)。

ガジェットはMediaWiki名前空間(ガジェットを定義するリストと実際のコードスニペット)に存在するため、コードを編集できるのはシステム担当者(1.32以降のインターフェイス管理者)だけです。 これは当然のことです。JavaScriptはアカウントの乗っ取りや人へのスパイに簡単に使用できるため、ウィキコミュニティから特に信頼されているユーザーのみが、他のユーザーが使用するJavaScript コードを編集できるようにする必要があります。

インストール

  • ダウンロードして、ファイルをextensions/フォルダー内のGadgetsという名前のディレクトリ内に配置します。
    開発者とコード寄稿者は、上記の代わりに以下を使用してGitからインストールします:cd extensions/
    git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Gadgets
  • 以下のコードを LocalSettings.php ファイルの末尾に追加します:
    wfLoadExtension( 'Gadgets' );
    
  • Yes 完了 – ウィキの「Special:Version」に移動して、拡張機能が正しくインストールされたことを確認します。

使用法

de.wikipediaのユーザー環境設定でのいくつかのガジェットの選択

Once MediaWiki:Gadgets-definition is created with at least one valid gadget, a new "Gadgets" section will be shown on Special:Preferences for all users. Users can enable the gadgets they would like to use there. An overview of gadgets currently defined by MediaWiki:Gadgets-definition is also rendered on Special:Gadgets, along with helpful links to the relevant localisation and script/style pages for easy creation or editing. Statistics about gadget preferences are available at Special:GadgetUsage.

定義の書式

Each line on the MediaWiki:Gadgets-definition page should start with a "*" (asterisk) character to define a gadget. The line takes the following format:

* mygadget [options] | ページ名(群)

The first field ("mygadget" in the example) is the gadget's internal name. 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.

The internal name must begin with a basic Latin letter ([A-Za-z]) and may be followed by any number of letters, digits ([0-9]), hyphens (-), underscores (_), and periods (.). The reason for this limitation is that the internal name must be valid as the name of an HTML form name, as MediaWiki interface message key, and as ResourceLoader module name.

オプションの書式:

[ResourceLoader | オプション1 | オプション2 | ... オプションN]

The ResourceLoader 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.css

または

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

Using Gadget Definition Namespace

There are two ways to define gadgets depending on the $wgGadgetsRepoClass. If It is 'MediaWikiGadgetsDefinitionRepo' (the default value), the list of available gadgets is defined on MediaWiki:Gadgets-definition. In an alternative way, Gadget definitions are defined on pages in the Gadget definition namespace when $wgGadgetsRepoClass is set to 'GadgetDefinitionNamespaceRepo'.

既存のガジェット定義の移入はまだサポート外であり、以下のオプションを変更するとガジェット定義は上書きされ以前に書いたものは失われます。

Creation of the Gadget definition:mygadget page and putting in it the below JSON code have the same effect as 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": [],
		"messages": [],
		"type": ""
	}
}

In above example, the Gadget:Mygadget.js and the Gadget:mygadget.css are used.

オプション

名前 パラメーター 説明 バージョン
ResourceLoader なし Marks gadget's scripts as compatible with ResourceLoader . 1.17 (r76527)
dependencies Comma-separated module names These modules will be loaded before the scripts of this gadget execute. See list of default modules. 1.17 (r76639)
rights Comma-separated privilege names Make the gadget available (and visible in preferences) only to users who have the specified privileges. 1.18 (r85268)
hidden なし Hide the gadget from the Preferences page. This can be used in two ways:
  • Enable a gadget by default without ability to disable (as modular alternative to Common.js). Note that you need to add both: hidden | default to load a module for all users.
  • Gadgets that are not meant for end-users, but rather are meant to be loaded by other gadgets. For example to allow two gadgets to re-use the same internal code, or to register the "core" part of a gadget that only loads on certain pages.
1.28
skins Comma-separated skin names 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).
Use of skins is a last resort, and should be restricted to specialized code. For example code which relies on DOM manipulation in the absence of standardized APIs and that cannot be implemented using Core modules.
1.19 (r100509)
actions Comma-separated action names Make the gadget available only on the specified page actions. E.g. actions = edit, history to load a gadget only while editing and on history pages.
Specifying edit action will also load it on action=submit. Invalid actions effectively disable the gadget since it can't be run anywhere.
1.38 (gerrit:747112)
categories Comma-separated category names Make the gadget available only on the specified categories. E.g. categories = Archived, Maintenance to load a gadget only on pages in the Category:Archived or Category:Maintenance. 1.42 (gerrit:1005092)
namespaces Comma-separated namespace numbers Make the gadget available only on the specified namespaces. E.g. namespaces = 0, 2 to load a gadget only in mainspace and user namespace. 1.41 (gerrit:624517)
contentModels Comma-separated content models Make the gadget available on pages with the given content models. E.g. contentModels = wikitext to load a gadget only on wikitext pages. 1.41 (gerrit:922062)
default なし Enable the gadget by default for everyone (including IPs). Registered users can still disable it in their preferences. 1.18 (r85902)
package なし Mark this gadget as packaged. In this mode, only the first JavaScript page will be executed. Other pages can be imported by using the require() function. This mode also enables use of JSON pages, which cannot be included otherwise. 1.38
targets desktop, mobile or desktop,mobile(default) (1.42.0-wmf.16 で除去) Set the ResourceLoader target(s) for the gadget.
Do not use targets, instead use skins where absolutely necessary.
1.21 (gerrit:60954)
type styles (default for CSS-only gadgets) or general (default otherwise) Use styles for modules that only modify styling for elements already on the page (e.g. when customizing the skin, layout, or article content). It will cause the CSS files of the module to be included from the page HTML instead of being loaded via JavaScript. 詳細はResourceLoader/Migration guide (users)#Gadget typeを参照。
Using styles will not load in any specified JavaScript files. For gadgets that modify styling for elements through both JavaScript and CSS, two individual gadget definitions are required.
1.28
peers Comma-separated gadget names These CSS-only gadgets will be loaded together with this gadget. These gadgets will be loaded before any dependencies, and their styles will be applied even if JavaScript is disabled. 詳細はResourceLoader/Migration guide (users)#Gadget peersを参照。 1.29.0
supportsUrlLoad なし | true | false Make the gadget available to be loaded with the ?withgadget URL query parameter. 1.38
requiresES6 None (1.42.0-wmf.13 で除去) ES6 構文 (ES2015) をガジェットで使えるようにします。 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. 1.40.0-wmf.7 (gerrit:758086)
top なし (1.29 で除去) ガジェットの優先順位を top-loadedに指定。 This should be used sparingly, but may be needed for some initialization stuff like registering plugins with VisualEditor. 1.22 (gerrit:75506)

依拠関係をさらに定義するには、次の例があります。

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

この段階で ResourceLoader にモジュールの jquery.uijquery.effects.clip を mygadget とともに読み込むようリクエストします。 留意点として、ガジェット類は特定のページに書いたスクリプト、静的なファイルもしくは外部URLに依拠することは不可能で、ResourceLoader に登録済みのモジュールのみに規定されます。 特定のページにあるスクリプトを、他のページの特定のスクリプトに依拠させるには、どちらもガジェットであり ResourceLoader にモジュールとして定義する必要があり、その後、以下の構文を使って依存関係を定義します。

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

既定でガジェットを有効にするには"default"を採用:

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

適格な権限を預かる利用者のみガジェットを使えるようにするには、 rights オプションをたとえば以下のように設定します。

* ImprovedDeletion [rights=delete] | ImprovedDeletion.js

ガジェットの利用範囲は、実際にページ削除の権限がある人にのみ限定します。

制限は 許可に依拠し、管理者またはビューロクラットなどの利用者グループではありません。 実例をいくつかご紹介します。

* modrollback[ResourceLoader|rights=rollback]|modrollback.js
* UTCLiveClock[ResourceLoader|rights=purge]|UTCLiveClock.js
* Ajax_sysop[ResourceLoader|rights=patrol,rollback,markbotedits,delete]|Ajax_sysop.js


利用者権限

この拡張機能は、gadgets-editgadgets-definition-edit という新規の利用者権限2件を設定し、既定でこれを付与されたグループはありません。

LocalSettings.php に以下を加筆すると、インタフェース管理者グループに参加する利用者に適切な許可を付与します。 Gadget 名前空間にあるページを編集するには gadgets-edit 権限が必要で、ガジェット定義の名前空間にあるページは gadgets-definition-edit 権限がないと編集できません。

$wgGroupPermissions['interface-admin']['gadgets-edit'] = true;
$wgGroupPermissions['interface-admin']['gadgets-definition-edit'] = true;

ページ

定義行の残りのフィールドにはガジェットのモジュールを構成する JavaScript、CSS、JSON のソースページ が入ります。 これらの収容先は MediaWiki 名前空間で、インタフェース・メッセージとして記録されます(サンプルの MediaWiki:Gadget-mygadget.jsMediaWiki:Gadget-mygadget.css) ページ名の末尾には必ず ".css"、".js"、".json" のいずれかを書きます。

特定のガジェットごとに使えるソースページの数は無制限であり、例を示します。

 * frobinator[ResourceLoader]|frob.js|frob.css|pretty.css
 * l33t[ResourceLoader]|l33t.js
 * foobar[ResourceLoader|package]|foo.js|bar.js|foobar-data.json

ご留意点として、ウィキ構文と読み取れる文字列がコードが含まれている場合(例:署名の記法である~~~~)、その部分を‎<nowiki>...‎</nowiki> で挟んでタグを JavaScript または CSS のコメントにして、走らせたときに解釈されないようにしてください。

MediaWiki:Gadget-externalsearch-bar.js の1行目と最終行を参照。

2個以上の "="(等号)で挟まれた見出しを手掛かりに、MediaWiki:Gadgets-definition にあるガジェットの一覧を切り分け、節の題名を定義するシステムメッセージ単位にまとめることができます。その例です。

 == interface-gadgets ==

これで新しい節を定義し、ページのMediaWiki:Gadget-section-interface-gadgetsにある題名を添えます。

汎用されるガジェット

meta:Gadgetsには、ウィキメディアのコミュニティ間で汎用されるガジェットをまとめてあります。

関連項目