(:Summary:Page variables automatically made available through natural or explicit page markup:)
>>comment<<
[[#singleline]]
[-[[{=$FullName}|+]],-] \
[[#singlelineend]]
>><<

>>rframe font-size:smaller noprint clear=right<<
!!!! Table of contents
* [[#defining | Defining page text variables]]
* [[#usage | Usage]]
** [[#usagesamepage | On the same page]]
** [[#usageotherpage | From other pages]]
** [[#usageincludedpage | On included pages]]
** [[#nested | Nested]]
** [[#pagelists | With pagelists]]
** [[#templates | In templates]]
** [[#conditionals| With conditionals]]
** [[#usageother | Other usage]]
** [[#withincode | Within code]]
** [[#usagenotes | Usage notes]]
>><<

Page 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.

[[#defining]]
!! Defining Page Text Variables

There are three ways to define automated Page Text Variables:

* use a [[TextFormattingRules#DefinitionLists | definition list]] - the normal pmwiki markup for a definition list will create a page text variable
(:markup caption='Example definition list:' class="horiz":)
:Name: Crisses
"{$:Name}"
(:markupend:)
->This creates a new variable that can be accessed by [@{$:Name}@] (becomes: "{$:Name}") in the page.

* use a simple colon delimiter in normal text
(:markup caption='Example colon delimited:' class="horiz":)
Address: 1313 Mockingbird Lane

"{$:Address}"
(:markupend:)
->This creates the [@{$:Address}@] variable (variable markup becomes: "{$:Address}") in the page.

* hidden [[PmWiki/PageDirectives | directive]] form - PmWiki markup that doesn't render on the page, but defines the variable
(:markup caption='Example directive:' class="horiz":)
(:Country: Transylvania :)
"{$:Country}"
(:markupend:)
->This creates the [@{$:Country}@] variable (variable markup becomes: "{$:Country}") in the page.

[[#usage]]
!! Usage
[[#usagesamepage]]
!!! Usage on the same page

On the same page you can resolve page text variables through the [@{$:Var}@] format (shown above).

!!! Usage in headers and footers

If you want a GroupHeader, GroupFooter, SideBar, etc to call on page text variable in the main page, you need to include reference information.
To 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.
(:markup caption='Example' class=horiz:)
{*$:City}
(:markupend:)
To include a page text variable ''from'' a header or footer see [[#usageotherpage |usage from other pages]] below.


[[#usageotherpage]]
!!! Usage from other pages

If you want to pull the data from another page, use the [@{Group/PageName$:Var}@] format.
(:markup caption='Example:' class="horiz":)
Suburb: Khandallah
(:Lake:Taupo:)
:Mountain:Mt Ruapehu

->"{PmWiki/PageTextVariables$:Suburb}"
->"{{$FullName}$:Lake}"
->"{PmWiki/PageTextVariables$:Mountain}"
(:markupend:)

[[#usageincludedpage]]
!!! Usage from included pages

Page text variables are never [[IncludeOtherPages|included]] from their source page.
See [[#usageotherpage|Usage from other pages]] above to refer to a page text variable on another page.

[[#nested]]
!!! Nested page text variables

Page text variables can be nested
(:markup caption='Example:' class="horiz":)
: MailingAddress : {$:Address}, {$:City}, {$:Country}
"{$:MailingAddress}"
(:markupend:)

Another way you may nest PTVs is to make (part of) the variable name a variable in itself:
(:markup caption='Example:' class="horiz":)
x:Test/Ptvb
Contents of y on page {$:x}:
{{$:x}$:y}
(:markupend:)

[[#pagelists]]
!!! Usage with pagelists

[[Page lists]] can also access the page text variables:
(:markup caption='Example:' class="horiz":)
(:pagelist group=PmWiki order=$:Summary count=6 fmt=#singleline:)
(:markupend:)

And 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]]).

[[Page lists]] can also use page text variables to select pages :
(:markup caption='Example:' class="horiz":)
(:pagelist group=PmWiki $:City=Paris count=8 fmt=#singleline order=-name:)
(:markupend:)
->lists pages having '$:City' set to 'Paris'.

(:markup caption='Example: multiple selections' class="horiz":)
(:pagelist group=PmWiki $:Audience="*authors (intermediate)*,*administrators (intermediate)*" order=-$:Audience,name count=10 fmt=#singleline:)
(:markupend:)
->lists pages having a '$:Audience' of 'authors (intermediate)' or 'administrators (intermediate)'.

(:markup caption='Example: multiple selections with spaces' class="horiz":)
(:pagelist group=PmWiki $:City="Addis Ababa,Paris" order=-$:Version count=8 fmt=#singleline:)
(:markupend:)
->'quotes' must surround ''all'' the selections.


(:markup caption='Example: Pages with City variable set' class="horiz":)
City: Addis Ababa
(:pagelist group=PmWiki $:City=- count=10 fmt=#singleline:)
(:markupend:)
->City variable is set.

* 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.

[[#set]]
!!! Testing if set or not set
(:table:)
(:cellnr:)'''=-'''
(:cell:)PTV is set (is not empty), eg [@(:pagelist $:MyPageTextVariable=- :)@]
(:cellnr:)
%pre%'''=-?*'''
(:cell:)PTV is not set (is empty), ie is not set to one char followed by 0 or more chars, eg
-> [@(:pagelist $:MyPageTextVariable=-?* :) @]
(:cellnr:)'''=*'''
(:cell:)display ''all'' pages, the page text variable is irrelevant
(:cellnr:)'''=-*'''
(:cell:)display ''no'' pages, the page text variable is irrelevant
(:tableend:)

(:markup caption='Example: Pages without a summary' class="horiz":)
(:pagelist group=PmWiki $:Summary=-?* count=6 fmt=#singleline:)
(:markupend:)

[[#templates]]
!!! Use page text variable in a template
Display pages by Audience page text variable.
(:markup caption='Example:' class="horiz":)
>>comment<<
[[#byaudience]]
(:if ! equal '{=$:Audience}' '{<$:Audience}':)
-<'''{=$:Audience}''':
(:ifend:)
[[{=$Name}]]
[[#byaudienceend]]
>><<
(:pagelist group=PmWiki count=10 fmt=#byaudience order=-$:Audience:)
(:markupend:)

[[#conditionals]]
!!! Use page text variables in [[PmWiki/conditional markup]]
Page 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.


[[#usageother]]
!!! Usage - other

Data 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:

->[@// The pattern for figuring out the basename of a page
$BaseNamePatterns['/^Data-/'] = '';@]

Your pattern may vary.

[[#withincode]]
!!! Usage - from within code (developers only)

The standard @@PageVar($pagename,$varname)@@ function can return page text variables, but remember to include the dollar and colon like this:

->@@$var=PageVar($pagename,'$:City')@@

Actually, 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:

->@@$var=PageTextVar($pagename,'City')@@

It works by caching all page text-variables it finds in a page (in @@$PCache@@) and returns the one requested.

!! Feature availability
Page text variables were introduced in 2.2.0 beta 2.

Well macdaaima nuts, how about that.

Now I know who the brinay one is, I'll keep looking for your posts.

There's a terrific amunot of knowledge in this article!

nDzcLS , [url=http://tfgfibqhfchw.com/]tfgfibqhfchw[/url], [link=http://dfozwtvnqpzr.com/]dfozwtvnqpzr[/link], http://tyxbemwfolds.com/

Whoa, whoa, get out the way with that good infoarmiton.

This could not psoisbly have been more helpful!

55bEuu <a href="http://zlgmlxhqpkza.com/">zlgmlxhqpkza</a>

Cheers pal. I do apprecitae the writing.

And I thought I was the snesilbe one. Thanks for setting me straight.

Ya learn sotmehing new everyday. It's true I guess!

2v4RyB , [url=http://qxflripjdlyk.com/]qxflripjdlyk[/url], [link=http://xswujlfdxmnl.com/]xswujlfdxmnl[/link], http://zfoobgnwcqno.com/

1BkX49 <a href="http://rewtqnpvokpf.com/">rewtqnpvokpf</a>

What an awesome way to explain this—now I know evyrtehing!