Manual:Tag extensions/cs

Jednotlivé projekty často považují za užitečné rozšířit vestavěné značení wiki o další možnosti, ať už jde o jednoduché zpracování řetězců nebo plnohodnotné vyhledávání informací. Rozšíření značek umožňují uživatelům vytvářet nové vlastní značky, které to dělají. Například lze použít rozšíření značky k zavedení jednoduché značky, která na stránku vloží darovací formulář. Rozšíření, včetně funkcí parseru a háčků, jsou nejúčinnějším způsobem, jak změnit nebo vylepšit funkčnost MediaWiki. Před zahájením práce na rozšíření byste měli vždy zkontrolovat, zda někdo jiný neudělal přesně to, o co se pokoušíte.

Jednoduché rozšíření tagu se skládá z funkce callback, která je zaháčkováním připojena k analyzátoru, takže když analyzátor běží, najde a nahradí všechny instance konkrétní značky, voláním odpovídající funkce zpětného volání k vykreslení skutečného HTML.

Příklad
V extension.json nastavte háčky:

A přidejte háček do souboru PHP

Tento příklad registruje funkci zpětného volání pro značku. Když uživatel přidá tuto značku na stránku, jako je tato:, analyzátor zavolá funkci   a předá čtyři argumenty:


 * $input : Vstup mezi značky a  nebo null, pokud je značka "zavřená", tj.
 * $args : Argumenty značek, které se zadávají jako atributy značek HTML. Toto je asociativní pole indexované podle názvu atributu.
 * $parser : Nadřazený analyzátor (objekt analyzátoru). Pokročilejší rozšíření to používají k získání kontextového názvu, analýze wiki textu, rozbalení složených závorek, registraci vztahů a závislostí odkazů atd.
 * $frame : Rodičovský rámec (objekt PPFrame). To se používá spolu s $parser k poskytnutí analyzátoru úplnější informace o kontextu, ve kterém bylo rozšíření voláno.

Propracovanější příklad viz Příklad rozšíření značky

Atributy
Podívejme se na další příklad:

Tento příklad vypíše atributy předané značce spolu s jejich hodnotami. Je zcela zřejmé, že to umožňuje flexibilní specifikaci nových vlastních značek. Můžete například definovat rozšíření značky, které umožňuje uživateli vložit kontaktní formulář na svou uživatelskou stránku pomocí něčeho jako.

Pro MediaWiki je k dispozici nepřeberné množství rozšíření značek, z nichž některá jsou uvedena na tomto webu. Ostatní lze najít pomocí rychlého vyhledávání na webu. Zatímco řada z nich je pro svůj případ použití zcela specializovaná, existuje velké množství oblíbených a dobře používaných rozšíření poskytujících různé stupně funkčnosti.

Konvence
Viz pro obecné rozložení a nastavení rozšíření.



Publikování vašich rozšíření

 * 1) Vytvořte na této wiki novou stránku s názvem Extension:&lt;extension_name> s informacemi o vašem rozšíření, jak jej nainstalovat a se snímky obrazovky, které používá. Pro tyto informace byla vytvořena pohodlná šablona s názvem . Další informace naleznete na stránce šablony. Měli byste také přidat co nejvíce podrobností do těla stránky a je moudré je poměrně pravidelně kontrolovat, abyste odpověděli na dotazy uživatelů na související diskusní stránce. Také se ujistěte, že stránka patří.
 * 2) Rozšíření, která vytvářejí nové háčky v rámci kódu rozšíření, by je měla zaregistrovat do kategorie háčků rozšíření.
 * 3) Upozorněte na mediawiki-l mailing list.

Viz také publikování vašeho rozšíření.

FAQ


Bezpečnostní obavy
Výše si všimnete, že vstup ve výše uvedených příkladech je před vrácením escapován pomocí. Je životně důležité, aby byl veškerý uživatelský vstup ošetřen tímto způsobem, než jej odešle zpět klientům, aby se předešlo zavádění vektorů pro libovolné HTML injection, což může vést k cross-site skriptování zranitelnosti.



Načítání modulů
Správný způsob, jak přidat moduly pro vaše rozšíření, je připojit je k ParserOutput spíše než k $wgOut. Seznam modulů bude poté automaticky převzat z objektu ParserOutput a přidán do $wgOut, i když je vykreslování stránky předem uloženo do mezipaměti. Pokud moduly přidáváte přímo do $wgOut, nemusí být uloženy do mezipaměti ve výstupu analyzátoru.



Časování a rozšíření
Pokud změníte kód rozšíření, všechny stránky, které rozšíření používají, teoreticky okamžitě odrážejí výsledky nového kódu. Technicky vzato to znamená, že váš kód je spuštěn pokaždé, když je vykreslena stránka obsahující rozšíření.

V praxi tomu tak často není, kvůli ukládání stránek do mezipaměti – buď softwarem MediaWiki, prohlížečem nebo zprostředkujícími proxy či firewallem.

Chcete-li obejít mezipaměť analyzátoru MediaWiki a zajistit vygenerování nové verze stránky, klikněte na upravit, nahraďte "action=edit" v adrese URL zobrazené v adresním řádku vašeho prohlížeče "action=purge" a odešlete novou adresu URL. Stránka a všechny šablony, na které odkazuje, budou znovu vygenerovány, přičemž budou ignorována všechna data uložená v mezipaměti. Akce čištění je nutná, pokud není upravena samotná hlavní stránka, ale změnil se způsob jejího vykreslení (bylo upraveno rozšíření nebo byla upravena pouze odkazovaná šablona).

Pokud to k získání nové kopie stránky nestačí, můžete obvykle obejít mezipaměti přidáním "&rand=somerandomtext" na konec výše uvedené adresy URL. Ujistěte se, že 'somerandomtext' je pokaždé jiný.



Jak deaktivuji ukládání do mezipaměti pro stránky používající mé rozšíření?
Od MediaWiki 1.5 je analyzátor předán jako třetí parametr rozšíření. This parser can be used to invalidate the cache like this:

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

! is used a separator for different rendering options 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.
 * 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.
 * Some people use  instead of.

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

In other words, content such as  will be recognized and converted into the appropriate value. Although this unlikely to be the desired behavior, this was the only option available before MW 1.16.
 * If  is provided (using the value of   passed to your extension), then any template parameters in   will be expanded.
 * If  is not provided (e.g., ), or if   is set to false, then template parameters will not be expanded;   will not be altered.

However, one step of parsing that is still skipped for tags, even when using recursiveTagParse, is. preSaveTransform is the first step of parsing, responsible for making permanent changes to the about-to-be saved wikitext, such as:

(, ~ ,  )  Without this step, shorthand links such as Help:Contents are considered to be invalid, and are left in their wikitext form when parsed.
 * Converting signatures
 * Expanding link labels, also known as the pipe-trick (e.g., changing Help:Contents into Contents ).
 * 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):

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. This can sometimes be an issue in some extensions.
 * Replace strip markers.
 * which turns *'s into lists, and turns any line starting with a leading space into a &lt;pre&gt; among other things.

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:

Toolbar buttons
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  in your extension's   folder. The file should look like this:

Further details about customizing this file can be found here. Once you've created the file, you need to register it with so it will be delivered to visitors; this is done by editing your  :

Then, in your PHP file: