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

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:

1. $pagename: the full name of the currently processed page.
2. $directive: the directive keyword, as in "mydirective" (you may have different directives calling the same function).
3. $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'.
4. $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

Contributors

Written and maintained by Petko.

Comments

See discussion at MarkupDirectiveFunctions-Talk?