Manual:Tag extensions/de

Individuelle Projekte werden es häufig nützlich finden, den eingebauten Wiki-Markup mit zusätzlichen Fähigkeiten, ob einfache String-Verarbeitung oder voll ausgereifte Informationsgewinnung zu erweitern. Tag-Erweiterungen erlaubt es Benutzern, neue benutzerdefinierte Tags zu erstellen, die genau nur das tun. Zum Beispiel, könnte man eine Tag-Erweiterung dazu verwenden, um einen einfachen &lt;donation /&gt;-Tag einzuführen, der ein Spendenformular auf einer Seite anlegt. Erweiterungen zusammen mit Parserfunktionen und Hooks, sind die effektivste Art und Weise, um die Funktionalität von MediaWiki zu ändern oder zu verbessern. Um vorhandene Erweiterungen zu sehen, welche von anderen MediaWiki Benutzern entwickelt wurden, werfen Sie einen Blick auf die Erweiterungsmatrix. Sie sollten immer die Erweiterungsmatrix überprüfen, bevor Sie damit anfangen, an einer Erweiterung zu arbeiten, um sicherzustellen jemand anderes hat nicht genau das getan, was Sie zu tun versuchen.

Eine einfache Tag-Erweiterung besteht aus einer Rückruffunktion, die an den Parser eingehakt ist, so dass wenn der Parser läuft, es alle Instanzen von einem bestimmten Tag finden und ersetzen wird, durch den Aufruf der entsprechenden Rückruffunktion, um das tatsächliche HTML zu rendern.

Beispiel
Dieses Beispiel registriert eine Rückruffunktion für den &lt;sample&gt;-Tag. Wenn ein Benutzer diesen Tag zu einer Seite wie diese hinzufügt:   ruft der Parser die wfSampleRender-Funktion auf und übergibt drei Argumente:


 * $input : Eingabe zwischen den &lt;sample&gt; und &lt;/sample&gt; Tags oder null, wenn das Tag "geschlossen" ist, z.B. &lt;sample /&gt;
 * $args : Tag Argumente, die wie HTML-Tag Attribute eingegeben werden, dies ist ein assoziatives Array, das von Attribut-Namen indiziert wird.
 * $parser : Die Stammparser (ein Parserobjekt); weiter fortgeschrittenere Erweiterungen nutzen dies, um den kontextuellen Titel zu erhalten, Wikitext zu analysieren (parse), Träger (braces) zu erweitern, Linkbeziehungen und Abhängigkeiten registrieren, etc.
 * $frame : Die übergeordneten Frame (ein PPFrame Objekt). Dies wird zusammen mit $parser ververwendet, um den Parser mit vollständigeren Informationen über den Kontext, in dem die Erweiterung aufgerufen wurde.

Attribute
Lasst uns ein anderes Beispiel ansehen:

Dieses Beispiel lädt die Attribute ab und übergibt sie dem Tag, zusammen mit ihren Werten. Es ist ziemlich offensichtlich, dass dies eine flexible Spezifikation von neuen, individuellen Tags ermöglicht. Sie könnten zum Beispiel eine Tag-Erweiterung definieren, die es einem Benutzer ermöglicht ein Kontaktformular auf ihrer Benutzerseite anlegen zu können, durch Verwendung mit so etwas wie &lt;emailform to="User" email="user@foo.com" /&gt;.

Es ist eine wahre Fülle von Tag-Erweiterungen für MediaWiki verfügbar, von denen einige auf dieser Seite aufgelistet sind, andere können über eine schnelle Websuche gefunden werden. Während eine Reihe von diesen, ganz für ihren Anwendungsfall spezialisiert sind, gibt es sehr viele beliebte und gut genutzte Erweiterungen, die variierende Grade an Funktionalität bereitstellen.

Konventionen
Während eine Erweiterung eine einzelne Datei sein kann, wird es empfohlen dass für jede Erweiterung ein einzelnes Unterverzeichnis  im Verzeichnis der Erweiterungen erstellt wird, dass drei Dateien enthält:


 * eine kleine Setup-Datei,
 * eine Internationalisierungs-Datei,
 * eine  Datei mit dem größten Teil des Codes.

Per Konvention wird die Setup-Datei ein Element an das Array  anfügen, die angibt welche Dateien geladen werden sollen:

Für weitere allgemeine Hinweise, sehen Sie sich die Seite Erweiterungen entwickeln (engl.) an.

Veröffentlichung Ihrer Erweiterungen

 * 1) Erstellen Sie eine neue Seite in diesem Wiki namens Erweiterung: mit Informationen über Ihre Erweiterung, wie sie zu installieren ist, und Screenshots davon in Gebrauch. Eine praktische Vorlage wurde erstellt, um diese Informationen zu halten, genannt Vorlage:Erweiterung. Sehen Sie sich die Vorlagenseite für weitere Informationen an. Sie sollten so viele Details wie möglich zum Hauptteil der Seite hinzufügen, es ist außerdem klug diese regelmäßig zu überprüfen, um auf Fragen der Benutzer auf der dazugehörigen Diskussionsseite zu antworten. Stellen Sie außerdem sicher, dass die Seite zur Kategorie:Erweiterungen gehört.
 * 2) Erweiterungen, die neue Hooks innerhalb des Erweiterungscode schaffen, sollten sie auf der Seite Extension hook registry (engl.) registrieren.
 * 3) Benachrichtigen Sie die mediawiki-l-Mailingliste.

Siehe auch: Veröffentlichung Ihrer Erweiterung. (engl.)

Sicherheitsbedenken
You'll notice above that the input in the examples above is escaped using htmlspecialchars</tt> 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.

Timing und Erweiterungen
If you change the code for an extension, all pages that use the extension will, theoretically, immediately reflect the results of new code. 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.

Wie deaktiviere ich Caching für Seiten die meine Erweiterung nutzen?
Since MediaWiki 1.5, the parser is passed as the third parameter to an extension. This parser can be used to invalidate the cache like this:

Regenerierung der Seite, wenn eine andere Seite bearbeitet wird
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 CoreParserFunctions.php and appears to work for this purpose.

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

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

The second parameter to recursiveTagParse, $frame</tt>, is an optional argument introduced in MW 1.16 alpha (r55682).
 * If $frame</tt> is provided (using the value of $frame</tt> passed to your extension), then any template parameters in $text</tt> will be expanded. In other words, content such as   </tt> will be recognized and converted into the appropriate value.
 * If $frame</tt> is not provided (e.g., $parser->recursiveTagParse( $text )</tt>), or if $frame</tt> is set to false, then template parameters will not be expanded;  </tt> 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: 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.
 * 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.

Version 1.8 bis Version 1.15
The only difference before 1.16 is that the $frame argument was not available for Parser::recursiveTagParse</tt>.

If the resulting inability to recognize template variables is a problem, see Extensions and Templates and bug 2257 for more information and workarounds.

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

Wie kann ich die Modifikation der HTML-Ausgabe meiner Erweiterung vermeiden?
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 that look like UNIQe62a6957e0dbf6e-item-53--QINU</tt> 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 &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 nowiki</tt> 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.

Wie bekomme ich meine Erweiterung dazu, sie auf Spezial:Version anzuzeigen?
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</tt> variable as the first executable line of code before the hook line or function definition.

An example extension credit is:

Replace validextensionclass</tt> 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 <tt>myextensionmsg</tt> 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 <tt>description</tt> field will be used instead.