Writing Macros

Macros are probably the easyest kind of extension to write for Shellwiki. A macro is simply any command line program, and it can be written in any programming language. Most of the default macros are written in shell script. Macros are located in the macros/ directory of the Shellwiki codebase.

Macros are called on a page by including a text segment like <<macroname --flags arguments>>.

When parsing a page this will become the call to your macro. The program file named after the specified macroname will be executed and the arguments will be passed as regular command line parameters.

A prerendered version of the full HTML document will be passed to the standard input of your macro program. This is useful when working with data from the page, e.g. when generating a table of content, etc. You may however choose to ignore the standard input. In the prerendered HTML document all macro calls will appear in the form of a <code class=".macro"> tag and you cannot refer directly to the output of another macro from the page.

Whatever text your macro produces on its standard output, gets inserted in place of the macro call. You should make use of html classes signifying that the code was produces by your macro.

Because macros are executed as standalone programs, they cannot access shell functions from Shellwiki without loading them on their own. Macro authors may want to load $_EXEC/acl.sh and $_EXEC/tools.sh to access some common wiki functions. Keep in mind that you may want to provide internationalised versions of your text messages.

Most importantly keep in mind, that Macros can access all wiki data regardless of ACLs.

Macro authors are responsible for checking access permissions to the information they process.

I.e. before reading data from another wiki page, you should always cheack acl_read "$page".

You may also find it useful to use the "page_glob()" and "attachment_glob()" functions from tools.sh.

Look at existing macros to learn how to work with wiki data and helper functions.