Manual:変数

This page is a translated version of the page Manual:Variable and the translation is 97% complete.
このページでは変数の作成方法について説明しています。既定の変数については、Help:マジックワード を参照してください。MediaWiki が内部的に使用する PHP グローバル変数については、Manual:wg変数 を参照してください。

変数は、テンプレートのようにみえる小さなウィキテキストですが、パラメーターがなく、決め打ちされた値が割り当てられます。標準的なウィキ マークアップ、例えば {{PAGENAME}} {{SITENAME}} などは変数です。独自のカスタム変数を定義することでウィキ マークアップを拡張することもできます。

用語は多少間違っています。変数について変えられるものが存在しないからです。エンドユーザは変数の値を変更することは出来ません。値を計算するたくさんのPHPコードによってあらかじめ決定されているからです。"変数(variable)"という用語は「変わる(vary)」に由来しています: PHP 変数または変数に割り当てることができるもの、例えば、文字列、数字、式、または関数の戻り値です。

カスタム変数を定義する

変数はマジックワードの特別な場合で、最初の段階でマジックワードとして変数を定義します:

  1. 変数のためにマジックワードIDを選択する。 これは変数定義の様々な部分を結びつけるために使用される内部の識別子のみ、すなわちウィキテキストで現れる名前と値を変数に割り当てるPHPコードです。 拡張機能によって独自に関係にあるIDを選択することが最善で他の拡張機能によって使用される他のマジックワードIDと混同することはありそうにないでしょう。 共通の戦略は MAG_canonicalname のようなものを使用することです。canonicalname は拡張機能で登録する名前です (下記のカスタム変数を登録するをご覧ください)。
  2. ウィキテキストで現れる名前を定義する。これを実現するためには、$magic を用いて $magicWords 配列をファイルに定義する必要があります。詳細な情報については Manual:マジックワード を参照してください。名前は大文字と小文字を区別して独立した言語です。
  3. 値を変数に割り当てるPHPコードを準備する。 これを実現するためには、フック関数を定義して ParserGetVariableValueSwitch で登録する必要があります。

上記の方法と一般的なマジックワードの定義方法との違いは、最後の ParserGetVariableValueSwitch のフック関数を定義する部分です。 パーサー関数にはIDとPHPコードを関連付ける別のメソッドがあります。 詳細情報は Manual:パーサー関数 を参照してください。

カスタム変数を登録する

これは 2 段階の作業です:

  1. 変数がSpecial:Versionsに含まれるように変数を定義します これはメンバーを $wgExtensionCredits に追加することが求められます。もっと詳細な情報については、MediaWikiで機能を登録するをご覧ください。
  2. マジックワードIDを変数として宣言する。 これを実現するためにフックを書いて MagicWordwgVariableIDs 、この記事の題目に割り当てします。
このフックは変数で使用するためのみです。パーサー関数を定義するために使用してはなりません。

注: コーディングテンプレートとしてこの例をしたい場合、MediaWikiまたは、他の拡張機能の名前との衝突をする危険性を減らすために'My'を何かあなたのプロジェクトでユニークなものに置き換えてください。例えば、拡張機能がBigExtravagantStylingToolという名前で'My'を'BEST'で置き換えたい場合、定数、変数、関数、または'BEST_'、'wgBEST'、'wfBEST'、または'BEST'を持っていることを確認してください。

ファイル Example.i18n.magic.php

<?php
/**
 * Step 1: choose a magic word ID
 * Step 2: define some words to use in wiki markup
 */

$magicWords = [];

/** English (English) */
$magicWords['en'] = [
	// tell MediaWiki that all {{NiftyVar}}, {{NIFTYVAR}}, {{CoolVar}},
	// {{COOLVAR}} and all case variants found in wiki text should be mapped to
	// magic ID 'mycustomvar1' (0 means case-insensitive)
	'mycustomvar1' => [ 0, 'NiftyVar', 'CoolVar' ],
];

ファイル Example.php

<?php
/**
 * Step 3: Register the file with the magic words.
 */
$wgExtensionMessagesFiles['ExampleMagic'] = __DIR__ . '/Example.i18n.magic.php';

/**
 * Step 4: assign a value to our variable
 */
$wgHooks['ParserGetVariableValueSwitch'][] = 'wfMyAssignAValue';
function wfMyAssignAValue( &$parser, &$cache, &$magicWordId, &$ret ) {
	if ( $magicWordId === 'mycustomvar1' ) {
		// We found a value
		$ret = 'This is a really silly value';
	}
	// We must return true for two separate reasons:
	// 1. To permit further callbacks to run for this hook.
	//    They might override our value but that's life.
	//    Returning false would prevent these future callbacks from running.
	// 2. At the same time, "true" indicates we found a value.
	//    Returning false would set variable value to null.
	//
	// In other words, true means "we found a value AND other
	// callbacks will run," and false means "we didn't find a value
	// AND abort future callbacks." It's a shame these two meanings
	// are mixed in the same return value.  So as a rule, return
	// true whether we found a value or not.
	return true;
}

/**
 * Step 5: register the custom variable(s) so that it shows up in
 * Special:Version under the listing of custom variables.
 */
$wgExtensionCredits['variable'][] = [
	'name' => 'ExampleMagic',
	'author' => 'John Doe',
	'version' => '1.0',
	'description' => 'Provides a variable as an example and performs no discernible function',
	'url' => 'https://www.mediawiki.org/wiki/Extension:ExampleMagic',
];

/**
 * Step 6: register wiki markup words associated with
 *         MAG_NIFTYVAR as a variable and not some
 *         other type of magic word
 */
$wgHooks['MagicWordwgVariableIDs'][] = 'wfMyDeclareVarIds';
function wfMyDeclareVarIds( &$customVariableIds ) {
	// $customVariableIds is where MediaWiki wants to store its list of custom
	// variable IDs. We oblige by adding ours:
	$customVariableIds[] = 'mycustomvar1';
}

詳細な情報

  • Help:マジックワード - MediaWiki コアのパッケージに組み込まれている既定のマジックワードについて議論します
  • Manual:マジックワード - さまざまな種類のマジックワードや、MediaWiki がどのように変数、パーサー関数、テンプレートを区別して伝えるのかを再検討しています。