View source for Manual:Tag extensions/pt

<languages />
{{ExtensionTypes}}
[[File:MediaWiki-extensions-icon.svg|125px|alt=Extensões do MediaWiki|{{dir|{{pagelang}}|left|right}}]]
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>  
<span lang="en" dir="ltr" class="mw-content-ltr">Tag extensions allow users to create new custom tags that do just that.</span>  
<span lang="en" dir="ltr" class="mw-content-ltr">For example, one might use a tag extension to introduce a simple {{tag|donation|single}} tag, which injects a donation form into the page.</span>  
<span lang="en" dir="ltr" class="mw-content-ltr">Extensions, including [[Special:MyLanguage/Manual:Parser Functions|parser functions]] and [[Special:MyLanguage/Manual:Hooks|hooks]], are the most effective way to change or enhance the functionality of MediaWiki.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
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.
</div>

<span id="Example"></span>
== Exemplo ==
{{Update|Section}}

<span lang="en" dir="ltr" class="mw-content-ltr">In [[Special:MyLanguage/Manual:Extension registration|extension.json]], set up the [[Special:MyLanguage/Manual:Hooks|hooks]]:</span>

<syntaxhighlight lang="json">
...
  "Hooks": {
    "ParserFirstCallInit": "ExampleExtension::onParserFirstCallInit"
   },
...
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr">And add the hook into a PHP file</span>

<syntaxhighlight lang="php">
<?php

class ExampleExtension {
	// Register any render callbacks with the parser
	public static function onParserFirstCallInit( Parser $parser ) {
		// When the parser sees the <sample> tag, it executes renderTagSample (see below)
		$parser->setHook( 'sample', [ self::class, 'renderTagSample' ] );
	}

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

<span lang="en" dir="ltr" class="mw-content-ltr">This example registers a callback function for the {{tag|sample|open}} tag.</span>  
<span lang="en" dir="ltr" class="mw-content-ltr">When a user adds this tag to a page like this: <syntaxhighlight lang=html inline><sample arg1="xxx" arg2="xxx">...input...</sample></syntaxhighlight>, the parser will call the <code>renderTagSample()</code> function, passing in four arguments:</span>

;$input : <span lang="en" dir="ltr" class="mw-content-ltr">Input between the {{tag|sample|open}} and {{tag|sample|close}} tags, or '''null''' if the tag is "closed", i.e. {{tag|sample|single}}</span>
;$args : <span lang="en" dir="ltr" class="mw-content-ltr">Tag arguments, which are entered like HTML tag attributes; this is an associative array indexed by attribute name.</span>
;$parser : <span lang="en" dir="ltr" class="mw-content-ltr">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.</span>
;$frame : <span lang="en" dir="ltr" class="mw-content-ltr">The parent frame (a PPFrame object).</span>  <span lang="en" dir="ltr" class="mw-content-ltr">This is used together with $parser to provide the parser with more complete information on the context in which the extension was called.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
For a more elaborate example, see [[Special:MyLanguage/Manual:Tag extensions/Example|Tag extension example]]
</div>

<span id="Attributes"></span>
== Atributos ==

<div lang="en" dir="ltr" class="mw-content-ltr">
Let's look at another example:
</div>

<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 = [];    
	// This time, make a list of attributes and their values, and dump them, along with the user input
	foreach( $args as $name => $value ) {
		$attr[] = '<strong>' . htmlspecialchars( $name ) . '</strong> = ' . htmlspecialchars( $value );
	}
	return implode( '<br />', $attr ) . "\n\n" . htmlspecialchars( $input );

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

<span lang="en" dir="ltr" class="mw-content-ltr">This example dumps the attributes passed to the tag, along with their values.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">It's quite evident that this allows for flexible specification of new, custom tags.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">You might, for example, define a tag extension that allows a user to inject a contact form on their user page, using something like <syntaxhighlight lang=html inline><emailform to="User" email="user@foo.com" /></syntaxhighlight>.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">There is a veritable plethora of tag extensions available for MediaWiki, some of which are [[Special:MyLanguage/Category:Parser extensions|listed on this site]]; others can be found via a quick web search.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>

<span id="Conventions"></span>
== Convenções ==

Consulte {{ll|Manual:Developing extensions}} para a disposição geral e a configuração de uma extensão.

<span id="Publishing_your_extensions"></span>
== Publicar as suas extensões ==
{{merge|Manual:Developing extensions#Deploying and registering#Publishing}}
<div lang="en" dir="ltr" class="mw-content-ltr">
#Create a new page on this wiki named {{tmpl|0=Extension:&lt;$1>|extension_name}} with information on your extension, how to install it, and screenshots of it in use.
</div> <span lang="en" dir="ltr" class="mw-content-ltr">A convenient template has been created to hold this information called {{ll|Template:Extension}}.</span> <span lang="en" dir="ltr" class="mw-content-ltr">See the template page for more information.</span> <span lang="en" dir="ltr" class="mw-content-ltr">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.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Also, make sure the page belongs to {{ll|Category:Extensions}}.</span>
<div lang="en" dir="ltr" class="mw-content-ltr">
#Extensions that create new [[Special:MyLanguage/Manual:Hooks|hooks]] within the extension code should register them in the [[Special:MyLanguage/Category:Extension_hooks|extension hook category]].
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
#Notify the [[mail:mediawiki-l|mediawiki-l]] mailing list.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
See also [[Special:MyLanguage/Manual:Developing extensions#Publishing your extension|publishing your extension]].
</div>

<span id="FAQ"></span>
== Perguntas Mais Frequentes ==

<span id="Security_concerns"></span>
=== Preocupações de segurança ===
<span lang="en" dir="ltr" class="mw-content-ltr">You'll notice above that the input in the examples above is escaped using <code>[https://php.net/function.htmlspecialchars htmlspecialchars()]</code> before being returned.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>

<span id="Loading_modules"></span>
=== Carregar módulos ===
<span lang="en" dir="ltr" class="mw-content-ltr">The right way to add modules for your extension is to attach them to the ParserOutput rather than to $wgOut.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">The module list will then be automatically taken from the ParserOutput object and added to $wgOut even when the page rendering is pre-cached.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">If you are directly adding the modules to $wgOut they might not be cached in the parser output.</span>

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

<div lang="en" dir="ltr" class="mw-content-ltr">
===Timing and extensions===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">If you change the code for an extension, all pages that use the extension will, theoretically, immediately reflect the results of new code.</span>  
<span lang="en" dir="ltr" class="mw-content-ltr">Technically speaking, this means your code is executed each and every time a page containing the extension is rendered.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
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.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">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.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">The page and all templates it references will be regenerated, ignoring all cached data.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">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).</span>

<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>  
<span lang="en" dir="ltr" class="mw-content-ltr">Make sure 'somerandomtext' is different every time.</span>

<span id="How_do_I_disable_caching_for_pages_using_my_extension?"></span>
=== Como é que eu desativo a clocação em cache para as páginas que utilizam a minha extensão? ===
<span lang="en" dir="ltr" class="mw-content-ltr">Since MediaWiki 1.5, the parser is passed as the third parameter to an extension.</span>  
<span lang="en" dir="ltr" class="mw-content-ltr">This parser can be used to invalidate the parser cache like this:</span>

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

<div lang="en" dir="ltr" class="mw-content-ltr">
====Regenerating the page when another page is edited ====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">This can be done using the parser object that is passed to your hook function.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">The following method was lifted from {{ll|Manual:CoreParserFunctions.php|CoreParserFunctions.php}} and appears to work for this purpose.</span> 

<syntaxhighlight lang="php">
/** Make the page being parsed have a dependency on $page via the templatelinks table. 
*/
function wfSampleaddTemplateLinkDependency( Parser $parser, $page )  {
	$title = Title::newFromText( $page );
	$rev = Revision::newFromTitle( $title );
	$id = $rev ? $rev->getPage() : 0;
	// Register dependency in templatelinks
	$parser->getOutput()->addTemplate( $title, $id, $rev ? $rev->getId() : 0 );
}
</syntaxhighlight>


<div lang="en" dir="ltr" class="mw-content-ltr">
===Fine grained adjustment of caching behavior===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">You can use fine grained caching for your extension by using cache keys to differentiate between different versions of your extension output.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">While rendering you can add cache keys for every feature by adding an addExtraKey method to your hook function, e.g.:</span>

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

<span lang="en" dir="ltr" class="mw-content-ltr">However, modifying {{phpi|$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 {{ll|Manual:Hooks/PageRenderingHash|PageRenderingHash}} hook to set extra options.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>  
Por exemplo:

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

Algumas notas importantes sobre isto:

<div lang="en" dir="ltr" class="mw-content-ltr">
*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.
</div> <span lang="en" dir="ltr" class="mw-content-ltr">''!'' is used a separator for different rendering options</span>
<div lang="en" dir="ltr" class="mw-content-ltr">
*Some people use <code>$parser->getOptions()->addExtraKey()</code> instead of <code>$parser->getOptions()->optionUsed()</code>.
</div> <span lang="en" dir="ltr" class="mw-content-ltr">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.</span>

<span id="How_do_I_render_wikitext_in_my_extension?"></span>
=== Como é que renderizo texto wiki na minha extensão? ===

<span id="Since_version_1.16"></span>
==== Desde a versão 1.16 ====
{{MW 1.16|and later}}
<div lang="en" dir="ltr" class="mw-content-ltr">
Parser hook functions are passed a reference to the parser object and a frame object; these should be used to parse wikitext.
</div>

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

<span lang="en" dir="ltr" class="mw-content-ltr"><code>Parser::recursiveTagParse()</code> has been around since version 1.8.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
The second parameter to recursiveTagParse, <code>$frame</code>, is an optional argument introduced in MW 1.16 alpha (r55682).
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
* If <code>$frame</code> is provided (using the value of <code>$frame</code> passed to your extension), then any template parameters in <code>$text</code> will be expanded.
</div> <span lang="en" dir="ltr" class="mw-content-ltr">In other words, content such as <code><nowiki>{{{1}}}</nowiki></code> will be recognized and converted into the appropriate value.</span>  
<div lang="en" dir="ltr" class="mw-content-ltr">
* If <code>$frame</code> is not provided (e.g., {{phpi|$parser->recursiveTagParse( $text )}}), or if <code>$frame</code> is set to false, then template parameters will not be expanded; <code><nowiki>{{{1}}}</nowiki></code> will not be altered.
</div> <span lang="en" dir="ltr" class="mw-content-ltr">Although this unlikely to be the desired behavior, this was the only option available before MW 1.16.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">However, one step of parsing that is still skipped for tags, even when using recursiveTagParse, is {{phpi|Parser::preSaveTransform}}.</span>  
<span lang="en" dir="ltr" class="mw-content-ltr">preSaveTransform is the first step of parsing, responsible for making permanent changes to the about-to-be saved wikitext, such as:</span>

* Converter assinaturas (<nowiki>~~~</nowiki>, <nowiki>~~~~</nowiki>, <nowiki>~~~~~</nowiki>)
<div lang="en" dir="ltr" class="mw-content-ltr">
* Expanding link labels, also known as the ''pipe-trick'' (e.g., changing <nowiki>[[Help:Contents|]]</nowiki> into <nowiki>[[Help:Contents|Contents]]</nowiki>).
</div>  <span lang="en" dir="ltr" class="mw-content-ltr">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.</span>
<div lang="en" dir="ltr" class="mw-content-ltr">
* Expanding <nowiki>{{subst:}}</nowiki> templates.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">The original call to preSaveTransform intentionally skips such conversions within all extension tags.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">If you need pre save transform to be done, you should consider using a [[Special:MyLanguage/Manual:Parser functions|parser function]] instead.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
===How can I pass XML-style parameters in my extension tag?===
</div>

<span id="Since_version_1.5"></span>
==== Desde a versão 1.5 ====
<span lang="en" dir="ltr" class="mw-content-ltr">Since MediaWiki 1.5, XML-style parameters (tag attributes) are supported.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">The parameters are passed as the second parameter to the hook function, as an associative array.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
===How can I avoid modification of my extension's HTML output?===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">The return value of a tag extension is considered ''almost'' parsed text, which means its not treated as pure html, but still modified slightly.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">There are two main things that are done to the output of a tag extension (Along with a couple other minor things):</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
*Replace [[strip marker]]s.
</div> <span lang="en" dir="ltr" class="mw-content-ltr">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.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This is not something extensions usually need to worry about.</span>
<div lang="en" dir="ltr" class="mw-content-ltr">
*{{class doclink|Parser|anchor=ad463888e40c078ac9bcfcaf1231e39d7|Parser::doBlockLevels}} which turns *'s into lists, and turns any line starting with a leading space into a {{tag|pre|open}} among other things.
</div> <span lang="en" dir="ltr" class="mw-content-ltr">This can sometimes be an issue in some extensions.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">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.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">The 0th value of the array must be the HTML.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">The "markerType" key can be set to <code>nowiki</code> in order to stop further parsing.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">Doing something like <syntaxhighlight lang="php" inline>return [ $html, 'markerType' => 'nowiki' ];</syntaxhighlight> would ensure that the $html value is not further modified and treated as just plain html.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
===How do I get my extension to show up on Special:Version?===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
In order for your extension to be displayed on the MediaWiki [[Special:Version]] page, you must assign extension credits within the PHP code.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
To do this, add a <code>{{ll|Manual:$wgExtensionCredits|$wgExtensionCredits}}</code> variable as the first executable line of code before the hook line or function definition.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
An example extension credit is:
</div>

<syntaxhighlight lang="php">
<?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(){
	// ...
}
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
Replace <code>validextensionclass</code> with one of the following (unless your extension falls under multiple classes&mdash;then create a credit for ''each'' class):
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
*'specialpage'&mdash;reserved for additions to MediaWiki Special Pages;
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
*'parserhook'&mdash;used if your extension modifies, complements, or replaces the parser functions in MediaWiki;
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
*'variable'&mdash;extension that add multiple functionality to MediaWiki;
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
*'media'&mdash;used if your extension is a media handler of some sort
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
*'other'&mdash;all other extensions.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">The <code>myextensionmsg</code> 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.</span> 
<span lang="en" dir="ltr" class="mw-content-ltr">If you omit this field, the <code>description</code> field will be used instead.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Retrieving the tag name inside of the callback ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Suppose you have several tags {{tag|foo|open}} and {{tag|bar|open}} that share the same callback, and inside the callback function, you want to obtain the ''name of the tag'' that invoked the callback.
</div>

<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 ) {
	// How to distinguish between 'foo' and 'bar' calls?
}
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr">The short answer is: the tag name (<code>foo</code> or <code>bar</code>) is not present in any of the callback's arguments.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">But you can work around this by dynamically constructing a separate callback for each tag:</span>

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

</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Toolbar buttons ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">{{ll|Extension:WikiEditor}} provides an editing toolbar, allowing users to add tags into their editor by simply clicking a button.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If you want a toolbar button for your new tag, create a file named something like <code>toolbar-button.js</code> in your extension's <code>resources</code> folder.</span> <span lang="en" dir="ltr" class="mw-content-ltr">The file should look like this:</span>

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

<div lang="en" dir="ltr" class="mw-content-ltr">
[[Special:MyLanguage/Extension:WikiEditor/Toolbar customization|Further details about customizing this file can be found here]].
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Once you've created the file, you need to register it with {{ll|ResourceLoader}} so it will be delivered to visitors; this is done by editing your <code>extension.json</code>:</span>

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

<span lang="en" dir="ltr" class="mw-content-ltr">Then, in your PHP file:</span>

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

<div lang="en" dir="ltr" class="mw-content-ltr">
==See also==
</div>
*{{ll|Help:Magic words}} &ndash; <span lang="en" dir="ltr" class="mw-content-ltr">List of special tag/variables like <nowiki>{{PAGENAME}}</nowiki>, <nowiki>{{SERVER}}</nowiki>, ...</span>
*{{ll|Parser extension tags}} &ndash; <span lang="en" dir="ltr" class="mw-content-ltr">List of parser tags in use on Wikimedia wikis.</span>
*{{ll|Manual:Extensions}}
*{{ll|Extensions FAQ|Extensions FAQ}}
*{{ll|Category:Extensions}}
*{{ll|Manual:$wgExtensionFunctions|Manual:$wgExtensionFunctions}}

{{Extensions}}

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