Manual:Parser functions/da

Udvidelser:

Tag Extensions/da

Parserfunktioner

Hooks/da

Special Pages/da

Udseende

Magiske ord

API/da

Parserfunktioner, som tilføjedes i MediaWiki version 1.7, er en type udvidelse, der er tæt knyttet til syntaks-analysen, også kaldet parseren. Udtrykket "parserfunktion" må ikke forveksles med Extension:ParserFunctions, som er en samling af simple parserfunktioner.

Beskrivelse

Mærkeudvidelser er bygget til at omdanne uforarbejdet tekst til HTML og har meget lidt til fælles med resten af syntaksanalysen. For eksempel kan resultatet fra en mærkeudvidelse ikke anvendes som skabelon-parameter. Desuden er det muligt at bygge skabeloner ind i en mærkeudvidelse, men det skal gøres manuelt og kan være en fejlbehæftet proces, der skifter fra version til version.

Den typiske syntaks for en parserfunktion er:

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

Oprettelse af en parserfunktion er lidt mere kompliceret end at skabe et nyt mærke, fordi funktionens navn skal være et magisk ord/da - et nøgleord, der understøtter aliaser og sprogversioner.

Simpelt eksempel

Nedenfor er et eksempel på en udvidelse, der skaber en parserfunktion.

Denne fil skal kaldes ExampleExtension.php, hvis navnet på din udvidelse er ExampleExtension:

<?php
 
// Take credit for your work.
$wgExtensionCredits['parserhook'][] = array(
 
   // The full path and filename of the file. This allows MediaWiki
   // to display the Subversion revision number on Special:Version.
   'path' => __FILE__,
 
   // The name of the extension, which will appear on Special:Version.
   'name' => 'Example Parser Function',
 
   // A description of the extension, which will appear on Special:Version.
   'description' => 'A simple example parser function extension',
 
   // Alternatively, you can specify a message key for the description.
   'descriptionmsg' => 'exampleextension-desc',
 
   // The version of the extension, which will appear on Special:Version.
   // This can be a number or a string.
   'version' => 1, 
 
   // Your name, which will appear on Special:Version.
   'author' => 'Me',
 
   // The URL to a wiki page/web page with information about the extension,
   // which will appear on Special:Version.
   'url' => 'https://www.mediawiki.org/wiki/Manual:Parser_functions',
 
);
 
// Specify the function that will initialize the parser function.
$wgHooks['ParserFirstCallInit'][] = 'ExampleExtensionSetupParserFunction';
 
// Allow translation of the parser function name
$wgExtensionMessagesFiles['ExampleExtension'] = dirname( __FILE__ ) . '/ExampleExtension.i18n.php';
 
// Tell MediaWiki that the parser function exists.
function ExampleExtensionSetupParserFunction( &$parser ) {
 
   // Create a function hook associating the "example" magic word with the
   // ExampleExtensionRenderParserFunction() function.
   $parser->setFunctionHook( 'example', 'ExampleExtensionRenderParserFunction' );
 
   // Return true so that MediaWiki continues to load extensions.
   return true;
}
 
// Render the output of the parser function.
function ExampleExtensionRenderParserFunction( $parser, $param1 = '', $param2 = '' ) {
 
   // The input parameters are wikitext with templates expanded.
   // The output should be wikitext too.
   $output = "param1 is $param1 and param2 is $param2";
 
   return $output;
}

En anden fil, ExtensionName.i18n.php, bør indeholde:

<?php
/**
 * Internationalization file.
 */
 
$magicWords = array();
 
$magicWords['en'] = array(
   'example' => array( 0, 'example' ),
);

Med denne udvidelse aktiveret producerer

• {{#example: hello | hi}}

resultatet:

• param1 is hello and param2 is hi

Bemærk: Denne magicWords tabel er ikke valgfri. Hvis den udelades, vil parserfunktionen simpelthen ikke virke og {{#example: hello | hi}} vil blive gengivet som om udvidelsen ikke er blevet installeret.

Længere funktioner

For længere funktioner vil du måske adskille krog-funktionerne til en _body.php eller .hooks.php fil og lave dem til en klasses statiske funktioner. Så kan du hente klassen med $wgAutoloadClasses og kalde de statiske funktioner på krogene:

Sæt dette ind i din MyExtension.php fil:

$wgAutoloadClasses['MyExtensionHooks'] = "$dir/MyExtension.hooks.php";
$wgHooks[' ... '][] = 'MyExtensionHooks::MyExtensionFunction';

Så sæt dette i din MyExtension.hooks.php fil:

class MyExtensionHooks {
      public static function MyExtensionFunction( ... ) {
           ...
           $parser->setFunctionHook( 'example',
                'MyExtensionHooks::ExampleExtensionRenderParserFunction' );
           ...
      }
}

Mellemlagring

Ligesom med mærke-udvidelser kan $parser->disableCache() bruges til at afbryde mellemlagringen (cache'en) for dynamiske udvidelser.

Parser brugergrænseflade

Styring af systemanalyse-resultat

For at få wikiteksten, der returneres af din parserfunktion, til være fuldt systemanalyseret (med udvidelse af skabeloner), skal du indstille noparse til false ved returneringen:

return array( $output, 'noparse' => false );

Det ser ud til at standardværdien for noparse er ændret fra false til true, i hvert fald i nogle situationer, omkring version 1.12.

Omvendt, for at få din parserfunktion til at returnere ikke-gennemgået HTML i stedet for wikitekst, brug dette:

return array( $output, 'noparse' => true, 'isHTML' => true );

Imidlertid vil

Dette er {{#example:hallo | hej }} en test.

producere noget lignende dette:

Dette er

param1 is hallo and param2 is hej en test.

Dette sker på grund af den hårde kode "\n\n", der er foranstillet til parserfunktioners HTML resultat. For at undgå dette og sørge for, at HTML-koden er vises mellem til den omgivende tekst, kan du bruge denne:

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

Navngivning

Som standard tilføjer MW en hash karakter (nummertegn, "#") til navnet af hver parserfunktion. For at undertrykke denne tilføjelse (og opnå en parser funktion uden "#" præfiks), indsæt SFH_NO_HASH konstant i den valgfri flag-argument til setFunctionHook, som beskrevet nedenfor.

Når du vælger et navn uden et hash præfiks, vær opmærksom på at indlejring af en side med et navn, der starter med dette funktionsnavn efterfulgt af et kolon, er ikke længere muligt. Undgå især funktionsnavne svarende til et navnerums-navn. I tilfælde af at interwiki indlejring [1] er aktiveret, undgå da også funktionsnavne svarende til et interwiki præfiks.

setFunctionHook krogen

For flere oplysninger om grænsefladen ind i parseren, se dokumentationen for setFunctionHook i includes/Parser.php. Her er en (muligvis dateret) kopi af disse bemærkninger:

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

Parametre:

• string $id - det magiske ord ID
• mixed $callback - tilbagekalds-funktionen (og objektet) at bruge
• integer $flags - valgfri, sættes til SFH_NO_HASH konstanten, for at kalde funktionen uden "#".

Returværdi: navnets gamle tilbagekalds-funktion, hvis der er nogen

Opret en funktion, for eks. {{#sum:1|2|3}}. Tilbagekalds-funktionen bør have formen:

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

Tilbagekaldet kan enten returnere tekstresultatet af funktionen, eller en tabel med teksten i element 0, og et antal flag i de andre elementer. Navnene på flagene er specificeret i nøglerne. Gyldige flag er:

found 

Den returnerede tekst er gyldig, stop behandlingen af skabelonen. Dette er som standard aktiveret.

nowiki 

Wiki-opmærkning i resultatet skal udelades

noparse 

Usikre HTML-mærker bør ikke gennemgås osv.

noargs 

Erstat ikke triple-tuborgklamme argumenter i den returnerede værdi

isHTML 

Den returnerede tekst er HTML og skal værnes mod wikitekst forandring

Navngivne parametre

Parserfunktioner understøtter ikke navngivne parametre på samme måde som skabeloner og mærke-udvidelser, men det er til tider nyttigt at lade som om. Brugerne er ofte vant til at bruge lodrette streger ( | ) til at adskille argumenter, så det er rart også at kunne gøre det i parserfunktionens kontekst. Her er et simpelt eksempel på hvordan det gøres.

Blanding af positionelle parametre med denne navngivne parameter-teknik er fyldt med farer! Dit liv vil blive forbedret betydeligt, hvis du enten holder dig til det ene eller det andet.

Din tilbagekaldsfunktion ser typisk sådan ud:

function ExampleExtensionRenderParserFunction( $parser, $arg1, $arg2, ..., $argn )

For at snyde navngivne parametre, udelad simpelthen alle argumenter efter $parser og par den med func_num_args(). Her er et eksempel:

function ExampleExtensionRenderParserFunction( $parser ) {
	//Suppose the user invoked the parser function like so:
	//{{#myparserfunction:foo=bar|apple=orange}}
 
	$opts = array();
	// Argument 0 is $parser, so begin iterating at 1
	for ( $i = 1; $i < func_num_args(); $i++ ) {
		$opts[] = func_get_arg( $i );
	}
	//The $opts array now looks like this:
	//	[0] => 'foo=bar'
	//	[1] => 'apple=orange'
 
	//Now we need to transform $opts into a more useful form...
	$options = extractOptions( $opts );
 
	#Continue writing your code...
}
 
/**
 * Converts an array of values in form [0] => "name=value" into a real
 * associative array in form [name] => value
 *
 * @param array string $options
 * @return array $results
 */
function extractOptions( array $options ) {
	$results = array();
 
	foreach ( $options as $option ) {
		$pair = explode( '=', $option );
		if ( count( $pair ) == 2 ) {
			$name = trim( $pair[0] );
			$value = trim( $pair[1] );
			$results[$name] = $value;
		}
	}
	//Now you've got an array that looks like this:
	//	[foo] => bar
	//	[apple] => orange
 
	return $results;
}

Se også

• Manual:Hooks/ParserFirstCallInit
• Manual:Extensions/da
• Manual:Tag extensions/da
• Manual:Magic words/da
• Manual:Parser.php/da
• Extensions FAQ/da
• Help:Extension:ParserFunctions/da
• ParserFunctions-udvidelsen er en velkendt samling af parserfunktioner.