TiddlyWiki macros and plugins

In this, the penultimate installment on the wonders of TiddlyWiki, the free, open source, personal, portable wiki system, we'll look at two of the three topics promised last week, TiddlyWiki's macros and plugins.

Macros and plugins allow you to change the behavior of TiddlyWiki without having to change the source code. Both macros and plugins are JavaScript code stored in tiddlers (TiddlyWiki's basic unit of content) that are labeled with the tag "systemConfig". This allows the TiddlyWiki system to identify them as code.

TiddlyWiki includes a number of macros, such as "newTiddler" which is shown as a link in the right hand menu of the standard distribution and, as you might guess, creates a new tiddler.

To continue reading, register here and become an Insider. You'll get free access to premium content from CIO, Computerworld, CSO, InfoWorld, and Network World. See more Insider content or sign in.

In this, the penultimate installment on the wonders of TiddlyWiki, the free, open source, personal, portable wiki system, we'll look at two of the three topics promised last week, TiddlyWiki's macros and plugins.

Macros and plugins allow you to change the behavior of TiddlyWiki without having to change the source code. Both macros and plugins are JavaScript code stored in tiddlers (TiddlyWiki's basic unit of content) that are labeled with the tag "systemConfig". This allows the TiddlyWiki system to identify them as code.

TiddlyWiki includes a number of macros, such as "newTiddler" which is shown as a link in the right hand menu of the standard distribution and, as you might guess, creates a new tiddler.

There's also a "sparklines" macro that creates sparkline graphics; "tabs", which creates a tabbed presentation inside a tiddler, and "slider", which creates a button that, when clicked, slides out text.

The difference between a macro and a plugin is that plugins are executed at load time (when the TiddlyWiki file is loaded into the browser and rendered) while macros are called when individual tiddlers are opened or other events occur, such as buttons being clicked. Also, after a plugin has executed at load time, it can also provide code to be invoked by a macro, making the distinction between plugins and macros a little loose.

Here's a demonstration of a very simple plugin. It consists of a code fragment in a tiddler that is tagged with "systemConfig":

//{{{
alert("Hello world");
//}}}

At start-up the code fragment will be executed and display the message "Hello world" (yawn). This technique is frequently used for making global changes to the TiddlyWiki architecture before the user gets involved.

To create a macro we need to modify the code and add the macro's name to the global object "config.macros" and then declare a handler for that name. We now have a macro, actually a JavaScript function, which can be executed on demand. Here's what a macro looks like:

//{{{
config.macros.helloWorld = {
handler: function (place, macroName, params, wikifier, paramString, tiddler)
{
// this will run when macro is called from a tiddler
var who = params[0] || "world";
alert("Hello " + who);
}
};
//}}}

Like the plugin, in the code is the content of a tiddler and it is tagged with systemConfig.

Macros can be very sophisticated and include features such as parameter passing, domain object model awareness, calling tiddler identification. To use the above macro from a tiddler you'd include the text:

<<helloWorld 'all TiddlyWiki fans'>>

The angle brackets are TiddlyWiki markup defining a macro call. In this case, the helloWorld handler will be called when the tiddler is opened and a dialog box containing the message will be displayed (if no argument is provided the macro would print "Hello world").

There are a few guides to creating custom macros such as the one at TiddlyWiki Guides (from which the above code example were taken), but they are not for the faint of heart as they are mostly short on detail and incomplete.