Macros Plugin

Download and install the plugin using the Plugin Manager using the URL given above. Refer to Plugins on how to install plugins manually.

This plugin allows you to define custom macros that can be used to generate page text. It also processes simple conditional expressions, removes block comments and allows escaping of literal characters (those are useful features when using macros).

Any text between block comment markers is simply removed:

{{## comment ##}}

A character that is preceded by a backtick ` will be rendered as a literal character. That allows use of characters that otherwise would be interpreted as markup characters:

`{`{ literal braces `}`}

Double that to render a backtick:

``

The format of a macro definition is:

{{$name=definition$}}

where name is the macro identifier and definition is the macro text. The definition may contain placeholders @0, @1, … @9 for up to ten macro arguments.

Macros are used (expanded) by:

$name            (without specified arguments - equal to an empty argument list)
$name[]          (with an empty argument list)
$name[arg]       (with one argument)
$name[arg1|arg2] (with two arguments, etc.)

An example:

{{$format=**@0** @1 //@2//$}}
$format[bold|and|italics]

Produces this text: bold and italics

The plugin processes two types of conditional expressions:

$??[cond|T|F]

expands to T if cond is not an empty string, otherwise expands to F

$?[a|b]          (shortcut for $??[a|a|b])

expands to a if a is not an empty string, otherwise expands to b

1. it goes through all environments (<nowiki>, <code>, %%, <file>) and this is not only a problem (it's impossible to present the macro syntax when it is installed) but also dangerous, because it manipulates source codes which are presented on the wiki.
2. the “edit” button for page sections disappear after installing the macros plugin.
   1. one idea is to disable global $conf; $conf['maxseclevel'] = 0; in action.php http://forum.dokuwiki.org/post/26514

The author says: The plugin definitely would benefit from better integration. It was created as a quick port of a module from my own experiments with another wiki.

If a macro is processed, that changes the length of a section text. It may even generate new sections! I could not find how to make dokuwiki adjust the sections (and positions of edit buttons) properly, therefore I decided to disable the section buttons, when a macro is involved in generating page text. Like so, although this is an ugly hack, I think:

if ($data != $event->data) {
  // disable section edit if any change took place
  global $conf; $conf['maxseclevel'] = 0;
  $event->data = $data;
}

If anyone, who knows well how dokuwiki environments work, could improve the plugin integration, it would be most appreciated!

The plugin autolink2 substitutes defined words with corresponding internal page links.
Unfortunately the replacements through macros are not substituted.
Is there any way to change that? It will be great! _{Joachim 2011-11-05}

This code, run by the latest version of the plugin, with Cristian's changes, properly links “some name” 6 times. (I do not think that the changes made it to do so - perhaps some update in the DokuWiki core?)

{{$SN=@0ome @1ame$}}

<autolink>
The text on the page. Blah, blah, blah...

And of course the text Some Name. Also some name is valid, as well as SOME NAME.
|The test can be in a table also| Some Name, **but** there needs to be a space after the leading`|| through a macro: $SN[S|N] |

$SN[s|n]

</autolink>

_{Ian 2012-03-05}

Thanks to Cristian Spiescu for submitting a patch which now has been rolled into the plugin.

It is possible to specify a “global include” page (as namespace:page) in Configuration Manager/Macros Plugin Setting. Macro definitions from that page become available in the whole wiki.