kopia lustrzana https://github.com/miklobit/TiddlyWiki5
Docs update
rodzic
e0b630686e
commit
cd824a350a
29
readme.md
29
readme.md
File diff suppressed because one or more lines are too long
|
@ -9,11 +9,11 @@ tags: docs
|
||||||
|
|
||||||
! Concepts
|
! Concepts
|
||||||
|
|
||||||
* [[Tiddler]]
|
* [[Tiddlers]]
|
||||||
* [[Wiki]]
|
* [[Wiki]]
|
||||||
* TiddlyWiki
|
* TiddlyWiki
|
||||||
* WikiText
|
* WikiText
|
||||||
* [[Filters]]
|
* TiddlerFilters
|
||||||
* TiddlerFields
|
* TiddlerFields
|
||||||
* ShadowTiddlers
|
* ShadowTiddlers
|
||||||
* TiddlerModules
|
* TiddlerModules
|
||||||
|
|
|
@ -0,0 +1,51 @@
|
||||||
|
title: ParsingMechanism
|
||||||
|
tags: docs mechanism
|
||||||
|
|
||||||
|
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}}}) in `js/WikiTextParser.js`
|
||||||
|
* JavaScript ({{{text/javascript}}}) in `js/JavaScriptParser.js`
|
||||||
|
* Images ({{{image/png}}} and {{{image/jpg}}}) in `js/ImageParser.js`
|
||||||
|
* JSON ({{{application/json}}}) in `js/JSONParser.js`
|
||||||
|
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:
|
||||||
|
|
||||||
|
$$$.js
|
||||||
|
var parseTree = parser.parse(type,text) // Parses the text and returns a parse tree object
|
||||||
|
$$$
|
||||||
|
|
||||||
|
The parse tree object exposes the following fields:
|
||||||
|
|
||||||
|
$$$.js
|
||||||
|
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.
|
|
@ -1,24 +1,20 @@
|
||||||
title: ReadMe
|
title: ReadMe
|
||||||
tags: introduction
|
tags: introduction
|
||||||
|
|
||||||
!Welcome to TiddlyWiki5
|
! Welcome to TiddlyWiki5
|
||||||
|
|
||||||
<<tiddler HelloThere>>
|
<<tiddler HelloThere>>
|
||||||
|
|
||||||
!Usage
|
! Usage
|
||||||
|
|
||||||
<<tiddler CommandLineInterface>>
|
<<tiddler CommandLineInterface>>
|
||||||
|
|
||||||
!Architecture
|
! Architecture
|
||||||
|
|
||||||
<<tiddler TiddlyWikiArchitecture>>
|
<<tiddler TiddlyWikiArchitecture>>
|
||||||
|
|
||||||
!Plugin Mechanism
|
! Plugin Mechanism
|
||||||
|
|
||||||
<<tiddler PluginMechanism>>
|
<<tiddler PluginMechanism>>
|
||||||
|
|
||||||
!Planned WikiText Features
|
|
||||||
|
|
||||||
<<tiddler NewWikiTextFeatures>>
|
|
||||||
|
|
||||||
//This `readme` file was automatically generated by TiddlyWiki5//
|
//This `readme` file was automatically generated by TiddlyWiki5//
|
||||||
|
|
|
@ -0,0 +1,38 @@
|
||||||
|
title: RenderingMechanism
|
||||||
|
tags: docs mechanism
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
$$$.js
|
||||||
|
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:
|
||||||
|
renderer.rerender(node,changes,tiddler,store,renderStep);
|
||||||
|
}}}
|
||||||
|
|
||||||
|
The parameters to `rerender()` are:
|
||||||
|
|
||||||
|
|!Name |!Description |
|
||||||
|
|node |A reference to the DOM node containing the rendering to be rerendered |
|
||||||
|
|changes |A hashmap of `{title: "created|modified|deleted"}` indicating which tiddlers have changed since the original rendering |
|
||||||
|
|tiddler |The tiddler providing the rendering context |
|
||||||
|
|store |The store to use for resolving references to other tiddlers |
|
||||||
|
|renderStep |See below |
|
||||||
|
|
||||||
|
Currently, the only macro that supports rerendering is the `<<story>>` macro; all other macros are rerendered by calling the ordinary `render()` method again. The reason that the `<<story>>` macro goes to the trouble of having a `rerender()` method is so that it can be carefully selective about not disturbing tiddlers in the DOM that aren't affected by the change. If there were, for instance, a video playing in one of the open tiddlers it would be reset to the beginning if the tiddler were rerendered.
|
|
@ -0,0 +1,12 @@
|
||||||
|
title: Tiddlers
|
||||||
|
tags: docs concepts
|
||||||
|
|
||||||
|
!! 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.
|
|
@ -1,7 +1,7 @@
|
||||||
title: TiddlyWiki
|
title: TiddlyWiki
|
||||||
modifier: JeremyRuston
|
modifier: JeremyRuston
|
||||||
modified: 20120211110622
|
modified: 20120211110622
|
||||||
tag: introduction
|
tag: docs concepts
|
||||||
|
|
||||||
TiddlyWiki is a rich, interactive interface for manipulating complex data with structure that doesn't easily fit into conventional tools like spreadsheets or wordprocessors.
|
TiddlyWiki is a rich, interactive interface for manipulating complex data with structure that doesn't easily fit into conventional tools like spreadsheets or wordprocessors.
|
||||||
|
|
||||||
|
|
|
@ -1,6 +1,6 @@
|
||||||
title: TiddlyWikiArchitecture
|
title: TiddlyWikiArchitecture
|
||||||
modifier: JeremyRuston
|
modifier: JeremyRuston
|
||||||
tags: internals
|
tags: docs internals
|
||||||
|
|
||||||
!! Overview
|
!! Overview
|
||||||
|
|
||||||
|
@ -25,115 +25,4 @@ store.addTiddler(new Tiddler(storyTiddler,{text: navigateTo + "\n" + storyTiddle
|
||||||
|
|
||||||
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.
|
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:
|
|
||||||
|
|
||||||
* 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}}}) in `js/WikiTextParser.js`
|
|
||||||
* JavaScript ({{{text/javascript}}}) in `js/JavaScriptParser.js`
|
|
||||||
* Images ({{{image/png}}} and {{{image/jpg}}}) in `js/ImageParser.js`
|
|
||||||
* JSON ({{{application/json}}}) in `js/JSONParser.js`
|
|
||||||
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:
|
|
||||||
|
|
||||||
$$$.js
|
|
||||||
var parseTree = parser.parse(type,text) // Parses the text and returns a parse tree object
|
|
||||||
$$$
|
|
||||||
|
|
||||||
The parse tree object exposes the following fields:
|
|
||||||
|
|
||||||
$$$.js
|
|
||||||
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:
|
|
||||||
|
|
||||||
$$$.js
|
|
||||||
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:
|
|
||||||
renderer.rerender(node,changes,tiddler,store,renderStep);
|
|
||||||
}}}
|
|
||||||
|
|
||||||
The parameters to `rerender()` are:
|
|
||||||
|
|
||||||
|!Name |!Description |
|
|
||||||
|node |A reference to the DOM node containing the rendering to be rerendered |
|
|
||||||
|changes |A hashmap of `{title: "created|modified|deleted"}` indicating which tiddlers have changed since the original rendering |
|
|
||||||
|tiddler |The tiddler providing the rendering context |
|
|
||||||
|store |The store to use for resolving references to other tiddlers |
|
|
||||||
|renderStep |See below |
|
|
||||||
|
|
||||||
Currently, the only macro that supports rerendering is the `<<story>>` macro; all other macros are rerendered by calling the ordinary `render()` method again. The reason that the `<<story>>` macro goes to the trouble of having a `rerender()` method is so that it can be carefully selective about not disturbing tiddlers in the DOM that aren't affected by the change. If there were, for instance, a video playing in one of the open tiddlers it would be reset to the beginning if the tiddler were rerendered.
|
|
||||||
|
|
|
@ -0,0 +1,16 @@
|
||||||
|
title: Wiki
|
||||||
|
tags: docs concepts
|
||||||
|
|
||||||
|
!! ~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.
|
Ładowanie…
Reference in New Issue