Manual:Tag extensions/ru

Индивидуальные проекты часто находят полезным расширить встроенную Вики-разметку дополнительными возможностями, будь то простые операции со строками, или полноценный информационный поиск. Расширения тегов позволяют пользователям создавать новые пользовательские теги. Например, можно использовать расширение тега, чтобы ввести простой тег, который вставляет форму пожертвования в страницу. Расширения, наряду с Функциями парсера и Hooks являются наиболее эффективным способом, чтобы изменить или расширить функциональность MediaWiki. Перед тем, как начать работу над новым расширением, обязательно нужно проверить матрицу расширений и убедиться, не сделал ли уже кто-то другой именно то, что вы пытаетесь сделать.

Простое расширение тега состоит из функции обратного вызова, которая перехватывает вызов синтаксического анализатора так, что, когда синтаксический анализатор работает, он будет искать и заменять все вхождения указанного признака, вызывая соответствующую функцию обратного вызова для отображения HTML.

Примеры
In extension.json, set up the hooks:

And add the hook into a PHP file

This example registers a callback function for the  tag. When a user adds this tag to a page like this:, the parser will call the   function, passing in four arguments:


 * $input : Input between the  and   tags, or null if the tag is "closed", i.e.
 * $args : Tag arguments, which are entered like HTML tag attributes; this is an associative array indexed by attribute name.
 * $parser : 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.
 * $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.

For a more elaborate example, see Tag extension example

Атрибуты
Посмотрите следующие примеры:

This example dumps the attributes passed to the tag, along with their values. It's quite evident that this allows for flexible specification of new, custom tags. You might, for example, define a tag extension that allows a user to inject a contact form on their user page, using something like.

There is a veritable plethora of tag extensions available for MediaWiki, some of which are listed on this site; others can be found via a quick web search. 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.

Соглашение
See for the general layout and setup of an extension.

Публикация своего расширения

 * 1) Create a new page on this wiki named Extension: with information on your extension, how to install it, and screenshots of it in use. A convenient template has been created to hold this information called . См. страницу шаблонов с дополнительной информацией. 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. Also, make sure the page belongs to.
 * 2) Extensions that create new hooks within the extension code should register them on extension hook registry.
 * 3) Notify the mediawiki-l mailing list.

See also publishing your extension.

Вопросы безопасности
You'll notice above that the input in the examples above is escaped using  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.

Timing and extensions
Если вы измените код расширения, все страницы, использующие это расширения, будет, теоретически, сразу же отражать результаты работы нового кода. Technically speaking, this means your code is executed each and every time a page containing the extension is rendered.

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.

Как отключить кэширование страниц, использующие моё расширение?
Начиная с mediawiki 1.5, синтаксический анализатор передается в качестве третьего параметра расширения. This parser can be used to invalidate the cache like this:

Обновление страницы, когда другие редактируют страницу
Возможно, Вы не хотите отключить кэширование полностью, Вы просто хотите, чтобы страницы, были обновлены, когда ктото редактирует страницу, подобно тому, как обрабатывается шаблон transclusions. This can be done using the parser object that is passed to your hook function. The following method was lifted from 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 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.

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

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, so you can nest extension tags.

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


 * If  is provided (using the value of   passed to your extension), then any template parameters in   will be expanded.  In other words, content such as   will be recognized and converted into the appropriate value.
 * If  is not provided (e.g.,  ), or if   is set to false, then template parameters will not be expanded;   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 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.

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.

Since version 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, to avoid the risk of HTML injection.

How can I avoid modification of my extension's HTML output?
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.
 * 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  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.

How do I get my extension to show up on 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  variable as the first executable line of code before the hook line or function definition.

An example extension credit is:

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


 * 'specialpage'&mdash;reserved for additions to MediaWiki Special Pages;
 * 'parserhook'&mdash;used if your extension modifies, complements, or replaces the parser functions in MediaWiki;
 * 'variable'&mdash;extension that add multiple functionality to MediaWiki;
 * 'media'&mdash;used if your extension is a media handler of some sort
 * 'other'&mdash;all other extensions.

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

Retrieving the tag name inside of the callback
Suppose you have several tags  and   that share the same callback, and inside the callback function, you want to obtain the name of the tag that invoked the callback.

The short answer is: the tag name ( or  ) 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:

См. также

 * – Список специальных тегов/переменных, таких как,  , ...
 * – Список тегов парсера, используемых в вики Wikimedia.