Is there a "Getting Started Guide" for for creating a plugin?

[Simon Baird]

https://tiddlywiki.com/#PluginMechanism talks about plugins and how they work etc, but how do I make one?

Suppose I wanted to run alert("Hello") when TiddlyWiki starts up, or create a macro that creates a button that runs alert("Hello World").

Where do I begin?

-Simon

--

simon...@gmail.com

[Mat]

Hi Simon

You refer to alerts like that so I guess you're talking about JS plugins. Then the github forum is really more suitable. With that said, maybe you can find info in the dev wiki. Otherwise, for packaging tiddlers into plugins from within TW itself, the easiest way is to use the Tinka plugin packer.

<:-)

[Mark S.]

You're really asking two different questions. Maybe even 3.

A plugin is just a packaged bundle of tiddlers. It's not too hard to make with node. Make a directory "plugins/myplugin" below your node-based TW folder and then put whatever tiddlers you want in myplugin. Add a file "plugin.info" (see tiddlywiki for details how to populate plugin.info) and run node.js. Navigate to plugins and you'll see your new plugin. You can export if from there if you want.

A button that invokes javascript would need a widget or a javascript macro. The easiest way to make a javascript macro is to look at an existing one (e.g. $:/core/modules/macros/now.js) and modify it accordingly.

For starting things during boot, type "startup" into tiddlywiki.com for information on how to set up tiddlers that get invoked at startup. However it's possible that what you really want is $:/tags/RawMarkup . Be aware that if you put JS code into RawMarkup inside a plugin that you will have to save and reload your TW file twice.

But you may actually want help with writing widgets. If you find any simple, understandable guide to writing widgets please let me know! Chris Hunt (?) had a guide, but now you have to find it on the internet archive, and the code he uses doesn't match the current code, which is confusing.

[Javier Eduardo Rojas Romero]

On Wed, Mar 10, 2021 at 04:45:31PM -0500, Simon Baird wrote:
> https://tiddlywiki.com/#PluginMechanism talks about plugins and how they
> work etc, but how do I make one?
>
> Suppose I wanted to run alert("Hello") when TiddlyWiki starts up, or create
> a macro that creates a button that runs alert("Hello World").
>
> Where do I begin?

Hello,

Yes, please have a look at
https://tiddlywiki.com/dev/#Developing%20plugins%20using%20Node.js%20and%20GitHub

Cheers,

--
Javier

[Javier Eduardo Rojas Romero]

On Wed, Mar 10, 2021 at 05:01:43PM -0500, Javier Eduardo Rojas Romero wrote:
> Yes, please have a look at
> https://tiddlywiki.com/dev/#Developing%20plugins%20using%20Node.js%20and%20GitHub

It's worth mentioning that page is only for setting up the environment
for developing your plugin, and doesn't mention a thing about
exposing/calling JS code :(

In my case, I searched for an existing plugin that did something
similar/had a similar architecture to what I wanted.

Given your usecase, I'd look into how to add a new widget, or perhaps
adding a new type of message, either in the available plugins, or in the
tiddlywiki codebase...

>
> Cheers,
>
> --
> Javier

[David Gifford]

I put off learning plugins for years. Then I finally broke down and tried the Tinka plugin-packaging plugin, and was surprised at how easy it was.

[Saq Imtiaz]

Hi Simon,

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.

Macros are used just to do text substitution. Most macros are defined in wikitext but there are JavaScript macros as well.

Widgets 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:

<$button>

<$action-sendmessage $message="tm-notify" $param="HelloThere"/>

Click me!

</$button>

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):

https://gist.github.com/saqimtiaz/4733d7a81784103d66610275a2160c93

Now you have an action-alert action widget that can be used whenever you need to trigger an alert for example:

<$button>

<$action-alert message="HelloThere"/>

Click me!

</$button>

TiddlyWiki implements several module-types which determine when and how JavaScript code is interpreted.

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 is a better resource for JavaScript development).

Also perhaps useful to point out there that a plugin can contain several tiddlers, some of which may be startup modules and others may for example be widgets. That is, the JavaScript tiddlers in a plugin can be executed at different times.

Especially on the topic of startup behaviour, there are a lot of facilities as well to execute action-widgets on startup as an alternative to writing JavaScript.

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.

Regards,

Saq

On Wednesday, March 10, 2021 at 10:45:50 PM UTC+1 SimonBaird wrote:

[Simon Baird]

Thanks everyone for the thoughtful and detailed responses.

I'll do some reading and see if I can make sense of it all. (Perhaps I'll contribute some docs in future, maybe "Hacking TiddlyWiki - a beginners guide".

--

simon...@gmail.com