Pulsar Group

(:Summary: PmWiki group header. Includes styles and trail.:)

(:Summary: Documentation for the PmWiki internal function FmtPageName() :) (:Audience: admins (advanced) :) This page describes an internal function in PmWiki's engine called FmtPageName(). The contents are not intended for those with a weak heart ;-)

Also see: PmWiki.Functions

FmtPageName($fmt, $pagename)

Returns $fmt, with $variable and internationalisation substitutions performed, under the assumption that the current page is pagename. As a rule is used to pre-process all variables which by convention have a "Fmt" suffix (like $GroupFooterFmt), but also other strings that require interpolation, notably the page template (.tmpl) file. See PmWiki.Variables for an (incomplete) list of available variables, PmWiki.Internationalizations for internationalisation.

The function FmtPageName() applies internationalization-substitutions and $Variable-substitions to the string $fmt under the assumption that the current page is $pagename.

The substitutions go as follows:

1. Replace any sequences of the form $XyzFmt with value of any corresponding global variable.
2. Process the string for any $[...] phrases (internationalized phrase), using the currently loaded translation tables.
3. Replace any instances of {$ScriptUrl} with $ScriptUrl (to defer processing to the URI processing phase)
4. Replace any instances of standard Page Variables (beginning with an upper case letter, followed by at least one word character) with their values. Note that PVs of the form {Group.Page$Var} are not replaced. If there are no more $-sequences, then return the formatted string and exit the function
5. Perform any pattern replacements from the array $FmtP. Typically this is used to handle things like $Name and $Group etc that are specific to the name of the current page. ?? Appears to be used in robots.php to hide actions from robots.
6. Replace any remaining instances of Page Variables with their values. Note that these variables are in the form $Var rather than the usual PV form of {$Var}.
7. If $EnablePathInfo isn't set, convert URIs to use the syntax $ScriptUrl?n=<Group>.<Name> instead of $ScriptUrl/<Group>/<Name>. In any case, replace $ScriptUrl with its value. If there are no more $-sequences, then return the formatted string and exit the function
8. Replace any $-sequences with global variables (caching as needed) of the same name (in reverse alphabetical order, and filtering out any unsafe globals) *
9. Replace any $-sequences with values out of the array $FmtV.

Note that FmtPageName() is automatically aware of any global variables. However, since modifying global variables may be expensive, the array $FmtV exists as a way to avoid rebuilding the variable cache for values that change frequently.

Security

According to PM, as a general rule it's unwise to be calling FmtPageName() on strings that are coming from page markup, as this exposes the ability for people to view the values of variables that perhaps they shouldn't see. This is also why page variables (which come from markup) use PageVar() and PageTextVar() and don't go through FmtPageName().

Availability of Variables in FmtPageName

To be very specific, here's what Pm wrote regarding different ways of defining a variable that can be used by FmtPageName (when it is formatting a string):

• Set a global variable. FmtPageName() automatically performs substitution on all global variables that aren't arrays. If the variable is going to change value over repeated calls to FmtPageName, it's probably better to use $FmtV as in the next item.
• Set a value in the $FmtV array. $FmtV['$MyVariable']='something' means to replace instances of '$MyVariable' with 'something'. Use this for variables that change value frequently over multiple calls to FmtPageName.
• Set a pattern/replacement in the $FmtP array. This is normally done for substitutions that have to be dynamic somehow based on the pagename being referenced, such as '$Title', '$Group', '$Name', '$PageUrl', etc.

Also see: Cookbook:Functions#FmtPageName

Finally, here's something else Pm wrote that is related and explains why we have this function:

$page = ReadPage($pagename);
PCache($pagename, $page);
$ptitle = FmtPageName('$Title', $pagename);
$pauthor = FmtPageName('$LastModifiedBy', $pagename);

(:Summary:Trail and talk page links:)