TiddlyWiki macros and plugins

Continuing with his exploration of TiddlyWiki wiki technology, Mark Gibbs looks at the system's macros and plugins that modify and extend the how and what the software can do.

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.

A few particularly interesting macros and plugins are the TiddlyWiki Address Book, twab, which allows you to keep your Address Book in a TiddlyWiki; Clock2, a macro that draws a real time, updating analog clock in a tiddler; Tiddlylock, which allows two people to edit the same TiddlyWiki by locking tiddlers to prevent overwriting; and PublishMacro, which exports tiddlers with a specific tag as HTML pages.

Another group of TiddlyWiki macros and plugins that are really useful are UdoBorkowski's Extensions for TiddlyWiki that include really sophisticated forms support.

Join the Network World communities on Facebook and LinkedIn to comment on topics that are top of mind.

Copyright © 2009 IDG Communications, Inc.