Manual:マジックワード
Magic words are strings of text that MediaWiki links to specific functions or return values, such as current date and time, page titles, site information, and more. They can be thought of as special commands or variables that allow dynamic content generation and interaction with the MediaWiki software during page rendering.
From a technical standpoint, magic words map a range of wiki text strings to a unique internal identifier (ID), which is then associated with a particular function. This ID directs MediaWiki to execute a corresponding operation or return a specific value. Both variables (which output dynamic values) and parser functions (which perform operations or conditional logic) make use of this mapping technique.
特定のIDに対応付けされたさまざまなテキストは、関数の戻り値に置換されます。
$wgExtensionMessagesFiles[] を使って読み込んだファイルの $magicWords 変数には、ID に対応するすべての文字列を格納します。
既定のマジックワードはCoreParserFunctions.phpで実装されています。
マジックワードの動作の仕組み
MediaWikiでは二重の波括弧に挟まれた文字列 ({{XXX ...}}) を検知すると、その中に含まれるXXXが変数、パーサー関数あるいはテンプレートのどれに該当するか識別する必要があります。そのためにいくつかの問いを解きます。
- マジックワード ID が関連付けられているか?
{{XXX...}}形式のマークアップを解決する最初の段階として、 MediaWiki は XXX をマジックワード ID に変換できるかどうか検討します。変換テーブルは $magicWords によって定義されます。- XXX に関連付けられたマジックワード ID が見つからない場合、XXX はテンプレートと見なされます。
- 変数か? マジックワードIDが検出されると、MediaWikiは次にパラメータがあるかどうか確認します。
- パラメータを検出しなかった場合、MediaWikiはマジックワードIDが有効な変数IDとして宣言されているかどうか確認します。 これを確認するために、
MagicWord::getVariableIDs()を呼び出し、マジックワードのリストを取得します。 この方法により、ハードコードされた変数ID（Help:Variables を参照）と MagicWordwgVariableIDs フックに接続する関数をすべて提供するカスタム変数IDのリストから、変数IDのリストを取得します。- マジックワードIDが変数に分類されている場合、MediaWikiは変数名に関連付けられている値を取得するために ParserGetVariableValueSwitch 関数を呼びます。
- パラメータを検出しなかった場合、MediaWikiはマジックワードIDが有効な変数IDとして宣言されているかどうか確認します。 これを確認するために、
- パーサー関数か? パラメータがあるもしくはマジックワードIDが変数マジックワードIDのリストにない場合、MediaWikiは当該のマジックワードをパーサー関数もしくはテンプレートだと判定します。 宣言されているパーサー関数のリストでそのマジックワードIDが見つかれば、パーサー関数として扱われ、
$renderingFunctionNameという関数を使用して処理します。 そうでなければ、テンプレートだと見なされます。
マジックワードを定義する
慣習により：
- 変数と呼ばれるマジックワードは大文字化され、大文字/小文字が区別され、空白文字を含みません。
- パーサー関数はハッシュ記号 (#) を前に付け、大文字と小文字を区別せず、空白文字を含みません。
しかし、これは慣例であり、(歴史的な理由により) 一貫しては適用されていません。
- 変数に空白文字は含みませんが、一部の言語では変数の翻訳が空白文字を含む場合があります
- 変数は一般に大文字化され、大文字/小文字が区別されますが、一部のパーサー関数でもこの命名規則が使われている。
- パーサー関数には、ハッシュ記号 (#) で始まるものと、そうでないものがあります。
可能であればマジックワードを定義または翻訳するときは慣習に従うべきです。 マジックワードはテンプレートよりも優先順位が高いので、マジックワードが定義されていると定義された名前はテンプレートとして使えなくなります。
競合の可能性が増えるのを避けるために慣習に従ってください。マジックワードが期待される処理を実行するには、以下の 2 点を定義します:
- ウィキテキストとマジックワード ID の対応付け
- マジックワード ID とマジックワードを解釈する php 関数の対応付け。
ウィキテキストからマジックワード ID への対応付け
$magicWords変数を使い、マジックワードIDに対応付けられたすべてのテキスト文字列を記述した言語依存の配列をそれぞれのマジックワードIDに関連付けます。
重要点: これにより処理されるのはバックエンドの地域化対応付け (i18nマッピング) のみで、MediaWikiがそのマジックワードをあらゆることに使うようにするには、さらにその他のコード作成が必要です。
また、言語別の値を追加する前に $magicWords を空の配列として初期化していることを確かめてください。そうしないと、マジックワードを読み込もうとしたときにエラーが発生し、地域化キャッシュを再構築しないと動作しなくなります。
この配列の最初の要素は、マジックワードが大文字小文字を区別するかどうかを示す整数フラグです。残りの要素は、マジックワードIDに関連付けるべきテキストのリストです。大文字小文字を区別するフラグが0の場合、配列内の名前のあらゆる大文字と小文字の変化にマッチします。大文字小文字の区別フラグが1の場合、マジックワードIDに関連付けられるのは、大文字小文字表記が完全に一致するものに限定されます。
以上をふまえた書式は右のとおりです。$magicWords['en'] = [ 'InternalName' => [ 0, 'NameUserTypes', 'AdditionalAliasUserCanType' ] ];
この組み合わせは $wgExtensionMessagesFiles[] を介して保存された特定のファイルから、$magicWordsを使って生成しました。
下記の例では、スペイン語版 MediaWiki のインストレーションは 'MAG_CUSTOM' というマジックワード ID を "personalizado"、"custom"、"PERSONALIZADO"、"CUSTOM" およびその他のあらゆる大文字と小文字の変化と関連付けます。 英語版 MediaWiki では、"custom"の様々な大文字と小文字の組み合わせのみを 'MAG_CUSTOM' に対応付けます。
ファイル Example.i18n.magic.php:
<?php
$magicWords = [];
$magicWords['en'] = [
'MAG_CUSTOM' => [ 0, 'custom' ],
];
$magicWords['es'] = [
'MAG_CUSTOM' => [ 0, 'personalizado' ],
];
extension.json ファイルの一部:
"ExtensionMessagesFiles": {
"ExampleMagic": "Example.i18n.magic.php"
}
単純な国際化ファイルで使うキー（通常は "Example" のように拡張機能のタイトルだけ）と異なり、 "ExampleMagic" としていることにご注意ください。間違って他のものを上書きしないよう、意図的に "Magic" を追加しています。
インライン PHP
i18n ファイルを通じてではなく、 PHP でインラインにマジックワードを関連付けることができます。
これは LocalSettings.php でフックを定義するときに便利ですが、拡張機能では使用してはいけません。
MediaWiki\MediaWikiServices::getInstance()->getContentLanguage()->mMagicExtensions['wikicodeToHtml'] = ['MAG_CUSTOM', 'custom'];
マジックワード ID と PHP 関数の関連付け
マジックワードIDとレンダリング関数の関連付けの仕組みは、マジックワードがパーサー関数と変数のどちらとして使われるかに依存します。詳細については以下を参照してください：
地域化
- ヘルプは Help:マジックワード#地域化 を参照してください。
地域化マジックワードの定義および使用法の詳細は Manual:メッセージAPI、Manual:言語#名前空間、メッセージで {{SITENAME}} を避けるをご覧ください。
挙動スイッチ(二重のアンダースコアで囲まれたマジックワード)
挙動スイッチは特殊なマジックワードです。（二重の波括弧ではなく）二重のアンダースコア（_）を使用するのが特徴です。
例:
__NOTOC__
これらの特殊なマジックワードはコンテンツを出力するのではなく、ページの挙動の変更および/またはページのプロパティの設定を行います。
一覧は MagicWordFactory::mDoubleUnderscoreIDs で取得でき、ヘルプ:マジックワード#挙動スイッチでも参照できます。
ほとんどの標準挙動スイッチの効果は Parser::handleDoubleUnderscore() で定義されています。
特に効果が定義されていない場合、マジックワードは単にページプロパティを page_props テーブルに設定します。
これは、$parser->getOutput()->getPageProperty( 'MAGIC_WORD' ) が null か空文字列かどうかをテストすることで、後で確認することもできます
カスタム挙動スイッチ
以下は、カスタム __CUSTOM__ 挙動スイッチを実装した拡張機能の例です
MyExt/extension.json - これは最小限のものであり、実際の拡張機能ではより多くのフィールドが埋められているでしょう。
{
"name": "MyExt",
"type": "parserhook",
"AutoloadNamespaces": {
"MediaWiki\\Extension\\MyExt\\": "includes/"
},
"Hooks": {
"GetDoubleUnderscoreIDs": "main",
"ParserAfterParse": "main"
},
"HookHandlers": {
"main": {
"class": "MediaWiki\\Extension\\MyExt\\Hooks",
"services": [ "MainConfig" ]
}
},
"ExtensionMessagesFiles": {
"MyExtMagic": "custom.i18n.magic.php"
},
"manifest_version": 2
}
MyExt/MyExt.i18n.magic.php
<?php
$magicWords = [];
$magicWords['en'] = [
'MAG_CUSTOM' => [ 0, '__CUSTOM__' ],
];
MyExt/includes/Hooks.php
<?php
namespace MediaWiki\Extension\MyExt;
class Hooks implements GetDoubleUnderscoreIDsHook, ParserAfterParseHook {
public function onGetDoubleUnderscoreIDs( &$ids ) {
$ids[] = 'MAG_CUSTOM';
}
public function onParserAfterParse( $parser, &$text, $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