Handbuch:Parser functions

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page Manual:Parser functions and the translation is 92% complete.

Outdated translations are marked like this.
Other languages:
Bahasa Indonesia • ‎Deutsch • ‎English • ‎Tiếng Việt • ‎dansk • ‎español • ‎français • ‎polski • ‎português do Brasil • ‎русский • ‎ไทย • ‎中文 • ‎日本語 • ‎한국어
OOjs UI icon puzzle-ltr.svg Erweiterungen: Entwicklung Tag extensions Handbuch:Parser functions Hooks Spezialseiten Handbuch:Skins Handbuch:Magische Wörter API Content models
MediaWiki extensions

Parserfunktionen, die in MediaWiki 1.7 hinzugefügt wurden, sind eine Art Erweiterung, die eng mit dem Parser integrieren. Der Begriff „Parserfunktionen“, sollte nicht mit Erweiterung:ParserFunctions verwechselt werden, das ist eine Sammlung von einfachen Parserfunktionen. (siehe Hilfe:Erweiterung:ParserFunctions )

Beschreibung

Während eine Tag Extension unverarbeiteten Text in HTML-Code verwandelt, kann eine Parser Function mit anderen Wiki-Elementen auf der Seite „interagieren“. Die Ausgabe einer Parser Function kann beispielsweise als Parameter für eine Vorlage oder für die Konstruktion eines Links genutzt werden.

Die typische Syntax für eine Parserfunktion lautet:

{{ #functionname: param1 | param2 | param3 }}

Für weitere Informationen, siehe die Dokumentation für Parser::setFunctionHook ( $id, $callback, $flags = 0 ). Diese Dokumentation führt aus:

Die Callback-Funktion sollte diese Form haben:
function myParserFunction( &$parser, $arg1, $arg2, $arg3 ) { ... }
Oder mit SFH_OBJECT_ARGS:
function myParserFunction( $parser, $frame, $args ) { ... }"

Die Erstellung einer Parserfunktion ist etwas komplizierter als die Schaffung eines neuen Tag, weil der Name der Funktion ein magisches Wort sein muss — ein Schlüsselwort, das Aliase und Lokalisierung unterstützt.

Einfaches Beispiel

Hier ist ein Beispiel einer Erweiterung zur Erstellung einer Parser Function.

Die Registrierung steht in extension.json, der Code in ExampleExtension.class.php:

{
	"name": "ExampleExtension",
	"author": "Me",
	"version": "1.0.0",
	"url": "https://www.mediawiki.org/wiki/Extension:ExampleExtension",
	"descriptionmsg": "exampleextension-desc",
	"license-name": "GPL-2.0-or-later",
	"type": "parserhook",
	"MessagesDirs": {
		"ExampleExtension": [
			"i18n"
		]
	},
	"AutoloadClasses": {
		"ExampleExtensionHooks": "src/ExampleExtensionHooks.php"
	},
	"ExtensionMessagesFiles": {
		"ExampleExtensionMagic": "ExampleExtension.i18n.php"
	},
	"Hooks": {
		"ParserFirstCallInit": "ExampleExtensionHooks::onParserFirstCallInit"
	},
	"manifest_version": 1
}
<?php
class ExampleExtensionHooks {
   // Register any render callbacks with the parser
   public static function onParserFirstCallInit( Parser $parser ) {

      // Create a function hook associating the "example" magic word with renderExample()
      $parser->setFunctionHook( 'example', [ self::class, 'renderExample' ] );
   }

   // Rendert die Ausgabe von {{#example}}.
   public static function renderExample( Parser $parser, $param1 = '', $param2 = '', $param3 = '' ) {

      // The input parameters are wikitext with templates expanded.
      // Die Ausgabe sollte auch wikitext sein.
      $output = "param1 is $param1 and param2 is $param2 and param3 is $param3";

      return $output;
   }
}

Eine weitere Datei, ExampleExtension.i18n.php, sollte enthalten:

<?php
/**
 * @license GPL-2.0-or-later
 * @author Your Name (YourUserName)
 */

$magicWords = [];

/** English
 * @author Your Name (YourUserName)
 */
$magicWords['en'] = [
   'example' => [ 0, 'example' ],
];

Mit dieser Erweiterung aktiviert,

  • {{#example: hello | hi | hey}}

produziert:

  • param1 is hello and param2 is hi and param3 is hey
Das magicWords-Array ist nicht optional. Wenn es ausgelassen wird, funktioniert die Parser Function nicht. {{#example: hello | hi}} wird dann so gerendert, als ob die Extension nicht installiert wäre.

Umfangreichere Funktionen

Für umfangreichere Funktionen, können Sie die Hook-Funktionen in eine _body.php oder Hooks.php-Datei aufteilen und mit statischen Funktionen einer Klasse arbeiten. Dann können Sie die Klasse mit $wgAutoloadClasses laden und in den Hooks die statischen Funktionen aufrufen, z.B.:

Schreiben Sie dies in die Datei extension.json:

"Hooks": {
	"ParserFirstCallInit": "ExampleExtensionHooks::onParserFirstCallInit"
},
"AutoloadClasses": {
	"ExampleExtensionHooks": "src/ExampleExtensionHooks.php"
}

Und dies in die Datei src/ExampleExtensionHooks.php:

class ExampleExtensionHooks {
      public static function onParserFirstCallInit( Parser $parser ) {
           $parser->setFunctionHook( 'example', [ self::class, 'renderExample' ] );
      }
}


Caching/Zwischenspeicher

Wie bei Tag-Erweiterungen kann $parser->disableCache() verwendet werden, um den Zwischenspeicher (Cache) für dynamische Erweiterungen zu deaktivieren.

Parserschnittstelle

Steuerung des Parsens der Ausgabe

Um den Wikitext Ihrer Parser Function vollständig geparst zurückgeben zu lassen (einschließlich Erweiterung der Vorlagen), setzen Sie die noparse-Option bei der Rückgabe auf false:

return [ $output, 'noparse' => false ];

Wie es scheint, wurde der Standardwert für noparse irgendwann um Version 1.12 von false auf true geändert.

Umgekehrt, damit Ihre Parser Function anstelle von Wikitext HTML zurückgibt, das ungeparst bleibt, benutzen Sie dies:

return [ $output, 'noparse' => true, 'isHTML' => true ];
This is {{#example:hello | hi | hey }} a test.

produziert allerdings so etwas wie das:

This is

param1 is hello and param2 is hi and param3 is hey a test.

Dies geschieht aufgrund eines fest programmierten "\n\n", das der HTML-Ausgabe von Parserfunktionen vorangestellt wird. Um dies zu vermeiden und sicherzustellen, dass der HTML-Code inline mit dem umgebenden Text gerendert wird, können Sie dies nutzen:

return $parser->insertStripItem( $output, $parser->mStripState );

Benennung

Standardmäßig fügt MW ein Raute-Zeichen („#“) zum Namen der jeweiligen Parserfunktion hinzu. Um dies zu unterdrücken (und eine Parserfunktion ohne „#“-Präfix zu erhalten), verwenden Sie die SFH_NO_HASH-Konstante für das optionale Flags-Argument von setFunctionHook, wie unten beschrieben.

Bei der Wahl eines Namens ohne einen Hash-Präfix, beachten Sie, dass die Vorlageneinbindung einer Seite, deren Name mit dem der Funktion gefolgt von einem Doppelpunkt identisch ist, nicht mehr möglich ist. Vermeiden Sie insbesondere Funktionsnamen gleich einem Namensraum-Namen. Für den Fall, dass Interwiki-Vorlageneinbindung [1] aktiviert ist, vermeiden Sie auch Funktionsnamen die einem Interwiki-Präfix entsprechen.

Der setFunctionHook Hook

Weitere Einzelheiten zur Parser-Schnittstelle finden Sie in der Dokumentation zu setFunctionHook in includes/Parser.php. Hier ist eine (möglicherweise veraltete) Kopie der dortigen Dokumentation:

function setFunctionHook( $id, $callback, $flags = 0 ) Parameter:

  • string $id - Die ID des magischen Worts
  • mixed $callback - Die Callback-Funktion (oder das Objekt), die/das verwendet werden sollte
  • integer $flags - Optional, auf die SFH_NO_HASH-Konstante setzen, um die Funktion ohne „#“ aufrufen zu können.

Rückgabewert: Die alte Callback-Funktion für diesen Namen, wenn überhaupt

Erstelle eine Funktion, z.B. {{#sum:1|2|3}}. Die Callback-Funktion sollte diese Form haben:

function myParserFunction( $parser, $arg1, $arg2, $arg3 ) { ... }

Die Callback-Funktion kann entweder das Textergebnis der Funktion zurückgeben, oder ein Array mit dem Text in Element 0, und eine Anzahl von Flags in den anderen Elementen. Die Namen der Flags werden in den Schlüsseln angegeben. Gültige Flags sind

found 
Der zurückgegebene Text ist gültig, Ausführen der Vorlage anhalten. Dies ist standardmäßig aktiviert.
nowiki 
Wiki-Markup im Rückgabewert sollte maskiert werden
noparse 
Unsichere HTML-Tags sollten nicht entfernt werden, usw.
noargs 
Argumente in Dreifach-Klammer sollen im Rückgabewert nicht ersetzt werden
isHTML 
Der zurückgegebene Text ist HTML, schütze es gegen Wikitext-Transformationen

Benannte Parameter

Parser Function unterstützen benannte Parameter nicht auf die gleiche Weise wie Vorlagen und Tag Extensions, aber es kann manchmal nützlich sein, dieses Verhalten zu simulieren. Benutzer sind oft daran gewöhnt, senkrechte Striche (|) zu verwenden, um Parameter zu trennen, sodass es auch im Kontext von Parser Function sinnvoll sein kann, dies zu ermöglichen. Hier ist ein einfaches Beispiel, wie das erreicht werden kann:

function ExampleExtensionRenderParserFunction( &$parser ) {
	//Suppose the user invoked the parser function like so:
	//{{#myparserfunction: foo=bar | apple=orange | banana }}

	$options = extractOptions( array_slice(func_get_args(), 1) );

	#Continue writing your code...
}

/**
 * Converts an array of values in form [0] => "name=value" into a real
 * associative array in form [name] => value. If no = is provided,
 * true is assumed like this: [name] => true
 *
 * @param array string $options
 * @return array $results
 */
function extractOptions( array $options ) {
	$results = array();

	foreach ( $options as $option ) {
		$pair = explode( '=', $option, 2 );
		if ( count( $pair ) === 2 ) {
			$name = trim( $pair[0] );
			$value = trim( $pair[1] );
			$results[$name] = $value;
		}

		if ( count( $pair ) === 1 ) {
			$name = trim( $pair[0] );
			$results[$name] = true;
		}
	}
	//Now you've got an array that looks like this:
	//  [foo] => "bar"
	//	[apple] => "orange"
	//	[banana] => true

	return $results;
}

Siehe auch