version=pmwiki-2.2.74 ordered=1 urlencoded=1
author=gb
charset=UTF-8
csum=+PageTextVariables can only have a name containing basic Latin/Roman (ASCII) letters
ctime=1159470179
name=PmWiki.PageTextVariables
rev=146
targets=PmWiki.Name,PmWiki.FullName,Cookbook.InternationalPTVs,PmWiki.PageTextVariables-Talk,PmWiki.TextFormattingRules,PmWiki.PageDirectives,PmWiki.PageVariables,PmWiki.PageListTemplates,PmWiki.IncludeOtherPages,PmWiki.PageLists,Site.PageListTemplates,Site.LocalTemplates,PmWiki.ConditionalMarkup
text=(:Summary:Page variables automatically made available through natural or explicit page markup:)%0a>>comment%3c%3c%0a[[#singleline]]%0a[-[[{=$FullName}|+]],-] \%0a[[#singlelineend]]%0a>>%3c%3c%0a%0a>>rframe font-size:smaller noprint clear=right%3c%3c%0a!!!! Table of contents%0a* [[#defining | Defining page text variables]]%0a* [[#usage | Usage]]%0a** [[#usagesamepage | On the same page]]%0a** [[#usageotherpage | From other pages]]%0a** [[#usageincludedpage | On included pages]]%0a** [[#pagelists | With pagelists]]%0a** [[#templates | In templates]]%0a** [[#conditionals| With conditionals]]%0a** [[#withincode | Within code]]%0a>>%3c%3c%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. In the default installation, PageTextVariables can only have a name containing basic Latin/Roman (ASCII) letters, digits, dash and underscore. 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 [@{$: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 [@{$: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 [@{$:Country}@] variable (variable markup becomes: "{$:Country}") in the page.%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 [@{$: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:  [@{*$: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 [@{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: [@(:Linkme: [[PageToLink]]:) (:if false:){$:Linkme}(:if:)@]%0a%0a[[#set]]%0a!!! Testing if set or not set%0a|| border=0 cellpadding=4 rules=all%0a|| '''=-'''    ||PTV is set (is not empty), eg [@(:pagelist $:Var=- :)@] ||%0a|| '''=-?*'''  ||PTV is not set (is empty), ie not one character followed by 0 or more characters, eg. [@(: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 : [@(: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 [@(:if false:)....(:if:)@] condition.%0a%0a[[#withincode]]%0a!!! Usage - from within code (developers only)%0a%0aThe standard @@PageVar($pagename,$varname)@@ function can return page text variables, but remember to include the dollar and colon like this:%0a%0a->@@$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.
time=1429297452
