MonkeyWiki: Monkey Wiki Macros

For advanced users, Monkey Wiki now offers a method of defining macros that can be called from within the editable text of a page.

Implementation

To implement macros, you need to define a Python module called mwmacros.py, and place it within the module search path of the Monkey Wiki script - typically this simply means putting it in the same directory. The mwmacros module should contain whatever functions you wish to define, and the return values of these functions are what will appear in the wiki page that called them.

Syntax

On the wiki page that you want your macro to deposit its output, simply call the relevant function contained in the mwmacros module, using normal Python syntax, and enclose the whole call in double square brackets.

Failsafe

Because macro calls share syntax with Hidden Comments, any call which Monkey Wiki fails to recognise as valid will simply appear as a comment. Equally, unless you provide specific error handling within the macro function, any exception thrown by that function will also result in the call remaining as a comment.

Example

For example, suppose I want a function that inserts a <span> element with a particular CSS class, containing some particular text, and I want to name the macro 'span'.

1. I would create the module mwmacros.py, and put the following function in it:

def span(css_class, text):
    return <span class="%s">%s</span> %(css_class, text)

2. When editing a page in which I want the span to appear, I would write

[[span('myclass','Some text that I want to appear in my span')]]

3. The HTML output would be as follows:

<span class="myclass">Some text that I want to appear in my span</span>

Dangers

Obviously some care must be taken here. Whilst you, as the wiki owner, are the one writing the macro functions, you are potentially opening up your site to dangers from users' edits, especially if your functions take arguments. For example, you may wish to define a macro to allow the insertion of HTML - something like this:

def html(raw_html):
    raw_html = raw_html.replace('&lt;', '<')
    raw_html = raw_html.replace('&gt;', '>')
    raw_html = raw_html.replace('&quot;', '"')
    raw_html = raw_html.replace('&amp;', '&')
    return raw_html

This macro would allow users to put anything at all into the page, including scripts that might do any old thing! However, it might be a very useful function on a wiki for which you reserve all editing rights (see Owner Only Editing).