diff --git a/readme.md b/readme.md index d5edc0a01..569d9bcce 100644 --- a/readme.md +++ b/readme.md @@ -14,7 +14,7 @@ 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:
NameDescription
nodeA reference to the DOM node containing the rendering to be rerendered
changesA hashmap of {title: "created|modified|deleted"} indicating which tiddlers have changed since the original rendering
tiddlerThe tiddler providing the rendering context
storeThe store to use for resolving references to other tiddlers
renderStepSee 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.



Plugin Mechanism

Introduction

TiddlyWiki5 is based on a 500 line boot kernel that runs on node.js or in the browser, and everything
else is plugins.

The kernel boots just enough of the TiddlyWiki environment to allow it to load tiddlers as plugins and execute them (a barebones tiddler class, a barebones wiki store class, some utilities etc.). Plugin modules are written like node.js modules; you can use require() to invoke sub components and to control load order.

There are several different types of plugins: parsers, serializers, deserializers, macros etc. It goes much further than you might expect. For example, individual tiddler fields are plugins, too: there's a plugin that knows how to handle the tags field, and another that knows how to handle the special behaviour of
the modified and created fields.

Some plugins have further sub-plugins: the wikitext parser, for instance, accepts rules as individual plugins.

Plugins and Modules

In TiddlyWiki5, a plugin is a bundle of related tiddlers that are distributed together as a single unit. Plugins can include tiddlers which are JavaScript modules.

The file core/boot.js is a barebones TiddlyWiki kernel that is just sufficient to load the core plugin modules and trigger a startup plugin module to load up the rest of the application.

The kernel includes:

Each module is an ordinary node.js-style module, using the require() function to access other modules and the exports global to return JavaScript values. The boot kernel smooths over the differences between node.js and the browser, allowing the same plugin modules to execute in both environments.

In the browser, core/boot.js is packed into a template HTML file that contains the following elements in order:


On the server, core/boot.js is executed directly. It uses the node.js local file API to load plugins directly from the file system in the core/modules directory. The code loading is performed synchronously for brevity (and because the system is in any case inherently blocked until plugins are loaded).

The boot kernel sets up the $tw global variable that is used to store all the state data of the system.

Core


The 'core' is the boot kernel plus the set of plugin modules that it loads. It contains plugins of the following types:

TiddlyWiki5 makes extensive use of JavaScript inheritance:

Planned WikiText Features

It is proposed to extend the existing TiddlyWiki WikiText syntax with the following extensions

  1. Addition of **bold** character formatting
  2. Addition of `backtick for code` character formatting
  3. Addition of WikiCreole-style forced line break, e.g. force\\linebreak
  4. Addition of WikiCreole-style headings, e.g. ==Heading
  5. Addition of WikiCreole-style headings in tables, e.g. |=|=table|=header|
  6. Addition of white-listed HTML and SVG tags intermixed with wikitext
  7. Addition of WikiCreole-style pretty links, e.g. [[description -> link]]
  8. Addition of multiline macros, e.g.
<<myMacro
+
The parameters to rerender() are:
NameDescription
nodeA reference to the DOM node containing the rendering to be rerendered
changesA hashmap of {title: "created|modified|deleted"} indicating which tiddlers have changed since the original rendering
tiddlerThe tiddler providing the rendering context
storeThe store to use for resolving references to other tiddlers
renderStepSee 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.



Plugin Mechanism

Introduction

TiddlyWiki5 is based on a 500 line boot kernel that runs on node.js or in the browser, and everything
else is plugins.

The kernel boots just enough of the TiddlyWiki environment to allow it to load tiddlers as plugins and execute them (a barebones tiddler class, a barebones wiki store class, some utilities etc.). Plugin modules are written like node.js modules; you can use require() to invoke sub components and to control load order.

There are several different types of plugins: parsers, serializers, deserializers, macros etc. It goes much further than you might expect. For example, individual tiddler fields are plugins, too: there's a plugin that knows how to handle the tags field, and another that knows how to handle the special behaviour of
the modified and created fields.

Some plugins have further sub-plugins: the wikitext parser, for instance, accepts rules as individual plugins.

Plugins and Modules

In TiddlyWiki5, a plugin is a bundle of related tiddlers that are distributed together as a single unit. Plugins can include tiddlers which are JavaScript modules.

The file core/boot.js is a barebones TiddlyWiki kernel that is just sufficient to load the core plugin modules and trigger a startup plugin module to load up the rest of the application.

The kernel includes:

Each module is an ordinary node.js-style module, using the require() function to access other modules and the exports global to return JavaScript values. The boot kernel smooths over the differences between node.js and the browser, allowing the same plugin modules to execute in both environments.

In the browser, core/boot.js is packed into a template HTML file that contains the following elements in order:


On the server, core/boot.js is executed directly. It uses the node.js local file API to load plugins directly from the file system in the core/modules directory. The code loading is performed synchronously for brevity (and because the system is in any case inherently blocked until plugins are loaded).

The boot kernel sets up the $tw global variable that is used to store all the state data of the system.

Core


The 'core' is the boot kernel plus the set of plugin modules that it loads. It contains plugins of the following types:

TiddlyWiki5 makes extensive use of JavaScript inheritance:

tiddlywiki.plugin files


Planned WikiText Features

It is proposed to extend the existing TiddlyWiki WikiText syntax with the following extensions

  1. Addition of **bold** character formatting
  2. Addition of `backtick for code` character formatting
  3. Addition of WikiCreole-style forced line break, e.g. force\\linebreak
  4. Addition of WikiCreole-style headings, e.g. ==Heading
  5. Addition of WikiCreole-style headings in tables, e.g. |=|=table|=header|
  6. Addition of white-listed HTML and SVG tags intermixed with wikitext
  7. Addition of WikiCreole-style pretty links, e.g. [[description -> link]]
  8. Addition of multiline macros, e.g.
<<myMacro
 param1: Parameter value
 param2: value
 "unnamed parameter"
diff --git a/tw5.com/tiddlers/PluginMechanism.tid b/tw5.com/tiddlers/PluginMechanism.tid
index f8c176aa1..132a53695 100644
--- a/tw5.com/tiddlers/PluginMechanism.tid
+++ b/tw5.com/tiddlers/PluginMechanism.tid
@@ -59,3 +59,6 @@ The 'core' is the boot kernel plus the set of plugin modules that it loads. It c
 TiddlyWiki5 makes extensive use of JavaScript inheritance:
 * Tree nodes defined in `$:/core/treenodes/` all inherit from `$:/core/treenodes/node.js`
 * Macros defined in `$:/core/macros/` all inherit from `$:/core/treenodes/macro.js`
+
+`tiddlywiki.plugin` files
+