diff --git a/readme.md b/readme.md index 5b6e1cb21..0b816253b 100644 --- a/readme.md +++ b/readme.md @@ -5,11 +5,17 @@ node tiddlywiki.js --verbose --load mywiki.html --savetiddler ReadMe ./readme.ht

Notes

--wikitest looks for *.tid files in the specified folder. It then wikifies the tiddlers to both "text/plain" and "text/html" format and checks the results against the content of the *.html and *.txt files in the same directory.

Try it out

The easiest way to try out the code is to visit http://tiddlywiki.com/tiddlywiki5/

For trying it out under node.js, two batch files are provided:


Architecture

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. Furthermore, it can efficiently selectively update the rendering to track any changes in the tiddler or its dependents.

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.

The key feature of wikitext is the ability to include one tiddler within another (usually referred to as transclusion). For example, one could have a tiddler called Disclaimer that contains the boilerplate of a legal disclaimer, and then include it within lots of different tiddlers with the macro call <<tiddler Disclaimer>>. This simple feature brings great power in terms of encapsulating and reusing content, and evolving a clean, usable implementation architecture to support it efficiently is a key objective of the TiddlyWiki5 design.

It turns out that the transclusion capability combined with the selective refreshing mechanism provides a good foundation for building TiddlyWiki's user interface itself. Consider, for example, the StoryMacro in its simplest form:
<<story story:MyStoryTiddler>>
The story macro looks for a list of tiddler titles in the tiddler MyStoryTiddler, and displays them in sequence. The subtle part is that subsequently, if MyStoryTiddler changes, the <<story>> macro is selectively re-rendered. So, to navigate to a new tiddler, code merely needs to add the name of the tiddler and a line break to the top of MyStoryTiddler:
var storyTiddler = store.getTiddler("MyStoryTiddler");
 store.addTiddler(new Tiddler(storyTiddler,{text: navigateTo + "\n" + storyTiddler.text}));
-
The mechanisms that allow all of this to work are fairly intricate. The sections below progressively build the key architectural concepts of TiddlyWiki5 in a way that should provide a good basis for exploring the code directly.

Tiddlers

Tiddlers are an immutable 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 and Rendering

TiddlyWiki parses the content of tiddlers to build an internal tree representation that is used for several purposes:
The parse tree is built when needed, and then cached by the WikiStore until the tiddler changes.

TiddlyWiki5 uses multiple parsers:
Additional parsers are planned:
One global instance of each parser is instantiated in js/App.js and registered with the main WikiStore object.

The parsers are all used the same way:
The parse tree object exposes the following fields:
The dependencies are returned as an object like this:
{
+
The mechanisms that allow all of this to work are fairly intricate. The sections below progressively build the key architectural concepts of TiddlyWiki5 in a way that should provide a good basis for exploring the code directly.

Tiddlers

Tiddlers are an immutable 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 and Rendering

TiddlyWiki parses the content of tiddlers to build an internal tree representation that is used for several purposes:
The parse tree is built when needed, and then cached by the WikiStore until the tiddler changes.

TiddlyWiki5 uses multiple parsers:
Additional parsers are planned:
One global instance of each parser is instantiated in js/App.js and registered with the main WikiStore object.

The parsers are all used the same way:
var parseTree = parser.parse(type,text) // Parses the text and returns a parse tree object

+
The parse tree object exposes the following fields:
var renderer = parseTree.compile(type); // Compiles the parse tree into a renderer for the specified MIME type
+console.log(parseTree.toString(type)); // Returns a readable string representation of the parse tree (either text/html or text/plain)
+var dependencies = parseTree.dependencies; // Gets the dependencies of the parse tree (see below)

+
The dependencies are returned as an object like this:
{
 	tiddlers: {"tiddlertitle1": true, "tiddlertitle2": false},
 	dependentAll: false
 }
-
The tiddlers field is a hashmap of the title of each tiddler that is linked or included in the current one. The value is true if the tiddler is a 'fat' dependency (ie the text is included in some way) or false if the tiddler is a skinny dependency.

The dependentAll field is used to indicate that the tiddler contains a macro that scans the entire pool of tiddlers (for example the <<list>> macro), and is potentially dependent on any of them. The effect is that the tiddler should be rerendered whenever any other tiddler changes.

Rendering

The parseTree.compile(type) method returns a renderer object that contains a JavaScript function that generates the new representation of the original parsed text.

The renderer is invoked as follows:
The tiddler parameter to the render method identifies the tiddler that is acting as the context for this rendering — for example, it provides the fields displayed by the <<view>> macro. The store parameter is used to resolve any references to other tiddlers.

Rerendering

When rendering to the HTML/SVG DOM in the browser, TiddlyWiki5 also allows a previous rendering to be selectively updated in response to changes in dependent tiddlers. At the moment, only the WikiTextRenderer supports rerendering.

The rerender method on the renderer is called as follows:
var node = document.getElementById("myNode");
+
The tiddlers field is a hashmap of the title of each tiddler that is linked or included in the current one. The value is true if the tiddler is a 'fat' dependency (ie the text is included in some way) or false if the tiddler is a skinny dependency.

The dependentAll field is used to indicate that the tiddler contains a macro that scans the entire pool of tiddlers (for example the <<list>> macro), and is potentially dependent on any of them. The effect is that the tiddler should be rerendered whenever any other tiddler changes.

Rendering

The parseTree.compile(type) method returns a renderer object that contains a JavaScript function that generates the new representation of the original parsed text.

The renderer is invoked as follows:
var renderer = parseTree.compile("text/html");
+var html = renderer.render(tiddler,store);
+
The tiddler parameter to the render method identifies the tiddler that is acting as the context for this rendering — for example, it provides the fields displayed by the <<view>> macro. The store parameter is used to resolve any references to other tiddlers.

Rerendering

When rendering to the HTML/SVG DOM in the browser, TiddlyWiki5 also allows a previous rendering to be selectively updated in response to changes in dependent tiddlers. At the moment, only the WikiTextRenderer supports rerendering.

The rerender method on the renderer is called as follows:
var node = document.getElementById("myNode");
 var renderer = parseTree.compile("text/html");
 myNode.innerHTML = renderer.render(tiddler,store);
 // And then, later: