This page is part of a static HTML representation of the TiddlyWiki at https://tiddlywiki.com/

PluginMechanism

28th September 2019 at 8:20am
Mechanisms

Introduction

Plugins are bundles of tiddlers that are distributed and managed as a single unit. Users can install them with drag and drop, or using the plugin library.

New in: 5.1.22 Plugins that contain JavaScript modules require a reload of the wiki before they will work. Plugins that do not contain JavaScript modules are automatically dynamically loaded and unloaded.

Plugins can be used to package any tiddler content, including JavaScript modules that extend and enhance the core TiddlyWiki5 functionality. The tiddlers within registered plugins are ShadowTiddlers: 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.

By convention, plugin titles have the form $:/plugins/<publisher>/<name>. Plugins that are part of the core TiddlyWiki distribution have titles of the form $:/plugins/tiddlywiki/<name>.

When running TiddlyWiki under Node.js, plugins can also be stored as individual tiddler files in PluginFolders.

Plugin Types

Plugins have a plugin-type field that determines how it is treated. The following values are defined by the core:

  • plugin - an ordinary plugin
  • theme - a theme plugin (see ThemeMechanism). Only the theme plugin named in the tiddler $:/theme is activated at any one time (along with any dependent theme plugins)
  • language - a language plugin (see TranslationMechanism). Only the language plugin named in the tiddler $:/language is activated at any one time (along with any dependent language plugins)

The following plugin types are used internally by the core:

While not supported by the plugin library, it is also possible to use custom plugin types to build plugin-like behaviour with a custom user interface. Plugins with a custom type will automatically receive the same behaviour as plain plugins but can display a custom user interface using an appropriate view template segment.

By default, tiddlers within plugins with custom plugin types will not be registered as shadow tiddlers (the constituent tiddlers can still be addressed as subtiddlers by the TranscludeWidget, ViewWidget or the plugintiddlers Operator). Setting a configuration tiddler $:/config/RegisterPluginType/<plugin-type> to yes will cause the tiddlers within the plugin to be registered as shadow tiddlers.

Plugin Dependencies

The simplest form of dependency between plugins is that one plugin can declare itself to be a sub-plugin of another plugin by specifying that plugin in the parent-plugin field. Sub-plugins are displayed in the control panel plugin chooser within the expandable area of their parent plugin. For example, the official plugin library includes the CodeMirror Plugin and also more than a dozen sub-plugins that extend the CodeMirror plugin with optional functionality. Note that sub-plugins cannot themselves have further sub-plugins.

Plugins can also use their dependents field to list the titles of any other plugins that should also be installed. Note that the list is not resolved recursively: dependents of dependents will not be installed.

When installing a plugin from the plugin library, both the parent-plugin and dependents fields are used to determine any additional plugins to be installed.

Note that the dependents field is also used by the ThemeMechanism and the LanguageMechanism to switch in dependent theme/language plugins.

Plugin Ordering

Plugin Fields

Plugins are stored as tiddlers with the following fields:

FieldDescription
author(optional) Author of plugin
dependentsList of dependencies: plugins that should be installed in order for this one to work
descriptionDescription of plugin
listNames of exposed plugin information tiddlers (see below)
nameBrief name of the plugin
plugin-priority(optional) Numerical priority (higher numbers install later, the core plugin has a priority of zero
plugin-typeGenerally plugin, language or theme; see PluginMechanism for details
parent-plugin(optional) New in: 5.1.22 Title of the plugin under which this plugin should be displayed as a sub-plugin in the control panel plugin chooser
source(optional) Source URL of plugin
textJSON encoding of the list of tiddlers comprising the plugin
titleTitle of plugin
typeMust be application/json
version(optional) Version string (should conform to SemanticVersioning convention)

More information