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

Toolbox

Questions answered by this recipe

This section is optional; use it to indicate the types of questions (if any) this recipe is intended to answer.

Description

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

NOTE: If you are using writeptv() then version 2009-04-19 of this recipe will necessitate re-coding the parameters of this function. Several little-used and optional parameters at the end were re-coded to use a $opt array instead.

Installation

Please follow instructions for installation from the recipe making use of this toolbox recipe. The quick installation overview is not meant to replace the specific instructions for installing another recipe which uses toolbox.

• Download toolbox.phpΔ and place it in your cookbook directory
• Add a line such as this to your config.php:

Again, pay strict attention to any installation instructions found in the calling recipe -- typically those instructions supersede these brief installation instructions.

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, $opt)
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"
 $opt - array containing options such as
    'fmtpn'=>1  - whether to run FmtPagename() over $pn
    'fmtval'=>1 - whether to run FmtPagename() over $val
    'simplewrite'=>1 - use WritePage() instead of UpdatePage()

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

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

• 2009-04-20 Changed the 2009-04-19 change related to RunMarkupRules(). Now toolbox.php calls ResolvePageName() in its mainline as it is included. Installation instructions should be modified accordingly.
• 2009-04-19 Changed parameter scheme in writeptv(). IF YOU ARE USING WRITEPTV() THIS RELEASE WILL NECESSITATE CHANGES TO YOUR CODE. Fixed a problem with RunMarkupRules() where $pagename had a problem slash vs dot - this impacted primarily SecLayer and (by extension) WikiSh and AuthUserSignup in certain edge conditions.
• 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

See Also

Contributors

Comments