Manual:Variable/ja

From MediaWiki.org

< Manual:Variable

Jump to: navigation, search

このページでは変数の作成方法について説明されています。デフォルトの変数については、Help:Variables/jaをご覧下さい。

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

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

1 カスタム変数を定義する
2 カスタム変数を登録する
3 例
4 複数の変数を持つエクステンション
5 詳細な情報

[edit] カスタム変数を定義する

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

変数のためにマジックワードidを選択する。 これは変数定義の様々な部分を結びつけるために使用される内部の識別子のみです: wikiテキストで現れる名前と値を変数に割り当てるphpコードです。エクステンションによって独自に関係にあるidを選択することがベストで他のエクステンションによって使用される他のマジックワードidと混同することはありそうにないでしょう。共通の戦略はMAG_canonicalnameのようなものを使用することです。canonicalnameはエクステンションで登録する名前です(下記の#カスタム変数を登録するをご覧下さい)。
wikiテキストで現れる名前を定義する。 これを達成するために、フック関数を定義してLanguageGetMagicで登録する必要があります。フック関数は配列に渡されフック関数はキーが内部マジックワードidで値が変数のために使用したいすべての名前を含む配列であるエントリを追加します。名前は大文字と小文字を区別して独立した言語です。詳細な情報についてはLanguageGetMagicとmagic words/jaをご覧下さい。
値を変数に割り当てるphpコードを準備する これを実現するためには、フック関数を定義してManual:Hooks/ParserGetVariableValueSwitchで登録する必要があります。

[edit] カスタム変数を登録する

これは２つの段階のプロセスです:

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

[edit] 例

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

#--------------------------------------------------
# ステップ 1: マジックワードidを選択します
#--------------------------------------------------
 
# 選択したidを定数に保存することは求められていませんが
# プログラミングのよい習慣です - 
# これによってすべてのマジックワードidの存在に対する
# 検索が少し簡単になります - 割り当てられた定数と値の名前は
# お互いに何も共有する必要がないことに注意して下さい。
 
define('MAG_NIFTYVAR', 'mycustomvar1');
 
#---------------------------------------------------
# ステップ 2: wikiマークアップで使用するために
# いくつかの単語を定義します
#---------------------------------------------------
 
$wgHooks['LanguageGetMagic'][] = 'wfMyWikiWords';
function wfMyWikiWords(&$aWikiWords, &$langID) {
 
  #すべての{{NiftyVar}}、{{NIFTYVAR}}、{{CoolVar}}、{{COOLVAR}} 
  #とすべての小文字大文字のバリアントをマジックidの'mycustomvar1'
  #にマッピングするようにMediaWikiに伝えます
  # (0は大文字と小文字を区別することを意味します)
  $aWikiWords[MAG_NIFTYVAR] = array(0, 'NiftyVar','CoolVar');
 
  #これをしなければならないもしくはこの後で
  # すべてのLanguageGetMagicフックを沈黙させます！
  return true;
}
 
#---------------------------------------------------
# ステップ 3: 値を変数に割り当てる
#---------------------------------------------------
 
$wgHooks['ParserGetVariableValueSwitch'][] = 'wfMyAssignAValue';
function wfMyAssignAValue(&$parser, &$cache, &$magicWordId, &$ret) {
  if (MAG_NIFTYVAR == $magicWordId) {
     $ret='これは本当にお馬鹿な値です';
 
     #検索を停止できることをMediaWikiに伝えます - 値が見つかりました
     return true;  
  } else {
     #ParserGetVariableValueSwitchに割り当てられた次のフックに移動して
     #それが値を割り当てます
     return false;
  }
}
 
#---------------------------------------------------
# ステップ 4: Special:Versionの下のカスタム変数のリストに
#　　　　　　 表示されるようにカスタムの変数を登録します
#---------------------------------------------------
 
$wgExtensionCredits['variable'][] = array(
       'name' => 'NiftyVar',
       'author' =>'John Doe', 
       'url' => 'http://www.mediawiki.org/wiki/Extension:NiftyVar', 
       'description' => 'This variable is an example and performs no discernable function'
       );
 
#---------------------------------------------------
# ステップ 5: 別の種類のマジックワードではなく変数として
#　　　　　　 MAG_NIFTYVARと関連したwikiマークアップ単語を
#　　　　　　 登録します
#---------------------------------------------------
 
$wgHooks['MagicWordwgVariableIDs'][] = 'wfMyDeclareVarIds';
function wfMyDeclareVarIds(&$aCustomVariableIds) {
 
  #aCustomVariableIdsはMediaWikiに求められる
  #カスタム変数idのリストに保存する場所です
  #我々のものを追加することでMediaWikiの願いを叶えます:
  $aCustomVariableIds[] = MAG_NIFTYVAR;
 
  #これをしなければならないかこの後で
  #すべてのMagicWordwgVariableIdsを沈黙させます！
  return true;
}

[edit] 複数の変数を持つエクステンション

もちろん、一つのエクステンションのために一つ以上の変数を定義することが出来ます。それぞれの変数のために上記のコードを繰り返すことは少し退屈です。下記のメソッドによって一つの場所ですべての変数についてのすべてのデータを持つデータ構造を定義することが出来ます。次のコードでは登録をセットアップするデータを使用します。

この方法でコードとデータを分類することはいくつかの利点があります:

変更する必要がある場合すべてのものが一カ所にあります
すべてのエクステンションの変数の全体像を素早くみることが簡単です

逆に不利な点はコードが少し抽象的で新人のプログラマが理解するには難しいかもしれないことです。

ノート: 下記のコードはコンセプトの理解だけを目的にしたものです: 構文エラーのためにテストされていません - 自己責任でテンプレートとしてご利用下さい。

#--------------------------------------------------
# ステップ 1: 情報を保存するためにデータ構造を定義します
# それぞれの変数のためのエクステンションの中の変数です。
# この構造は4つの要素を持ちます:
#   [0] = 標準的な名前
#   [1] = 説明
#   [2] = 変数のためのwikiテキストの配列で言語によるキーを持つ
#   [3] = 変数の値を設定するコードスニペットです。
#       コード上の複雑性に制限はありません。
#       イコール記号の右側に続くコードはどんなものでも認められます。
#       スニペットは';'で終わります。
#       また実際のコードがバックスラッシュを持つとき、
#       コードは2つのバックスラッシュを持つべきであることを忘れないで下さい
#       PHPが引用符で囲まれた文字列を実際の文字列に変換するときに
#       バックスラッシュの片方が無くなります。
#       すなわち'\\n'は\nをコーディングしたことと同じです
#
# 下記のコードは2つの変数をセットアップします。
# 変数の一つは文字列と等しいです: 'This is a really silly value'
# ともう一つは42に設定されます。
#--------------------------------------------------
 
$wgMyExtensionVariables 
  = array( array('NiftyVar1'
                 , 'One of the variables in my extension'
                 , array( 'en' => array(0, 'NiftyVar1')
                         , 'fr' => array(0, 'NiftyVar1', 'VarChouette1'))
                         )
                 , '\'This is a really silly value\';'
                 )
           , array('NiftyVar2'
                  , 'The other variable in my extension'
                  , array( 'en' => array(0, 'NiftyVar2')
                          , 'fr' => array(0, 'NiftyVar1', 'VarChouette2')
                          )
                  , '42;'
                  )
           ) 
          );
 
#---------------------------------------------------
# ステップ 2: それぞれの変数とwikiワード間のマッピングを
#         セットアップする機能を追加します
# 
#         機能は下記のステップ4で定義されます。
#---------------------------------------------------
$wfHooks['LanguageGetMagic'] = 'wfMyWikiWords';
 
#----------------------------------------------------
# ステップ3: それぞれの変数のために、マジックワードと
#            値をそれに割り当てるPHPコードの関係を定義します。
#            またそれぞれの変数を登録します。
#
#         この作業をする機能は下記のステップ4で定義されます。
#         これで大丈夫なのはPHP4とPHP5において実際の定義の
#         *前に*関数を使用するコードを設置することが出来るからです。
#----------------------------------------------------
$wgMyExtensionAuthor = 'John Doe';
$wgMyExtensionURL = 'http://www.mediawiki.org/wiki/Extension:NiftyVars'
wfMyExtensionDefineAndRegisterVariables($wgMyExtensionAuthor
                                        , $wgMyExtensionURL
                                        , $wgMyExtensionVariables);
 
 
#---------------------------------------------------
# ステップ4: ステップ2と3で言及した機能を定義します。
#
#                これは特定のエクステンションに
#                特有のコードではないのでこれらは一緒にしています。
#                これらの機能はステップ4で定義した配列
#                のような配列で動作します。
#---------------------------------------------------
 
# ---------------------------------------------------
# ステップ 4a: 'LanguageGetMagic'フックのために
#              使用する関数を定義します
# ---------------------------------------------------
function wfMyWikiWords(&$aWikiWords, &$langID) {
  foreach ($wgMyExtensionVariables as $aVariableData) {
     $sCanonicalName =& $aVariableData[0];
     $aAllLanguages =& $aVariableData[2];
 
     #利用可能であれば言語特有の配列を使用します
     #さもなければデフォルトの英語を使用します
     $sMagicWordId = 'MAG_' . $sCanonicalName;
     if (isset($aAllLanguages[$langID])) {
        $aText =& $aAllLangauges[$langID];
     } else {
        $aText =& $aAllLangauges['en'];
     }
     $aWikiWords[$sCanonicalName, $aText];
   }
   return true;
}
 
#---------------------------------------------------
# ステップ 4b: ステップ1で定義したような
#              変数定義の配列を振る舞う関数を定義し
#              PHPコードに関連したマジックワードidを
#              セットアップし変数を定義します
#
#              我々のグローバル変数のために
#              選択した命名規約が何であれ
#              完全に独立であるために
#              関数が下記の3つの変数を取得します
#---------------------------------------------------
function wfMyExtensionDefineAndRegisterVariables(&$aVariables
                                                 , $sAuthor
                                                 , $sURL) {
  $sAssignAValue = 'switch($magicWordId){'
  $sRegisterVariables='';
 
  foreach($aVariables as $aVariableData) {
     $sCanonicalName = $aVariableData[0];
     $sDescription = $aVariableData[1];
     $sAssignmentCode = $aVariableData[3];
 
     #マジックワードidを値と関連づけます
     $sMagicWordId = '\'MAG_' . $sCanonicalName . '\'';
     $sAssignAValue .= 'case ' . $sMagicWordId . ': $ret=' 
        . $sCode . '; return true;'
 
 
     #Special:Version経由で公開する
     $wgExtensionCredits['variable'][] = array(
       'name' => $sCanonicalName,
       'author' => $sAuthor, 
       'url' => $sURL, 
       'description' => $sDescription
       );
 
     #変数を登録するコードを追加する
     $sAssignAValue .= 'default: return true; }';
     $sRegisterVariables
        .= '$aCustomVariableIds[] =' . $sMagicWordId . ';';
  }
 
  #完結させてPHPコードをマジックワードidに追加する
  $wgHooks['ParserGetVariableValueSwitch'][] 
    = create_function('&$parser, &$cache, &$magicWordId, &$ret'
                      , $sAssignAValue);
 
  #完結させて変数登録フックを追加する
  $sRegisterVariables .= 'return true;';
  $wgHooks['MagicWordwgVariableIDs'][] 
    = create_function('&$aCustomVariableIds'
                      , $sRegisterVariables);
 
}