View source for Manual:Tag extensions

<languages />
{{Magic words}}
[[File:MediaWiki-extensions-icon.svg|125px|alt=<translate><!--T:1--> MediaWiki extensions</translate>|{{dir|{{pagelang}}|left|right}}]]
<translate><!--T:2--> Individual projects will often find it useful to '''extend the built-in wiki markup''' with additional capabilities, whether simple string processing, or full-blown information retrieval.</translate>  
<translate><!--T:3--> Tag extensions allow users to create new custom tags that do just that.</translate>  
<translate><!--T:4--> For example, one might use a tag extension to introduce a simple <tvar name=donation>{{tag|donation|single}}</tvar> tag, which injects a donation form into the page.</translate>  
<translate><!--T:5--> Extensions, including [[<tvar name=man1>Special:MyLanguage/Manual:Parser Functions</tvar>|parser functions]] and [[<tvar name=man2>Special:MyLanguage/Manual:Hooks</tvar>|hooks]], are the most effective way to change or enhance the functionality of MediaWiki.</translate> 
<translate><!--T:6--> You should always check before you start work on an extension to make sure someone else hasn't done exactly what you are trying to do.</translate>

<translate>
<!--T:7-->
A simple tag extension consists of a [[w:Callback (computer science)|callback]] function, which is [[w:Hooking|hooked]] to the parser so that, when the parser runs, it will find and replace all instances of a specific tag, calling the corresponding callback function to render the actual HTML.

==Example== <!--T:8-->
</translate>
{{Update|Section}}

<translate><!--T:147--> In <tvar name=3>{{ll|Manual:Extension registration|extension.json}}</tvar>, set up the [[<tvar name=2>Special:MyLanguage/Manual:Hooks</tvar>|hooks]]:</translate>

<syntaxhighlight lang="json">
...
  "Hooks": {
       "ParserFirstCallInit": "ExampleExtensionHooks"
   },
   "HookHandlers": {
       "ExampleExtensionHooks": {
           "class": "MediaWiki\\Extension\\ExampleExtension\\Hooks"
       }
   }
...
</syntaxhighlight>

<translate><!--T:148--> And add the hook into a PHP file</translate>

<syntaxhighlight lang="php">
<?php
namespace MediaWiki\Extension\ExampleExtension;

class ExampleExtension implements ParserFirstCallInitHook {
	// <translate nowrap><!--T:9--> Register any render callbacks with the parser</translate>
	public function onParserFirstCallInit( $parser ) {
		// <translate nowrap><!--T:10--> When the parser sees the <sample> tag, it executes renderTagSample (see below)</translate>
		$parser->setHook( 'sample', [ $this, 'renderTagSample' ] );
	}

	// Render <sample>
	public function renderTagSample( $input, array $args, Parser $parser, PPFrame $frame ) {
		// <translate nowrap><!--T:11--> Nothing exciting here, just escape the user-provided input and throw it back out again (as example)</translate>
		return htmlspecialchars( $input );
	}
}
</syntaxhighlight>

<translate><!--T:12--> This example registers a callback function for the <tvar name=sample>{{tag|sample|open}}</tvar> tag.</translate>  
<translate><!--T:13--> When a user adds this tag to a page like this: <tvar name=code><syntaxhighlight lang=html inline><sample arg1="xxx" arg2="xxx">...input...</sample></syntaxhighlight></tvar>, the parser will call the <code>renderTagSample()</code> function, passing in four arguments:</translate>

;$input : <translate><!--T:14--> Input between the <tvar name=1>{{tag|sample|open}}</tvar> and <tvar name=2>{{tag|sample|close}}</tvar> tags, or '''null''' if the tag is "closed", i.e. <tvar name=3>{{tag|sample|single}}</tvar></translate>
;$args : <translate><!--T:15--> Tag arguments, which are entered like HTML tag attributes; this is an associative array indexed by attribute name.</translate>
;$parser : <translate><!--T:16--> The parent parser (a Parser object); more advanced extensions use this to obtain the contextual Title, parse wiki text, expand braces, register link relationships and dependencies, etc.</translate>
;$frame : <translate><!--T:17--> The parent frame (a PPFrame object).</translate>  <translate><!--T:18--> This is used together with $parser to provide the parser with more complete information on the context in which the extension was called.</translate>

<translate>
<!--T:19-->
For a more elaborate example, see [[<tvar name=1>Special:MyLanguage/Manual:Tag extensions/Example</tvar>|Tag extension example]]</translate>

<translate>

==Attributes== <!--T:20-->

<!--T:21-->
Let's look at another example:
</translate>

<syntaxhighlight lang="php">
<?php

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

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

function wfSampleRender( $input, array $args, Parser $parser, PPFrame $frame ) {
	$attr = [];    
	// <translate nowrap><!--T:127--> This time, make a list of attributes and their values, and dump them, along with the user input</translate>
	foreach( $args as $name => $value ) {
		$attr[] = '<strong>' . htmlspecialchars( $name ) . '</strong> = ' . htmlspecialchars( $value );
	}
	return implode( '<br />', $attr ) . "\n\n" . htmlspecialchars( $input );

/**
 * <translate nowrap><!--T:128--> The following lines can be used to get the variable values directly:</translate>
 * $to = $args['to'] ;
 * $email = $args['email'] ;
 */
}
</syntaxhighlight>

<translate><!--T:22--> This example dumps the attributes passed to the tag, along with their values.</translate> 
<translate><!--T:23--> It's quite evident that this allows for flexible specification of new, custom tags.</translate> 
<translate><!--T:24--> You might, for example, define a tag extension that allows a user to inject a contact form on their user page, using something like <tvar name=1><syntaxhighlight lang=html inline><emailform to="User" email="user@foo.com" /></syntaxhighlight></tvar>.</translate>

<translate><!--T:25--> There is a veritable plethora of tag extensions available for MediaWiki, some of which are [[<tvar name=cat>Special:MyLanguage/Category:Parser extensions</tvar>|listed on this site]]; others can be found via a quick web search.</translate> 
<translate><!--T:26--> 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.</translate>

<translate>
==Conventions== <!--T:27-->

<!--T:28-->
See <tvar name=1>{{ll|Manual:Developing extensions}}</tvar> for the general layout and setup of an extension.

==Publishing your extensions== <!--T:29-->
</translate>
{{merge|Manual:Developing extensions#Deploying and registering#Publishing}}
# <translate><!--T:30--> Create a new page on this wiki named {{<tvar name=1>tmpl|0=Extension:&lt;$1></tvar>|extension_name}} with information on your extension, how to install it, and screenshots of it in use.</translate> <translate><!--T:31--> A convenient template has been created to hold this information called <tvar name=extension>{{ll|Template:Extension}}</tvar>.</translate> <translate><!--T:32--> See the template page for more information.</translate> <translate><!--T:33--> You should also add as much detail as possible to the body of the page, and it is wise to check back fairly regularly to respond to user questions on the associated talk page.</translate> <translate><!--T:34--> Also, make sure the page belongs to <tvar name=cat>{{ll|Category:Extensions}}</tvar>.</translate>
# <translate><!--T:35--> Extensions that create new [[<tvar name=1>Special:MyLanguage/Manual:Hooks</tvar>|hooks]] within the extension code should register them in the [[<tvar name=2>Special:MyLanguage/Category:Extension_hooks</tvar>|extension hook category]].</translate>
# <translate><!--T:36--> Notify the [[mail:mediawiki-l|mediawiki-l]] mailing list.</translate>

<translate>
<!--T:37-->
See also [[<tvar name=1>Special:MyLanguage/Manual:Developing extensions#Publishing your extension</tvar>|publishing your extension]].

==FAQ== <!--T:38-->

===Security concerns=== <!--T:39-->
</translate>
<translate><!--T:40--> You'll notice above that the input in the examples above is escaped using <tvar name=1><code>[https://php.net/function.htmlspecialchars htmlspecialchars()]</code></tvar> before being returned.</translate> 
<translate><!--T:41--> 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 [[w:Code injection|HTML injection]], which can lead to [[w:Cross-site scripting|cross-site scripting]] vulnerabilities.</translate>

<translate>
===Loading modules=== <!--T:42-->
</translate>
<translate><!--T:43--> Your extension should add modules by attaching them to the ParserOutput.</translate> 
<translate><!--T:44--> The module list will be taken from the ParserOutput object and added to the OutputPage, even when the page rendering is pre-cached.</translate> 
<translate><!--T:45--> If you are adding the modules directly to the OutputPage they might not be cached in the parser output.</translate>

<syntaxhighlight lang="php">
public function renderTagSample( $input, array $args, Parser $parser, PPFrame $frame ) {
	// ... <translate nowrap><!--T:149--> do stuff</translate> ...
	$parser->getOutput()->addModules( 'ext.ExampleExtension' );
	$parser->getOutput()->addModuleStyles( 'ext.ExampleExtension.styles' );
	// ... <translate nowrap><!--T:150--> do more stuff</translate> ...
}
</syntaxhighlight>

<translate>

===Timing and extensions=== <!--T:46-->
</translate>
<translate><!--T:47--> If you change the code for an extension, all pages that use the extension will, theoretically, immediately reflect the results of new code.</translate>  
<translate><!--T:48--> Technically speaking, this means your code is executed each and every time a page containing the extension is rendered.</translate>

<translate>
<!--T:49-->
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.
</translate>

<translate><!--T:50--> 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.</translate> 
<translate><!--T:51--> The page and all templates it references will be regenerated, ignoring all cached data.</translate> 
<translate><!--T:52--> 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).</translate>

<translate><!--T:53--> 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.</translate>  
<translate><!--T:54--> Make sure 'somerandomtext' is different every time.</translate>

<translate>
===How do I disable caching for pages using my extension?=== <!--T:55-->
</translate>
<translate><!--T:56--> Since MediaWiki 1.5, the parser is passed as the third parameter to an extension.</translate>  
<translate><!--T:57--> This parser can be used to invalidate the parser cache like this:</translate>

<syntaxhighlight lang="php">
function wfSampleSomeHookFunction( $text, array $args, Parser $parser, PPFrame $frame ) {
	$parser->getOutput()->updateCacheExpiry(0);
	// ...
}
</syntaxhighlight>

<translate>
====Regenerating the page when another page is edited ==== <!--T:58-->
</translate>
<translate><!--T:59--> 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.</translate> 
<translate><!--T:60--> This can be done using the parser object that is passed to your hook function and calling the <tvar name="1"><code>addTemplate</code></tvar>.</translate>

<translate>

===Fine grained adjustment of caching behavior=== <!--T:62-->
</translate>
<translate><!--T:63--> You can use fine grained caching for your extension by using cache keys to differentiate between different versions of your extension output.</translate>
<translate><!--T:64--> While rendering you can add cache keys for every feature by adding an addExtraKey method to your hook function, e.g.:</translate>

<syntaxhighlight lang="php">
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' );
	...
}
</syntaxhighlight>

<translate><!--T:65--> However, modifying <tvar name=1>{{phpi|$parser->getOptions()}}</tvar> 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 <tvar name=2>{{ll|Manual:Hooks/PageRenderingHash|PageRenderingHash}}</tvar> hook to set extra options.</translate> 
<translate><!--T:66--> 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.</translate>  
<translate><!--T:67--> e.g:</translate>

<syntaxhighlight lang="php">
$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' );
	}
}
</syntaxhighlight>

<translate>
<!--T:68-->
Some important notes on this:

<!--T:69-->
*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.</translate> <translate><!--T:70--> ''!'' is used a separator for different rendering options</translate>
<translate>
<!--T:71-->
*Some people use <code>$parser->getOptions()->addExtraKey()</code> instead of <code>$parser->getOptions()->optionUsed()</code>.</translate> <translate><!--T:72--> 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.</translate>

<translate>
===How do I render wikitext in my extension?=== <!--T:73-->

====Since version 1.16==== <!--T:74-->
</translate>
{{MW 1.16|and later}}
<translate>
<!--T:75-->
Parser hook functions are passed a reference to the parser object and a frame object; these should be used to parse wikitext.
</translate>

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

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

<translate>
<!--T:78-->
The second parameter to recursiveTagParse, <code>$frame</code>, is an optional argument introduced in MW 1.16 alpha (r55682).

<!--T:79-->
* If <tvar name=1><code>$frame</code></tvar> is provided (using the value of <tvar name=1><code>$frame</code></tvar> passed to your extension), then any template parameters in <tvar name=2><code>$text</code></tvar> will be expanded.</translate> <translate><!--T:80--> In other words, content such as <tvar name=1><code><nowiki>{{{1}}}</nowiki></code></tvar> will be recognized and converted into the appropriate value.</translate>  
<translate>
<!--T:81-->
* If <tvar name=1><code>$frame</code></tvar> is not provided (e.g., <tvar name=2>{{phpi|$parser->recursiveTagParse( $text )}}</tvar>), or if <tvar name=1><code>$frame</code></tvar> is set to false, then template parameters will not be expanded; <tvar name=3><code><nowiki>{{{1}}}</nowiki></code></tvar> will not be altered.</translate> <translate><!--T:82--> Although this unlikely to be the desired behavior, this was the only option available before MW 1.16.</translate>

<translate><!--T:83--> However, one step of parsing that is still skipped for tags, even when using <tvar name=1>recursiveTagParse</tvar>, is <tvar name=2>{{phpi|Parser::preSaveTransform}}</tvar>.</translate>  
<translate><!--T:84--> <tvar name=1>preSaveTransform</tvar> is the first step of parsing, responsible for making permanent changes to the about-to-be saved wikitext, such as:</translate>

<translate>
<!--T:85-->
* Converting signatures</translate> (<nowiki>~~~</nowiki>, <nowiki>~~~~</nowiki>, <nowiki>~~~~~</nowiki>)
<translate>
<!--T:86-->
* Expanding link labels, also known as the ''pipe-trick'' (e.g., changing <nowiki>[[Help:Contents|]]</nowiki> into <nowiki>[[Help:Contents|Contents]]</nowiki>).</translate>  <translate><!--T:87--> Without this step, shorthand links such as <nowiki>[[Help:Contents|]]</nowiki> are considered to be invalid, and are left in their wikitext form when parsed.</translate>
<translate>
<!--T:88-->
* Expanding <nowiki>{{subst:}}</nowiki> templates.
</translate>

<translate><!--T:89--> The original call to preSaveTransform intentionally skips such conversions within all extension tags.</translate> 
<translate><!--T:90--> If you need pre save transform to be done, you should consider using a [[<tvar name=1>Special:MyLanguage/Manual:Parser functions</tvar>|parser function]] instead.</translate> 
<translate><!--T:91--> All tag extensions can also be called as a parser function using <code><nowiki>{{#tag:tagname|input|attribute_name=value}}</nowiki></code> which will have pre save transform applied.</translate>

<translate>
===How can I pass XML-style parameters in my extension tag?=== <!--T:95-->

====Since version 1.5==== <!--T:96-->
</translate>
<translate><!--T:97--> Since MediaWiki 1.5, XML-style parameters (tag attributes) are supported.</translate> 
<translate><!--T:98--> The parameters are passed as the second parameter to the hook function, as an associative array.</translate> 
<translate><!--T:99--> 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 <code>htmlspecialchars( $codeToEncode, ENT_QUOTES )</code>, to avoid the risk of HTML injection.</translate>

<translate>
===How can I avoid modification of my extension's HTML output?=== <!--T:100-->
</translate>
<translate><!--T:101--> The return value of a tag extension is considered ''almost'' parsed text, which means its not treated as pure html, but still modified slightly.</translate> 
<translate><!--T:102--> There are two main things that are done to the output of a tag extension (Along with a couple other minor things):</translate>

<translate>
<!--T:103-->
*Replace [[strip marker]]s.</translate> <translate><!--T:104--> 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.</translate> <translate><!--T:105--> This is not something extensions usually need to worry about.</translate>
<translate>
<!--T:106-->
*<tvar name=1>{{class doclink|Parser|anchor=ad463888e40c078ac9bcfcaf1231e39d7|Parser::doBlockLevels}}</tvar> which turns *'s into lists, and turns any line starting with a leading space into a <tvar name=2>{{tag|pre|open}}</tvar> among other things.</translate> <translate><!--T:107--> This can sometimes be an issue in some extensions.</translate>

<translate><!--T:108--> 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.</translate> 
<translate><!--T:109--> The 0th value of the array must be the HTML.</translate> 
<translate><!--T:110--> The "markerType" key can be set to <code>nowiki</code> in order to stop further parsing.</translate> 
<translate><!--T:111--> Doing something like <tvar name=1><syntaxhighlight lang="php" inline>return [ $html, 'markerType' => 'nowiki' ];</syntaxhighlight></tvar> would ensure that the $html value is not further modified and treated as just plain html.</translate>

<translate>
===How do I get my extension to show up on Special:Version?=== <!--T:112-->

<!--T:168-->
See <tvar name=1>{{ll|Manual:Extension registration}}</tvar> and register your extension accordingly.

=== Retrieving the tag name inside of the callback === <!--T:129-->

<!--T:130-->
Suppose you have several tags <tvar name=foo>{{tag|foo|open}}</tvar> and <tvar name=bar>{{tag|bar|open}}</tvar> that share the same callback, and inside the callback function, you want to obtain the ''name of the tag'' that invoked the callback.
</translate>

<syntaxhighlight lang="php">
$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 ) {
	// <translate nowrap><!--T:131--> How to distinguish between 'foo' and 'bar' calls?</translate>
}
</syntaxhighlight>

<translate><!--T:132--> The short answer is: the tag name (<tvar name=foo><code>foo</code></tvar> or <tvar name=bar><code>bar</code></tvar>) is not present in any of the callback's arguments.</translate>
<translate><!--T:133--> But you can work around this by dynamically constructing a separate callback for each tag:</translate>

<syntaxhighlight lang="php">
$wgHooks['ParserFirstCallInit'][] = 'onParserFirstCallInit';

# ...

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

# ...

public function sharedFunctionality( $input, array $args, Parser $parser, PPFrame $frame, $tagName) {
	// <translate nowrap><!--T:139--> Now we can retrieve the tag name and perform custom actions for that tag</translate>
	switch ( $tagName ) {
		//...
	}
}

</syntaxhighlight>

<translate>
=== Toolbar buttons === <!--T:152-->
</translate>
<translate><!--T:153--> <tvar name=1>{{ll|Extension:WikiEditor}}</tvar> provides an editing toolbar, allowing users to add tags into their editor by simply clicking a button.</translate>
<translate><!--T:154--> If you want a toolbar button for your new tag, create a file named something like <tvar name=1><code>toolbar-button.js</code></tvar> in your extension's <tvar name=2><code>resources</code></tvar> folder.</translate> <translate><!--T:155--> The file should look like this:</translate>

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

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

<translate>
<!--T:156-->
[[<tvar name=1>Special:MyLanguage/Extension:WikiEditor/Toolbar customization</tvar>|Further details about customizing this file can be found here]].</translate>
<translate><!--T:157--> Once you've created the file, you need to register it with <tvar name=1>{{ll|ResourceLoader}}</tvar> so it will be delivered to visitors; this is done by editing your <tvar name=2><code>extension.json</code></tvar>:</translate>

<syntaxhighlight lang="js">
"Hooks": {
    "BeforePageDisplay": "ExtensionName::onBeforePageDisplay"
}
"ResourceModules": {
    "ext.ExtensionName": {
        "scripts": ["toolbarButton.js"]
    }
}
</syntaxhighlight>

<translate><!--T:158--> Then, in your PHP file:</translate>

<syntaxhighlight lang="php">
public static function onBeforePageDisplay( OutputPage $out ) {
    $out->addModules( [ 'ext.ExtensionName' ] );
}
</syntaxhighlight>

<translate>
==See also== <!--T:124-->
</translate>
*{{ll|Help:Magic words}} &ndash; <translate><!--T:125--> List of special tag/variables like <nowiki>{{PAGENAME}}</nowiki>, <nowiki>{{SERVER}}</nowiki>, ...</translate>
*{{ll|Parser extension tags}} &ndash; <translate><!--T:126--> List of parser tags in use on Wikimedia wikis.</translate>
*{{ll|Manual:Extensions}}
*{{ll|Extensions FAQ|Extensions FAQ}}
*{{ll|Category:Extensions}}
*{{ll|Manual:$wgExtensionFunctions|Manual:$wgExtensionFunctions}}

{{Extension development}}

[[Category:Customization techniques{{#translation:}}|{{PAGENAME}}]]
[[Category:MediaWiki development{{#translation:}}]]
[[Category:Parser extensions{{#translation:}}|*]]
[[Category:Sample code{{#translation:}}]]