Handboek:Parserfuncties

Een parserfunctie, toegevoegd in MediaWiki 1.7, is een soort extensie die nauw integreert met de parser. De uitdrukking "parserfunctie" moet niet worden verward met Extension:ParserFunctions , wat een verzameling eenvoudige parserfuncties is. (Zie voor die Help extension ParserFunctions .)

Beschrijving

Terwijl van een tag extensie wordt verwacht dat die onbewerkte tekst neemt en HTML terugstuurt naar de browser, kan een parserfunctie 'samenwerken' met andere wiki-elementen op de pagina. De uitvoer van een parserfunctie kan bijvoorbeeld worden gebruikt als een sjabloon-parameter of bij de constructie van een link.

De typische syntaxis voor een parserfunctie is:

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

Zie de documentatie voor meer informatie voor Parser::setFunctionHook ( $id, $callback, $flags = 0 ). In deze documentatie staat:

De functie callback moet de vorm hebben:

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

Of met SFH_OBJECT_ARGS:

function myParserFunction( $parser, $frame, $args ) { ... }

De eerste variant van de aanroep geeft alle argumenten door als gewone tekst. De tweede geeft alle argumenten door als een array van PPNode s, behalve de eerste ($args[0]), die nu tekst is, hoewel dit in de toekomst kan veranderen. Deze vertegenwoordigen de niet uitgebreide wikitext. De parameter $frame kan worden gebruikt om deze argumenten naar behoefte te vergroten. Dit wordt vaak gebruikt voor voorwaardelijke verwerking zodat alleen het geval true wordt geëvalueerd met een if- of switch-like parserfunctie. Het frame-object kan ook de documentboom doornemen om informatie over de caller te krijgen en heeft functies om de call depth, time-to-live, en of het resultaat van de parserfunctie vluchtig is te bepalen en te beheren.

Het maken van een parserfunctie is iets ingewikkelder dan het maken van een nieuwe tag, omdat de functienaam een magisch woord moet zijn, een trefwoord dat aliassen en lokalisatie ondersteunt.

Eenvoudig voorbeeld

Hieronder is een voorbeeld van een extensie die een parserfunctie creëert.

De registratie gaat respectievelijk in extension.json en de code in src/ExampleExtensionHooks.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 {
   // Registreer alle callbacks met de parser
   public static function onParserFirstCallInit( Parser $parser ) {

      // Maak een functie hook die het magische woord <code>example</code> associeert met renderExample()
      $parser->setFunctionHook( 'example', [ self::class, 'renderExample' ] );
   }

   // De uitvoer van {{#example:}} opbouwen.
   public static function renderExample( Parser $parser, $param1 = '', $param2 = '', $param3 = '' ) {

      // De invoerparameters zijn wikitext met uitgebreide sjablonen.
      // De uitvoer moet ook wikitext zijn.
      $output = "param1 is $param1 and param2 is $param2 and param3 is $param3";

      return $output;
   }
}

Een ander bestand, ExampleExtension.i18n.php, in uw map extension (Niet in de submap src/) moet bevatten:

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

$magicWords = [];

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

Met deze extension ingeschakeld,

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

resultaat:

• param1 is hello en param2 is hi en param3 is hey

Dit array magicWords is niet optioneel. Als het wordt weggelaten, zal de parserfunctie gewoon niet werken; Het {{#example: hello | hi}} wordt weergegeven alsof de extensie niet is geïnstalleerd. Als alleen het taalspecifieke array wordt geïnitialiseerd en niet het array magicWords zelf, kan dit lokalisatiefouten veroorzaken omdat vertalingen van andere extensies in de uwe lekken. U kunt magische woorden inline in PHP associëren, liever dan via een i18n bestand. Dit is handig bij het definiëren van hooks in LocalSettings.php

MediaWiki\MediaWikiServices::getInstance()->getContentLanguage()->mMagicExtensions['wikicodeToHtml'] = ['MAG_CUSTOM', 'custom'];

Binnen LocalSettings.php

Magische woorden en hun parserfuncties voor afhandeling kunnen volledig worden gedefinieerd in LocalSettings.php.

$wgHooks['ParserFirstCallInit'][] = function ( Parser $parser ) 
{
	MediaWiki\MediaWikiServices::getInstance()->getContentLanguage()->mMagicExtensions['wikicodeToHtml'] = ['wikicodeToHtml', 'wikicodeToHtml'];

	$parser->setFunctionHook( 'wikicodeToHtml', 'wikicodeToHtml' );
};
 
function wikicodeToHtml( Parser $parser, $code = '' ) 
{
	$title = $parser->getTitle();
	$options = $parser->Options();
	$options->enableLimitReport(false);
	$parser = $parser->getFreshParser();
	return [$parser->parse($code, $title, $options)->getText(), 'isHTML' => true];
}

Langere functies

Voor langere functies, kunt u de hook functies opdelen naar een _body.php of .hooks.php bestand en ze statische functies van een class maken. Dan kunt u de class laden met $wgAutoloadClasses en de statische functies in de hooks aanroepen; bijvoorbeeld:

Zet dit in uw extension.json bestand:

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

• Zie: een event-handler schrijven voor andere stijlen.

Zet dan dit in uw src/ExampleExtensionHooks.php bestand:

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

Parser interface

Het parsen van de uitvoer controleren

Om de wikitext die door uw parserfunctie wordt teruggestuurd volledig te laten analyseren (inclusief extensie van sjablonen), stel de optie noparse op false bij het retourneren:

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

Het lijkt erop dat de standaardwaarde voor noparse veranderde van false naar true, in sommige situaties, ergens rond versie 1.12.

Omgekeerd, om uw parserfunctie HTML terug te laten geven die niet is verwerkt, in plaats van wikitext, gebruik dit:

return [ $output, 'noparse' => true, 'isHTML' => true ];

Naamgeving

Standaard voegt MediaWiki een hash-teken (nummerteken, #) toe aan de naam van elke parserfunctie. Als u die toevoeging wilt onderdrukken (en een parserfunctie zonder voorvoegsel # wilt verkrijgen), neemt u de constante SFH_NO_HASH op in het argument flags voor setFunctionHook, zoals hieronder beschreven.

Bij het kiezen van een naam zonder een hashprefix, is het niet langer mogelijk om een pagina met een naam die begint met die functienaam gevolgd door een dubbele punt te transcluderen. Vermijd met name functienamen die gelijk zijn aan een namespace. In het geval dat interwiki transclusion [1] is ingeschakeld, vermijdt u ook functienamen die gelijk zijn aan een interwiki prefix.

De hook setFunctionHook

Voor meer informatie over de interface in de parser, zie de documentatie over setFunctionHook in includes/Parser.php. Hier is een (mogelijk gedateerde) kopie van die opmerkingen:

functie setFunctionHook( $id, $callback, $flags = 0 )

Parameters:

• string $id - Het magische woord ID
• mixed $callback - De te gebruiken functie met object (na de aanroep, callback)
• integer $flags - Optioneel. Waarden:

• SFH_NO_HASH (1) constante, als de functie wordt aangeroepen zonder de #.
• SFH_OBJECT_ARGS (2) als u een PPFrame-object en array van argumenten doorgeeft in plaats van een reeks functieargumenten, zie daarvoor hierboven.
• De standaard is 0 (geen flags).

Returnwaarde: De eventuele oude callback functie voor deze naam

Een functie maken, bijvoorbeeld {{#sum:1|2|3}}. De callback-functie moet de volgende vorm hebben:

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

Het resultaat kan het tekstresultaat van de functie zijn of een matrix met de tekst in element 0 en een aantal flags in de andere elementen. De namen van de flags staan in de keys. Geldige flags zijn:

Naam	Type	Standaard	Beschrijving
found	Boolean	true	true als de teruggegeven tekst geldig is en het verwerken van het sjabloon moet worden gestopt.
text	?	?	De tekst om terug te geven door de functie. Als isChildObj of isLocalObj worden gespecificeerd, moet dit in plaats daarvan een DOM-node zijn.
noparse	Boolean	true	true als tekst niet vooraf moet worden verwerkt naar een DOM-tree, bijvoorbeeld als onveilige HTML-tags niet moeten worden verwijderd, enz.
isHTML	Boolean	?	true als de teruggegeven tekst HTML is en moet worden beschermd tegen wikitext-transformatie. Maar bekijk de discussie
nowiki	Boolean	meestal false	true als de wiki-opmaak in de returnwaarde (tekst) moet worden beschermd (escaped).
isChildObj	Boolean	?	true als de tekst een DOM-node is die uitbreiding nodig heeft in een subframe.
isLocalObj	Boolean	?	true als de tekst een DOM-node is die uitbreiding nodig heeft in het huidige frame. De standaardwaarde is afhankelijk van andere waarden en resultaten.
preprocessFlags	?	false	Optionele flags PPFrame om te gebruiken bij het analyseren van de ontvangen tekst. Dit geldt alleen als noparse false is.
title	?	false	Het object Title waar de tekst vandaan kwam.
forceRawInterwiki	Boolean	?	true als de transclusion tussen wiki's in de raw-modus moet worden uitgevoerd en er geen opbouw nodig is.

Dure parserfuncties

Sommige parserfuncties zorgen voor een significant gebruik van de middelen van een wiki en moeten als "duur" worden gezien. Het aantal dure parserfuncties op een bepaalde pagina wordt beperkt door de instelling $wgExpensiveParserFunctionLimit . Wat als duur telt, wordt overgelaten aan de functie zelf, maar meestal moet alles worden overwogen dat waarschijnlijk een vertraging veroorzaakt die verder gaat dan een eenvoudige verwerking van gegevens. Dit omvat zaken als een database lezen / schrijven, een shellscript synchroon lanceren of bestandsmanipulatie. Aan de andere kant moeten niet al zulke functies noodzakelijkerwijs worden getagged. Semantische MediaWiki, bijvoorbeeld, geeft slechts een percentage van de database leesopdrachten als duur aan. Dit komt doordat op bepaalde data-intensive pagina's het gemakkelijk de normale limiet voor dure parserfuncties overschrijdt. In gevallen als deze is het potentieel voor een merkbaar langzamere prestaties die niet als duur worden gemarkeerd, een compromis met het hebben van de functionaliteit die Semantische MediaWiki biedt.

Om uw parserfunctie te markeren als duur, vanuit de code van de functie, gebruik $result = $parser->incrementExpensiveFunctionCount();. De returnwaarde zal false zijn als de limiet voor dure functies is bereikt of is overschreden.

Parameters met een naam

Parserfuncties ondersteunen benoemde parameters niet zoals sjablonen en tag-extensies dat doen, maar het is af en toe handig om ze te vervalsen. Gebruikers zijn vaak gewend om verticale balken ( | ) te gebruiken om argumenten van elkaar te scheiden, dus het is fijn om dat ook te kunnen doen in de context van de parserfunctie. Hier is een eenvoudig voorbeeld van hoe u dit kunt bereiken:

function ExampleExtensionRenderParserFunction( &$parser ) {
	// Stel dat de gebruiker de parserfunctie als volgt heeft aangeroepen:
	// {{#myparserfunction: foo=bar | apple=orange | banana }}

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

	// Nu heeft u een array dat er als volgt uitziet:
	// [foo] => 'bar'
	// [apple] => 'orange'
	// [banana] => true
	// Doorgaan met het schrijven van code...
}

/**
 * Converteert een array met waarden in vorm [0] => "name=value"
 * in een associatief array in vorm [name] => waarde
 * Als er geen = wordt opgegeven, wordt waar als volgt verondersteld: [naam] => true
 *
 * @param array string $options
 * @return array $results
 */
function extractOptions( array $options ) {
	$results = [];
	foreach ( $options as $option ) {
		$pair = array_map( 'trim', explode( '=', $option, 2 ) );
		if ( count( $pair ) === 2 ) {
			$results[ $pair[0] ] = $pair[1];
		}
		if ( count( $pair ) === 1 ) {
			$results[ $pair[0] ] = true;
		}
	}
	return $results;
}

Zie ook

Algemene en gerelateerde gidsen:

• Handleiding: Extensies ontwikkelen , of voor meer algemene informatie over extensies, zie Handleiding:Extensies en Extensions FAQ .
• Manual:Tag extensions
• Handleiding:Magische woorden

Code:

• Handboek:Parser.php
• Manual:Hooks/ParserFirstCallInit
• Parser function hooks - een (onvolledige) lijst van parserfuncties die worden aangeboden door core en extensies
• De Parser Hooks PHP-bibliotheek, die een objectgerichte interface biedt voor declaratieve parser hooks
• Manual:Extension data

Voorbeelden:

• De extensie ParserFunctions is een bekende verzameling van parserfuncties.
• Help extension ParserFunctions

Category:Parser function extensions[[::Category:Parser function extensions| ]]