MarkupDirectiveFunctions
A simple way to configure custom markup directives.
Description
This page documents the use of a new helper function (as of PmWiki 2.3.11) that makes it easy to add custom markup directives in the format:
!! Simple directive (:mydirective arg1=val1 arg2="val 2":) !! Multiline directive with start, content, end (:otherdirective arg1=val1 arg2="val 2":) Content (:otherdirectiveend:) |
New PmWiki core helper functions will:
- register the Markup() calls with the regular expressions for your directive
- receive the matching texts from the wiki pages
- extract the
$pagename
variable - parse the directive arguments, if any
- trim the multiline content, if any
- call your function with the arguments
$pagename
, $directive, $args, $content.
All the above is regularly done by authors of many individual recipes; the new helper functions should simplify this chore.
Usage
In your recipe, instead of Markup()
calls, just define your directive keyword, and the function that receives the parsed content:
$MarkupDirectiveFunctions['mydirective'] = 'FmtMyDirective'; $MarkupDirectiveFunctions['otherdirective'] = 'FmtMyDirective'; function FmtMyDirective($pagename, $directive, $args, $content = null) { // do your magic return $out; }
When markup directives are processed, your function will be called for every matching directive with the arguments:
: the full name of the currently processed page.$pagename
$directive
: the directive keyword, as in "mydirective" (you may have different directives calling the same function).$args
: an array with the parsed arguments within the start directive (see documentation for ParseArgs).- in the above example,
$args['arg1']
will be 'val1', and$args['arg2']
will be 'val 2'.
- in the above example,
$content
: the text between the start and end directives (in the case of a complex directive).
Return values
If your function returns wiki code such as (:notitle:)
or {*$FullName}
that needs to be re-processed by the markup engine, use PRR():
return PRR($out);
On your wiki, in Page?action=ruleset, the markup that should be wrapped in PRR() are the rules between "_begin"
at the top and the last rule with where the second column is "directives"
. If you output simple tables, wikistyles, and other inline markup you may not need to wrap it with PRR(). YMMV.
If your function returns HTML that should not be processed further, use Keep():
return Keep($out);
If your HTML is a block-level element like a <div>
, to prevent it from becoming wrapped in <p>
tags which would be invalid HTML, use <:block>
:
return '<:block>'. Keep($out);
Notes
Search the documentation about the PmWiki helper functions ParseArgs(), PRR() and Keep().
- The custom directive 'keyword' can only have letters, digits, minus and underscore characters, and is case sensitive.
- The end directive (if any) has simply an added "end", like XYZ...XYZend.
- Do not use the same directive name for both simple (single line) and complex (multiline) directives.
Change log / Release notes
- 2022-08-28 Helper function and added to Subversion for PmWiki 2.3.11. See PmWiki.ChangeLog for changes.
See also
- Cookbook /
- Functions Brief description of some of PmWiki's internal functions available to cookbook recipe authors and custom markup developers
- ParseArgs Description of ParseArgs function for parsing argument lists (Stable)
- PmWiki /
- CustomMarkup Using the Markup() function for custom wiki syntax; migration to PHP 5.5
- FunctionList A simple list of the functions provided by PmWiki
- Functions How some of the functions in pmwiki.php work
- Test /
- ParseArgs
Contributors
Written and maintained by Petko.
Comments
See discussion at MarkupDirectiveFunctions-Talk?
User notes? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.