How to create plugins in the browser
The recommended technique for building TiddlyWiki plugins involves running TiddlyWiki on Node.js, but there is now an experimental technique for creating plugins directly in the browser.
Loading a plugin in the browser has several consequences:
- The original plugin tiddler itself is unchanged
- The payload tiddlers are set up as individual ShadowTiddlers
To make a modified copy of a plugin, one edits the constituent shadow tiddlers (doing this actually overrides the shadow tiddler with a new non-shadow tiddler containing the modified content). The repacking process retrieves the current value of all the shadow tiddlers included in the plugin, and then bundles the new values back into the original plugin tiddler.
Step by step
1. Setup your development environment
Start with a blank TiddlyWiki. It is useful to create a HelloThere tiddler that contains links to various tiddlers that you'll be opening frequently during plugin development:
- The plugin itself (eg
- The payload tiddlers that are to be packed into the plugin (eg
2. Create the plugin tiddler
Click the link to the plugin tiddler to open it. Assuming it doesn't currently exist, it will open with an italicised title, indicating that it is a missing tiddler. Then switch to edit mode and set the following fields on the tiddler:
|dependents||Space separated list of dependent plugins (use square brackets for titles containing spaces)|
|plugin-type||Either "plugin" for a regular plugin, "theme" for a theme, or "language" for a language pack|
|type||Set to "application/json"|
|version||Set to the version number of the plugin (eg "0.0.1")|
Then in the body of the tiddler, insert:
Save the plugin tiddler
3. Modify the payload tiddlers
Create the payload tiddlers by clicking on the links in the HelloThere tiddler from step 1.
4. Pack the plugin
You should see a confirmation message, and then if you inspect the plugin tiddler you should see that it has been filled with the payload tiddlers.
Each time you save the plugin the last portion of the version number is automatically incremented. This will ensure that users with an older version of your plugin will be able to install the new version.
5. Testing the plugin
To test the plugin, first make sure that it has been packed. Then save changes and refresh the page in order to load the new plugin.
6. Repacking the plugin
Once you've built the plugin for the first time you can omit the second parameter to
repackPlugin() unless you are adding a new tiddler:
7. Removing tiddlers from the plugin
To remove tiddlers from the plugin specify their titles in the optional third parameter:
Creating theme and language plugins
Before attempting to repack your plugin you should ensure that the plugin is selected as the current theme or language. Otherwise the shadow tiddlers will not be present.