Things are a bit different in TW5 when it comes to plugins and can take a bit to wrap one's head around. Plugins are just a collection or packaging of tiddlers.
The general idea in TW5 that I use is, try to do as much as you can with wikitext, macros and widgets and when you find something there is no widget for, write one. That is, the focus again is on writing re-usable widgets that implement the missing behaviour that you need.
Keep in mind that the entire TiddlyWiki UI is written in this manner.
are used to be build UI and associated behaviour. Note that there is a widget tree, and refresh is propagated through the widget tree from the root node.
So for instance if you wanted to create a button that displays a message to the user you could use something like this:
<$action-sendmessage $message="tm-notify" $param="HelloThere"/>
What we have here is a button
widget, which creates a button UI element which can be used to trigger action widgets
In this particular case, we use the action-sendmessage widget which sends the message tm-notify, displaying the contents of the tiddler HelloThere.
ActionWidgets are a special case in that they don't implement any UI but rather carry out actions and are triggered by widgets that can trigger actions (such as Button or Checkbox etc..). Action widgets can be extremely powerful. As an example, in the Streams plugin
, there is keyboard handling for moving between list items, indenting them etc. All of this is handled by actions.
Coming back to your example of showing an alert on clicking a button, as far as I can remember we do not have an action-widget for displaying alerts. So to implement this you would use a ButtonWidget as above, but with your own action-widget, let's call it action-alert.
A good starting point when writing a module for TiddlyWiki - we will come back to modules a little later for now just understand that widgets are a type of module - is to find a similar one to use as an example. For example, action-log.js
Note that all widgets inherit from the Widget base class
. Now looking at action-log.js, note the comments at the top especially the lines for title, type and module-type
. These are mapped to tiddler fields in a node.js environment, but can otherwise be added the usual way as fields. The module-type
set to widget
is what tells TiddlyWiki to treat the code in this tiddler as a widget.
In an action widget, it is the invokeAction
method that is triggered when the action is executed by a triggering widget such as ButtonWidget. This is where your behaviour goes. The execute method
is where you read and assign parameters accepted by the widget, in this case it would be the text to display. The refresh method determines what to do if the input parameters have changed, destroy and re-create the entire widget and its children if any, or selectively update attributes of the widget (and associated DOM nodes if any).
So using action-log.js as a starting point and making a few changes, we arrive at this to show alerts (untested code):
Now you have an action-alert action widget that can be used whenever you need to trigger an alert for example:
TiddlyWiki implements several module-types
As we discussed above, Widget tiddlers have the module-type widget
. Similarly tiddlers with the module-type startup
are executed after loading all tiddlers and plugins but before the UI is displayed. (Note that tiddlywiki.com/dev
Probably the other big and important topic is filters. Filters have become extremely powerful and versatile
and combined with action widgets can be used to implement complex behaviours. I am unsure if you were active towards the end days of TWC when filters were first introduced.
Hope this helps.
On Wednesday, March 10, 2021 at 10:45:50 PM UTC+1 SimonBaird wrote: