View source for Manual:Magic words/ja

<languages/>
{{ExtensionTypes}}
[[File:MediaWiki-extensions-icon.svg|125px|alt=MediaWiki 拡張機能|right]]

{{notice|1='''マジックワード'''と変数の'''一覧'''をお探しですか? '''{{ll|Help:Magic words}}''' を参照してください。}}

'''マジックワード'''は、様々なウィキテキスト文字列を関数に関連付けられている単一のIDに対応付け（マッピング）する技術です。
[[Special:MyLanguage/Manual:Variables|変数]]にも[[Special:MyLanguage/Manual:Parser functions|パーサー関数]]にもこの技術が使われています。
特定のIDに対応付けされたさまざまなテキストは、関数の戻り値に置換されます。
{{ll|Manual:$wgExtensionMessagesFiles|$wgExtensionMessagesFiles[]}} を使って読み込んだファイルの <code>$magicWords</code> 変数には、ID に対応するすべての文字列を格納します。

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

<span id="How_magic_words_work"></span>
== マジックワードの動作の仕組み ==

MediaWikiでは二重の波括弧に挟まれた文字列 (<code><nowiki>{{</nowiki>XXX ...}}</code>) を検知すると、その中に含まれるXXXが[[Special:MyLanguage/Manual:Variables|変数]]、[[Special:MyLanguage/Manual:Parser functions|パーサー関数]]あるいは[[Special:MyLanguage/Help:Templates|テンプレート]]のどれに該当するか識別する必要があります。そのためにいくつかの問いを解きます。

#'''マジックワード ID が関連付けられているか?''' <code><nowiki>{{XXX...}}</nowiki></code> 形式のマークアップを解決する最初の段階として、 MediaWiki は ''XXX'' をマジックワード ID に変換できるかどうか検討します。変換テーブルは $magicWords によって定義されます。
#*''XXX'' に関連付けられたマジックワード ID が見つからない場合、''XXX'' は[[Special:MyLanguage/Help:Templates|テンプレート]]と見なされます。
#:<br/>
#'''変数か?''' マジックワードIDが検出<em>される</em>と、MediaWikiは次にパラメータがあるかどうか確認します。 
#*パラメータを検出しなかった場合、MediaWikiはマジックワードIDが有効な変数IDとして宣言されているかどうか確認します。 これを確認するために、<code>MagicWord::getVariableIDs()</code> を呼び出し、マジックワードのリストを取得します。 この方法により、ハードコードされた変数ID（{{ll|Help:Variables}} を参照）と {{ll|Manual:Hooks/MagicWordwgVariableIDs|MagicWordwgVariableIDs}} フックに接続する関数をすべて提供するカスタム変数IDのリストから、変数IDのリストを取得します。
#**マジックワードIDが変数に分類されている場合、MediaWikiは変数名に関連付けられている値を取得するために {{ll|Manual:Hooks/ParserGetVariableValueSwitch|ParserGetVariableValueSwitch}} 関数を呼びます。
#:<br/>
#<span class="mw-translate-fuzzy">'''パーサー関数か?''' パラメータがあるもしくはマジックワードIDが変数マジックワードIDのリストにない場合、MediaWikiは当該のマジックワードを[[Special:MyLanguage/Manual:Parser functions|パーサー関数]]もしくは[[Special:MyLanguage/Help:Templates|テンプレート]]だと判定します。<code>$wgParser->setFunctionHook($magicWordId, $renderingFunctionName)</code>を呼び出して宣言されているパーサー関数のリストでそのマジックワードIDが見つかれば、パーサー関数として扱われ、<code>$renderingFunctionName</code>という関数を使用して処理します。そうでなければ、テンプレートだと見なされます。</span> <span lang="en" dir="ltr" class="mw-content-ltr">If the magic word ID is found in the list of parser functions declared via a call to <code>$wgParser->setFunctionHook($magicWordId, $renderingFunctionName)</code>, it is treated as a parser function and rendered using the function named <code>$renderingFunctionName</code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Otherwise, it is presumed to be a template.</span>

{{note|1=
慣習により：

* 変数と呼ばれるマジックワードは大文字化され、大文字/小文字が区別され、空白文字を含みません。
* パーサー関数はハッシュ記号 (<nowiki>#</nowiki>) を前に付け、大文字と小文字を区別せず、空白文字を含みません。

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

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

可能であればマジックワードを定義または翻訳するときは慣習に従うべきです。
マジックワードはテンプレートよりも優先順位が高いので、マジックワードが定義されていると定義された名前はテンプレートとして使えなくなります。
競合の可能性が増えるのを避けるために慣習に従ってください。
}}

<span id="Defining_magic_words"></span>
== マジックワードを定義する ==

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

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

<span id="Mapping_wiki_text_to_magic_word_IDs"></span>
=== ウィキテキストからマジックワード ID への対応付け ===
$magicWords変数を使い、マジックワードIDに対応付けられたすべてのテキスト文字列を記述した言語依存の配列をそれぞれのマジックワードIDに関連付けます。
重要点: これにより処理されるのはバックエンドの地域化対応付け (i18nマッピング) のみで、MediaWikiがそのマジックワードをあらゆることに使うようにするには、さらにその他のコード作成が必要です。
また、言語別の値を追加する前に <code>$magicWords</code> を空の配列として初期化していることを確かめてください。そうしないと、マジックワードを読み込もうとしたときにエラーが発生し、地域化キャッシュを再構築しないと動作しなくなります。

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

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

下記の例では、スペイン語版 MediaWiki のインストレーションは 'MAG_CUSTOM' というマジックワード ID を "personalizado"、"custom"、"PERSONALIZADO"、"CUSTOM" およびその他のあらゆる大文字と小文字の変化と関連付けます。
英語版 MediaWiki では、"custom"の様々な大文字と小文字の組み合わせのみを 'MAG_CUSTOM' に対応付けます。

ファイル <code>Example.i18n.magic.php</code>:

<syntaxhighlight lang="php">
<?php

$magicWords = [];

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

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

extension.json ファイルの一部:

<syntaxhighlight lang="json">
"ExtensionMessagesFiles": {
	"ExampleMagic": "Example.i18n.magic.php"
}
</syntaxhighlight> 

単純な国際化ファイルで使うキー（通常は "Example" のように拡張機能のタイトルだけ）と異なり、 "ExampleMagic" としていることにご注意ください。間違って他のものを上書きしないよう、意図的に "Magic" を追加しています。

<span id="In_inline_PHP"></span>
==== インライン PHP ====
i18n ファイルを通じてではなく、 PHP でインラインにマジックワードを関連付けることができます。
これは <code>LocalSettings.php</code> でフックを定義するときに便利ですが、拡張機能では使用してはいけません。

<syntaxhighlight lang="php">
MediaWiki\MediaWikiServices::getInstance()->getContentLanguage()->mMagicExtensions['wikicodeToHtml'] = ['MAG_CUSTOM', 'custom'];
</syntaxhighlight> 

<span id="Associating_a_magic_word_ID_with_a_PHP_function"></span>
=== マジックワード ID と PHP 関数の関連付け ===

マジックワードIDとレンダリング関数の関連付けの仕組みは、マジックワードが[[Special:MyLanguage/Manual:Parser functions|パーサー関数]]と[[Special:MyLanguage/Manual:Variables|変数]]のどちらとして使われるかに依存します。詳細については以下を参照してください：

* {{ll|Manual:Parser functions}}
* {{ll|Manual:Variables}}

<span id="Localisation"></span>
=== 地域化 ===

:''ヘルプは [[Special:MyLanguage/Help:Magic words#Localisation|Help:マジックワード#地域化]] を参照してください。''

地域化マジックワードの定義および使用法の詳細は [[Special:MyLanguage/Manual:Messages API|Manual:メッセージAPI]]、 [[Special:MyLanguage/Manual:Language#Namespaces|Manual:言語#名前空間]]、[[Special:MyLanguage/Help:System_message#Avoid_.7B.7BSITENAME.7D.7D_in_messages|<nowiki>メッセージで {{SITENAME}} を避ける</nowiki>]]をご覧ください。

<span id="Behavior_switches_(double_underscore_magic_words)"></span>
== 挙動スイッチ(二重のアンダースコアで囲まれたマジックワード) ==
挙動スイッチは特殊なマジックワードです。（二重の波括弧ではなく）二重のアンダースコア（_）を使用するのが特徴です。
例:
<code><nowiki>__NOTOC__</nowiki></code>

これらの特殊なマジックワードはコンテンツを出力するのではなく、ページの挙動の変更および/またはページのプロパティの設定を行います。
一覧は {{phpi|MagicWordFactory::mDoubleUnderscoreIDs}} で取得でき、[[Special:MyLanguage/Help:Magic words#Behavior switches|ヘルプ:マジックワード#挙動スイッチ]]でも参照できます。
ほとんどの標準挙動スイッチの効果は {{phpi|Parser::handleDoubleUnderscore()}} で定義されています。
特に効果が定義されていない場合、マジックワードは単にページプロパティを page_props テーブルに設定します。
これは、<syntaxhighlight lang="php" inline>$parser->getOutput()->getPageProperty( 'MAGIC_WORD' )</syntaxhighlight> が null か空文字列かどうかをテストすることで、後で確認することもできます

<span id="Custom_behavior_switch"></span>
=== カスタム挙動スイッチ ===

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

'''custom/extension.json''' - これは最小限のものであり、実際の拡張機能ではより多くのフィールドが埋められているでしょう。
<syntaxhighlight lang="json">
{
	"name": "Custom",
	"type": "parserhook",
	"AutoloadClasses": {
		"MyHooks": "MyHooks.php"
	},
	"Hooks": {
		"GetDoubleUnderscoreIDs": [
			"MyHooks::onGetDoubleUnderscoreIDs"
		],
		"ParserAfterParse": [
			"MyHooks::onParserAfterParse"
		]
	},
	"ExtensionMessagesFiles": {
		"CustomMagic": "custom.i18n.php"
	},
	"manifest_version": 1
}
</syntaxhighlight>
'''custom/custom.i18n.php'''
<syntaxhighlight lang="php">
<?php
$magicWords = [];
$magicWords['en'] = [
	'MAG_CUSTOM' => [ 0, '__CUSTOM__' ],
];
</syntaxhighlight>

'''custom/MyHooks.php'''
<syntaxhighlight lang="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' );
		}
	}
}

</syntaxhighlight>

<span id="See_also"></span>
==関連項目==
*{{ll|Help:Magic words}} - <nowiki>{{PAGENAME}}</nowiki> や <nowiki>{{SERVER}}</nowiki> などの変数の一覧
*{{ll|Manual:MagicWord.php}}

[[Category:Customization techniques{{#translation:}}|{{PAGENAME}}]]
[[Category:Magic words{{#translation:}}|{{PAGENAME}}]]