version=pmwiki-2.1.5 ordered=1 urlencoded=1
agent=Mozilla/5.0 (Macintosh; U; PPC Mac OS X; en) AppleWebKit/418 (KHTML, like Gecko) Safari/417.9.2
author=Pico
csum=Added audience id
host=66.108.51.56
name=PmWiki.FmtPageName
rev=11
targets=PmWiki.Functions,PmWiki.Variables,PmWiki.Internationalizations
text=%25audience%25 admins (advanced)%0aThis page describes an internal function in PmWiki's engine called%0a[@FmtPageName()@]. The 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@]. 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 goes 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# 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.%0a# If $EnablePathInfo isn't set, convert [@URIs@] to use the syntax \%0a  $ScriptUrl?n=%3cGroup>.%3cName> instead of $ScriptUrl/%3cGroup>/%3cName>.%0a# Replace any $-sequences with global variables (caching as needed) \%0a  of the same name (in reverse alphabetical order) *%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%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$pvar = `FmtPageName('$Title', $pagename);%0a$pvar = `FmtPageName('$`LastModifiedBy', $pagename);%0a@]%0a%0a!! Source code for [@FmtPageName()@]%0a%0aNote: The source code below was taken from "pmwiki-2.0.beta55", while the%0acurrent version is {$Version}.%0a%0a-> [@%0a## FmtPageName handles $[internationalization] and $Variable%0a## substitutions in strings based on the $pagename argument.%0afunction FmtPageName($fmt,$pagename) {%0a  # Perform $-substitutions on $fmt relative to page given by $pagename%0a  global $GroupPattern, $NamePattern, $EnablePathInfo, $ScriptUrl,%0a    $GCount, $UnsafeGlobals, $FmtV, $FmtP, $PCache, $AsSpacedFunction;%0a  if (strpos($fmt,'$')===false) return $fmt;%0a  $fmt = preg_replace('/\\$([A-Z]\\w*Fmt)\\b/e','$GLOBALS[\'$1\']',$fmt);%0a  $fmt = preg_replace('/\\$\\[(?>([^\\]] ))\\]/e',"XL(PSS('$1'))",$fmt);%0a  $match = array('','$Group','$Name');%0a  if (preg_match("/^($GroupPattern)[\\/.]($NamePattern)\$/", $pagename, $m))%0a    $match = $m;%0a  $fmt = preg_replace(array_keys($FmtP),array_values($FmtP),$fmt);%0a  $fmt = preg_replace('!\\$ScriptUrl/([^?#\'"\\s%3c>] )!e',%0a    (@$EnablePathInfo) ? "'$ScriptUrl/'.PUE('$1')" :%0a        "'$ScriptUrl?n='.str_replace('/','.',PUE('$1'))",%0a    $fmt);%0a  if (strpos($fmt,'$')===false) return $fmt;%0a  static $g;%0a  if ($GCount != count($GLOBALS) count($FmtV)) {%0a    $g = array();%0a    foreach($GLOBALS as $n=>$v) {%0a      if (is_array($v) || is_object($v) ||%0a         isset($FmtV["\$$n"]) || in_array($n,$UnsafeGlobals)) continue;%0a      $g["\$$n"] = $v;%0a    }%0a    $GCount = count($GLOBALS) count($FmtV);%0a    krsort($g); reset($g);%0a  }%0a  $fmt = str_replace(array_keys($g),array_values($g),$fmt);%0a  $fmt = str_replace(array_keys($FmtV),array_values($FmtV),$fmt);%0a  return $fmt;%0a}%0a@]
time=1146912078