1 3281ec97 2023-03-06 jrmu version=pmwiki-2.3.4 ordered=1 urlencoded=1
3 5127fd58 2021-12-17 jrmu charset=UTF-8
4 3281ec97 2023-03-06 jrmu csum=pm hlt, hlt php (+9)
5 5127fd58 2021-12-17 jrmu ctime=1159470179
6 5127fd58 2021-12-17 jrmu name=PmWiki.PageTextVariables
8 3281ec97 2023-03-06 jrmu targets=PmWiki.Name,PmWiki.FullName,Cookbook.InternationalPTVs,PmWiki.PageTextVariables-Talk,PmWiki.TextFormattingRules,PmWiki.PageDirectives,PmWiki.OtherVariables,PmWiki.PageVariables,PmWiki.PageListTemplates,PmWiki.IncludeOtherPages,PmWiki.PageLists,Site.PageListTemplates,Site.LocalTemplates,PmWiki.Functions,PmWiki.ConditionalMarkup
9 3281ec97 2023-03-06 jrmu text=(:Summary:Page variables automatically made available through natural or explicit page markup:)%0a(:if false:)%0a[[#singleline]]%0a[-[[{=$FullName}|+]],-] \%0a[[#singlelineend]]%0a(:ifend:)%0a%0aPage text variables are string variables created in the wiki text of a page, and can be automatically made available for inclusion in other pages.\\%0aIn the default installation, PageTextVariables can only have a name containing basic Latin/Roman (ASCII) letters, digits, dash and underscore (meaning regular PTVs don't have accented characters). This is a limitation for international wikis (experimental recipe for international PTV : Cookbook:InternationalPTVs). %0a%0a[[#defining]]%0a!! Defining Page Text Variables%0a%0aThere are three ways to define automated Page Text Variables ([[PmWiki:PageTextVariables-Talk#new_patterns|more patterns]] can be defined if needed) :%0a%0a* use a [[TextFormattingRules#DefinitionLists | definition list]] - the normal pmwiki markup for a definition list will create a page text variable%0a(:markup caption='Example definition list:' class="horiz":)%0a:Name: Crisses%0a"{$:Name}"%0a(:markupend:)%0a->This creates a new variable that can be accessed by %25pmhlt%25[@{$:Name}@] (becomes: "{$:Name}") in the page.%0a%0a* use a simple colon delimiter in normal text%0a(:markup caption='Example colon delimited:' class="horiz":)%0aAddress: 1313 Mockingbird Lane%0a%0a"{$:Address}"%0a(:markupend:)%0a->This creates the %25pmhlt%25[@{$:Address}@] variable (variable markup becomes: "{$:Address}") in the page.%0a%0a* hidden [[PmWiki/PageDirectives | directive]] form - PmWiki markup that doesn't render on the page, but defines the variable%0a(:markup caption='Example directive:' class="horiz":)%0a(:Country: Transylvania :)%0a"{$:Country}"%0a(:markupend:)%0a->This creates the %25pmhlt%25[@{$:Country}@] variable (variable markup becomes: "{$:Country}") in the page.%0a%0a[[#default]]%0a!! Default values for unset or empty Page Text Variables%0a%0aIf a page text variable is not [[#defining|defined in a page]], or if the current visitor doesn't have read permissions for the page containing the variable definition, then the markup to access the variable like %25pmhlt%25[@{$:Country}@] will return an empty string.%0a%0aAn administrator can define default values for such cases (PmWiki 2.2.121+). The following arrays can be defined in @@local/config.php@@:%0a%0a%25hlt php%25[@ $DefaultUnsetPageTextVars = array(%0a 'SpecificVariable' => 'SpecificVariable is unset',%0a '*PartialMatch*' => 'some value',%0a '*' => '(unset)',%0a );@]%0a %0a%25hlt php%25[@ $DefaultEmptyPageTextVars = array(%0a 'SpecificVariable' => 'SpecificVariable is set, but empty',%0a '*' => '(empty)',%0a );@]%0a%0aIn the above examples, %25pmhlt%25[@{$:SpecificVariable}@] or [@{OtherPage$:SpecificVariable}@] will output the value defined:%0a* in $DefaultUnsetPageTextVars if the variable is not defined in the page text, or if the user doesn't have read permissions for OtherPage%0a* in $DefaultEmptyPageTextVars if the user has read permissions, and the variable is defined but empty, for example %25pmhlt%25[@(:SpecificVariable::)@].%0a%0aThe patterns are processed in order, and the first matching pattern assigns the value to the variable. The asterisk %25pmhlt%25[@*@] matches any string, in the above examples an undefined variable that doesn't match 'SpecificVariable' or '*PartialMatch*' will output '(unset)'.%0a%0a%0a[[#usage]]%0a!! Usage%0a[[#usagesamepage]]%0a!!! Usage on the same page%0a%0aOn the same page you can resolve page text variables through the %25pmhlt%25[@{$:Var}@] format (shown above).%0a%0a[[#specialreferences]]%0a!!! Usage in headers and footers: special references%0a%0aIf you want a GroupHeader, GroupFooter, SideBar, etc to call on page text variable in the main page, you need to include special reference information. %0aTo explicitly reference the page text variable from the page being displayed add an asterisk to the page text variable's markup: %25pmhlt%25[@{*$:Address}@] on the GroupFooter or GroupHeader page. %0a(:markup caption='Example' class=horiz:)%0a{*$:Mountain} \\%0a{*$Namespaced}%0a(:markupend:)%0aTo include a page text variable ''from'' a header or footer see [[#usageotherpage |usage from other pages]] below.%0a-%3c Special references also apply to [[page variables(#specialreferences)]] and [[page list templates(#specialreferences)]].%0a%0a%0a[[#usageotherpage]]%0a!!! Usage from other pages%0a%0aIf you want to pull the data from another page, use the %25pmhlt%25[@{Group/PageName$:Var}@] format.%0a(:markup caption='Example:' class="horiz":)%0aSuburb: Khandallah%0a(:Lake:Taupo:)%0a:Mountain:Mt Ruapehu%0a%0a->"{PmWiki/PageTextVariables$:Suburb}"%0a->"{{$FullName}$:Lake}"%0a->"{PmWiki/PageTextVariables$:Mountain}"%0a(:markupend:)%0a%0a[[#usageincludedpage]]%0a!!! Usage from included pages%0a%0aPage text variables are never [[IncludeOtherPages|included]] from their source page.%0aSee [[#usageotherpage|Usage from other pages]] above to refer to a page text variable on another page.%0a%0a[[#pagelists]]%0a!!! Usage with pagelists%0a%0a[[Page lists]] can also access the page text variables:%0a(:markup caption='Example:' class="horiz":)%0a(:pagelist group=PmWiki order=$:Summary count=6 fmt=#singleline:)%0a(:markupend:)%0a%0aAnd to create pagelist formats (such as those documented at [[Site.Page List Templates]], [[PmWiki/Page Lists]], [[PmWiki/Page List Templates]], [[PmWiki/Page Variables]]. Store custom pagelists at [[Site.Local Templates]]).%0a%0a[[Page lists]] can also use page text variables to select pages :%0a(:markup caption='Example:' class="horiz":)%0a(:pagelist group=PmWiki $:City=Paris count=8 fmt=#singleline order=-name:)%0a(:markupend:)%0a->lists pages having '$:City' set to 'Paris'.%0a%0a(:markup caption='Example: multiple selections with spaces' class="horiz":)%0a(:pagelist group=PmWiki $:City="Addis Ababa,Paris" order=-$:Version count=8 fmt=#singleline:)%0a(:markupend:)%0a->'quotes' must surround ''all'' the selections.%0a%0a* When using page text variables for selection or ordering, don't put the curly braces around the variable name. The curly forms do a replacement before the pagelist command is evaluated. %0a* Link markup within the contents of a hidden page text variable directive (as opposed to other ways of specifying PTVs) will not be cached as a link on the page and thus won't be seen by pagelist's link= option. If you want the link to be found by link=, you need to specify the PTV using non-directive markup, or else put the link on the page even if it's hidden within a false conditional: %25pmhlt%25[@(:Linkme: [[PageToLink]]:) (:if false:){$:Linkme}(:ifend:)@]%0a%0aThe page text variable value is always the text that is written in the page. %0aIt is only evaluated when the variable is printed/output to HTML. %0aTo sort by a page text variable variable, all values in all pages are the not-yet-evaluated text strings, and the pagelist order function does what it can with them. It does not process/evaluate the text at this point.%0a%0aE.g. With a page name in to format "yyyyMonth" it is simpler to use a @@PageVariable@@ calculated in @@config.php@@, not a @@PageTextVariable@@:%0a-> %25hlt php%25[@$FmtPV['$NameToYearMonth'] = 'PSFT("%25Y%25m", strtotime($name))';@]%25%25 # see $FmtPV and [[PmWiki/Functions#PSFT|PSFT]]%0aThen use %25pmhlt%25[@(:pagelist order=$NameToYearMonth:)@]%0a%0aAn alternative is writing in the wiki page:%0a-> %25pmhlt%25[@(:MonthNum:07:)@]%0aas the markup expression that follows won't work:%0a-> %25pmhlt%25[@(:MonthNum:{(ftime fmt=%25m when="{$Namespaced}")}:)@]%0a%0a[[#set]]%0a!!!! Testing if set or not set within a pagelist%0a|| border=0 cellpadding=4 rules=all%0a|| '''=-''' ||PTV is set (is not empty), eg %25pmhlt%25[@(:pagelist $:Var=- :)@] ||%0a|| '''=-?*''' ||PTV is not set (is empty), ie not one character followed by 0 or more characters, eg. %25pmhlt%25[@(:pagelist $:Var=-?* :) @] ||%0a|| '''=*''' ||display ''all'' pages, regardless of the page text variable (slow) ||%0a|| '''=-*''' ||display ''no'' pages, regardless of the page text variable (slow) ||%0a%0a%0a[-Tip : %25pmhlt%25[@(:if ! equal "{$:PTV}" "":)@] will test if PTV is empty/unset or not.-]%0a%0a%0a(:markup caption='Example: Pages without a summary' class="horiz":)%0a(:pagelist group=PmWiki $:Summary=-?* count=6 fmt=#singleline:)%0a(:markupend:)%0a%0a[[#templates]]%0a!!! Use page text variable in a template%0aDisplay pages by Audience page text variable.%0a(:markup caption='Example:' class="horiz":)%0a>>comment%3c%3c%0a[[#byaudience]]%0a(:if ! equal '{=$:Audience}' '{%3c$:Audience}':)%0a-%3c'''{=$:Audience}''': %0a(:ifend:)%0a[[{=$Name}]]%0a[[#byaudienceend]]%0a>>%3c%3c%0a(:pagelist group=PmWiki count=10 fmt=#byaudience order=-$:Audience:)%0a(:markupend:)%0a%0a[[#conditionals]]%0a!!! Use page text variables in [[PmWiki/conditional markup]]%0aPage text variables will be assigned/evaluated '''before''' any conditional markup is evaluated. This effectively means that you cannot declare a PTV within an @@if...else@@ condition; and also that a PTV will have a value even if it is set within a %25pmhlt%25[@(:if false:)....(:ifend:)@] condition.%0a%0a[[#withincode]]%0a!!! Usage - from within code (developers only)%0a%0aThe standard %25hlt php%25[@PageVar($pagename,$varname)@] function can return page text variables, but remember to include the dollar and colon like this:%0a%0a->%25hlt php%25[@$var=PageVar($pagename,'$:City')@]%0a%0aIt works by caching all page (text) variables it finds in a page (in @@$PCache@@) and returns the one requested.
10 3281ec97 2023-03-06 jrmu time=1650967314
