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.

Introduced in v5.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 Stability

Plugins are recommended to have a stability field that communicates the state of development of the plugin. It can contain the following values:

• STABILITY_0_DEPRECATED - Deprecated. This plugin is not recommended for new projects
• STABILITY_1_EXPERIMENTAL - Experimental. Non-backward compatible changes or removal may occur in any future release. Use of the plugin is not recommended in production environments
• STABILITY_2_STABLE - Stable.
• STABILITY_3_LEGACY - Legacy. Although this plugin is unlikely to be removed, it is no longer actively maintained, and other alternatives are available

These stability levels are taken from the Node.js project - https://nodejs.org/api/documentation.html#stability-index.

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:

• import - for the special $:/Import plugin created while importing is in progress
• info - for the special $:/temp/info-plugin tiddler created by the InfoMechanism

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

Using the Node.js client-server configuration plugins are activated in the following order:

1. Plugins found using the OS environment variables
   • See: PluginFolders
   • and: Environment Variables on Node.js
2. Plugins stored in the wiki /plugins path
   • See: PluginFolders
3. Plugins specified in the command line
   • See: Using TiddlyWiki on Node.js ... the notes about Introduced in v5.1.20
4. Plugins imported by drag and drop as wiki content
   • See: Installing a plugin from the plugin library or Manually installing a plugin

Important:

• Elements lower in the list take precedence
• Including a plugin as an ordinary tiddler by drag and drop into the browser, will result in the plugin only being active in the browser
  • It will not be available under Node.js

Option 1:

• Using a Node.js configuration option 1 is the most common one
• It lowers maintenence, because all plugins can be updated in one go

Option 2:

• Option 2 is preferred if you want to work with a fixed configuration
• Plugin updates only effect the corresponding wiki

Option 3:

• This option allows to add and start an edition without the need to overwrite an existing tiddlywiki.info file
• It allows you to start any edition as a client-server edition, even if the tiddlywiki.info file didn't specify it.

Option 4:

• Is the exact same mechanism used for a single-file wiki
• This mechanism should only be used in a Node.js configuration for testing and debugging purposes, since the plugins are stored in the tiddlers/ directory

Plugin Fields

Plugins are stored as tiddlers with the following fields:

More information

• Disabling Plugins
• Plugin Dependencies
• Plugin Fields
• Plugin Information Tiddlers
• Plugin Ordering
• Plugin Stability
• Plugin Types
• PluginFolders