DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:macros

Macros Plugin

Compatible with DokuWiki

Angua, Adora Belle, Weatherwax, Binky

plugin Use macro expressions and conditional expressions to generate page text

Last updated on
2012-02-09
Provides
Syntax, Action
Repository
Source

This extension has not been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues.

Similar to easyvar, fields, kixovar, replace, textinsert

Tagged with extension, formatting, macro

Download and Installation

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

Description

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).

Syntax and Usage

Block Comments

Any text between block comment markers is simply removed:

{{## comment ##}}

Escaped Characters

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:

``

Macros

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

Conditionals

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

Discussion

Vanishing PHP text

Unfortunately, the Macros plugin simply removes undefined macros. This clobbers PHP code, because PHP variables look a lot like macros.

There is an easy fix: in macros.php, function expand_macro_callback(), change the following code to return the original match instead of an empty string:

// a defined macro?
$res = @$this->macroDefs[$name];
if(!$res) {
	$this->undefinedMacros[] = $name;
	return $m[0];
	// return '';
}

Also, the macro identifying character $ can be changed to another character or a sequence of characters. In macros.php, search for and replace \$ in regular expressions.

Bug Report

1. Macros affect verbatim environments

Macro definitions go 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.

Any solution for that? — mubedmubed

2012/05/24 17:32

2. Edit button disappeared

The “edit” button for page sections disappear after installing the macros plugin.

:!: 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!

And what about this one? Any better idea? — mubedmubed

2012/05/24 17:32

I have started a thread form regarding this: https://forum.dokuwiki.org/thread/9138 — Cristian 2012/11/22

Feature Requests

add autolink2 compatibility

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

seems to be working

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

New Feature Added

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.

plugin/macros.txt · Last modified: 2015-05-03 12:53 by igb