• 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, and cast numeric values to floating point numbers,
• call your function with the arguments $pagename, $directive, $args, $content (if any).

All the above is regularly done by authors of many individual recipes; the new helper functions should simplify this chore.

This format may also be more future-proof than direct Markup() calls, as it should be simpler for the PmWiki core to automatically adapt these to changes in future PHP versions.

On the other hand, these directives are processed quite early in the markup sequence, normally just after conditionals. If your function needs to be called at a specific point of the processing, or relative to other markup rules, you may need to use the standard Markup() calls.

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 = '') {
  // 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). Note that $content will be:
   • "" (empty string) with the single line directive,
   • in a multiline directive it will keep any leading and trailing line breaks and spaces; you can use trim($content) to remove these if needed.

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 "anydir1" in the first column. 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, call 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, call KeepBlock():

  return KeepBlock($out);
  ### before 2.3.19, please use this instead:
  # 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 unlike some other markup 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

• 2023-03-06 Bug-fix for multi-line directives (PmWiki 2.3.21).
• 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