version=pmwiki-2.2.5 ordered=1 urlencoded=1
agent=Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/532.0 (KHTML, like Gecko) Chrome/3.0.195.21 Safari/532.0
author=simon
charset=ISO-8859-1
csum=force formatting
ctime=1159470179
host=203.97.214.12
name=PmWiki.PageTextVariables
rev=130
targets=PmWiki.Name,PmWiki.FullName,PmWiki.TextFormattingRules,PmWiki.PageDirectives,PmWiki.IncludeOtherPages,PmWiki.PageLists,Site.PageListTemplates,PmWiki.PageListTemplates,PmWiki.PageVariables,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** [[#nested | Nested]]%0a** [[#pagelists | With pagelists]]%0a** [[#templates | In templates]]%0a** [[#conditionals| With conditionals]]%0a** [[#usageother | Other usage]]%0a** [[#withincode | Within code]]%0a** [[#usagenotes | Usage notes]]%0a>>%3c%3c%0a%0aPage text variables are string variables automatically made available through [[PmWiki/TextFormattingRules | natural page]] markup or explicitly with [[PmWiki/PageDirectives | page directive]] markup within the wiki text of the page.%0a%0a[[#defining]]%0a!! Defining Page Text Variables%0a%0aThere are three ways to define automated Page Text Variables:%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!!! Usage in headers and footers%0a%0aIf you want a GroupHeader, GroupFooter, SideBar, etc to call on page text variable in the main page, you need to include 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{*$:City}%0a(:markupend:)%0aTo include a page text variable ''from'' a header or footer see [[#usageotherpage |usage from other pages]] below.%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[[#nested]]%0a!!! Nested page text variables%0a%0aPage text variables can be nested%0a(:markup caption='Example:' class="horiz":)%0a: MailingAddress : {$:Address}, {$:City}, {$:Country}%0a"{$:MailingAddress}"%0a(:markupend:)%0a%0aAnother way you may nest PTVs is to make (part of) the variable name a variable in itself:%0a(:markup caption='Example:' class="horiz":)%0ax:Test/Ptvb%0aContents of y on page {$:x}:%0a{{$:x}$:y}%0a(:markupend:)%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' class="horiz":)%0a(:pagelist group=PmWiki $:Audience="*authors (intermediate)*,*administrators (intermediate)*" order=-$:Audience,name count=10 fmt=#singleline:)%0a(:markupend:)%0a->lists pages having a '$:Audience' of 'authors (intermediate)' or 'administrators (intermediate)'.%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%0a(:markup caption='Example: Pages with City variable set' class="horiz":)%0aCity: Addis Ababa%0a(:pagelist group=PmWiki $:City=- count=10 fmt=#singleline:)%0a(:markupend:)%0a->City variable is set.%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%0a[[#set]]%0a!!! Testing if set or not set%0a(:table:)%0a(:cellnr:)'''=-''' %0a(:cell:)PTV is set (is not empty), eg [@(:pagelist $:MyPageTextVariable=- :)@]%0a(:cellnr:)%0a%25pre%25'''=-?*''' %0a(:cell:)PTV is not set (is empty), ie is not set to one char followed by 0 or more  chars, eg%0a-> [@(:pagelist $:MyPageTextVariable=-?* :) @]%0a(:cellnr:)'''=*''' %0a(:cell:)display ''all'' pages, the page text variable is irrelevant%0a(:cellnr:)'''=-*''' %0a(:cell:)display ''no'' pages, the page text variable is irrelevant%0a(:tableend:)%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. That means you can use page text variables with conditional markup, but not conditional markup within page text variables. For instance a PTV will have a value even if it is set within a [@(:if false:)....(:if:)@] condition. %0a%0a%0a[[#usageother]]%0a!!! Usage - other%0a%0aData relevant to a page (the "Base" page) may now also be found in other groups.  If the Base page is Main/HomePage, the data page could be Data-Main/HomePage.  A new variable called $BaseName, which automatically calculates the Base page name from the Data page name, and can be defined by including the following in config.php:%0a%0a->[@// The pattern for figuring out the basename of a page%0a$BaseNamePatterns['/^Data-/'] = '';@]%0a%0aYour pattern may vary.%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%0aActually, for text variables, @@PageVar@@ just calls @@PageTextVar($pagename,$varname)@@, so your code can be sped up slightly by calling it directly, but it takes just the raw variable name without any leading characters, like this: %0a%0a->@@$var=PageTextVar($pagename,'City')@@%0a%0aIt works by caching all page text-variables it finds in a page (in @@$PCache@@) and returns the one requested.%0a%0a!! Feature availability%0aPage text variables were introduced in 2.2.0 beta 2.%0a
time=1254026595