1
0
mirror of https://github.com/Jermolene/TiddlyWiki5 synced 2024-12-24 00:50:28 +00:00

Docs updates

This commit is contained in:
Jeremy Ruston 2012-06-09 22:26:48 +01:00
parent ca56de0495
commit 622884cd5d

View File

@ -2,11 +2,9 @@
store.addTiddler(new Tiddler(storyTiddler,{text: navigateTo + &quot;\n&quot; + storyTiddler.text}));</pre><p>The mechanisms that allow all of this to work are fairly intricate. The sections below progressively build the key architectural concepts of <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='TiddlyWiki5'>TiddlyWiki5</a> in a way that should provide a good basis for exploring the code directly.</p><h1> Tiddlers</h1><p>Tiddlers are an immutable dictionary of name:value pairs called fields.</p><p>The only field that is required is the <code>title</code> field, but useful tiddlers also have a <code>text</code> field, and some or all of the standard fields <code>modified</code>, <code>modifier</code>, <code>created</code>, <code>creator</code>, <code>tags</code> and <code>type</code>.</p><p>Hardcoded in the system is the knowledge that the <code>tags</code> field is a string array, and that the <code>modified</code> and <code>created</code> fields are <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='JavaScript'>JavaScript</a> <code>Date</code> objects. All other fields are strings.</p><p>The <code>type</code> field identifies the representation of the tiddler text with a MIME type.</p><h1> WikiStore</h1><p>Groups of uniquely titled tiddlers are contained in <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='WikiStore'>WikiStore</a> objects.</p><p>The <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='WikiStore'>WikiStore</a> also manages the plugin modules used for macros, and operations like serializing, deserializing, parsing and rendering tiddlers.</p><p>Each <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='WikiStore'>WikiStore</a> 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).</p><h1> WikiStore Events</h1><p>Clients can register event handlers with the <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='WikiStore'>WikiStore</a> 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.</p><p>Whenever a change is made to a tiddler, the wikistore registers a <code>nexttick</code> handler (if it hasn't already done so). The <code>nexttick</code> handler looks back at all the tiddler changes, and dispatches any matching event handlers. </p><h1> Parsing and Rendering</h1><p><a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>TiddlyWiki</a> parses the content of tiddlers to build an internal tree representation that is used for several purposes:</p><ul><li> Rendering a tiddler to other formats (e.g. converting wikitext to HTML)</li><li> Detecting outgoing links from a tiddler, and from them...</li><li> ...computing incoming links to a tiddler</li><li> Detecting tiddlers that are orphans with no incoming links</li><li> Detecting tiddlers that are referred to but missing</li></ul><p>The parse tree is built when needed, and then cached by the <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='WikiStore'>WikiStore</a> until the tiddler changes.</p><p><a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='TiddlyWiki5'>TiddlyWiki5</a> uses multiple parsers:</p><ul><li> Wikitext (<code>text/x-tiddlywiki</code>) in <code>js/WikiTextParser.js</code></li><li> <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='JavaScript'>JavaScript</a> (<code>text/javascript</code>) in <code>js/JavaScriptParser.js</code></li><li> Images (<code>image/png</code> and <code>image/jpg</code>) in <code>js/ImageParser.js</code></li><li> JSON (<code>application/json</code>) in <code>js/JSONParser.js</code></li></ul><p>Additional parsers are planned:
* CSS (<code>text/css</code>)
* Recipe (<code>text/x-tiddlywiki-recipe</code>)</p><p>One global instance of each parser is instantiated in <code>js/App.js</code> and registered with the main <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='WikiStore'>WikiStore</a> object.</p><p>The parsers are all used the same way:</p><pre class='javascript-source'><span class='javascript-keyword'>var</span> <span class='javascript-identifier'>parseTree</span> <span class='javascript-punctuator'>=</span> <span class='javascript-identifier'>parser</span><span class='javascript-punctuator'>.</span><span class='javascript-identifier'>parse</span><span class='javascript-punctuator'>(</span><span class='javascript-identifier'>type</span><span class='javascript-punctuator'>,</span><span class='javascript-identifier'>text</span><span class='javascript-punctuator'>)</span> <span class='javascript-comment javascript-line-comment'>// Parses the text and returns a parse tree object
</span></pre><p>The parse tree object exposes the following fields:</p><pre class='javascript-source'><span class='javascript-keyword'>var</span> <span class='javascript-identifier'>renderer</span> <span class='javascript-punctuator'>=</span> <span class='javascript-identifier'>parseTree</span><span class='javascript-punctuator'>.</span><span class='javascript-identifier'>compile</span><span class='javascript-punctuator'>(</span><span class='javascript-identifier'>type</span><span class='javascript-punctuator'>)</span><span class='javascript-punctuator'>;</span> <span class='javascript-comment javascript-line-comment'>// Compiles the parse tree into a renderer for the specified MIME type
</span><span class='javascript-identifier'>console</span><span class='javascript-punctuator'>.</span><span class='javascript-identifier'>log</span><span class='javascript-punctuator'>(</span><span class='javascript-identifier'>parseTree</span><span class='javascript-punctuator'>.</span><span class='javascript-identifier'>toString</span><span class='javascript-punctuator'>(</span><span class='javascript-identifier'>type</span><span class='javascript-punctuator'>)</span><span class='javascript-punctuator'>)</span><span class='javascript-punctuator'>;</span> <span class='javascript-comment javascript-line-comment'>// Returns a readable string representation of the parse tree (either <code>text/html</code> or <code>text/plain</code>)
</span><span class='javascript-keyword'>var</span> <span class='javascript-identifier'>dependencies</span> <span class='javascript-punctuator'>=</span> <span class='javascript-identifier'>parseTree</span><span class='javascript-punctuator'>.</span><span class='javascript-identifier'>dependencies</span><span class='javascript-punctuator'>;</span> <span class='javascript-comment javascript-line-comment'>// Gets the dependencies of the parse tree (see below)
</span></pre><p>The dependencies are returned as an object like this:</p><pre>{
tiddlers: {&quot;tiddlertitle1&quot;: true, &quot;tiddlertitle2&quot;: false},
dependentAll: false