==Using MediaWiki Parser Functions==

A survey of some commonly used parser functions and their uses.  The examples on this page refer to templates frequently, so [[Using Templates]] is recommended pre-reading.

===What are parser functions used for?===

Parser functions are a very advanced MediaWiki feature, either included in MediaWiki or implemented by extensions, that are typically used in templates to provide behavior that's more complex than filling in blanks.  Parser functions can be used to do many things, including:

* Include or exclude a piece of content based on a logical condition
* Perform mathematical operations
* Retrieve the current date or time
* Perform URL encoding on a string prior to constructing a link out of it
* Extract a subset of a string
* Replace one string with another
* Create a link conditionally on the existence of the target

Complex templates like [[Template:Project]] make heavy use of parser functions to make "decisions" about what behavior to produce depending on the provided parameter values.

===How do parser functions work?===

The basic syntax for parser functions is similar to that used for templates:

 <nowiki>{{</nowiki>#'''function''':'''param1'''|'''param2...'''}}

Note the '''#''' before the function name, and the ''':''' between the function name and the first parameter.  

Unlike templates, which can be added by any contributor just by creating new pages, new parser functions can only be implemented by MediaWiki extensions that define their behavior, so unless you're ready to start writing your own extension and then get the wiki admin to install it, you're limited to the set of parser functions implemented by the wiki you're using.  The [[Special:Version]] page lists all of the extensions installed on the wiki, with extensions that add parser functions listed under the "parser hooks" heading.  MediaWiki itself comes with a few parser functions as well that are documented in the [http://www.mediawiki.org/wiki/Help:Magic_words#Parser_functions MediaWiki help].

An example of a parser function added by an extension is the '''#expr:''' function, which evaluates mathematical expressions.  The function accepts only a single parameter, which is a string containing any of a wide set of mathematical operators similar to what you might find in a normal programming language or a decent pocket calculator; see the [http://www.mediawiki.org/wiki/Help:Extension:ParserFunctions#.23expr: help page] for a list of supported operators.  For example, adding the following code to a page:

 <nowiki>2 + 3 = {{ #expr: 2 + 3 }}</nowiki>

will produce the following text:

 2 + 3 = {{ #expr: 2 + 3 }}

This same function might be used to create a simple template called '''Template:Sum''' whose source looks like:

 <nowiki>{{{1|0}}} + {{{2|0}}} = {{ #expr: {{{1|0}}} + {{{2|0}}} }}</nowiki>

and invoking this template with any two numeric values:

 <nowiki>{{Sum|6|9}}</nowiki>

would produce a string of text representing their sum:

 6 + 9 = 15

Since there are dozens of parser functions implemented on this wiki, the usage of each one will not be demonstrated here, but the entries on [[Special:Version]] link back to project pages that include documentation and examples of the functions implemented by each extension.

===Example: creating a link conditionally===

The '''#ifexist:''' function is a good example of a conditional statement; that is, a parser function that returns one outcome or another depending on a condition.  This function can be used to create a template which generates a wiki link if and only if the target already exists (that is, it will never create a "red link").  

The source of the template will be:

 <nowiki>{{#ifexist:{{{1|}}}|[[{{{1|}}}]]|{{{1|}}}}}</nowiki>

Since that looks like a string of line noise, here it is with some extra whitespace and with the parameter bolded:

 <nowiki>{{</nowiki> #ifexist: '''<nowiki>{{{</nowiki>1|}}}''' | [['''<nowiki>{{{</nowiki>1|}}}''']] | '''<nowiki>{{{</nowiki>1|}}}''' }}

This expression says that if the page referenced by the parameter <nowiki>{{{1|}}}</nowiki> exists, the output will be "<nowiki>[[{{{1|}}}]]</nowiki>", that is, the parameter with double brackets around it (creating a link to it).  If not, the output will simply be the unaltered parameter, <nowiki>{{{1|}}}</nowiki>.

Supposing we call our template '''Template:SafeLink''', giving the name of a real page as the parameter:

 <nowiki>{{</nowiki>SafeLink|FAQ}}

gets us a link:

 {{#ifexist:FAQ|[[FAQ]]|FAQ}}

whereas passing in a nonexistent page name:

 <nowiki>{{</nowiki>SafeLink|OIWEJFLKJSLDKJF}}

gets us plain text:

 {{#ifexist:OIWEJFLKJSLDKJF|[[OIWEJFLKJSLDKJF]]|OIWEJFLKJSLDKJF}}

This type of expression is used a few times in [[Template:Project]] to generate links to user pages and categories if and only if they already exist.

===Example: DepotBrief===

[[Template:DepotBrief]] is a fairly complex example of manipulating a string using parser functions.  Here is the source for it:

 <nowiki>{{#ifeq: {{#sub:{{{1}}}|-1}} | / | 
  {{ DepotPath|{{{1}}}| {{#sub:{{{1}}}|{{#expr:{{#rpos:{{#sub:{{{1}}}|0|-1}}|/}}+1}}|0}} }} |
  {{#ifeq: {{#sub:{{{1}}}|-4}} | /... |
    {{ DepotPath|{{#sub:{{{1}}}|0|-3}}| {{#sub:{{#sub:{{{1}}}|0|-3}}|{{#expr:{{#rpos:{{#sub:{{#sub:{{{1}}}|0|-3}}|0|-1}}|/}}+1}}|0}} }} |
    {{ DepotFile|{{{1}}}|{{#sub:{{{1}}}|{{#expr:{{#rpos:{{{1}}}|/}}+1}}|0}} }}
  }}
}}</nowiki>

The purpose of this template is to examine its parameter to determine if it's a depot directory path (ending in "/...") or a depot file path, and generate a useful link that uses the last component of the path as the link text.  If it's a directory path, [[Template:DepotPath]] is used to generate a P4Web link to it; if it's a file path, [[Template:DepotFile]] is used to generate a WebKeeper link.  In either case, a sequence of string operations is used to find the last component of the path (by finding the index of the last "/" character and extracting everything after that index), and this is passed as the link text.

It is not recommended that you try to create something like this as your first experiment with templates and parser functions.

===Example: RecentChanges===

[[Template:RecentChanges]] is a simpler example that uses the '''#p4changes:''' function implemented by the Perforce extension, along with a couple of other templates, [[Template:DepotRSS]] and [[Template:DepotNormalized]], to generate a section on a page out of changelists recently submitted to a given depot path:

 <nowiki>===Recent Changes {{DepotRSS|{{{1}}}}} ===
{{#p4changes:5|{{DepotNormalized|{{{1}}}}}|full}}</nowiki>

[[Template:DepotNormalized]] itself uses a few string parser functions and another template, [[Template:TrimWhitespace]], to ensure that the parameter is returned in a "normalized" style with extraneous whitespace removed and trailing "/" characters converted to the Perforce wildcard expression "/...":

 <nowiki>{{#ifeq:{{#sub:{{TrimWhitespace|{{{1}}}}}|-1}}|/|{{TrimWhitespace|{{{1}}}}}...|{{TrimWhitespace|{{{1}}}}}}}</nowiki>

The '''#p4changes:''' function is then passed 5 (the number of changelists to return), the normalized depot path resulting from passing the parameter to [[Template:DepotNormalized]], and "full" (for full change descriptions).  The table returned by this function is placed under a level 3 heading with an RSS feed icon provided by [[Template:DepotRSS]].

For examples of this template in action, go to the [[Template:RecentChanges]] page and click "What links here" from the Toolbox.

{{Advanced Mediawiki usage|Parser Functions}}