mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-12-25 01:20:30 +00:00
Docs updates
This commit is contained in:
Jeremy Ruston
parent
363e90fca8
commit
1d0eed6957
@ -1,4 +1,45 @@
|
||||
title: ParsingMechanism
|
||||
tags: mechanism
|
||||
created: 201311011307
|
||||
modified: 201311011307
|
||||
|
||||
! Introduction
|
||||
|
||||
The parsing mechanism analyses the text of a tiddler against a set of parsing rules, producing a tree representing the structure of the text. The RenderingMechanism is used to transform parse trees into render trees of widget nodes.
|
||||
|
||||
TiddlyWiki5 includes ParserModules for several types of tiddler:
|
||||
|
||||
* WikiText
|
||||
* Raw HTML
|
||||
* Plain text
|
||||
* Images (bitmap, SVG and PDF)
|
||||
|
||||
The WikiText parser is the most complex, comprising separate individual WikiRuleModules encapsulating each parsing rule.
|
||||
|
||||
! Parse Trees
|
||||
|
||||
The output of parsing a tiddler is an object containing a tree of parse nodes corresponding to the original text. For example:
|
||||
|
||||
```
|
||||
> JSON.stringify($tw.wiki.parseText("text/vnd.tiddlywiki","Some //italics// and a {{Transclusion}}.").tree)
|
||||
|
||||
[
|
||||
{type: "element", tag: "p", children: [
|
||||
{type: "text", text: "Some "},
|
||||
{type: "element", tag: "em", children: [
|
||||
{type: "text", text: "italics"}
|
||||
]},
|
||||
{type: "text", text: " and a "},
|
||||
{type: "tiddler", attributes:{
|
||||
tiddler: {type: "string", value: "Transclusion"}
|
||||
}, children:[
|
||||
{type: "transclude", attributes:{
|
||||
tiddler: {type: "string", value: "Transclusion"}
|
||||
}}
|
||||
]},
|
||||
{type: "text", text: "."}
|
||||
]}
|
||||
]
|
||||
```
|
||||
|
||||
Parse tree nodes are plain JavaScript objects, and do not have a prototype.
|
||||
|
||||
@ -1,3 +1,5 @@
|
||||
title: RenderingMechanism
|
||||
tags: mechanism
|
||||
created: 201311011307
|
||||
modified: 201311011307
|
||||
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
created: 201308251621
|
||||
creator: JeremyRuston
|
||||
modified: 201308251621
|
||||
modified: 201311011307
|
||||
modifier: JeremyRuston
|
||||
tags: dev
|
||||
tags: dev moduletypes
|
||||
title: SyncAdaptorModules
|
||||
|
||||
! Introduction
|
||||
|
||||
@ -1,2 +1,81 @@
|
||||
title: WidgetModules
|
||||
tags: dev moduletypes
|
||||
created: 201311011307
|
||||
modified: 201311011307
|
||||
|
||||
! Introduction
|
||||
|
||||
Widget modules are used as part of the RenderingMechanism to implement each type of renderable entity. As well as the widgets that are familiar to end users, the following primitives are also implemented as widgets:
|
||||
|
||||
* HTML text nodes
|
||||
* HTML element nodes
|
||||
* HTML entities
|
||||
|
||||
All widgets inherit from a base widget class that is defined in [[$:/core/modules/new_widgets/widget.js]].
|
||||
|
||||
! Widget Properties
|
||||
|
||||
The following widget properties are defined by the core. The lifecycle of a widget object is largely a matter of maintaining the consistency of these internal properties in the face of external state changes. Individual widgets usually add their own additional properties too.
|
||||
|
||||
|!Name |!Description |
|
||||
|''parseTreeNode'' |Reference to the parse tree node corresponding to this widget |
|
||||
|''wiki'' |Reference to the [[Wiki]] object associated with this widget |
|
||||
|''variables'' |Hashmap of information about each [[widget variable|WidgetVariables]] (see below) |
|
||||
|''parentWidget'' |Reference to the parent widget |
|
||||
|''document'' |Reference to the document object associated with this widget. Usually either the browser global `document` variable or a reference to the FakeDomMechanism's `$tw.document` |
|
||||
|''attributes'' |Hashmap of information about each attribute attached to this widget (see below) |
|
||||
|''children'' |Array of child widgets |
|
||||
|''domNodes'' |For widgets that directly generate DOM nodes, an array of the generated nodes |
|
||||
|''eventListeners'' |Array of event listener definitions |
|
||||
|
||||
!! Widget Variables
|
||||
|
||||
The widget variables defined on a widget are stored in a hashmap of the variable name. The hashmap contains:
|
||||
|
||||
* `name`: name of variable
|
||||
* `params`: array of parameters for macro definitions, each `{name: "<name>", default: "<optionaldefault>"}`
|
||||
* `value`: string value of variable
|
||||
|
||||
!! Widget Attributes
|
||||
|
||||
The widget attributes associated with a widget are stored in a hashmap of the attribute name. The hashmap contains an object that describes the attribute value. Currently three attribute value types are supported:
|
||||
|
||||
* Strings: `{type: "string", value: "<value>"}`
|
||||
* Tiddler text reference indirection: `{type: "indirect", textReference: "<textref>"}`
|
||||
* Macro invocation: `{type: "macro", value: {name: "<macroname>", params: [{name: "<paramname>", value: "<paramvalue>"}, ... ]}`
|
||||
|
||||
!! Widget Event Listeners
|
||||
|
||||
The event listeners attached to a widget are stored as a hashmap by event type. Each value is a handler function that accepts a single `event` parameter.
|
||||
|
||||
! Widget methods
|
||||
|
||||
The individual methods defined by the widget object are documented in the source code of [[$:/core/modules/new_widgets/widget.js]]. Here we give an overview of the overall lifecycle, and how the methods fit together
|
||||
|
||||
!! Widget `initialise` method
|
||||
!! Widget `widgetClasses` method
|
||||
!! Widget `render` method
|
||||
!! Widget `execute` method
|
||||
!! Widget `getVariable` method
|
||||
!! Widget `substituteVariableParameters` method
|
||||
!! Widget `substituteVariableReferences` method
|
||||
!! Widget `evaluateMacroModule` method
|
||||
!! Widget `setVariable` method
|
||||
!! Widget `hasVariable` method
|
||||
!! Widget `getStateQualifier` method
|
||||
!! Widget `computeAttributes` method
|
||||
!! Widget `hasAttribute` method
|
||||
!! Widget `getAttribute` method
|
||||
!! Widget `assignAttributes` method
|
||||
!! Widget `makeChildWidgets` method
|
||||
!! Widget `makeChildWidget` method
|
||||
!! Widget `renderChildren` method
|
||||
!! Widget `addEventListeners` method
|
||||
!! Widget `addEventListener` method
|
||||
!! Widget `dispatchEvent` method
|
||||
!! Widget `refresh` method
|
||||
!! Widget `refreshSelf` method
|
||||
!! Widget `refreshChildren` method
|
||||
!! Widget `findNextSiblingDomNode` method
|
||||
!! Widget `findFirstDomNode` method
|
||||
!! Widget `removeChildDomNodes` method
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
created: 201308252147
|
||||
creator: JeremyRuston
|
||||
modified: 201308252147
|
||||
modified: 201311011307
|
||||
modifier: JeremyRuston
|
||||
tags: dev moduletypes
|
||||
title: WikiRuleModules
|
||||
|
||||
@ -14,5 +14,5 @@ The checkbox widget displays an HTML `<input type="checkbox">` element that is d
|
||||
The content of the `<$checkbox>` widget is displayed within an HTML `<label>` element immediately after the checkbox itself. This means that clicking on the content will toggle the checkbox.
|
||||
|
||||
|!Attribute |!Description |
|
||||
|tiddler |Title of the tiddler to manipulate (defaults to the [[TiddlerVariable: currentTiddler]]) |
|
||||
|tiddler |Title of the tiddler to manipulate (defaults to the [[WidgetVariable: currentTiddler]]) |
|
||||
|tag |The name of the tag to which the checkbox should be bound |
|
||||
|
||||
@ -14,4 +14,4 @@ The edit bitmap widget provides a user interface in the browser for editing bitm
|
||||
The content of the `<$edit-bitmap>` widget is ignored.
|
||||
|
||||
|!Attribute |!Description |
|
||||
|tiddler |The tiddler to edit (defaults to the [[TiddlerVariable: currentTiddler]]) |
|
||||
|tiddler |The tiddler to edit (defaults to the [[WidgetVariable: currentTiddler]]) |
|
||||
|
||||
@ -16,7 +16,7 @@ By default, the edit text widget generates a `<textarea>` as the HTML editing el
|
||||
The content of the `<$edit-text>` widget is ignored.
|
||||
|
||||
|!Attribute |!Description |
|
||||
|tiddler |The tiddler to edit (defaults to the [[TiddlerVariable: currentTiddler]]) |
|
||||
|tiddler |The tiddler to edit (defaults to the [[WidgetVariable: currentTiddler]]) |
|
||||
|field |The field to edit (defaults to `text`). Takes precedence over the `index` attribute |
|
||||
|index |The index to edit |
|
||||
|default |The default text to be provided when the target tiddler doesn't exist |
|
||||
|
||||
@ -14,7 +14,7 @@ The edit widget provides a general purpose interface for editing a tiddler. It d
|
||||
The content of the `<$edit>` widget is ignored.
|
||||
|
||||
|!Attribute |!Description |
|
||||
|tiddler |The tiddler to edit (defaults to the [[TiddlerVariable: currentTiddler]]) |
|
||||
|tiddler |The tiddler to edit (defaults to the [[WidgetVariable: currentTiddler]]) |
|
||||
|field |The field to edit (defaults to `text`). Takes precedence over the `index` attribute |
|
||||
|index |The index to edit |
|
||||
|class |A CSS class to be added the generated editing widget |
|
||||
|
||||
@ -20,4 +20,4 @@ The field manager widget manipulates the fields and tags of a tiddler. It does s
|
||||
The field mangler widget displays any contained content, and responds to WidgetMessages dispatched within it.
|
||||
|
||||
|!Attribute |!Description |
|
||||
|tiddler |Title of the tiddler to manipulate (defaults to the [[TiddlerVariable: currentTiddler]]) |
|
||||
|tiddler |Title of the tiddler to manipulate (defaults to the [[WidgetVariable: currentTiddler]]) |
|
||||
|
||||
@ -23,7 +23,7 @@ The provided template is rendered with the following special substitutions:
|
||||
The content of the `<$fields>` widget is ignored.
|
||||
|
||||
|!Attribute |!Description |
|
||||
|tiddler |Title of the tiddler from which the fields are to be displayed (defaults to the [[TiddlerVariable: currentTiddler]]) |
|
||||
|tiddler |Title of the tiddler from which the fields are to be displayed (defaults to the [[WidgetVariable: currentTiddler]]) |
|
||||
|template |Text of the template (see above) |
|
||||
|exclude |Lists of fields to be excluded (defaults to "text") |
|
||||
|stripTitlePrefix |If set to "yes" then curly bracketed prefixes are removed from titles (for example `{prefix}HelloThere` converts to `HelloThere`) |
|
||||
|
||||
@ -6,7 +6,7 @@ The `link` widget generates links to tiddlers.
|
||||
! Content and Attributes
|
||||
|
||||
|!Attribute |!Description |
|
||||
|to |The title of the target tiddler for the link (defaults to the [[TiddlerVariable: currentTiddler]]) |
|
||||
|to |The title of the target tiddler for the link (defaults to the [[WidgetVariable: currentTiddler]]) |
|
||||
|
||||
The content of the link widget is rendered within the `<a>` tag.
|
||||
|
||||
|
||||
@ -7,7 +7,7 @@ tags: widget
|
||||
|
||||
! Introduction
|
||||
|
||||
The set variable widget assigns a value to a specified [[variable|TiddlerVariables]]. The new value of the variable is availale to the content within the set variable widget.
|
||||
The set variable widget assigns a value to a specified [[variable|WidgetVariables]]. The new value of the variable is availale to the content within the set variable widget.
|
||||
|
||||
! Content and Attributes
|
||||
|
||||
|
||||
@ -14,7 +14,7 @@ The view widget displays the contents of a tiddler field in a specified format.
|
||||
The content of the `<$view>` widget is ignored.
|
||||
|
||||
|!Attribute |!Description |
|
||||
|tiddler |The title of the tiddler (defaults to the [[TiddlerVariable: currentTiddler]]) |
|
||||
|tiddler |The title of the tiddler (defaults to the [[WidgetVariable: currentTiddler]]) |
|
||||
|field |The name of the field to view (defaults to "text") |
|
||||
|format |The format for displaying the field (see below) |
|
||||
|template |The optional template used with certain formats |
|
||||
|
||||
Loading…
Reference in New Issue
Block a user