Manual:Tag extensions/de

Erweiterungen:

Tag-Erweiterungen

Parserfunktionen

Hooks

Spezialseiten

Skins

Zauberworte

API

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 erlauben 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 <donation />-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 sie immer ü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

<?php
 
$wgHooks['ParserFirstCallInit'][] = 'wfSampleParserInit';
 
// Hook our callback function into the parser
function wfSampleParserInit( Parser $parser ) {
// When the parser sees the <sample> tag, it executes
// the wfSampleRender function (see below)
$parser->setHook( 'sample', 'wfSampleRender' );
// Always return true from this function. The return value does not denote
// success or otherwise have meaning - it just must always be true.
return true;
}
 
// Execute 
function wfSampleRender( $input, array $args, Parser $parser, PPFrame $frame ) {
// Nothing exciting here, just escape the user-provided
// input and throw it back out again
return htmlspecialchars( $input );
}

Dieses Beispiel registriert eine Rückruffunktion für den <sample>-Tag.
Wenn ein Benutzer diesen Tag zu einer Seite wie diese hinzufügt: <sample arg1="xxx" arg2="xxx">...input...</sample> ruft der Parser die wfSampleRender()-Funktion auf und übergibt drei Argumente:

$input 

Eingabe zwischen den <sample> und </sample> Tags oder null, wenn das Tag "geschlossen" ist, z.B. <sample />

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

<?php
 
$wgHooks['ParserFirstCallInit'][] = 'wfSampleSetup';
 
function wfSampleSetup( Parser $parser ) {
$parser->setHook( 'sample', 'wfSampleRender' );
return true;
}
 
function wfSampleRender( $input, array $args, Parser $parser, PPFrame $frame ) {
$attr = array();    
// 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'] ;
*/
}

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 <emailform to="User" email="user@foo.com" />.

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 erweiterungs_name im Verzeichnis der Erweiterungen erstellt wird, dass drei Dateien enthält:

• eine kleine Setup-Datei, erweiterungs_name.setup.php
• eine Internationalisierungs-Datei, erweiterungs_name.i18n.php
• eine extension_name.body.php Datei mit dem größten Teil des Codes.

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

$wgAutoloadClasses[erweiterungs_name] = dirname(__FILE__) . '/erweiterungs_name.body.php';

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

FAQ

Sicherheitsbedenken

Sie werden oben feststellen, dass die Eingabe in den obigen Beispielen mit Verwendung von htmlspecialchars() entgangen ist, bevor sie zurückgegeben wurde. Es ist wichtig, dass alle Benutzereingaben auf diese Weise behandelt werden, bevor es zurück zu den Clients hallt (echoing), um die Einführung von Vektoren für willkürliche HTML-Injektion zu vermeiden, die zu Cross-Site Scripting Schwachstellen führen können.

Timing und Erweiterungen

Wenn Sie den Code für eine Erweiterung ändern, werden alle Seiten, welche die Erweiterung verwenden, theoretisch die Ergebnisse des neuen Codes sofort widerspiegeln. Technisch gesehen bedeutet dies, dass Ihr Code jedes Mal und jederzeit ausgeführt wird, sobald eine Seite welche die Erweiterung enthält, gerendert wird.

In der Praxis ist dies oft nicht der Fall, durch das Seiten-Caching - entweder von der MediaWiki-Software, dem Browser oder von einem zwischengeschalteten Proxy oder einer Firewall.

Um den MediaWiki-Parsercache zu umgehen und zu gewährleisten, das eine neue Version von der Seite generiert wird, klicken Sie darauf, ersetzen Sie "action=edit" wie in der URL in der Adresszeile Ihres Browsers durch "action=purge" angezeigt und überreichen die neue URL. Die Seite und alle Vorlagen die sie referenziert wird regeneriert, alle zwischengespeicherten Daten werden ignoriert. Die Säuberungsmaßnahme ist erforderlich, wenn die Hauptseite selbst nicht verändert wird, aber die Art wie es gemacht werden muss hat sich geändert (die Erweiterung wurde modifiziert, oder nur eine referenzierte Vorlage wurde modifiziert).

Wenn dies nicht ausreicht, damit Sie eine frische Kopie der Seite bekommen, können Sie in der Regel den Zwischencache umgehen, durch hinzufügen von '&rand=somerandomtext' am Ende der oben genannten URL. Stellen Sie sicher, dass 'somerandomtext' jedes Mal anders ist.

Wie deaktiviere ich Caching für Seiten die meine Erweiterung nutzen?

Seit MediaWiki 1.5, wird der Parser als dritter Parameter an eine Erweiterung weitergeleitet. Dieser Parser kann verwendet werden, um den Cache wie diesen unwirksam zu machen:

function wfSampleSomeHookFunction( $text, array $args, Parser $parser, PPFrame $frame ) {
$parser->disableCache();
...
}

Regenerierung der Seite, wenn eine andere Seite bearbeitet wird

Vielleicht wollen Sie das Cachen nicht vollständig deaktivieren, Sie wollen einfach nur die Seite neu generieren, sobald eine andere Seite bearbeitet wird, ähnlich wie, dass Vorlageneinbindungen behandelt werden. Das kann durch Verwendung des Parserobjekts gemacht werden, das auf Ihre Hook-Funktion übergeben wird. Das folgende Verfahren wurde von CoreParserFunctions.php angehoben und scheint für diesen Zweck zu arbeiten.

/** 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->mOutput->addTemplate( $title, $id, $rev ? $rev->getId() : 0 );
}

Wie kann ich Wikitext in meiner Erweiterung machen?

Seit Version 1.16

MediaWiki Version:

≥ 1.16

Parser Hook-Funktionen übergeben eine Referenz zum Parserobjekt und einem Frameobjekt; diese sollten verwendet werden, um Wikitext grammatisch zu analysieren.

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

Parser::recursiveTagParse() gibt es bereits seit Version 1.8. Seine Vorteile umfassen Einfachheit (es benötigt nur ein Argument und gibt einen String zurück) und die Tatsache, dass es Erweiterungs-Tags in $text analysiert (parst, parsen), so können Sie Erweiterungs-Tags verschachteln.

Der zweite Parameter zu recursiveTagParse, $frame, ist ein optionales Argument, eingeführt in MW 1.16 alpha (r55682).

• Wenn $frame vorgesehen ist (durch verwenden des Wertes von $frame passed to your extension), so werden die Vorlagenparameter in $text erweitert. Mit anderen Worten, Inhalt wie z.B. {{{1}}} wird erkannt und in den entsprechenden Wert umgewandelt.
• Wenn $frame nicht vorgesehen ist (z.B., $parser->recursiveTagParse( $text )), oder wenn $frame auf falsch gesetzt ist, dann werden die Vorlagenparameter nicht erweitert; {{{1}}} wird nicht verändert. Obwohl dies unwahrscheinlich ist, das gewünschte Verhalten zu sein, war dies die einzige Option, welche vor MW 1.16 zur Verfügung stand.

Jedoch noch einen Schritt von parsing, das noch für Tags übersprungen wird, auch bei von Verwendung durch recursiveTagParse, ist Parser::preSaveTransform. preSaveTransform ist der erste Schritt der Analyse, der dafür verantwortlich ist, dauerhafte Änderungen mit dem über-zukünftigen gesparten Wikitext vorzunehmen, wie z.B.:

• Konvertieren von Signaturen (~~~, ~~~~, ~~~~~)
• Erweiterung der Link-Label, auch bekannt als der pipe-trick (z.B., ändern [[Help:Contents/de|]] in [[Help:Contents/de|Inhalt(e)]]). Ohne diesen Schritt, werden Kurzschrift-Links wie z.B. [[Help:Contents/de|]] als ungültig betrachtet, und in ihrer Form belassen, wenn Wikitext geparst wird.
• Erweitern von {{subst:}} Vorlagen.

Der ursprüngliche Aufruf zu preSaveTransform überspringt absichtlich solche Konvertierungen innerhalb aller Erweiterungs-Tags. Wenn Sie pre save transform brauchen um es zu tun, sollten Sie sich überlegen, stattdessen eine Parserfunktion zu verwenden. Alle Tag-Erweiterungen können auch als eine Parserfunktion mit {{#tag:tagname|attribute_name=value|input}} aufgerufen werden, die pre save transform angewandt haben.

Version 1.8 bis Version 1.15

MediaWiki Versions:

1.8 – 1.15

Der einzige Unterschied vor 1.16 ist, dass das $frame Argument für Parser::recursiveTagParse() nicht zur Verfügung stand.

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

Für weitere Informationen siehe Bug 2257.

Wie kann ich XML-Style-Parameter in meinem Erweiterungs-Tag genehmigen?

Seit Version 1.5

Seit MediaWiki 1.5, werden XML-Styleparameter (Tag-Attribute) unterstützt. Die Parameter werden als der zweite Parameter an die Hook-Funktion übergeben, als ein assoziatives Array. Die Wert-Strings haben bereits HTML-Entitäten für Sie entschlüsselt, also wenn Sie sie wieder zu HTML emittieren, vergessen Sie nicht htmlspecialchars( $codeToEncode, ENT_QUOTES ) zu verwenden, um das Risiko von HTML-Injektion zu vermeiden.

Wie kann ich die Modifikation der HTML-Ausgabe meiner Erweiterung vermeiden?

Der Rückgabewert einer Tag-Erweiterung gilt als nahezu geparster Text (parsed text), das heißt es ist nicht als reines HTML behandelt, aber immer noch leicht modifiziert. Es gibt zwei wesentliche Dinge, die an der Ausgabe einer Tag-Erweiterung (zusammen mit ein paar anderen Kleinigkeiten) getan werden:

• Ersetzen Streifenmarker. Streifenmarker sind bestimmte Dinge, die wie UNIQe62a6957e0dbf6e-item-53--QINU aussehen, die an verschiedenen Stufen der Verarbeitung Wikitext eingefügen, um als Marker zu handeln um entfernten Inhalt zu einem späteren Zeitpunkt wieder einzufügen. Das ist nicht etwas, worüber sich Erweiterungen gewöhnlich sorgen müssen.
• Parser::doBlockLevels, der *'s in Listen verwandelt, und jede Linie umwandelt, die mit einem Hauptraum in einen <pre> unter anderem anfängt. Dies kann manchmal ein Problem in einigen Erweiterungen sein.

Tag-Erweiterungen unterstützen auch die Rückgabe eines Arrays, anstatt nur einen String (ähnlich wie Parserfunktionen), um zu ändern wie der Rückgabewert interpretiert wird. Der 0. Wert des Arrays muss der html sein. Die "markerType"-Schlüssel kann auf nowiki eingestellt werden, um eine weitere Analyse (further parsing) zu stoppen. Etwas tun wie return array( $html, "markerType" => 'nowiki' ); würde sicherstellen, dass der $ html-Wert nicht weiter modifiziert und behandelt wird, als einfach nur html.

Wie bekomme ich meine Erweiterung dazu, sie auf Spezial:Version anzuzeigen?

Um Ihre Erweiterung auf der MediaWiki Spezial:Version-Seite anzuzeigen, müssen Sie Erweiterungs-Credits innerhalb des PHP-Codes zuweisen.

Um dies zu tun, fügen Sie eine $wgExtensionCredits Variable als die erste ausführbare Codezeile vor der Hookline oder Funktionsdefinition ein.

Ein Beispiel für Erweiterungs-Credits ist:

<?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' => 'myextensionmessage',
'description'    => 'This extension is an example and performs no discernible function'
);
 
// Here is where we set up our extension
function wfExample(){
..
 
}

Ersetzen Sie validextensionclass mit einer der folgenden Klasse (es sei denn, Ihre Erweiterung fällt unter mehrere Klassen—dann erstellen Sie ein Credit für jede Klasse):

• 'specialpage' — reserviert für Ergänzungen zu MediaWiki-Spezialseiten;
• 'parserhook' — wird verwendet, wenn Ihre Erweiterung verändert, ergänzt oder die Parserfunktionen in MediaWiki ersetzt;
• 'variable' — Erweiterung, die mehrere Funktionen auf MediaWiki hinzufügt;
• 'media' — verwendet, wenn Ihre Erweiterung ein Medienhandler jeglicher Art ist;
• 'other' — alle anderen Erweiterungen.

Die myextensionmsg ist der Name einer interface/i18n Nachricht, die Ihre Erweiterung beschreibt, die in Ihrer Erweiterung i18n.php-Datei definiert werden müssen.

Siehe auch

• Magische Wörter - List von Verhaltensschalter/Variablen wie {{PAGENAME}}, {{SERVER}}, ...
• Erweiterungen
• Extensions FAQ (engl.)
• Category:Extensions/de
• Extension Matrix (engl.)
• Manual:$wgExtensionFunctions (engl.)
• Project:Extension requests (engl.)