mirrors/TiddlyWiki5
1
0
Fork 0
mirror of https://github.com/Jermolene/TiddlyWiki5 synced 2024-11-27 03:57:21 +00:00
Code Issues Releases Wiki Activity

Fixed typo with class member of linkInfo

Browse Source 
And improved the docs
This commit is contained in:
Jeremy Ruston 2012-04-07 14:28:50 +01:00
parent 94ff60f64b
commit e7701d8af0
3 changed files with 11 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
js/macros/link.js
View File

@ -21,10 +21,12 @@ as follows:
The link massager is called with the `attributes` hashmap initialised as follows:
{
classes: an array of strings representing the CSS classes to be applied to the link. The default classes are already applieda according to whether the heuristics decide the tiddler is external or missing
class: an array of strings representing the CSS classes to be applied to the link. The default classes are already applieda according to whether the heuristics decide the tiddler is external or missing
href: the href to be used in the link (defaults to the unencoded value of the `to` parameter)
}
Note that the member `class` cannot be referred to with JavaScript dot syntax: use `linkInfo.attributes["class"]` rather than `linkInfo.attributes.class`.
The linkMassager can modify the `classes` and `href` fields as required, and add additional HTML attributes, such as the `target` attribute.
The linkMassager can cause the link to be suppressed by setting the `linkInfo.suppressLink` to `true`. The content of the link will still be displayed.
@ -78,15 +80,15 @@ exports.macro = {
href: linkInfo.to
};
// Generate the default classes for the link
linkInfo.attributes.classes = ["tw-tiddlylink"];
linkInfo.attributes["class"] = ["tw-tiddlylink"];
if(linkInfo.isExternal) {
linkInfo.attributes.classes.push("tw-tiddlylink-external");
linkInfo.attributes["class"].push("tw-tiddlylink-external");
} else {
linkInfo.attributes.classes.push("tw-tiddlylink-internal");
linkInfo.attributes["class"].push("tw-tiddlylink-internal");
if(linkInfo.isMissing) {
linkInfo.attributes.classes.push("tw-tiddlylink-missing");
linkInfo.attributes["class"].push("tw-tiddlylink-missing");
} else {
linkInfo.attributes.classes.push("tw-tiddlylink-resolves");
linkInfo.attributes["class"].push("tw-tiddlylink-resolves");
}
}
// Invoke the link massager if defined

2
readme.md
View File

@ -6,7 +6,7 @@ node tiddlywiki.js --load mywiki.html --servewiki 127.0.0.1:8000
node tiddlywiki.js --recipe tiddlywiki.com/index.recipe --savewiki tmp/
</code><br>This example ginsus a TiddlyWiki into its constituent tiddlers:<br><code>
node tiddlywiki.js --load mywiki.html --savetiddlers tmp/tiddlers
</code><br><h2> Notes</h2><code>--servewiki</code> and <code>--servetiddlers</code> are for different purposes and should not be used together. The former is for TiddlyWiki core developers who want to be able to edit the TiddlyWiki source files in a text editor and view the results in the browser by clicking refresh; it is slow because it reloads all the TiddlyWiki JavaScript files each time the page is loaded. The latter is for experimenting with the new wikification engine.<br><br><code>--wikitest</code> looks for <code>*.tid</code> files in the specified folder. It then wikifies the tiddlers to both &quot;text/plain&quot; and &quot;text/html&quot; format and checks the results against the content of the <code>*.html</code> and <code>*.txt</code> files in the same directory.<br><br><code>--links</code> controls the way that links are generated. Currently, the only option supported is:<br><br> <code>none</code>: Tiddler links are disabled<br><br><br></div><br><h1>Testing</h1><div data-tiddler-target='Testing' data-tiddler-template='Testing' class='tw-tiddler-frame'><h1>Test Scripts</h1><br>Three test scripts are provided, each as a Mac OS X <code>*.sh</code> bash script and a Windows <code>*.bat</code> batch file. In each case they should be run with the current directory set to the directory in which they reside.<br><br><ul><li> <code>test.sh</code>/<code>test.bat</code> cooks the main tiddlywiki.com recipe for TiddlyWiki 2.6.5 and compares it with the results of the old build process (ie, running cook.rb and then opening the file in a browser and performing a 'save changes' operation). It also runs a series of wikifications tests that work off the data in <code>test/wikitests/</code>.</li><li> <code>tw5.sh</code>/<code>tw5.bat</code> builds TiddlyWiki5 as a static HTML file</li><li> <code>tw5s.sh</code>/<code>tw5s.bat</code> serves TiddlyWiki5 over HTTP on port 8080</li></ul></div><br><h1>Architecture</h1><div data-tiddler-target='TiddlyWikiArchitecture' data-tiddler-template='TiddlyWikiArchitecture' class='tw-tiddler-frame'><h2> Overview</h2><br>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.<br><br>The most important transformations are from <code>text/x-tiddlywiki</code> wikitext into <code>text/html</code> or <code>text/plain</code> 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.<br><br>The key feature of wikitext is the ability to include one tiddler within another (usually referred to as <em>transclusion</em>). For example, one could have a tiddler called <em>Disclaimer</em> that contains the boilerplate of a legal disclaimer, and then include it within lots of different tiddlers with the macro call <code>&lt;&lt;tiddler Disclaimer&gt;&gt;</code>. 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.<br><br>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:<br><pre>&lt;&lt;story story:MyStoryTiddler&gt;&gt;
</code><br><h2> Notes</h2>The HTTP serving functionality built into TiddlyWiki5 is designed to support personal use scenarios. If you want to flexibly and robustly share tiddlers on the web for multiple users, you should use TiddlyWeb or TiddlySpace.<br><br><code>--servewiki</code> and <code>--servetiddlers</code> are for different purposes and should not be used together. The former is for TiddlyWiki core developers who want to be able to edit the TiddlyWiki source files in a text editor and view the results in the browser by clicking refresh; it is slow because it reloads all the TiddlyWiki JavaScript files each time the page is loaded. The latter is for experimenting with the new wikification engine.<br><br><code>--wikitest</code> looks for <code>*.tid</code> files in the specified folder. It then wikifies the tiddlers to both &quot;text/plain&quot; and &quot;text/html&quot; format and checks the results against the content of the <code>*.html</code> and <code>*.txt</code> files in the same directory.<br><br><code>--links</code> controls the way that links are generated. Currently, the only option supported is:<br><br> <code>none</code>: Tiddler links are disabled<br><br><br></div><br><h1>Testing</h1><div data-tiddler-target='Testing' data-tiddler-template='Testing' class='tw-tiddler-frame'><h1>Test Scripts</h1><br>Three test scripts are provided, each as a Mac OS X <code>*.sh</code> bash script and a Windows <code>*.bat</code> batch file. In each case they should be run with the current directory set to the directory in which they reside.<br><br><ul><li> <code>test.sh</code>/<code>test.bat</code> cooks the main tiddlywiki.com recipe for TiddlyWiki 2.6.5 and compares it with the results of the old build process (ie, running cook.rb and then opening the file in a browser and performing a 'save changes' operation). It also runs a series of wikifications tests that work off the data in <code>test/wikitests/</code>.</li><li> <code>tw5.sh</code>/<code>tw5.bat</code> builds TiddlyWiki5 as a static HTML file</li><li> <code>tw5s.sh</code>/<code>tw5s.bat</code> serves TiddlyWiki5 over HTTP on port 8080</li></ul></div><br><h1>Architecture</h1><div data-tiddler-target='TiddlyWikiArchitecture' data-tiddler-template='TiddlyWikiArchitecture' class='tw-tiddler-frame'><h2> Overview</h2><br>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.<br><br>The most important transformations are from <code>text/x-tiddlywiki</code> wikitext into <code>text/html</code> or <code>text/plain</code> 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.<br><br>The key feature of wikitext is the ability to include one tiddler within another (usually referred to as <em>transclusion</em>). For example, one could have a tiddler called <em>Disclaimer</em> that contains the boilerplate of a legal disclaimer, and then include it within lots of different tiddlers with the macro call <code>&lt;&lt;tiddler Disclaimer&gt;&gt;</code>. 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.<br><br>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:<br><pre>&lt;&lt;story story:MyStoryTiddler&gt;&gt;
</pre>The story macro looks for a list of tiddler titles in the tiddler <code>MyStoryTiddler</code>, and displays them in sequence. The subtle part is that subsequently, if <code>MyStoryTiddler</code> changes, the <code>&lt;&lt;story&gt;&gt;</code> 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 <code>MyStoryTiddler</code>:<br><pre>var storyTiddler = store.getTiddler(&quot;MyStoryTiddler&quot;);
store.addTiddler(new Tiddler(storyTiddler,{text: navigateTo + &quot;\n&quot; + storyTiddler.text}));
</pre>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.<br><h2> Tiddlers</h2>Tiddlers are an immutable dictionary of name:value pairs called fields.<br><br>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>.<br><br>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 JavaScript <code>Date</code> objects. All other fields are strings.<br><br>The <code>type</code> field identifies the representation of the tiddler text with a MIME type.<br><h2> WikiStore</h2>Groups of uniquely titled tiddlers are contained in WikiStore objects.<br><br>The WikiStore also manages the plugin modules used for macros, and operations like serializing, deserializing, parsing and rendering tiddlers.<br><br>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).<br><h2> WikiStore Events</h2>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.<br><br>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. <br><h2> Parsing and Rendering</h2>TiddlyWiki parses the content of tiddlers to build an internal tree representation that is used for several purposes:<br><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>The parse tree is built when needed, and then cached by the WikiStore until the tiddler changes.<br><br>TiddlyWiki5 uses multiple parsers:<br><ul><li> Wikitext (<code>text/x-tiddlywiki</code>) in <code>js/WikiTextParser.js</code></li><li> JavaScript (<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>Additional parsers are planned:<br><ul><li> CSS (<code>text/css</code>)</li><li> Recipe (<code>text/x-tiddlywiki-recipe</code>)</li></ul>One global instance of each parser is instantiated in <code>js/App.js</code> and registered with the main WikiStore object.<br><br>The parsers are all used the same way:<br><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

2
tiddlywiki5/store/CommandLineInterface.tid
View File

@ -47,6 +47,8 @@ This example ginsus a TiddlyWiki into its constituent tiddlers:
node tiddlywiki.js --load mywiki.html --savetiddlers tmp/tiddlers
`
!! Notes
The HTTP serving functionality built into TiddlyWiki5 is designed to support personal use scenarios. If you want to flexibly and robustly share tiddlers on the web for multiple users, you should use TiddlyWeb or TiddlySpace.
`--servewiki` and `--servetiddlers` are for different purposes and should not be used together. The former is for TiddlyWiki core developers who want to be able to edit the TiddlyWiki source files in a text editor and view the results in the browser by clicking refresh; it is slow because it reloads all the TiddlyWiki JavaScript files each time the page is loaded. The latter is for experimenting with the new wikification engine.
`--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.