PmWiki.FmtPageName 6.9 KB

12345678910
  1. version=pmwiki-2.1.5 ordered=1 urlencoded=1
  2. agent=Mozilla/5.0 (Macintosh; U; PPC Mac OS X; en) AppleWebKit/418 (KHTML, like Gecko) Safari/417.9.2
  3. author=Pico
  4. csum=Added audience id
  5. host=66.108.51.56
  6. name=PmWiki.FmtPageName
  7. rev=11
  8. targets=PmWiki.Functions,PmWiki.Variables,PmWiki.Internationalizations
  9. 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@]
  10. time=1146912078