Manual:Tag extensions/ja

個別のプロジェクトにおいてシンプルな文字列の処理、本格的な情報の取得といった付加的な機能を持つ組み込みのwikiマークアップを拡張することが便利だと思うことはよくあります. タグエクステンションによって新しいカスタムタグを作ることができます. 例えば、シンプルな新しい寄付フォームをページに挿入する&lt;donation /&gt;タグを導入するタグエクステンションを使うことを考えます. パーサー関数とフックを持つエクステンションはMediaWikiの機能を変更もしくは強化するためにもっとも効果的な手段です. 他のMediaWikiユーザーによって作成された既存のエクステンションに関しては、エクステンションの一覧表をご覧下さい. エクステンションを作成する前に誰かが既に作成していないかどうか常に一覧表を確認すべきです.

シンプルなタグエクステンションはコールバック(callback)関数で構成されます. パーサーが実行されるとき、実際のHTMLをレンダーするために対応するコールバック関数を呼び出すことで、パーサーはすべての特別なタグのインスタンスを見つけて置き換えるために、コールバック関数はパーサーにフック(hook)されます.

例
この例では、&lt;sample&gt;タグに対するコールバック関数を登録します. 次のようにユーザーはこのタグをページに追加できます:

...input...

パーサーはefSampleRenderを呼び出し、3つの引数に渡します:


 * $input : &lt;sample&gt;と&lt;/sample&gt;タグの間、もしくはnull、タグが"閉じている"場合では、&lt;sample /&gt;となります
 * $args : タグの引数で、HTMLのタグ属性のように入力されます; これは属性名でインデックス化された連想配列です
 * $parser : 親パーサーです; もっと高度なエクステンションが文脈上のTitleを取得したり、wikiテキストを解析したり、中括弧を拡張したり、リンク関係や依存性を登録したりするためにこれを使用します.

属性
別の例を見てみましょう:

この例では、値と一緒にタグに渡された属性をダンプします. これによって新しい、カスタムタグの柔軟な仕様を作成できるようになります. 例えば、&lt;emailform to="User" email="user@foo.com" /&gt;のようなものを使用して、ユーザーがユーザーページにコンタクトフォームを差し込むを可能にするタグエクステンションを定義するとします.

MediaWikiで利用可能なタグエクステンションは非常に豊富です. その中のいくつかはこのサイトに登録されており; 他のものはウェブ検索を通して見つけることが出来ます.

規約
一つのエクステンションを単独のファイルで構成できますが、それぞれのエクステンションに対して、extensionsディレクトリの中に サブディレクトリを作成してその中に以下の3つのファイルを設置することをお勧めします:


 * 小さなセットアップファイル、
 * 国際化ファイル、
 * コード本体を含むファイル、

セットアップファイルによって1つの要素が 配列に追加されます. この配列はどのファイルがロードされるのかを指定します:

$wgAutoloadClasses[extension_name] = dirname(__FILE__). '/extension_name.body.php';

エクステンションを公開する

 * 1) Extension:という名前の新しいページを作成します. そのページではどのようにインストールするのか、それを使っている様子を表すスクリーンショットなどの情報を掲載します. これらの情報の掲載を支援するためにTemplate:Extensionという便利なテンプレートがあります. 詳細についてはテンプレートページをご覧下さい. ページの本体にできるだけ多くの情報を追加し、talkページに書き込まれるユーザの質問への回答を定期的に行った方がよいでしょう. また、Category:Extensionsカテゴリにあなたのページが表示されているかどうかを確認して下さい. ノート: meta.wikimedia.org上にエクステンションのページが存在する場合、管理者によって完全な履歴と一緒に移転されます - それまでの間は、metaで編集を続けて下さい
 * 2) エクステンションコードの範囲内で新しくManual:Hooks/jaを作成するエクステンションに関してはextension hook registryページに登録をお願いします. 新しく[Manual:Special Pages/ja|特別ページ]]を作成するエクステンションに関してはextension special page registryページで登録をお願いします.
 * 3) mediawiki-lメーリングリストに通知する.

セキュリティ関連
上記の例において、入力値を返す前に、htmlspecialchars</tt>を利用して入力値をエスケープしていることにおきづきになると思います. 任意のHTMLインジェクションを回避するためにすべてのユーザー入力をechoしてクライアントに返す前にこの方法で取り扱うことは大切です. HTMLインジェクションはクロスサイトスクリプティング(XSS)の脆弱性を導く可能性があるからです.

タイミングとエクステンション
エクステンションに対してコードを変更する場合、エクステンションを利用するすべてのページが、理論的には、即座に新しいコードの結果を反映します. 技術的には、エクステンションを含むページがレンダーされるたびにコードが実行されることを意味します.

実際には、ページキャッシングのおかげで、これはあまり当てはまりません. ページキャッシングはMediaWikiソフトウェア、ブラウザ、もしくは中間のプロクシ、ファイヤーウォールによって行われます.

MediaWikiのパーサーキャッシュを回避して、新しいバージョンのページが生成されることを保証するためには、ブラウザのアドレスバーに表示されている記事のURLの一番後ろに"?action=purge"を追加してEnterキーを押してページを再読込します. これによってページとそれを参照するすべてのテンプレートはすべてのキャッシュデータを無視して再生成されます. メインページ自身が修正されない場合はパージアクションが必要ですが、レンダーされなけばならない方法法は変更されます(エクステンションが修正された、もしくは修正されたテンプレートを参照しました).

ページの新しいコピーを取得するためにこの方法が十分ではない場合、通常は上記のURLの末端に'&rand=somerandomtext'を追加することで中間状態のキャッシュを回避できます. 'somerandomtext'が毎回異なることを確認して下さい.

エクステンションを利用してキャッシングを無効にする方法は？
MediaWiki 1.5以降では、パーサーは3番目のパラメータとしてエクステンションに渡されます. このパーサは次のようなキャッシュを無効にするために使われます:

サイト上でのすべてのサーバーサイドキャッシングを無効にするために、次のコードをLocalSettings.phpに追加して下さい:

バージョン1.8以降
パーサーフック関数parserオブジェクトに参照として渡され、wikitextを解析するためにこれを使います.

Parser::recursiveTagParse</tt>がバージョン1.8前後で導入されました. これを使う利点は簡潔であること(一つの引数だけを取得して一つの文字列を返します)と$text</tt>でエクステンションタグを解析するのでエクステンションタグをネストできることです.

バージョン1.8以前
バージョン1.8以前では、次のようなあまりきれいではない方法を使わなければなりません:

Parser::parseへの4番目と5番目のパラメータは$lineStart</tt>と$clearState</tt>です; これらはパーサーの振るまい方を指示します. $lineStart</tt>は、trueの場合、wikiテキストが新しい行で始まるものとして取り扱うように指示します(ブロック、もしきはリストなどを取り扱う場合に使います). $clearState</tt>、はtrueの場合、内部状態の情報をクリアします; 多くの場合、これはfalseになります.

上記の例において、Parser::parse</tt>は生のHTMLではなく、ParserOutputオブジェクトを返すことに注意して下さい.

これが動作しない場合(実行の順番、ネスト、別のフックとの混合などがよくある原因)、parserオブジェクトのクローンコピーを使って下さい:

エクステンションとテンプレート
テンプレートパラメータはエクステンションタグ内部で使用される場合(例えば、 "はエクステンションに直接渡され、テンプレートが呼び出されたときに指定された正しい値に変換されません. パーサーのテンプレートの前にエクステンションが解析されるからです. もっと詳細な情報と利用可能なパッチについてはbug 2257をご覧下さい.

この問題の次善策はテンプレート変数を拡張するいパーサー関数を作成しエクステンションコードを作成することです. テンプレートパラメータで を呼び出すためには、次のような新しいパーサー関数を作成します:

次のようなページ上で関数を呼び出します:

バージョン1.5以降
MediaWiki 1.5以降では、XMLスタイルのパラメータ(タグ属性)がサポートされています. パラメータは2番目のパラメータとしてフック機能に連想配列として渡されます. 文字列の値は既にデコードされたHTML文字エンティティを持つので、それらをHTMLに戻す場合、HTMLインジェクションのリスクを避けるために、 を使用することを忘れないで下さい.

バージョン1.5以前
MediaWiki 1.5はパラメータとエクステンションタグの間にパラメータを渡さなければなりません. すなわち、オプションのために特別な構文と、それらのためのフック入力テキストを分析しなければなりません. 可能な構文の一つは次の通りです:

@option1=foo @option2=bar

...content to be processed by the extension....

エクステンション機能に置いて、通常の処理を実行する前に@option1=foo</tt>のような行を探します. 他の構文を選択することももちろん自由です.

エクステンションのHTML出力の修正を避ける方法は？
現在のエクステンションコードではパーサーフックエクステンションがインラインのマテリアルを生成しそれらが最後のブロックレベルに挿入されることを前提としています(Bugilla:8997参照).

これに取りかかる方法は実際の結果の代わりにマーカーを出力するエクステンションのパーサーフック関数を作成し、そのマーカーをParserAfterTidyフックのために登楼されたハンドラ関数の実際の結果で置き換えることです.

別の方法としては、マーカーの出力の代わりに、武装されたフォーム(例えば、Base64でエンコードされたもの)に結果を出力することと、ParserAfterTidyハンドラでそれを武装解除(デコード)することも可能です.

Special:Version上でエクステンションを表示するには？
エクステンションをMediaWikiのSpecial:Versionページで表示するためには、PHPコードの範囲内でエクステンションクレジットを割り当てなければなりません.

これを行うために、フック行もしくは関数の定義の前に$wgExtensionCredits変数を最初の実行可能な行のコードとして追加します

エクステンションクレジットの例は次の通りです:

'validextensionclass'を次の一つで置き換えて下さい:
 * 'specialpage' -- MediaWikiの特別ページへの追加するために確保されます;
 * 'parserhook' -- エクステンションが修正され、補完、もしくはMediaWikiでパーサ関数に置き換える場合に使用されます;
 * 'variable' -- MediaWikiに複数の機能を追加するエクステンションです;
 * 'other' -- すべての他のエクステンションです.

関連項目

 * Manual:Extensions/ja
 * Extensions FAQ/ja
 * Manual:Extensions/ja
 * Category:Extensions/ja
 * Extension Matrix
 * $wgExtensionFunctions
 * Comparison of parser function and XML-style parser extension - refers to DynamicPageList2, but is of general interest
 * Project:Extension requests