Overview
The heart of
TiddlyWiki can be seen as an extensible representation transformation engine. Given the text of a tiddler and its associated MIME type, the engine can produce a rendering of the tiddler in a new MIME type.
The most important transformations are from
text/x-tiddlywiki wikitext into
text/html or
text/plain but the engine is used throughout the system for other transformations, such as converting images for display in HTML, sanitising fragments of
JavaScript, and processing CSS.
Tiddlers
Tiddlers are a dictionary of name:value pairs called fields.
The only field that is required is the
title field, but useful tiddlers also have a
text field, and some or all of the standard fields
modified,
modifier,
created,
creator,
tags and
type.
Hardcoded in the system is the knowledge that the
tags field is a string array, and that the
modified and
created fields are
JavaScript Date objects. All other fields are strings.
The
type field identifies the representation of the tiddler text with a MIME type.
WikiStore
Groups of uniquely titled tiddlers are contained in
WikiStore objects.
The
WikiStore also manages the plugin modules used for macros, and operations like serializing, deserializing, parsing and rendering tiddlers.
Each
WikiStore is connected to another shadow store that is used to provide default content. Under usual circumstances, when an attempt is made to retrieve a tiddler that doesn't exist in the store, the search continues into its shadow store (and so on, if the shadow store itself has a shadow store).
WikiStore Events
Clients can register event handlers with the
WikiStore object. Event handlers can be registered to be triggered for modifications to any tiddler in the store, or with a filter to only be invoked when a particular tiddler or set of tiddlers changes.
Whenever a change is made to a tiddler, the wikistore registers a
nexttick handler (if it hasn't already done so). The
nexttick handler looks back at all the tiddler changes, and dispatches any matching event handlers.
Parsing
TiddlyWiki parses the content of tiddlers to build an internal tree representation that is used for several purposes:
- Rendering a tiddler to other formats (e.g. converting wikitext to HTML)
- Detecting outgoing links from a tiddler, and from them...
- ...computing incoming links to a tiddler
- Detecting tiddlers that are orphans with no incoming links
- Detecting tiddlers that are referred to but missing
The parse tree is built when needed, and then cached by the
WikiStore until the tiddler changes.
TiddlyWiki5 uses multiple parsers:
- Wikitext (
text/x-tiddlywiki) - JavaScript (
text/javascript) - CSS (
text/css) - JSON (
application/json) - Recipe (
text/x-tiddlywiki-recipe)
Compiling and Rendering
When the text of a tiddler is requested in a different format than its native type,
TiddlyWiki5 compiles a
JavaScript function that generates the new format from the text of the tiddler.
So, a simple tiddler in
application/x-tiddlywiki format might read:
Hello World
The function to render it to
text/html might look like this:
function() {
return "<p>Hello World</p>";
}
The function can also include calls to the store to incorporate the values of other tiddlers. Consider this tiddler, called
HelloThere:
Hello <<tiddler Who>>
And this one called
Who:
World
The function to generate
HelloThere in
text/html might be:
function() {
return ["<p>","Hello ", getTiddlerText("Who","text/html"), "</p>"].join("");
}
Now, the return value of this function can be cached until a tiddler in the dependency chain changes. The function itself can be cached until the tiddler itself changes, or a macro that it uses changes.
The dependency chain is calculated when a tiddler is parsed. Every tiddler that is directly referenced is accumulated (until the point at which it is concluded that it is simpler to mark the tiddler as being dependent on any other tiddler changing).
Evaluated macro parameters are parsed and can be checked for safeness, and then included in the compiled code. For example,
Hello <<echo {{2+2}}>>
Compiles to:
function() {
return ["Hello ",(function(){
return 2+2;
})().toString()].join("");
}
The compilation process has several steps:
- First, the parse tree is used to generate a JavaScript tree
- The JavaScript tree is scanned to determine the tiddlers on which this one depends
- Finally, executable JavaScript text is generated by walking the JavaScript tree