Help:Parser function

From Eugene Neighbors

{{#if: Help|

MediaWiki Handbook: Contents, Readers, Editors, Moderators, System admins Template:Edi

{{#if:|Other languages:}} Template:H-langs:

{{#if: Help||}}|

MediaWiki Handbook: Contents, Readers, Editors, Moderators, System admins Template:Edi

{{#if:|Other languages:}} Template:H-langs: {{#if: Help||}}}} A "parser function" is a template-like construct which returns a value based on at least one unnamed parameter, separated from the function name by a colon ":"; there may be more parameters which, like those of ordinary templates, are each preceded by "|". The syntax can be without or with leading hash character (#):

for:

Core parser functions (standardly built into MediaWiki); this is for backwards compatibility; the function "language" is an exception; it is a core parser function, but in MessagesEn.php is specified that the wikitext name is "#language" anyway.
Optionally for parser function extensions.

By default for parser function extensions, e.g. ParserFunctions extension, to prevent collision with namespaces and interwiki prefixes.

The distinction with variables is that the latter do not have any arguments, and also no colon.

For each language there is a file like MessagesEn.php specifying for each variable and parser function whether the name is case-sensitive.

Usually variables are case-sensitive and parser functions are not. To some variables ":R" can be added ("raw" modifier), but, although now a parser function, the name is still case-insensitive. Also the names DISPLAYTITLE, PAGESINNS, and DEFAULTSORT are case-sensitive.

MediaWiki's core parser functions are listed below and in Help:Magic words .

[edit] Formatting

[edit] LC

Makes a text lowercase.

{{lc:AbCdEf}} gives abcdef.
{{lc:Ä Β Ç}} gives ä β ç, expected ä β ç.

[edit] UC

Makes a text uppercase.

{{uc:AbCdEf}} gives ABCDEF.
{{uc:ä β ß}} gives Ä Β ß, expected: Ä Β SS. Don't expect too much.

[edit] LCFIRST

Makes the first character lowercase: {{lcfirst:Ab Cd}} gives ab Cd.

[edit] UCFIRST

Makes the first character uppercase: {{ucfirst:aB cD}} gives AB cD.

[edit] URLENCODE

Converts the text into URL friendly format by replacing spaces with "+" and other url formatting characters with their escaped equivalents: {{urlencode:hello world ?&=#/:}} gives hello+world+%3F%26%3D%23%2F%3A.

[edit] NS

Gives the namespace name for a given namespace number or name:

Code with Number	Code with Name	Returns with Number	Returns with Name
`{{ns:-2}}`	`{{ns:media}}`	Media	Media
`{{ns:-1}}`	`{{ns:special}}`	Special	Special
`{{ns:0}}`	(not applicable)		(not applicable)
`{{ns:1}}`	`{{ns:talk}}`	Talk	Talk
`{{ns:2}}`	`{{ns:user}}`	User	User
`{{ns:3}}`	`{{ns:user_talk}}`	User_talk	User_talk
`{{ns:4}}`	`{{ns:project}}`	Eugene_Neighbors	Eugene_Neighbors
`{{ns:5}}`	`{{ns:project_talk}}`	Eugene_Neighbors_talk	Eugene_Neighbors_talk
`{{ns:6}}`	`{{ns:image}}`	Image	Image
`{{ns:7}}`	`{{ns:image_talk}}`	Image_talk	Image_talk
`{{ns:8}}`	`{{ns:mediawiki}}`	MediaWiki	MediaWiki
`{{ns:9}}`	`{{ns:mediawiki_talk}}`	MediaWiki_talk	MediaWiki_talk
`{{ns:10}}`	`{{ns:template}}`	Template	Template
`{{ns:11}}`	`{{ns:template_talk}}`	Template_talk	Template_talk
`{{ns:12}}`	`{{ns:help}}`	Help	Help
`{{ns:13}}`	`{{ns:help_talk}}`	Help_talk	Help_talk
`{{ns:14}}`	`{{ns:category}}`	Category	Category
`{{ns:15}}`	`{{ns:category_talk}}`	Category_talk	Category_talk
Namespaces 100 and higher are customized by each site
`{{ns:100}}`	`{{ns:hilfe}}`		Template:Ns:Hilfe
`{{ns:101}}`	`{{ns:hilfe_diskussion}}`		Template:Ns:Hilfe Diskussion

<code>{{ns:{{ns:12}}_talk}} gives Help_talk.

However {{ns:{{SITENAME}}}} for {{SITENAME}}=Eugene Neighbors doesn't work, on Meta it has the same effect as {{Meta}}<code>, calling an existing Template:Meta.

Similarly <code>{{ns:{{ns:8}} talk}} fails without underscore: MediaWiki_talk. See Help:Variable for more canonical names like "project" and "talk".

[edit] NS:1

{{ns:{{ns:0}}_talk}} fails: Talk. The canonical name for the talk namespace of articles is "talk" and not "_talk". But the following constructs work:

{{ns:01}} gives Talk, {{ns:+1}} gives Talk, {{ns:TALK}} gives Talk, and {{ns:{{ns:1}}}} gives also Talk. Space sensitive, but not case sensitive.

[edit] NS:0

'''#{{ns:0}}#''' gives ##, an empty string. This is often handy, less vulnerable than a template void or similar, and less cryptic than magic words like __END__.

In constructs like {{ {{#if: {{{T|}}} | {{{T}}} | ns:0}} }}, where parameter T is normally the name of a template to be evaluated, but can be undefined or empty, {{ns:0}} is then a clean empty string. Without it {{}} would result in {{}}.

Please note that {{ns:{{ns:0}}}} fails: Template:Ns:. NS cannot handle an empty {{ns:0}} argument.

[edit]

An empty section title like above is obtained using, in this case, ==== {{ns:0}} ====. This is dubious, but arguably better than using the same trick to get invisble section headers twice on a page. At least /* {{ns:0}} */ makes sense in the edit history, if there's only one section using this particular trick.

As shown in the table of contents this and similar tricks result in non-functional links. In conjunction with __NOTOC__ it's less harmful, and maybe useful to get edit links for invisible sections with categories and interlanguage links. Other possibilities for different invisible section headers:

=== __NOTOC__ ===
=== ===
===   ===
===   ===

[edit] URLs etc.

`{{localurl:fullpagename}}`	/wiki/Fullpagename
`{{localurl:page\|query=x}}`	/w/index.php?title=Page&query=x
`{{localurl:a&b! c}} {{localurle:a&b! c}}`	/wiki/A%26b%21_c /wiki/A%26b%21_c
`{{urlencode:a&b! c}}`	a%26b%21+c
<code>{{fullurl:fullpagename}}	http://wiki.eugeneneighbors.org/wiki/Fullpagename
`{{fullurl:ab}}`	http://wiki.eugeneneighbors.org/wiki/Ab
`{{fullurl:a b}}`	http://wiki.eugeneneighbors.org/wiki/A_b
`{{fullurl:ab\|u=v}}`	http://wiki.eugeneneighbors.org/w/index.php?title=Ab&u=v
`{{fullurl:m:a b\|u=v}}`	http://wiki.eugeneneighbors.org/w/index.php?title=M:a_b&u=v
`{{fullurl:m:ab\|u=v}}`	http://wiki.eugeneneighbors.org/w/index.php?title=M:ab&u=v
`{{fullurl:a b\|u=v}}`	http://wiki.eugeneneighbors.org/w/index.php?title=A_b&u=v
`{{fullurl:a&b!\|u=v}}` http://wiki.eugeneneighbors.org/w/index.php?title=A%26b%21&u=v `{{fullurle:a&b!\|u=v}}` http://wiki.eugeneneighbors.org/w/index.php?title=A%26b%21&u=v

Note that with the interwiki prefix the format "wiki/" is used even for edit pages etc., while it does not write the page name in canonical form.

For interwiki links localurl and fullurl give the same:

{{localurl:w:a}} {{fullurl:w:a}} /wiki/W:a
http://wiki.eugeneneighbors.org/wiki/W:a

The parser function localurl:<tt> replaces spaces by underscores and special characters by escape codes, e.g. {{localurl:a !}} gives /wiki/A_%21. The main purpose was to create a link to a given page in external link style in the same project or a project which uses the same string in the URL between the server name and the page name. This function is now better served by less verbose <tt>fullurl: constructs, {{fullurl:page}} is a shorthand for {{SERVER}}{{localurl:page}}.

Both fullurle: and localurle: performed additional character escaping on the resulting link, but no example is known where that still has any additional effect.

Note that fullurl: and localurl: don't encode special characters and spaces in the optional query-string parameter. At least for spaces this will result in broken URLs:
{{fullurl:m:Special:Contributions|target=Jimbo Wales&limit=10}}
http://wiki.eugeneneighbors.org/w/index.php?title=M:Special:Contributions&target=Jimbo Wales&limit=10

With target={{urlencode:Jimbo Wales}}&limit=10 as query-string it works:
http://wiki.eugeneneighbors.org/w/index.php?title=M:Special:Contributions&target=Jimbo+Wales&limit=10

The new urlencode: encodes spaces as "+", not "_" or the generally supported "%20", this might have interesting effects, take care. Trailing spaces are stripped, leading spaces respected: {{urlencode: @ ! }} yields %40+%21.

For obvious reasons encoding "}}" or "|" cannot work directly. Don't encode "=", "&", or ";" in structured query-strings unless you really want it.

[edit] Example

Say you want to create a link in a template to the block log for blocked usernames -> "{{fullurl:Special:Log/block|user=User:{{{1}}} }}". This won't work with spaces in the name like "Example blocked user" (unless they are manually underlined) as you'd get: "http://wiki.eugeneneighbors.org/w/index.php?title=Special:Log/block&user=User:Example blocked user", so what you can do is escape it with: "{{fullurl:Special:Log/block|user=User:{{urlencode:{{{1}}}}} }}", giving you "http://wiki.eugeneneighbors.org/w/index.php?title=Special:Log/block&user=User:Example+blocked+user"

Also, the magic words for page name like {{PAGENAME}} {{FULLPAGENAME}} etc all have 'escaped' versions: {{PAGENAMEE}} {{FULLPAGENAMEE}} etc.

[edit] #language:

{{#language: code}} gives the local language name of selected RFC 3066 language codes, otherwise it returns the input value as is. For a complete list see the IANA registry.

{{ #language:da}} {{#ifeq: +|-|{{{2}}}|gives}} Dansk

{{ #language:fo}} {{#ifeq: +|-|{{{2}}}|gives}} Føroyskt

{{ #language:zh}} {{#ifeq: +|-|{{{2}}}|gives}} 中文

{{ #language:zh-min-nan}} {{#ifeq: +|-|{{{2}}}|gives}} Bân-lâm-gú

{{ #language:ang}} {{#ifeq: +|-|{{{2}}}|gives}} Anglo Saxon

{{ #language:tlh}} {{#ifeq: +|-|{{{2}}}|gives}} tlh (missing, incomplete list)

{{ #language:frr}} {{#ifeq: +|-|{{{2}}}|gives}} frr (missing, introduced 2006)

{{ #language:mw}} {{#ifeq: +|-|{{{2}}}|gives}} mw (no language code as of 2006)

This function will replace Template:Links-core and some of the Special:Prefixindex/Template:Lang name - templates. For actually supported alpha2 and alpha3 codes see Template:Links-core, the 27*26*26 template calls may take some time.

[edit] Use of result

The result, like that of a variable or template, and like a template parameter value, can be used in the following ways:

*the name of a template: {{ {{lc:ABC}}}}
*the name of a variable: {{ {{uc:currenttime}}}}
*the name of a parser function: {{ {{uc:lc}}:ABC}}
*the name of a template parameter: {{t2|{{#expr:3-1}}=a}}
*the value of a template parameter: {{t2|{{#expr:3-1}}}}
*a template parameter default value: {{{1|{{#expr:7-2}}}}}
*a template parameter definition ( ''name'' = ''value'' ): {{pab|{{lc:AB=CD}}}}
*the name of a switch parameter: {{#switch:2|{{#expr:3-1}}=a}}
*the value of a parser function parameter: {{#ifeq:{{lc:AbC}}|abc|yes}}
*a switch parameter definition ( ''name'' = ''value'' ): {{#switch:ab|{{lc:AB=CD}}}}
*the target or label of an internal link: [[{{lc:ABc}}|{{uc:ABc}}]]
*the target or label of an external link: [http://{{lc:ABc}} {{uc:ABc}}]

gives:

the name of a template: Template:Abc
the name of a variable: 20:37
the name of a parser function: abc
the name of a template parameter: parameter 1 is ( {{{1}}} ) , parameter 2 is ( {{{2}}} )
the value of a template parameter: parameter 1 is ( {{#expr:3-1}} ) , parameter 2 is ( {{{2}}} )
a template parameter default value: {{#expr:7-2}}
a template parameter definition ( name = value ): Template:Pab
the name of a switch parameter: {{#switch:2|{{#expr:3-1}}=a}}
the value of a parser function parameter: {{#ifeq:abc|abc|yes}}
a switch parameter definition ( name = value ): {{#switch:ab|ab=cd}}
the target or label of an internal link: ABC
the target or label of an external link: ABC

The result cannot be used inside XML-style extension tags:

<math>{{#expr:3-1}} \over 3 </math>

[edit] Interpretation of a parser function as a template

In some cases a "wrong" parser function call is interpreted as a template call, which results in an entry in the templatelinks table, giving an entry in the list of pages included in a page (on the edit box of the source page) and What links here of the target page.

This applies e.g. for localurl and fullurl if the parameter is not a valid page name, while "Template:localurl:" and "Template:fullurl:" followed by the parameter is. This is the case if the parameter is a namespace prefix followed by a colon, e.g.:

{{localurl:Template:}} giving Template:Localurl:Template:
{{fullurl:Template:}} giving Template:Fullurl:Template:
{{localurl:Project:}} giving Template:Localurl:Project:
{{fullurl:Project:}} giving Template:Fullurl:Project:

This entry in the templatelinks table occurs even if the result produced is not rendered due to a conditional parser function. This may occur in practice using e.g.:

{{ #if:{{{1|}}}|..{{ fullurl:Template:{{{1|}}} }}..}}
{{ #if:{{{1}}}|..{{ fullurl:Template:{{{1}}} }}..}} in the case that the parameter is equal to the empty string; it does not occur if the parameter is undefined, because "Template:fullurl:Template:{{{1}}}" is not a valid page name.

Thus the list of templates transcluded in a page may be polluted with the entries of the non-existing template Template:fullurl:Template: and similarly for other namespace names instead of the second "Template", and for "localurl" instead of "fullurl". A remedy is e.g.:

{{ #if:{{{1|}}}|..{{ fullurl:Template:{{#if:{{{1}}}|{{{1}}}|[]}} }}..}} because "Template:fullurl:Template:[]" is not a valid page name.

[edit] Substitution

See also: Help:Substitution.

Applying "subst:" to a parser function works:

{{subst:LC:AbC}} gives abc.

Note that unless a technique like optional recursive substitution is used, substituting a template which uses a parser function does not replace that parser function with its result.

[edit] Terminology and history

Core parser functions were originally collectively unnamed in the MediaWiki codebase, although they were informally referred to simply as "functions" by developers. At some time around February 2006, editors of this documentation labelled them "colon functions", an unusual term which was unknown to the developers and the majority of users. In April 2006, the ParserFunctions extension was introduced, along with a new extension interface allowing efficient addition of arbitrary numbers of these entities, now labelled "parser functions". The syntax for the new parser functions was modelled on that of the old core parser functions, the main difference being the addition of the leading hash "#".

In July 2006, the parser function interface was extended to allow old-style hashless functions, and the old core parser functions were converted from using special-case code to the new parser function interface. They were moved to a CoreParserFunctions module. Thus today, there is no difference at all in syntax or functionality between core parser functions and extension parser functions, besides the leading hash convention.

Despite this, some users are in the habit of reserving the term "parser function" for members of the ParserFunctions extension. This is confusing and inaccurate -- any extension may define a parser function. The parser function interface has diverse applications. Perhaps it was confusing to call the extension ParserFunctions in the first place, but it was imagined as a fairly general repository of parser functions useful to Wikimedia.