1. Macros

Macros allow the insertion of system features into normal wiki pages; the only thing that makes those pages special is that they contain macros. If you edit pages like RecentChanges or SystemInfo, you'll see what that means.

loads I18N texts (mainly intended for use on Help pages or in generated output on wiki pages) and replaces %s in the message by the arguments. The first character of the argument is used as the separator (in this example: a comma). You can escape the separator by using a backslash.

"<<GetText2(,[You may not read %s],FooBar)>>" yields "[You may not read FooBar]"

Allow the user to create (sub-) pages easily, using the page PageTemplateas the template for the new page and the string NameTemplate as a template for the name.3@ME is used if you want the page created below the users homepage. @SELF is used to create a subpage below the page where it is called from.

<<GetVal(NeatSnippets,regards)>>

Retrieve dictionary entries from dict pages.

If you have a page called GermanDict which contains the entry Test, you should see the translation here:

<<MonthCalendar(,,12)>>

Displays a Calendar and creates link for entries to each day on subpages

"timestamp" can be empty (current time), a number of seconds since 1970 (unix timestamp), or a W3C time specification ("2002-01-23T12:34:56"). See RFC822, sect. 5. (2)

NameTemplate is formatted with time.strftime(), with the exception of %s which is replaced by the input into the edit box (which is only shown if necessary). If NameTemplate is not specified or empty, it defaults to %s. (3)

2. Writing your own macro

Create a python file called MacroName.py located in your data/plugin/macro directory. Ensure it has a single function called macro_MacroName(macro, arg1, arg2, ...), which is the entry-point.

the first argument macro is an instance of class Macro, and also evaluates to a string of the macroname,

arguments arg1, arg2, ... are the arguments given by the user, but special rules apply, see below.

You can access the request object by using macro.request - e.g. to access form parameters and other information related to user interaction.

Your function should use the formatter to construct valid markup for the current target format. In most cases this is HTML, so writing a macro which returns HTML will work in most cases but fail when formats like XML or text/plain are requested - you can use macro.formatter to access the current formatter.

Add an entry into Dependencies if the output from your macro should not be cached. This is important if the macro output could change from one moment to another, for example if your macro searches in wiki pages which may be being edited by other users, or loads information from an external database whose contents may change. Currently the value of any entry does not matter and may be considered a short description for 'why results from this macro should not be cached', but please look at the entries used in other macros for values which may be suitable.

If your macro can generate headings (by calling macro.formatter.heading()) then set generates_headings to True to allow the TableOfContents macro to evaluate your macro for headings to take into the table of contents.

2.1. Macro arguments

The arguments given to your macro are normally passed as unicode instances or None if the user gave no argument.