mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-11-24 18:47:20 +00:00
78 lines
3.7 KiB
Plaintext
78 lines
3.7 KiB
Plaintext
modified: 201305011454
|
|
title: PluginMechanism
|
|
tags: docs mechanism
|
|
|
|
[[Plugins]] are bundles of tiddlers that are distributed and managed as a single unit by being packed into a single JSON tiddler. If a tiddler isn't found in the main store, then the registered plugins are searched for it instead.
|
|
|
|
Tiddlers within plugins behave something like shadow tiddlers in classic TiddlyWiki: they can be freely overwritten by creating a tiddler with the same title, but deleting that tiddler restores the underlying tiddler value from the plugin.
|
|
|
|
Plugins also have a `plugin-type` field that may be:
|
|
|
|
* `plugin` //(default)// - a plain plugin
|
|
* `theme` - a theme plugin (see ThemeMechanism)
|
|
|
|
Plugins can be used to package ordinary content, or can include JavaScript [[modules|Modules]] that extend and enhance the core TiddlyWiki5 functionality.
|
|
|
|
Plugins conventionally have a title of the form `$:/plugins/publisher/name`. Plugins that are part of the core TiddlyWiki distribution have titles of the form `$:/plugins/tiddlywiki/name`.
|
|
|
|
Plugins that define macros, views or other named entities are expected to prefix the name with their publisher identifier, for example: `tiddlytools.slider`.
|
|
|
|
! Plugin format
|
|
|
|
Plugins are stored as tiddlers of type `application/json` with the field `plugin` present and the text containing a JSON structure encoding the plugin metadata and the list of tiddlers within it.
|
|
|
|
The JSON structure for plugin tiddlers is as follows:
|
|
|
|
```
|
|
{
|
|
"title": "$:/plugins/publisher/name",
|
|
"description": "An exemplary plugin for demonstration purposes",
|
|
"author": "JeremyRuston",
|
|
"version": "1.2.3-alpha3",
|
|
"coreVersion": ">=5.0.0",
|
|
"source": "http://tiddlywiki.com/MyPlugin",
|
|
"plugin-type": "plugin",
|
|
"tiddlers": {
|
|
"$:/plugins/publisher/name/title1": {"type": "image/png", "text": "<base64>"},
|
|
"title2": {"text": "Text"}
|
|
}
|
|
}
|
|
```
|
|
|
|
The titles of the individual tiddlers are typically prefixed with the title of the containing plugin (as in the **title1** example above), but they are not restricted to do so (the second example specifies a tiddler with the raw title **title2**).
|
|
|
|
! Plugin folders
|
|
|
|
On the server, plugins can be stored as ordinary JSON tiddlers but it is often more convenient to store them as separate tiddler files within folders. Plugin folders must contain a `plugin.info` file that contains the metadata for the plugin. It can also optionally identify files external to the plugin folder that should be loaded as tiddlers.
|
|
|
|
The `plugin.info` file should contain the same JSON as given for plugin tiddlers above, with the `tiddlers` object omitted.
|
|
|
|
! Plugin library
|
|
|
|
The standard distribution of TiddlyWiki includes a number of standard plugins in the `plugins` directory.
|
|
|
|
! Including plugins in a wiki
|
|
|
|
To be usable in the browser, plugins just need to be included in the wiki. This is done when the wiki is generated on the server.
|
|
|
|
A folder containing an exploded TiddlyWiki can contain a `tiddlywiki.info` file that identifies the plugins to be included in this wiki:
|
|
|
|
```
|
|
{
|
|
"plugins": [
|
|
"tiddlywiki/slider",
|
|
"tiddlytools/chooser"
|
|
]
|
|
}
|
|
```
|
|
|
|
Plugins names refer to plugin folders listed in TiddlyWiki5's root `plugins` folder.
|
|
|
|
Plugins can also be included manually by copying them into the `plugins` subfolder of the wiki.
|
|
|
|
! Plugin processing
|
|
|
|
The wiki object keeps track of all of the currently loaded plugins. If a request for a tiddler isn't in the store then the wiki looks through the cascade of plugins to find the requested tiddler. It is a similar idea to the way that shadow tiddlers are implemented in classic TiddlyWiki.
|
|
|
|
In the browser, any constituent tiddlers that are JavaScript modules (ie shadow tiddlers of content type `application/javascript` and possessing the field `module-type`) are executed during startup processing.
|