Note: An alternative skin, TW4MW (work in progress), is available from the user preferences.
Dev:Plugin Specifications
TiddlyWiki Community Wiki
This page provides guidelines for structuring plugin tiddlers.
A standardized, consistent structure simplifies automated aggregation (cf. Plugin Library), and also provides easy-to-follow guidelines for new TiddlyWiki developers.
Generally, a plugin consists of two basic sections: The metadata (i.e. description) and the actual JavaScript code.
Contents |
[edit] Metadata
The metadata section is divided into two parts: The machine-readable meta fields and the documentation.
[edit] Meta-Slices
| Field | Used By | Description | Notes |
|---|---|---|---|
| Name | TiddlyWiki core | plugin designation | usually corresponds to the respective tiddler title |
| Description | TiddlyWiki core | concise description of the plugin's functionality | |
| Icon | Plugin Library | URL to image identifying the author(s) and/or the plugin | recommended image dimensions: 100x100 px |
| Author | Plugin Library | main developers' and/or maintainers' names | multiple names separated by semicolon; can contain PrettyLinks (e.g. e-mail address) |
| Contributors | convention only | contributors' names | multiple names separated by semicolon; can contain PrettyLinks (e.g. e-mail address) |
| Version | convention only | plugin version number | |
| Date | convention only | latest release date | ideally ISO 8601 format |
| Status | Plugin Library | development status (stability) | supported values: //unknown//; @@experimental@@; @@beta@@; //obsolete//; stable |
| Source | Plugin Library | plugin origin (direct TiddlyWiki permalink) | can contain PrettyLink |
| CodeRepository | convention only | developers' development repository | can contain PrettyLink |
| Copyright | convention only | copyright holder | |
| License | convention only | plugin license | N.B.: if unspecified, regular copyright applies |
| CoreVersion | TiddlyWiki core | required TiddlyWiki core version | can contain PrettyLink |
| Requires | TiddlyWiki core | dependencies; list of plugin names | bracketed list |
| Overrides | convention only | core functions replaced by this plugin | |
| Feedback | convention only | location to submit feedback | |
| Documentation | Plugin Library | location of the plugin documentation (e.g. ##Usage to reference the respective documentation section)
| |
| Demonstration | [TBD] | location of the plugin demonstration (e.g. ##Examples to reference the respective documentation section)
| |
| Keywords | [TBD] | plugin categorization | bracketed list |
[edit] Documentation Sections
| Title | Purpose | Notes |
|---|---|---|
| Description | detailed description | |
| Notes | general remarks (e.g. limitations, alternative implementations) | |
| Usage | usage instructions (e.g. syntax) | |
| Parameters | list of macro parameters (sequential or named) | sub-section of Usage |
| Examples | usage examples | sub-section of Usage |
| Configuration | plugin-specific settings | |
| Revision History | version history | one sub-section per version |
| To Do | further development tasks |
Extensive documentation content can be moved to a separate tiddler (e.g. <pluginName>Documentation).
[edit] Code
Ideally the plugin's JavaScript code is presented as a preformatted block:
//{{{
<...>
//}}}
Alternatively, the source code can be hidden by wrapping it in the respective comment markers:
///% <...> //%/
[edit] Template
The latest version of this SamplePlugin is available in the TiddlyWiki Subversion repository.
/*** |''Name''|SamplePlugin| |''Description''|<...>| |''Icon''|<...>| |''Author''|<...>| |''Contributors''|<...>| |''Version''|<...>| |''Date''|<...>| |''Status''|<//unknown//; @@experimental@@; @@beta@@; //obsolete//; stable>| |''Source''|<...>| |''CodeRepository''|<...>| |''Copyright''|<...>| |''License''|<...>| |''CoreVersion''|<...>| |''Requires''|<...>| |''Overrides''|<...>| |''Feedback''|<...>| |''Documentation''|<...>| |''Keywords''|<...>| !Description <...> !Notes <...> !Usage {{{ <<sampleMacro>> }}} !!Parameters <...> !!Examples <<sampleMacro>> !Configuration Options <...> !Revision History !!v<#.#> (<yyyy-mm-dd>) * <...> !To Do <...> !Code ***/ //{{{ if(!version.extensions.SamplePlugin) { //# ensure that the plugin is only installed once version.extensions.SamplePlugin = { installed: true }; if(!config.extensions) { config.extensions = {}; } //# obsolete from v2.4.2 config.extensions.SamplePlugin = { sampleFunction: function() { /* ... */ } }; config.macros.SampleMacro = { handler: function(place, macroName, params, wikifier, paramString, tiddler) { /* ... */ } }; } //# end of "install only once" //}}}
