Tinka

easy plugin packer

Intro

2nd August 2020 at 11:21pm

This is a Control Panel extension that helps with creating and modifying plugins in the browser. You can get the extension by dragging the following link into your own wiki: $:/plugins/ahahn/tinka

Links to more information

Project Homepage on tinkaplugin.github.io

Repository on Github

$:/ControlPanel

29th July 2020 at 7:03pm

Choose Plugin to Modify:

$:/plugins/ahahn/tinka

Tinka: An easy plugin packer

$:/plugins/ahahn/tinka

0.5.0

How to create a new plugin

To create a completely new plugin, first go to the Control Panel extension Tinka provides and click on the "Create new Plugin" button. Next enter the plugin type of the plugin you want to create or choose a type from the dropdown menu. Usually you will want to use either the value "plugin" or "theme", as this covers most cases of plugins.

Next is the plugin path: This is the name of the tiddler where the finished plugin is going to be stored in. TiddlyWiki uses a special naming theme for these, so you will mostly find that the actual tiddlers that contain a plugin are named in this scheme:

$:/plugins/myOrganisation/pluginName.

This ensures that plugins can be not only immideately recognized, but are also separate from other tiddlers in the wiki.

After also entering a title for your new plugin or theme, you are basically good to go. These three fields: plugin type, plugin path and the plugin title are all the fields that are required for a functioning plugin. In theory, you could now go ahead and press the "Package Plugin" button, which will give you an empty plugin shell to which you can add tiddlers later.

In most cases however it is desired to also fill out the rest of the metadata fields. In detail, these are:

  • (Plugin-)Name: This will be the name of the plugin that is prominently displayed in the control panel.
  • (Plugin-)Description: This is a short description of the plugin's functionality that is displayed after the name in the control panel.
  • Author: Name of the plugin author.
  • Source: Website or URL of the plugin, also the place where updates are found.
  • Dependents: List of plugins this plugin depends on (usually empty, but e.g. $:/core)
  • List: List of tiddlers contained in the plugin, that will serve as readme tiddlers, when inspecting a plugin via the control panel. (e.g. $:/plugins/ahahn/tinka/readme)
  • Version: Version of your plugin in the format: X.X.X
  • Core-Version: Usually the minimal TiddlyWiki version your plugin requires in order for it to work (e.g >=5.1.8)

After entering the metadata, all that is left is to select the tiddlers you want to include in the plugin. You can search for these via the default search field, but you can also use a filter to find them (e.g. based on a tag). In most cases it is sufficient to enter the name of the plugin into the default search in order to find the tiddlers that belong to the plugin. Lastly, just click the "Package Plugin" button and you're done, you have now created your first plugin. A save&refresh will be required for it to be loaded into TiddlyWiki.

Using the Sidebar Tab

When working on a plugin, it is often handy to be able to navigate quickly between the plugin tiddlers. That is what the Sidebar Tab is for. After enabling it in the "Tinka Plugin Management" tab for a specific plugin in the Control Panel, it gives you an additional sidebar tab, that contains a list of all the tiddlers that are contained in the plugin in question. Furthermore, it also shows you tiddlers that live in the same "directory" which are likely tiddlers that you want to add to the plugin eventually.

If you have tiddlers whose names aren't prefixed by the plugin path, you can use the Filter search included in the help tab to select those. For example, if the rest of your tiddlers is scattered somewhere in the wiki, but tagged with myPlugin, you could use the filter: [tag[myPlugin]] to select them.

The "Quick Package" button gives you the option of quickly integrating changes you made to individual tiddlers into the plugin. Note that the "Quick Package" Button will only integrate the changes you made to tiddlers already contained in the plugin into the plugin tiddler itself, you can't add new tiddlers to a plugin this way. For those tasks, you will still have to use the control panel menu.

Notes

When repackaging a plugin, the version number of the plugin is automatically increased. This might not be wanted in all cases and has to be manually corrected after packaging.

Also version suffixes such as:

  • -prerelease
  • -beta

are supported and will be appended to the new version number when present.

Adding items to the list field

Items added to the list field will become tab entries in the generated plugin. Each item in the list should have a corresponding tiddler with the format:

$:/plugins/<author>/<plugin>/<tiddler>

where <author> is the name you provided as author, <plugin> is the name of the plugin you are creating, and <tiddler> is the same as the name that appears in the list entry.

The contents of the tab referenced in the list field will then be provided by the corresponding $:/plugins/<author>/<plugin>/<tiddler> tiddler.

Plugin mechanism

For more information about how the plugin mechanism in TiddlyWiki works, see the official documentation: http://tiddlywiki.com/#PluginMechanism

Filter language

Filters are useful to select a subset of tiddlers from a wiki. If you are new to filters, learn more about them here: http://tiddlywiki.com/#Filters