Manual:Tag extensions/ja

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

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

例
この例では、&lt;sample&gt;タグに対するコールバック関数を登録します. 以下のようにユーザーはこのタグをページに追加できます:, パーサーはefSampleRender関数に以下の 4 つの引数を指定して呼び出します:

For a more elaborate example, see Tag extension example
 * $input : &lt;sample&gt;と&lt;/sample&gt;タグの間、またはnull、タグが"閉じている"場合では、&lt;sample /&gt;となります
 * $args : タグの引数で、HTMLのタグ属性のように入力されます; これは属性名でインデックス化された連想配列です
 * $parser : 親パーサーです; もっと高度な拡張機能が、文脈上のTitleを取得、wikiテキストを解析、中括弧を拡張、リンク関係や依存関係を登録などする際にこれを使用します.
 * $frame : The parent frame (a PPFrame object). This is used together with $parser to provide the parser with more complete information on the context in which the extension was called.

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

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

MediaWikiで利用可能なタグ拡張機能は非常に豊富です. その中のいくつかはこのサイトに登録されており; 他のものはウェブ検索を通して見つけることが出来ます. While a number of these are quite specialised for their use case, there are a great deal of well-loved and well-used extensions providing varying degrees of functionality.

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


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

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

For more general instructions, see Manual:Developing_extensions/ja.

拡張機能を公開する

 * 1) Extension:という名前の新しいページを作成します. そのページではどのようにインストールするのか、それを使っている様子を表すスクリーンショットなどの情報を掲載します. これらの情報の掲載を支援するためにTemplate:Extensionという便利なテンプレートがあります. 詳細についてはテンプレートページをご覧ください. ページの本体にできるだけ多くの情報を追加し、talkページに書き込まれるユーザの質問への回答を定期的に行った方がいいでしょう. また、Category:Extensionsカテゴリにあなたのページが表示されているかどうかを確認してください.
 * 2) 拡張機能コードの範囲内で新しくManual:Hooks/jaを作成する拡張機能に関してはExtension hook registryページに登録をお願いします. 新しく特別ページを作成する拡張機能に関してはExtension hook registryページで登録をお願いします.
 * 3) mediawiki-lメーリングリストに通知する.

See also publishing your extension.

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

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

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

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

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

拡張機能を利用してキャッシングを無効にする方法は?
MediaWiki 1.5以降では、パーサーは3番目のパラメーターとして拡張機能に渡されます. このパーサーは以下のようなキャッシュを無効にするために使われます:

Regenerating the page when another page is edited
Maybe you don't want to disable caching entirely, you just want the page to be regenerated whenever another page is edited, similar to the way that template transclusions are handled. This can be done using the parser object that is passed to your hook function. The following method was lifted from CoreParserFunctions.php and appears to work for this purpose.

Fine grained adjustment of caching behavior
You can use fine grained caching for your extension by using cache keys to differentiate between different versions of your extension output. While rendering you have can add cache keys for every feature by adding an addExtraKey method to your hook function, e.g.:

However, modifying $parser->getOptions during parse means that the extra option keys aren't included when trying to get a cached page, only when rendering a page to go into cache, so you can use the PageRenderingHash hook to set extra options. PageRenderingHash is run both when putting a page into cache, and getting it out, so its important to only add new keys to the hash if they're not already there. e.g:

Some important notes on this:
 * Using "!setting1=$value" instead of just "!$value" in the confstr ensures that the parser cache does not become messed up if different extensions are installed or their load order changes. ! is used a separator for different rendering options
 * Some people use  instead of  . Be warned that addExtraKey does not tell the parser cache that the extra key is in use, and thus can easily result in breaking the cache if you are not careful.

バージョン1.16以降
Parser hook functions are passed a reference to the parser object and a frame object; these should be used to parse wikitext.

Parser::recursiveTagParse</tt> has been around since version 1.8. Its advantages include simplicity (it takes just one argument and returns a string) and the fact that it parses extension tags in $text</tt>, so you can nest extension tags.

The second parameter to recursiveTagParse, $frame</tt>, is an optional argument introduced in MW 1.16 alpha (r55682).
 * If $frame</tt> is provided (using the value of $frame</tt> passed to your extension), then any template parameters in $text</tt> will be expanded. In other words, content such as   </tt> will be recognized and converted into the appropriate value.
 * If $frame</tt> is not provided (e.g., $parser->recursiveTagParse( $text )</tt>), or if $frame</tt> is set to false, then template parameters will not be expanded;  </tt> will not be altered.  Although this unlikely to be the desired behavior, this was the only option available before MW 1.16.

However, one step of parsing that is still skipped for tags, even when using recursiveTagParse, is Parser::preSaveTransform. preSaveTransform is the first step of parsing, responsible for making permanent changes to the about-to-be saved wikitext, such as: The original call to preSaveTransform intentionally skips such conversions within all extension tags. If you need pre save transform to be done, you should consider using a parser function instead. All tag extensions can also be called as a parser function using  which will have pre save transform applied.
 * Converting signatures (, ~ ,  )
 * Expanding link labels, also known as the pipe-trick (e.g., changing Help:Contents into Contents ). Without this step, shorthand links such as Help:Contents are considered to be invalid, and are left in their wikitext form when parsed.
 * Expanding templates.

バージョン1.8から1.15
The only difference before 1.16 is that the $frame argument was not available for Parser::recursiveTagParse</tt>.

If the resulting inability to recognize template variables is a problem, see Extensions and Templates and bug 2257 for more information and workarounds.

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

拡張機能のHTML出力の修正を避ける方法は？
The return value of a tag extension is considered almost parsed text, which means its not treated as pure html, but still modified slightly. There are two main things that are done to the output of a tag extension (Along with a couple other minor things):
 * Replace strip markers. Strip markers are certain items that look like UNIQe62a6957e0dbf6e-item-53--QINU</tt> which are inserted at various stages of processing wikitext to act as a marker to re-insert removed content at a later time. This is not something extensions usually need to worry about.
 * Parser::doBlockLevels which turns *'s into lists, and turns any line starting with a leading space into a &lt;pre&gt; among other things. This can sometimes be an issue in some extensions.

Tag extensions also support returning an array instead of just a string (Much like parser functions) in order to change how the return value is interpreted. The 0th value of the array must be the html. The "markerType" key can be set to nowiki</tt> in order to stop further parsing. Doing something like  would ensure that the $html value is not further modified and treated as just plain html.

Special:Versionに拡張機能を表示するには?
拡張機能を MediaWiki の Special:Version ページに表示するには、PHP コード内で拡張機能のクレジットを割り当てなければなりません.

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

拡張機能クレジットの例は以下の通りです:

Replace validextensionclass</tt> with one of the following (unless your extension falls under multiple classes&mdash;then create a credit for each class):
 * 'specialpage'&mdash;MediaWiki の特別ページへの追加するために確保されます
 * 'parserhook'&mdash;拡張機能が修正され、補完、または MediaWiki でパーサー関数に置き換える場合に使用されます
 * 'variable'&mdash;MediaWiki に複数の機能を追加する拡張機能です
 * 'media'&mdash;used if your extension is a media handler of some sort
 * 'other'&mdash;すべての他の拡張機能です

The <tt>myextensionmsg</tt> is the name of an interface/i18n message that describes your extension that will need to be defined in your extension's i18n.php file. If you omit this field, the <tt>description</tt> field will be used instead.