/web/clip
Help
Page 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 (meaning regular PTVs don't have accented characters). This is a limitation for international wikis (experimental recipe for international PTV : Cookbook:InternationalPTVs).
There are three ways to define automated Page Text Variables (more patterns can be defined if needed) :
:Name: Crisses "{$:Name}" |
"Crisses" |
{$:Name}
(becomes: "Crisses") in the page.
Address: 1313 Mockingbird Lane "{$:Address}" | Address: 1313 Mockingbird Lane "1313 Mockingbird Lane" |
{$:Address}
variable (variable markup becomes: "1313 Mockingbird Lane") in the page.
(:Country: Transylvania :) "{$:Country}" | "Transylvania " |
{$:Country}
variable (variable markup becomes: "Transylvania ") in the page.
If a page text variable is not 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 {$:Country}
will return an empty string.
An administrator can define default values for such cases (PmWiki 2.2.121+). The following arrays can be defined in local/config.php
:
$DefaultUnsetPageTextVars = array( 'SpecificVariable' => 'SpecificVariable is unset', '*PartialMatch*' => 'some value', '*' => '(unset)', );
$DefaultEmptyPageTextVars = array( 'SpecificVariable' => 'SpecificVariable is set, but empty', '*' => '(empty)', );
In the above examples, {$:SpecificVariable}
or {OtherPage$:SpecificVariable}
will output the value defined:
$DefaultUnsetPageTextVars
if the variable is not defined in the page text, or if the user doesn't have read permissions for OtherPage
$DefaultEmptyPageTextVars
if the user has read permissions, and the variable is defined but empty, for example (:SpecificVariable::)
.
The patterns are processed in order, and the first matching pattern assigns the value to the variable. The asterisk *
matches any string, in the above examples an undefined variable that doesn't match 'SpecificVariable' or '*PartialMatch*' will output '(unset)'.
On the same page you can resolve page text variables through the {$:Var}
format (shown above).
If you want a GroupHeader, GroupFooter, SideBar, etc to call on page text variable in the main page, you need to include special 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.
{*$:Mountain} \\ {*$Namespaced} | Mt Ruapehu |
To include a page text variable from a header or footer see usage from other pages below.
If you want to pull the data from another page, use the {Group/PageName$:Var}
format.
Suburb: Khandallah (:Lake:Taupo:) :Mountain:Mt Ruapehu ->"{PmWiki/PageTextVariables$:Suburb}" ->"{{$FullName}$:Lake}" ->"{PmWiki/PageTextVariables$:Mountain}" | Suburb: Khandallah
"Khandallah"
"Taupo"
"Mt Ruapehu"
|
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.
Page lists can also access the page text variables:
(:pagelist group=PmWiki order=$:Summary count=6 fmt=#singleline:) |
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=PmWiki $:City=Paris count=8 fmt=#singleline order=-name:) |
(:pagelist group=PmWiki $:City="Addis Ababa,Paris" order=-$:Version count=8 fmt=#singleline:) |
(:Linkme: [[PageToLink]]:) (:if false:){$:Linkme}(:ifend:)
The page text variable value is always the text that is written in the page. It is only evaluated when the variable is printed/output to HTML. To 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.
E.g. With a page name in to format "yyyyMonth" it is simpler to use a PageVariable
calculated in config.php
, not a PageTextVariable
:
Then use (:pagelist order=$NameToYearMonth:)
An alternative is writing in the wiki page:
(:MonthNum:07:)
as the markup expression that follows won't work:
(:MonthNum:{(ftime fmt=%m when="{$Namespaced}")}:)
=- | PTV is set (is not empty), eg (:pagelist $:Var=- :) |
=-?* | PTV is not set (is empty), ie not one character followed by 0 or more characters, eg. (:pagelist $:Var=-?* :) |
=* | display all pages, regardless of the page text variable (slow) |
=-* | display no pages, regardless of the page text variable (slow) |
Tip : (:if ! equal "{$:PTV}" "":)
will test if PTV is empty/unset or not.
(:pagelist group=PmWiki $:Summary=-?* count=6 fmt=#singleline:) |
Display pages by Audience page text variable.
>>comment<< [[#byaudience]] (:if ! equal '{=$:Audience}' '{<$:Audience}':) -<'''{=$:Audience}''': (:ifend:) [[{=$Name}]] [[#byaudienceend]] >><< (:pagelist group=PmWiki count=10 fmt=#byaudience order=-$:Audience:) | visitors (intermediate) :
readers, authors (basic):
readers :
Developers:
authors, admins (intermediate) :
authors, admins (advanced) :
authors (intermediate) :
|
Page 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:)....(:ifend:)
condition.
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')
It works by caching all page (text) variables it finds in a page (in $PCache
) and returns the one requested.
This page may have a more recent version on pmwiki.org: PmWiki:PageTextVariables, and a talk page: PmWiki:PageTextVariables-Talk.