diff --git a/readme.md b/readme.md index d5d1a011e..55c9eb5c8 100644 --- a/readme.md +++ b/readme.md @@ -2,11 +2,9 @@ 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: * CSS (text/css) * Recipe (text/x-tiddlywiki-recipe)

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