Manual:マジックワード

マジックワードとは単一の関数の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（Help:Variables を参照）と MagicWordwgVariableIDs フックに接続する関数をすべて提供するカスタム変数IDのリストから、変数IDのリストを取得します。
     • If the magic word ID has been classified as a variable, MediaWiki calls the ParserGetVariableValueSwitch function to get the value associated with the variable name.

   
   

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

By convention:

• 変数と呼ばれるマジックワードは大文字化され、大文字/小文字が区別され、空白文字を含みません。
• Parserfunctions are prefixed with a hash sign (#), are case insensitive and do not include space characters.

しかし、これは慣例であり、(歴史的な理由により) 一貫しては適用されていません。

• 変数に空白文字は含みませんが、一部の言語では変数の翻訳が空白文字を含む場合があります
• 変数は一般に大文字化され、大文字/小文字が区別されますが、一部のパーサー関数でもこの命名規則が使われている。
• パーサー関数には、ハッシュ記号 (#) で始まるものと、そうでないものがあります。

Where possible you should follow the conventions when defining or translating magic words. Magic words are higher in priority than templates, so any magic word defined, will block the usage of that defined name as a template.

Following the conventions avoids adding more and more potential collisions.

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

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

• ウィキテキストとマジックワード ID の対応付け

• a mapping between a magic word ID and some php function that interprets the magic word.

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

$magicWords関数を使い、それぞれのマジックワードIDとそれを文字列と関連付ける言語依存型の配列の対応付けを行います。 重要点: これにより処理されるのはバックエンドの地域化対応付け (i18nマッピング) のみで、MediaWikiにあらゆるものを扱わせるには、さらにその他のコード作成が必要です。 Also, make sure that you initialize $magicWords as an empty array before adding language-specific values or you will get errors when trying to load the magic word and will need to rebuild your localization cache before it will work.

この配列の最初の要素とは、マジックワードが大文字小文字を区別するかどうかを示す整数フラグです。残りの要素とは、マジックワード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" は、間違って他の関数を上書きしないよう、意図的に追加してあるからです。

In inline PHP

You can associate magic words inline in PHP rather than through a i18n file. これは LocalSettings.php でフックを定義するときに便利ですが、拡張機能では使用してはいけません。

MediaWiki\MediaWikiServices::getInstance()->getContentLanguage()->mMagicExtensions['wikicodeToHtml'] = ['MAG_CUSTOM', 'custom'];

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

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

• Manual:パーサー関数
• Manual:Variables

地域化

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

You can read more on definition and usage of magic words for localisation at Manual:Messages API, Manual:Language#Namespaces; Avoid {{SITENAME}} in messages.

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

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

これらの特殊なマジックワードの出力は内容（コンテンツ）ではなくページの挙動の変更と/あるいはページの属性を決定します。 一覧は MagicWordFactory::mDoubleUnderscoreIDs で取得でき、ヘルプ:マジックワード#挙動スイッチでも参照できます。 The effect of most standard behavior switches is defined in Parser::handleDoubleUnderscore(). 特に効果を規定していない場合、マジックワードは単にページ属性 (page_props) テーブルにページの属性を書き込みます。 これは、$parser->getOutput()->getPageProperty( 'MAGIC_WORD' ) が null か空文字列かどうかをテストすることで、後で確認することもできます

Custom behavior switch

以下は、カスタム __CUSTOM__ 挙動スイッチを実装した拡張機能の例です

custom/extension.json - This is minimal, a real extension would fill out more fields.

{
	"name": "Custom",
	"type": "parserhook",
	"AutoloadClasses": {
		"MyHooks": "MyHooks.php"
	},
	"Hooks": {
		"GetDoubleUnderscoreIDs": [
			"MyHooks::onGetDoubleUnderscoreIDs"
		],
		"ParserAfterParse": [
			"MyHooks::onParserAfterParse"
		]
	},
	"ExtensionMessagesFiles": {
		"CustomMagic": "custom.i18n.php"
	},
	"manifest_version": 1
}

custom/custom.i18n.php

<?php
$magicWords = [];
$magicWords['en'] = [
	'MAG_CUSTOM' => [ 0, '__CUSTOM__' ],
];

custom/MyHooks.php

<?php
class MyHooks {
	public static function onGetDoubleUnderscoreIDs( &$ids ) {
		$ids[] = 'MAG_CUSTOM';
	}

	public static function onParserAfterParse( Parser $parser, &$text, StripState $stripState ) {
		if ( $parser->getOutput()->getPageProperty( 'MAG_CUSTOM' ) !== null ) {
			// Do behavior switching here ...
			// e.g. If you wanted to add some JS, you would do $parser->getOutput()->addModules( 'moduleName' );
		}
	}
}

関連項目

• Help:マジックワード - {{PAGENAME}}や{{SERVER}}などの変数の一覧
• Manual:MagicWord.php