PmWiki | Cookbook / Toolbox

Summary: Tools for recipe developers

Version: 2008-08-21

Prerequisites: 2.2.x Beta

Status: Alpha

Maintainer: Peter Bowers

Used By: WikiBox, WikiSh

Categories: DevelopmentTool

Download: Attach:toolbox.php Δ

Questions answered by this recipe

Description

Tools for recipe development. No capability offered to authors except through other recipes.

Notes

Reading pages with a do-it-all function

tbRetrieveAuthPage($basepage, $pagesource, $pmauth=, $prompt=false, $since=0, $slStore=null, $slAuth="", $RuleList=null'')
This function acts as RetrieveAuthPage() but adds this functionality:

If $pmauth is not specified then ReadPage() is called instead. This allows bypassing of pmwiki authorization if needed.
$prompt defaults to false instead of true
If $slStore and $slAuth are provided the SecLayer authorizations are enforced prior to any read
If $RuleList is provided then the markup rules in that array are run over the text of the page and the results returned in $page['ntext']
$pagesource can include a section specifier and it will be handled as appropriately (the full page will be returned in $page['text'] and the section specified will be returned in $page['ntext'])

Basically this provides a tested way to get a lot more functionality very quickly as opposed to putting together all the various pieces.

Error Reporting

Err($pagename, $opt, $msg)
This function will output an error. Currently all it does is to echo the error, but eventually it will allow for logging errors, putting them in (:errors:), etc.

logit($pagename, $pn, $text, $opt)
Append text to the end of a page.

 $pagename - a reference page (can be the same as $pn)
 $pn - the page to which to append
 $text - the text to write
 $opt - an array containing modifying semantics
   [NO_FMTPAGENAME] - suppress running FmtPageName() over $pn
   [NO_FMTTEXT]     - suppress running FmtPagename() over $text

Markup Manipulation

RunMarkupRules($pagename, $RuleList, $Text, $opt)
Run the markup rules held in $RuleList over the source held in $Text and return the results. This enables running a subset of markup rules.

PageTextVar writing

writeptv($pagename, $pn, $var, $val, $ptvfmt, $fmtpn, $fmtval)
Write a PTV to a given page. 1st 4 arguments are mandatory, remainder are optional.

 $pagename - a reference page (can be the same as $pn)
 $pn - the name of the page to which the PTV will be written
 $var - the name of the variable (no $ or {} characters) (can be an array of varnames to write several ptvs)
 $val - the value to be written to the variable (can be an array of values to write several ptvs)
 $ptvfmt - defaults "hidden", other options: "text", "deflist", "section"
 $fmtpn - whether to run FmtPagename() over $pn
 $fmtval - whether to run FmtPagename() over $val

ptv2text($text, $var, $val, $ptvfmt='hidden')
This is an "internal" function to writeptv() above, but it is often useful to handle just the text manipulation since the page manipulation might need to be handled elsewise.

 $text - the text that will be altered to insert/replace the PTV definition
 $var - the name of the variable
 $val - the value which will be assigned
 $ptvfmt - default "hidden", also "text", "deflist", and "section" (section as yet not implemented)

Debug/Trace

dbg($printlevel, $message [, $msg2, ...])
This function provides trace statement capability. A global $DebugLevel controls which statements will print. Any statement with a $printlevel greater than or equal to $DebugLevel will print.

Note that $message can either be a string (which will be put in a nice, unordered list) or an array (which will be output with print_r() in a nice PRE section). You can have up to 5 arguments so you can do something like this:

@@dbg(3, "MyFunc: Value of opt", $opt, "MyFunc: Value of page", $page);

and get a nicely formatted output of both the $opt array and the $page array with a little "header" line to tell you what it is you're looking at.

A typical function making use of dbg() will look like this:

function MyFunc()
{
   $func = 'MyFunc()'; $d = 1;
   dbg($d*4, "$func: Entering")
   dosomestuff();
   dbg($d*3, "$func: Doing something with $y.  Opt array follows", $opt);
   dosomethingelse();
   dbg($d*4, "$func: Returning $rtn");
   return($rtn)
}

od($text)
For use in debugging. HTML can sometimes make parts of your text disappear or etc. If you display it through od() then any non-alpha, non-numeric characters will be replaced with either a name for that character or a CHR(###) representation.

Release Notes

2008-08-21 Fix infinite loop when writing to self page in writeptv. Added section writing to writeptv. Added tbRetrieveAuthPage() function. (tbUpdateAuthPage() exists but is not yet fully tested.)
2008-08-08 Bug-fix for dbg(). Kind of ironic, don't you think? Basically multiple values being passed has never worked and now it does.
2008-07-31 Several updates to writeptv() - can now pass multiple variable/values in arrays and also split out ptv2text() so the actual textual manipulation can be separated from the page read/write process. If a PTV already exists but has the wrong type (as per $ptvfmt) then the type will be updated on the page.
2008-06-12 First "official" release

Toolbox