Page Text Variables

Page variables | Documentation index | Markup expressions

Page Variables | Variables | Markup Expressions

Page Text Variables were introduced in 2.2.0 beta 2. These are string variables automatically made available through natural page markup or explicitly with page directive markup within the wiki text of the page.

ConditionalMarkup works fine with page text variables. Page text variables don’t recognize ConditionalMarkup. This is also true for include other pages.
Page text variables don’t honor (:if:). This is the same way that doing (:include OtherPage#section:) doesn’t look to see if [[#section]] is inside of an (:if:)...(:ifend:) construct of some sort.

Defining Page Text Variables

There are three ways to define automated Page Text Variables:

  • use a definition list - the normal pmwiki markup for a definition list will create a page text variable
:Name: Crisses


This creates a new variable that can be accessed by {$:Name} (becomes: “Crisses”) in the page.
  • use a simple colon delimiter in normal text
Address: 1313 Mockingbird Lane


Address: 1313 Mockingbird Lane

“1313 Mockingbird Lane”

This creates the {$:Address} variable (variable markup becomes: “1313 Mockingbird Lane”) in the page.
  • hidden directive form - PmWiki markup that doesn’t render on the page, but defines the variable
(:Country: Transylvania :)

“Transylvania “

This creates the {$:Country} variable (variable markup becomes: “Transylvania “) in the page.


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.


Addis Ababa

To include a page text variable from a header or footer see usage from other pages below.

Usage from other pages

If you want to pull the data from another page, use the {Group/PageName$:Var} format.

Suburb: Khandallah
:Mountain:Mt Ruapehu


Suburb: Khandallah

Mt Ruapehu
“Mt Ruapehu”

Usage from included pages

Page text variables are never included from their source page. See Usage from other pages above to refer to a page text variable on another page.

Nested page text variables

Page text variables can be nested

: MailingAddress : {$:Address},
{$:City}, {$:Country}
1313 Mockingbird Lane, Addis Ababa, Transylvania

“1313 Mockingbird Lane, Addis Ababa, Transylvania “

Another way you may nest PTVs is to make (part of) the variable name a variable in itself:

Contents of y on page {$:x}:

x:Test/Ptvb Contents of y on page Test/Ptvb:

Usage with pagelists

Page lists can also access the page text variables:

(:pagelist group=PmWiki order=$:Summary

And to create pagelist formats (such as those documented at Site.Page List Templates, Page Lists, Page List Templates, Page Variables. Store custom pagelists at Site.Local Templates).

Page lists can also use page text variables to select pages :

(:pagelist group=PITS $:Category=Feature
lists pages having ‘$:Category’ set to ‘Feature’.
Example: multiple selections
(:pagelist group=Cookbook $:Version=1,2
order=-$:Version count=8
lists pages having a ‘$:Version’ of ‘1′ or ‘2′.
Example: multiple selections with spaces
(:pagelist group=PmWiki $:City="Addis
Ababa,Paris" order=-$:Version count=8
‘quotes’ must surround all the selections.
Example: Pages with City variable set
City: Addis Ababa
(:pagelist group=PmWiki $:City=-

City: Addis Ababa

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.

Testing if set or not set

=- PTV is set (is not empty), eg (:pagelist $:MyPageTextVariable=- :)
=-?* PTV is not set (is empty), ie is not set to one char followed by 0 or more chars, eg (:pagelist $:MyPageTextVariable=-?* :)
=* display all pages, the page text variable is irrelevant
=-* display no pages, the page text variable is irrelevant
Example: Pages without a summary
(:pagelist group=PmWiki $:Summary=-?*

Use page text variable in a template

Display pages by Country page text variable.

(:if ! equal {{=$FullName}$:Country}
{{<$FullName}$:Country} :)

(:pagelist group=PmWiki count=6
(:if ! equal {{=$FullName}$:Country} {{<$FullName}$:Country} :)
some parts of this example are not working correctly, should not display all pages

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.

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:


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:


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

PageTextVar relies on the $PageTextVarPatterns variable (which can be used to extend the recognized formats for page text variables in a page). In the older 2.2.0 Beta versions of PmWiki, this variable wasn’t initialized until stdmarkup.php was run, after config.php was executed. Thus, if you needed to use page text variables inside config.php, you had to initialize it yourself. This is no longer necessary, but for those who are still running earlier versions of the beta series, here’s the value to use:

 SDVA($PageTextVarPatterns, array(
    'var:' => '/^:*\\s*(\\w[-\\w]*)\\s*:[ \\t]?(.*)$/m',
    '(:var:...:)' => '/\\(: *(\\w[-\\w]*) *:(?!\\))\\s?(.*?):\\)/s'));

Page variables | Documentation index | Markup expressions

Page Variables | Variables | Markup Expressions

This page may have a more recent version on PmWiki:PageTextVariables, and a talk page: PmWiki:PageTextVariables-Talk.