MarkupDirectiveFunctions

Summary: Simply configured custom directives
Version: pmwiki-2.3.12
Prerequisites: PmWiki 2.3.11
Status: Experimental
Maintainer: Petko
License: GPLv2+
Categories: MarkupWriting
Users: (view? / edit)

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

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.