version=pmwiki-2.2.30 ordered=1 urlencoded=1
agent=Mozilla/5.0 (X11; Linux x86_64; rv:5.0) Gecko/20100101 Firefox/5.0
author=Peter Bowers
charset=UTF-8
csum=add comment re PV form in #6
name=PmWiki.FmtPageName
rev=44
targets=PmWiki.Functions,PmWiki.Variables,PmWiki.Internationalizations,PmWiki.PageVariables,Cookbook.Functions
text=(:Summary: Documentation for the PmWiki internal function [@FmtPageName()@] :)%0a(:Audience: admins (advanced) :)%0aThis page describes an internal function in PmWiki's engine called [=FmtPageName()=]. %0aThe contents are not intended for those with a weak heart%0a;-)%0a%0aAlso see: [[PmWiki.Functions]]%0a%0a!! [[#FmtPageName]] [@FmtPageName@]($fmt, $pagename)%0a%0a[[#FmtPageName-desc]]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 %25newwin%25[[Wikipedia:Variable_%2528programming%2529#Interpolation | interpolation]], notably the page template (.tmpl) file. See [[PmWiki.Variables]] for an (incomplete) list of available variables, [[PmWiki.Internationalizations]] for internationalisation.%0a%0aThe function [@FmtPageName()@] applies internationalization-substitutions%0aand $Variable-substitions to the string $fmt under the assumption that the%0acurrent page is $pagename.%0a%0aThe substitutions go as follows:%0a%0a# Replace any sequences of the form [@$XyzFmt@] with value of any \%0a  corresponding global variable.%0a# Process the string for any [@$[...]@] phrases (internationalized phrase), \%0a  using the currently loaded translation tables.%0a# Replace any instances of [@{$ScriptUrl}@] with [@$ScriptUrl@] \%0a  (to defer processing to the URI processing phase)%0a# Replace any instances of standard [[PmWiki/PageVariables|Page Variables]] \%0a  (beginning with an upper case letter, followed by at least one word character) \%0a  with their values. %25green%25Note that PVs of the form [@{Group.Page$Var}@] are '''not''' replaced.%25%25\%0a  If there are no more $-sequences, then return the formatted string and exit the function%0a# Perform any pattern replacements from the array $FmtP. Typically \%0a  this is used to handle things like $Name and $Group etc that are \%0a  specific to the name of the current page. %25green%25''?? Appears to be used in robots.php to hide actions from robots.''%0a# Replace any remaining instances of Page Variables with their values. \%0a  %25green%25Note that these variables are in the form [@$Var@] rather than the usual PV form of [@{$Var}@].%25%25%0a# If $EnablePathInfo isn't set, convert [@URIs@] to use the syntax \%0a  $ScriptUrl?n=%3cGroup>.%3cName> instead of $ScriptUrl/%3cGroup>/%3cName>. \%0a  In any case, replace $ScriptUrl with its value. \%0a  If there are no more $-sequences, then return the formatted string and exit the function%0a# Replace any $-sequences with global variables (caching as needed) \%0a  of the same name (in reverse alphabetical order, and filtering out any unsafe globals) *%0a# Replace any $-sequences with values out of the array $FmtV.%0a%0aNote that [@FmtPageName@]() is automatically aware of any global%0avariables. However, since modifying global variables may be expensive, the%0aarray $FmtV exists as a way to avoid rebuilding the variable cache for%0avalues that change frequently.%0a%0a!! Security%0a%0aAccording 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().%0a%0a!! Availability of Variables in FmtPageName%0a%0aTo be very specific, here's what Pm wrote regarding different ways of%0adefining a variable that can be used by FmtPageName (when it is formatting a%0astring):%0a%0a* Set a global variable.  FmtPageName() automatically performs \%0a  substitution on all global variables that aren't arrays. \%0a  If the variable is going to change value over repeated calls \%0a  to FmtPageName, it's probably better to use $FmtV as in the next item.%0a%0a* Set a value in the $FmtV array.  $FmtV['$MyVariable']='something'  \%0a  means to replace instances of '$MyVariable' with 'something'. \%0a  Use this for variables that change value frequently over \%0a  multiple calls to FmtPageName.  %0a%0a* Set a pattern/replacement in the $FmtP array.  This is normally \%0a  done for substitutions that have to be dynamic somehow based on \%0a  the pagename being referenced, such as '$Title', '$Group', '$Name', \%0a  '$PageUrl', etc.%0a%0aAlso see: [[Cookbook:Functions#FmtPageName]]%0a%0aFinally, here's something else Pm wrote that is related and explains%0awhy we have this function:%0a%0a-> In order to produce its output, PmWiki has to do a variety of string \%0a   substitutions:%0a%0a## Generating the full name, group, title, or url of a page \%0a    (other than the currently displayed page)%0a## Substituting the values of global variables%0a## Performing internationalization substitutions%0a## Converting $ScriptUrl/$Group/$Name to $ScriptUrl?n=$Group.$Name \%0a   for sites that cannot handle PATH_INFO urls%0a## Other substitutions needed by specific functions%0a   %0a-> PmWiki centralizes all of that substitute-a-dynamic-value-in-a-string \%0a   into the FmtPageName() subroutine.  Because some things are extremely \%0a   dynamic, such as the url or group for an arbitrary page that is not the \%0a   current one, those things cannot be simple global PHP variables.  Or, if \%0a   they do become global variables, they're variables that cannot be \%0a   trusted to hold a value for very long because some other routine (that \%0a   may happen to be formatting a string for a different page) will come \%0a   along and change that global variable for whatever it happens to be doing.%0a%0a->  A limited set of $-substitutions -- basically anything that \%0a    corresponds to a page attribute -- are not PHP variables and \%0a    are only available through the FmtPageName() subroutine.  \%0a    The complete set of these special substitutions is $Group, \%0a    $Name, $FullName, $PageUrl, $Title, $Titlespaced, $Namespaced, \%0a    $Groupspaced, $LastModifiedBy, $LastModifiedHost, and $LastModified.  \%0a    These items cannot just be standard PHP variables because often\%0a    PmWiki needs to obtain the url, name, group, title, etc. of a page \%0a    other than the one currently being viewed by a browser.%0a%0a->  At the moment, $Title, $LastModified, $LastModifiedBy, and \%0a    $LastModifiedHost can only work if the page's attributes have been \%0a    loaded and cached using the `PCache function.   So, to get\%0a    at these values one must typically do:%0a%0a-> [@%0a$page = ReadPage($pagename);%0aPCache($pagename, $page);%0a$ptitle = FmtPageName('$Title', $pagename);%0a$pauthor = FmtPageName('$LastModifiedBy', $pagename);%0a@]%0a
time=1315670897