Manual:タグ拡張機能

This page is a translated version of the page Manual:Tag extensions and the translation is 34% complete.

拡張機能:

単純な文字列処理でも本格的な情報検索でも、追加の機能を加えて組み込みウィキマークアップを拡張すると、個々のプロジェクトで有効な場合があります。タグ拡張機能を使用すると、ユーザーはそのような新しいカスタムタグを作成できます。たとえば、タグ拡張を使用して単純な‎<donation />タグを導入すると、寄付フォームがページに挿入されます。拡張機能は、パーサー関数やハックと共に、MediaWikiの機能を変更または強化する最も効果的な方法です。拡張機能に関する作業を始める前に、あなたがやろうとしていることを既に他の誰かがつくっていないかを確認するため拡張機能一覧をチェックするようにしてください。

単純なタグ拡張は、パーサーにフックされるコールバック関数で構成されています。そのため、パーサーが実行されると特定のタグに関するインスタンスがすべて検索・置換され、対応するコールバック関数が呼び出されて実際の HTML がレンダリングされます。

例

extension.json ファイルで、フックをセットアップします:

...
  "Hooks": {
       "ParserFirstCallInit": "ExampleExtensionHooks"
   },
   "HookHandlers": {
       "ExampleExtensionHooks": {
           "class": "MediaWiki\\Extension\\ExampleExtension\\Hooks"
       }
   }
...

そして、PHP ファイルにフックを追加します

<?php
namespace MediaWiki\Extension\ExampleExtension;

class ExampleExtension implements ParserFirstCallInitHook {
	// レンダリング コールバックをパーサーに登録します
	public function onParserFirstCallInit( $parser ) {
		// パーサーが<sample>タグを見つけると、renderTagSample（下記参照）を実行します
		$parser->setHook( 'sample', [ $this, 'renderTagSample' ] );
	}

	// Render <sample>
	public function renderTagSample( $input, array $args, Parser $parser, PPFrame $frame ) {
		// 目立ったことは何もありません。ただユーザーの入力をエスケープし、再び返しているだけです（例として）
		return htmlspecialchars( $input );
	}
}

この例では ‎<sample> タグのコールバック関数を登録します。ユーザーがこのタグを <sample arg1="xxx" arg2="xxx">...input...</sample> のようにしてページに書くと、パーサーは renderTagSample() 関数を呼び出し、4つの引数を引き渡します。

$input: ‎<sample> タグと ‎</sample> タグとの間に記された入力。あるいは、タグが閉じている場合、つまり ‎<sample /> であった場合は null
$args: HTMLタグ属性のように入力されたタグの引数。属性名をキーとする連想配列。
$parser: 上位パーサー（パーサーオブジェクト）。より高度な拡張機能はこれを使ってコンテキストタイトルを取得し、ウィキテキストを解析し、括弧を展開し、リンク関係と依存関係を登録します。
$frame: 上位フレーム（PPFrameオブジェクト）。 $parser と一緒に用いられ、拡張機能が呼び出されたコンテキストに関するより完全な情報をパーサーに提供します。

より複雑な例については、タグ拡張の例を参照してください

属性

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

<?php

$wgHooks['ParserFirstCallInit'][] = 'onParserFirstCallInit';

function onParserFirstCallInit( Parser $parser ) {
	$parser->setHook( 'sample', 'wfSampleRender' );
}

function wfSampleRender( $input, array $args, Parser $parser, PPFrame $frame ) {
	$attr = [];    
	// 今回は、属性名とその値のリストを作成し、ユーザーの入力と合わせてそれらを出力します。
	foreach( $args as $name => $value ) {
		$attr[] = '<strong>' . htmlspecialchars( $name ) . '</strong> = ' . htmlspecialchars( $value );
	}
	return implode( '<br />', $attr ) . "\n\n" . htmlspecialchars( $input );

/**
 * 以下のようにして変数値を直接取得することができます:
 * $to = $args['to'] ;
 * $email = $args['email'] ;
 */
}

この例ではタグに渡された属性の名前と値を出力します。こうして新たなカスタムタグを柔軟に指定できることは明らかです。例えば、<emailform to="User" email="user@foo.com" /> のように、利用者が自分の利用者ページに連絡先フォームを挿入できるようにするタグ拡張機能を定義することができます。

MediaWikiには非常にたくさんの拡張機能があり、その一部はこのサイトに掲載されています。その他の拡張機能も簡易ウェブ検索で見つけることができます。これらの多くは特定の利用場面に特化したものですが、よく好まれよく利用されているたくさんの拡張機能があります。それらの機能の程度もさまざまです。

規約

拡張機能の一般的な設計と設定については Manual:拡張機能の開発を参照してください。

拡張機能の公開

このウィキ上で、拡張機能に関する情報やインストール方法、使用例のスクリーンショットを含む、{{$2|拡張機能名}} という名前の新しいページを作成してください。この情報を保持するために便利なテンプレートが作成されており、Template:Extension と呼ばれています。詳細情報はテンプレートのページを参照してください。ページの本文にはできる限り詳細を追加するべきであり、関連するトークページでの利用者の質問に対応するために定期的に確認するのが賢明です。また、そのページがカテゴリ:拡張機能に属していることを確認してください。

Extensions that create new hooks within the extension code should register them in the extension hook category.

Notify the mediawiki-l mailing list.

よくある質問

セキュリティ上の問題

You'll notice above that the input in the examples above is escaped using htmlspecialchars() before being returned. It is vital that all user input is treated in this manner before echoing it back to the clients, to avoid introducing vectors for arbitrary HTML injection, which can lead to cross-site scripting vulnerabilities.

モジュールの読み込み

The right way to add modules for your extension is to attach them to the ParserOutput rather than to $wgOut. The module list will then be automatically taken from the ParserOutput object and added to $wgOut even when the page rendering is pre-cached. If you are directly adding the modules to $wgOut they might not be cached in the parser output.

function myCoolHook( $text, array $params, Parser $parser, PPFrame $frame ) {
	// ... do stuff ...
	$parser->getOutput()->addModules( 'ext.mycoolext' );
	$parser->getOutput()->addModuleStyles( 'ext.mycoolext.styles' );
	// ... do more stuff ...
}

Timing and extensions

If you change the code for an extension, all pages that use the extension will, theoretically, immediately reflect the results of new code. 技術的には、拡張機能を含むページがレンダリングされるたびに、あなたのコードが実行されることを意味します。

In practice, this is often not the case, due to page caching - either by the MediaWiki software, the browser or by an intermediary proxy or firewall.

To bypass MediaWiki's parser cache and ensure a new version of the page is generated, click on edit, replace "action=edit" in the URL shown in the address bar of your browser by "action=purge" and submit the new URL. The page and all templates it references will be regenerated, ignoring all cached data. The purge action is needed if the main page itself is not modified, but the way it must be rendered has changed (the extension was modified, or only a referenced template was modified).

If this is not sufficient to get you a fresh copy of the page, you can normally bypass intermediary caches by adding '&rand=somerandomtext' to the end of the above URL. Make sure 'somerandomtext' is different every time.

拡張機能を使用するページのキャッシュの無効化

Since MediaWiki 1.5, the parser is passed as the third parameter to an extension. This parser can be used to invalidate the parser cache like this:

function wfSampleSomeHookFunction( $text, array $args, Parser $parser, PPFrame $frame ) {
	$parser->getOutput()->updateCacheExpiry(0);
	// ...
}

他ページの編集時にページを再生成

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 and calling the addTemplate.

キャッシュ動作の微調整

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 can add cache keys for every feature by adding an addExtraKey method to your hook function, e.g.:

function wfSampleSomeHookFunction( $text, array $args, Parser $parser, PPFrame $frame ) {
	$userOptionsLookup = MediaWikiServices::getInstance()->getUserOptionsLookup();
	$setting1= (int)$userOptionsLookup->getOption( $parser->getUserIdentity(), 'setting1' );
	$parser->getOptions()->optionUsed( 'setting1' );
	$setting2= (int)$userOptionsLookup->getOption( $parser->getUserIdentity(), 'setting2' );
	$parser->getOptions()->optionUsed( 'setting2' );
	...
}

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. 例:

$wgHooks['PageRenderingHash'][] = 'wfMyExtOnPageRenderingHash';

function wfMyExtOnPageRenderingHash( &$confstr, $user, $optionsUsed ) {
	$userOptionsLookup = MediaWikiServices::getInstance()->getUserOptionsLookup();
	if ( in_array( 'setting1', $optionsUsed ) ) {
		$confstr .= "!setting1=" . $userOptionsLookup->getOption( $user, 'setting1' );
	}
	if ( in_array( 'setting2', $optionsUsed ) ) {
		$confstr .= "!setting2=" . $userOptionsLookup->getOption( $user, 'setting2' );
	}
}

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 $parser->getOptions()->addExtraKey() instead of $parser->getOptions()->optionUsed().

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以降

MediaWiki バージョン:

≧ 1.16

Parser hook functions are passed a reference to the parser object and a frame object; these should be used to parse wikitext.

function wfSampleWonderfulHook( $text, array $args, Parser $parser, PPFrame $frame ) {
	$output = $parser->recursiveTagParse( $text, $frame );
	return '<div class="wonderful">' . $output . '</div>';
}

Parser::recursiveTagParse() 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, so you can nest extension tags.

The second parameter to recursiveTagParse, $frame, is an optional argument introduced in MW 1.16 alpha (r55682).

If $frame is provided (using the value of $frame passed to your extension), then any template parameters in $text will be expanded.

In other words, content such as {{{1}}} will be recognized and converted into the appropriate value.

If $frame is not provided (e.g., $parser->recursiveTagParse( $text )), or if $frame is set to false, then template parameters will not be expanded; {{{1}}} 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:

Converting signatures

(~~~, ~~~~, ~~~~~)

Expanding link labels, also known as the pipe-trick (e.g., changing [[Help:Contents|]] into [[Help:Contents|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 {{subst:}} templates.

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 {{#tag:tagname|input|attribute_name=value}} which will have pre save transform applied.

拡張タグでのXMLスタイルパラメーターの渡し

バージョン1.5以降

Since MediaWiki 1.5, XML-style parameters (tag attributes) are supported. The parameters are passed as the second parameter to the hook function, as an associative array. The value strings have already had HTML character entities decoded for you, so if you emit them back to HTML, don't forget to use htmlspecialchars( $codeToEncode, ENT_QUOTES ), to avoid the risk of HTML injection.

拡張機能の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 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 ‎<pre> 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 in order to stop further parsing. Doing something like return [ $html, 'markerType' => 'nowiki' ]; would ensure that the $html value is not further modified and treated as just plain html.

Special:Versionへの拡張機能の表示

In order for your extension to be displayed on the MediaWiki Special:Version page, you must assign extension credits within the PHP code.

To do this, add a $wgExtensionCredits variable as the first executable line of code before the hook line or function definition.

An example extension credit is:

<?php
/**
 * ExampleExtension - this extension is an example that does nothing
 *
 * To activate this extension, add the following into your LocalSettings.php file:
 * require_once('$IP/extensions/Example.php');
 *
 * @ingroup Extensions
 * @author John Doe <john.doe@example.com>
 * @version 1.0
 * @link https://www.mediawiki.org/wiki/Extension:MyExtension Documentation
 * @license http://www.gnu.org/copyleft/gpl.html GNU General Public License 2.0 or later
 */

/**
 * Protect against register_globals vulnerabilities.
 * This line must be present before any global variable is referenced.
 */
if( !defined( 'MEDIAWIKI' ) ) {
	echo( "This is an extension to the MediaWiki package and cannot be run standalone.\n" );
	die( -1 );
}

// Extension credits that will show up on Special:Version    
$wgExtensionCredits['validextensionclass'][] = array(
	'path'           => __FILE__,
	'name'           => 'Example',
	'version'        => '1.0',
	'author'         => 'John Doe', 
	'url'            => 'https://www.mediawiki.org/wiki/Extension:MyExtension',
	'descriptionmsg' => 'example-desc', // Message key in i18n file.
	'description'    => 'This extension is an example and performs no discernible function'
);

$wgExtensionMessagesFiles[] = __DIR__ . '/Example.i18n.php';

// Here is where we set up our extension
function wfExample(){
	// ...
}

Replace validextensionclass with one of the following (unless your extension falls under multiple classes—then create a credit for each class):

'specialpage'—reserved for additions to MediaWiki Special Pages;

'parserhook'—used if your extension modifies, complements, or replaces the parser functions in MediaWiki;

'variable'—extension that add multiple functionality to MediaWiki;

'media'—used if your extension is a media handler of some sort

'other'—all other extensions.

The myextensionmsg 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 description field will be used instead.

Retrieving the tag name inside of the callback

Suppose you have several tags ‎<foo> and ‎<bar> that share the same callback, and inside the callback function, you want to obtain the name of the tag that invoked the callback.

$wgHooks['ParserFirstCallInit'][] = 'onParserFirstCallInit';

# ...

public function onParserFirstCallInit( Parser $parser ) {
	$parser->setHook( 'foo', 'sharedFunctionality' );
	$parser->setHook( 'bar', 'sharedFunctionality' );
}

# ...

public function sharedFunctionality( $input, array $args, Parser $parser, PPFrame $frame ) {
	// How to distinguish between 'foo' and 'bar' calls?
}

The short answer is: the tag name (foo or bar) is not present in any of the callback's arguments. But you can work around this by dynamically constructing a separate callback for each tag:

$wgHooks['ParserFirstCallInit'][] = 'onParserFirstCallInit';

# ...

public function onParserFirstCallInit( Parser $parser ) {
	// For each tag name
	foreach ( [ 'foo', 'bar' ] as $tagName ) {
		// Dynamically create a callback function
		$callback = function( $input, $args, $parser, $frame ) use ( $tagName ) {
			// The callback invokes the shared function.
			// Notice we now pass the tag name as a parameter.
			return sharedFunctionality( $input, $args, $parser, $frame, $tagName );
		};
		// Assign the callback to the tag
		$parser->setHook( $tagName, $callback );
	}
}

# ...

public function sharedFunctionality( $input, array $args, Parser $parser, PPFrame $frame, $tagName) {
	// Now we can retrieve the tag name and perform custom actions for that tag
	switch ( $tagName ) {
		//...
	}
}

Toolbar buttons

Extension:WikiEditor provides an editing toolbar, allowing users to add tags into their editor by simply clicking a button. If you want a toolbar button for your new tag, create a file named something like toolbar-button.js in your extension's resources folder. The file should look like this:

var customizeToolbar = function () {
    $('#wpTextbox1').wikiEditor('addToToolbar', {
        section: 'main',
        group: 'format',
        tools: {
            "ExtensionName": { // replace with the name of your extension
                label: 'TagName', // replace with the label that should appear when hoving the button
                type: 'button',
                icon: "extensions/ExtensionName/images/button-image.svg", // path to the image that should go on the button
                action: {
                    type: 'encapsulate',
                    options: {
                        pre: "<tagName>", // tags that get inserted when the button is clicked
                        post: "</tagName>"
                    }
                }
            }
        }
    });
};

/* Check if view is in edit mode and that the required modules are available. Then, customize the toolbar … */
if ( [ 'edit', 'submit' ].indexOf( mw.config.get( 'wgAction' ) ) !== -1 ) {
    mw.loader.using( 'user.options' ).then( function () {
        // This can be the string "0" if the user disabled the preference ([[phab:T54542#555387]])
        if ( mw.user.options.get( 'usebetatoolbar' ) == 1 ) {
            $.when(
                mw.loader.using( 'ext.wikiEditor' ), $.ready
            ).then( customizeToolbar );
        }
    } );
}

Further details about customizing this file can be found here.

Once you've created the file, you need to register it with ResourceLoader so it will be delivered to visitors; this is done by editing your extension.json:

"Hooks": {
    "BeforePageDisplay": "ExtensionName::onBeforePageDisplay"
}
"ResourceModules": {
    "ext.ExtensionName": {
        "scripts": ["toolbarButton.js"]
    }
}

Then, in your PHP file:

public static function onBeforePageDisplay( OutputPage $out ) {
    $out->addModules( [ 'ext.ExtensionName' ] );
}

例

属性

規約