• View
• Edit
• History
• Attach
• Print
• Backlinks

Functions

This page briefly describes some of PmWiki's internal functions available to cookbook recipe authors and custom markup developers.

FmtPageName($fmt, $pagename)

Returns $fmt, with $variable and $[internationalisation] substitutions performed, under the assumption that the current page is $pagename. See PmWiki.Variables for an (incomplete) list of available variables, PmWiki.Internationalizations for internationalisation.

IsEnabled($var, $flag)

Returns the value of $var if it is set; otherwise it returns $flag (i.e., a default value). Thus, IsEnabled($var, 0) returns false if $var is false or is not set, and IsEnabled($var, 1) returns true if $var is true or not set.

The purpose of the function is to provide an easy way to specify a default action without actually setting the configuration variable (because we may later need to know that the configuration variable was unset, as opposed to being programmatically set to a default).

For example: if (IsEnabled($cond, 0 )) { blah blah }, "blah blah" is executed if $cond is explicitly set to a non-zero (true) value. This is in contrast to something like: if (IsEnabled($cond, 1)) { blah blah }, where "blah blah" is executed unless $cond has been explicitly set to a zero (false) value.

Keep($value, $pool='')

Stores $value in a "Keep pool", and returns a "keep token" that's intended to be inserted into the wiki text (the keep token uniquely identifies $value in the pool).

$LinkFunctions['...']($pagename, $imap, $path, $title, $txt, $fmt)

$LinkFunctions is an array of functions, indexed by URL "protocol strings" such as 'http:', 'mailto:', or 'ftp:'. These functions get called after all markup processing and () elimination in links like [[(Wiki)Sandbox]]; they are supposed to construct the final HTML from their parameters:

• $pagename - The name of the current page.
• $imap - The protocol string ('http:', 'mailto:', ...)
• $path - The rest of the URL after the protocol string (i.e. the full URL is $imap . $path).
• $title - Text for a title='...' attribute (usually for images).
• $txt - Text that should go between <a href=...> and </a>.
• $fmt - A format string to be applied to $txt via FmtPageName($fmt, $txt).

LinkPage($pagename, $imap, $path, $title, $txt, $fmt)

Creates a link to the page given by $path, using the link text given by $txt. If $fmt isn't supplied, uses $LinkPageExistsFmt, $LinkPageCreateFmt, etc. as appropriate.

ListPages($pat=NULL)

Provides an array of pages whose filenames match $pat i.e. to get a list of all pages on a site, use $allpages = ListPages();. $pat is a pattern that will be matched by MatchPageNames(), for example 'Group1.*,Group2.*,-*.RecentChanges,-*.GroupAttributes'.

• found in pmwiki.php
  • makes use of the ls($pats=NULL) function, also in pmwiki.php
  • To get a list of pages within a specific group: $pagesingroup = ListPages('/^Group\\./'); or $pagesingroup = ListPages('Group.*');
  • for a list of groups:

        $listofgroups = array();
        foreach(ListPages() as $pn) {
          $group = preg_replace('/\\..*/', '', $pn);
          $listofgroups[$group]++;
        }
        $listofgroups = array_keys($listofgroups);
    

  • See this message from 2007 (examples are now listed here)
• compare to MakePageList()

MakePageName($basepage, $string)

Converts string into a valid pagename (relative to $basepage).

MakePageList($pagename, $opt, $retpages = 1)

generates a list of pages using the specifications given by $opt.

• found in /scripts/pagelist.php
• compare to ListPages()

MakeLink($pagename, $tgt, $txt, $suffix, $fmt)

Creates a link to $tgt (url, intermap link, or page name) using $txt as the link text according to the string given by $fmt. If $txt isn't given then it uses $tgt as the link text after stripping anything in parentheses. If $fmt isn't given then it uses the default formatting for whatever kind of link $tgt is. For page links this means the $LinkPageExistsFmt and $LinkPageCreateFmt variables, for intermap-style links it comes from either the $IMapLinkFmt array or from $UrlLinkFmt. Inside of the formatting strings, $LinkUrl is replaced by the resolved url for the link, $LinkText is replaced with the appropriate text, and $LinkAlt is replaced by any "title" (alternate text) information associated with the link.

Markup($name, $when, $pattern, $replacement)

Adds a new markup to the conversion table. Described in greater detail at PmWiki.CustomMarkup.

MarkupToHTML($pagename, $str)

Converts the string $str with PmWiki markup into the corresponding HTML code, assuming the current page is $pagename.

MarkupToHTML() replaces \n\n sequences by <:vspace> first thing when text is passed to it. Subsequently <:vspace> is processed by the markup rules:

MatchPageNames($list, $patterns)

Returns a matched new list of page names. $list is a pagename or array of pagenames, and $patterns is an array of patterns to be matched. If a pattern starts with a slash, the pagename must match the pattern, else if the pattern starts with an exclamation point, the pagename must not match the pattern, else the pagename must match the wildcard pattern. Mixed use of regex pattern and wildcards possible.

PageTextVar($pagename, $ptv)

Returns the value of PageTextVariable $ptv of page $pagename. Make sure $pagename points to the page with the PTV.

PageVar($pagename, $var, $pn)

Returns the contents of the page variable $var, assuming that the current page is named MakePageName($pagename, $pn). (The current page name influences some page variables.)

Here is another example using PageVar() (I don't understand the code above at all!):

# Get the group and page name
$pagename = ResolvePageName($pagename);
$group = PageVar($pagename, '$Group');
$name = PageVar($pagename, '$Name');

ParseArgs($str)

Parses arguments. $str is expected to be the arguments part of a markup like (:blah arguments:); the ParseArgs function finds name=value and name:value pairs (where value may be a quote-delimited string), as well as +value, -value and value options.
The found items are returned as an array, indexed by name, '+', '-', and '', respectively. Array values will be a string for name, arrays of strings otherwise.
See ParseArgs for a description, usage examples, and a demo.

PQA($x)

"Prepare Quoted Arguments" This function parses html argument parameters and makes sure they're properly quoted and protected against cross-site scripting attacks. Given a string like "border=1 cellspacing=0 onclick='destroy()'", PQA() converts it to "border='1' cellspacing='0'". For an example of use, one might define a form (:option...:) command that produces an html <option...> tag like this:

  Markup('option', 'inline',
    '/\\(:option (.*?):\\)/e',
    "Keep('<option '.PQA(PSS('$1')).' />')");

PRR()

"PmWiki Redo Rules": This shortcut function simply increments the global $RedoMarkupLine variable, which tells the markup engine to begin reprocessing the current string (line) from the beginning of the markup translation table. This is commonly used when the replacement string might contain newlines, directives, or other sequences that would normally have been processed by markups earlier in the table. PRR($text) returns $text.

• Note: some processing happens outside of markup rules, particularly regarding HTML entities and vertical space. For example, if you insert [[<<]] into a page as markup and call PRR() it may not be processed correctly.
  • You should process the newly inserted plain text with PVSE() to convert special characters to entities and vertical space.
  • Reading a raw page (ReadPage($somepagename)) and inserting text can run into this problem.

PSS($x)

"PmWiki Strip Slashes": When PHP's preg_replace function is called with the /e (execute) modifier, it automatically adds backslash escapes in front of any double-quotes (") in the matched string. The PSS() function removing the backslashes added by PHP in the match. Note that you don't need to call PSS() if the /e modifier isn't used on the pattern, or you know the matched component won't contain any double-quotes.

PUE($x)

"PmWiki URL Encode": The specifications for uris/urls indicate that non-ASCII characters and spaces should be encoded (via '%' and two hex digits) when used in uris/urls. The PUE() function performs this encoding on any string passed to it. (Yes, PHP provides a url_encode() function that does this; but url_encode() also encodes '%', '/', and other ASCII characters, which often isn't what we want.)

PZZ($x)

"PmWiki Zero Zero": Sometimes a markup replacement will need to assign a value to a variable but not return anything to be displayed in the output. The PZZ() function simply returns an empty string, to make it easier to perform variable assignments. For example, if a markup needs to set $XYZ=1 but not produce any output, it can do

        Markup('xyz', 'directives',
          '/\\(:xyz:\\)/e',
          "PZZ(\$GLOBALS['XYZ']=1)");

and the PZZ() function suppresses the '1' that would normally be returned from the assignment.

SDV($var, $x)

"Set Default Value": Assign a value $x to $var only if $var hasn't already been set. This is normally used in cookbook recipes and extension scripts to set the values for variables that weren't set by a previous configuration file.

SDVA($var, $x)

"Set Default Values in Array": This is the same as SDV(), except $var and $x are arrays (hashes). The key/value pairs in $x are copied into $var only for those keys which do not already exist in $var.

SDVA($RecipeVarName, [   #$RecipeName usually works well
  'RecipeFlag1'=>'defaultValue1',
  'RecipeVar2'=>'defaultValue2', #etc
  ]);

XL($key)

"Translate": This function looks up the $key value in the translation dictionary stored in $XL, trying each language from the $XLLangs array in turn until it finds a match or runs out of languages. If it finds a match, it returns the corresponding translation. If it fails to find a match, it returns the $key value unchanged. Note that this function will skip over languages that have dictionaries in $XL but no current entry in $XLLangs. This can be used to toggle dictionaries on and off for special purposes.

• NOTE: If you need to translate a phrase that has internationalization, you may be better off with FmtPageName()
  • For example: XL('<input value="$[Translated Phrase]">'); will NOT work;
  • XL('Translated Phrase'); will work.

XLPage($lang,$page)

"Translate Page": This function reads the page named in $page, looking for lines of the form:

'some key' => 'translation text'

If the page exists and contains at least one key/translation pair, then $lang is entered into the list of languages in $XLLangs and a dictionary for that language is stored in the $XL array using the XLSDV function. If the page doesn't exist, or is empty, then this function has no effect.

This function is also used to process user preferences from a Site.Preferences page, and can be used to implement a custom preference page (in this case for a fictitious recipe called 'zort') using a block of code like this:

# load settings from our prefs page.
XLPage('zort', 'Site.ZortPreferences');

# set our defaults, in case they weren't set on the page.
XLSDV('zort', array
  ( 'power' => '8'
  , 'volume' => '11'
  ));

# look up and save our prefs.
global $ZortPower, $ZortVolume;
$ZortPower = XL('power');
$ZortVolume = XL('volume');

# erase 'zort' from the language array
# so we don't pollute any translations.
array_shift($XLLangs);

XLSDV($lang,$vals)

"Translation Set Default Values": This acts much as SDVA does, but the key/value pairs in the $vals array are inserted into $XL under $lang as a set of translations for that language. As with all of the Set Default functions, it doesn't change any entries that are already set.

See Also

PmWiki.Functions - PmWiki.Variables