Manual:マジックワード

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page Manual:Magic words and the translation is 95% complete.

Outdated translations are marked like this.
Other languages:
Bahasa Indonesia • ‎Deutsch • ‎English • ‎Lëtzebuergesch • ‎Türkçe • ‎dansk • ‎español • ‎français • ‎galego • ‎italiano • ‎magyar • ‎polski • ‎português do Brasil • ‎svenska • ‎русский • ‎العربية • ‎ไทย • ‎中文 • ‎日本語 • ‎한국어
Gnome-preferences-other.svg 拡張機能: 開発 タグ拡張機能 パーサー関数 フック 特別ページ 外装 マジックワード API Content models
MediaWiki 拡張機能

マジックワードとは単一の関数のIDに対応するさまざまなウィキテキスト文字列を対応付けする技術で、変数 にもパーサ関数にも使われています。特定のIDに対応付けされたさまざまなテキストは、関数の戻り値に置換されます。$wgExtensionMessagesFiles[]を使って読み込んだファイルの$magicWords変数には、IDに対応するすべての文字列を格納します。

既定のマジックワードはCoreParserFunctions.php で実装されています。

マジックワードの動作の仕組み

MediaWikiでは二重の角括弧 ({{XXX ...}}) に挟まれた文字列を検地すると、その中に含まれるXXXが変数もしくはパーサ関数あるいはテンプレートのどれに該当するか識別必要があります。そのためにいくつかの問いを解きます。

  1. 文字列にはマジックワードのIDが付帯するか? {{XXX...}}という文字列のマークアップ解決において最初にMediaWikiはXXXをマジックワードIDに変換できるかどうか検討します。変換テーブルは$magicWordsによって定義されます。
    • 付帯するマジックワードIDが見つからない場合、XXXテンプレートだと判断されます。

  2. 関数ではないか? マジックワードIDが検出されると、MediaWikiは次にパラメータがあるかどうか確認します。
    • パラメータを検出しなかった場合、MediaWikiはマジックワードIDが有効なIDかどうか確認します。手順はMagicWord::getVariableIDs()を呼び出し、表示されるマジックワードのリストを取得します。この方法により、ハードコードされた変数ID(ヘルプ:関数を参照)とMagicWordwgVariableIDsフックに接続する関数をすべて提供するカスタム変数IDのリストから、変数IDのリストを取得します。
      • マジックIDが変数として分類されると、フックMediaWikiはイベント名'ParserGetVariableValueSwitch'に関連する関数を呼び出し続け、マジックワードを認識してその値を返すことができる変数を検出します。

  3. パーサ関数かどうか? パラメータもしくはマジックワードID一覧のIDの欠落の検出により、MediaWikiは当該のマジックワードをパーサ関数もしくはテンプレートだと判定します。$wgParser->setFunctionHook($magicWordId, $renderingFunctionName)を呼び出してパーサ関数を取得し、そこで検出したマジックワードIDは パーサ関数として扱われ、$renderingFunctionName関数を使用して処理します。あるいはテンプレートだと判定されます。


マジックワードを定義する

マジックワードが期待される処理を実行するには、2点を定義します。

  • ウィキテキストとマジックワードIDの対応付け
  • マジックワードIDとマジックワードを解釈するphp関数

ウィキテキストからマジックワード ID への対応付け

$magicWords関数を使い、それぞれのマジックワードIDとそれを文字列と関連付ける言語依存型の配列の対応付けを行います。 重要点: これにより処理されるのはバックエンドの地域化対応付け (i18nマッピング) のみで、MediaWikiにあらゆるものを扱わせるには、さらにその他のコード作成が必要です。

この配列の最初の要素とは、マジックワードが大文字小文字を区別するかどうかを示す整数フラグです。残りの要素とは、マジックワードIDに関連付ける必要のあるテキストの一覧です。大文字小文字を区別するフラグが0の場合、配列内の名前のあらゆる大文字と小文字の組み合わせが一致します。大文字小文字の区別フラグが1の場合、マジックワードIDに関連付けられるのは、大文字小文字表記が完全に一致するものに限定されます。 以上をふまえた書式は右のとおりです。$magicWords['en'] = [ 'InternalName' => [ 0, 'NameUserTypes', 'AdditionalAliasUserCanType' ] ];

この組み合わせは$wgExtensionMessagesFiles[]を介して保存された特定のファイルから、$magicWordsを使って生成しました。

下記にスペイン語版MediaWikiのインストールに'MAG_CUSTOM' というマジックワードIDと"personalizado"と"custom"、"PERSONALIZADO"と"CUSTOM"にその他のケース変数を加えて処理した例を示します。英語版MediaWikiの場合だと、'MAG_CUSTOM'に対応付けるのはさまざまなケース関数の組み合わせでも"custom"関数のみです。

ファイル Example.i18n.magic.php:

<?php

$magicWords = [];

$magicWords['en'] = [
	'MAG_CUSTOM' => [ 0, 'custom' ],
];

$magicWords['es'] = [
	'MAG_CUSTOM' => [ 0, 'personalizado' ],
];

In part of the extension.json file:

"ExtensionMessagesFiles": {
	"ExampleMagic": "Example.i18n.magic.php"
}

もし単純な国際化ファイルを扱うとしたら、キーとして"ExampleMagic"を用いることはできない (通常、"Example"など拡張機能の表題部分のみ使用しMagicは加えない) 点にご注意ください。"Magic" は、間違って歩かの関数を上書きしないよう、意図的に追加してあるからです。

マジックワード ID と PHP 関数の関連付け

マジックワードIDと処理関数の対応付けの仕組みはマジックワードの使われ方に依存し、パーサ関数あるいは変数のどちらかで決まります。詳細については以下を参照してください。

マジックワードの登録

MediaWiki 1.8以降はマジックワードIDの登録に制限条件はありません。マイックワードIDを用いるパーサ関数ないし変数を登録すれば完了です。1.8以前のバージョンにおける処理法は以下の節を参照してください。

地域化

ヘルプは Help:Magic words#地域化 を参照してください。

マジックワー殿定義と使用法を地域化するには、JavaScriptにおける複数形や性別 Localisation#PLURAL and GENDER support in JavaScriptと名前空間名と特別ページの別名 Localisation#Localizing namespaces and special page aliases、メッセージ内のスイッチ Localisation#Switches in messages…を参照してください。数字の複数形の扱い Localisation#Be aware of PLURAL use on all numbersと利用者の文法上の性別 Localisation#Users have grammatical gendersあるいはメッセージ内にサイト名を含めない [[S</nowiki>Localisation#Avoid_.7B.7BSITENAME.7D.7D_in_messages|Avoid {{SITENAME}} in messages]]などの注意事項も役に立ちます。

挙動の切り替え(二重の下線で囲まれたマジックワード)

挙動スイッチとは特殊なマジックワードを指します。 (二重の角括弧ではなく) 二重の下線(_)を使用するのが特徴で、__NOTOC__のようになります。

これらの特殊なマジックワードの出力は内容(コンテンツ)ではなくページの挙動の変更と/あるいはページの属性を決定します。一覧はMagicWord::mDoubleUnderscoreIDsで取得でき、ヘルプ:マジックワード#挙動スイッチでも参照できます。挙動スイッチの効果はそれぞれParser::doDoubleUnderscore()に規定されます。特に効果を規定していない場合、マジックワードは単にページ属性 (page_props) テーブルにページの属性を書き込みます。

関連項目