Introduction
New in v5.3.0 A custom widget is a special kind of procedure that can be called using the same syntax as widgets.
Custom widgets can also be used to override built-in JavaScript widgets to customise their behaviour.
Defining Custom Widgets
Custom widgets are usually defined with the Pragma: \widget:
\widget $my.widget(attribute:"Default value")
This is the widget, and the attribute is <<attribute>>.
\end
The name of the widget must start with a dollar sign. If it is a user defined widget that does not override an existing widget then it must include at least one period (dot) within the name (for example $my.widget
or $acme.logger
).
Note that the Pragma: \whitespace setting is inherited from the parsing context in which the procedure definition occurs. That means that a tiddler containing multiple procedure definitions only needs a single whitespace pragma at the top of the tiddler, and the setting will be automatically inherited by the procedure definitions without needing the pragma to be repeated.
Using Custom Widgets
Custom widgets are called in the same way as ordinary built-in widgets:
<$my.widget/>
<$my.widget attribute="The parameter"/>
The attributes that are specified in the widget call are made available as parameter variables.
Accessing Content of Custom Widgets
Within the definition of a custom widget the content of the calling widget is available via the <$slot $name="ts-raw"/>
widget. The contents of the $slot
widget is used as the default content if the widget was called without any content.
For example:
\widget $my.widget(one:'Jaguar')
<$text text=<<one>>/>
<$slot $name="ts-raw">
Whale
</$slot>
\end
<$my.widget one="Dingo">
Crocodile
</$my.widget>
<$my.widget/>
That renders as:
Dingo Crocodile
Jaguar Whale
How Custom Widgets Work
Custom widgets are implemented as a special kind of variable. The only thing that distinguishes them from ordinary variables is the way that they can be called as a custom widget with attributes mapped to parameters.
Overriding Core JavaScript Widgets
Custom widgets can use the $genesis
widget to invoke the original widget, bypassing the override. For example, here we override the $codeblock
widget to add ≤≥
symbols around each string of text.
\widget $codeblock(code)
<$genesis $type="$codeblock" $remappable="no" code={{{ [<code>addprefix[≤]addsuffix[≥]] }}}/>
\end
<$codeblock code="Kangaroo"/>
<$codeblock code={{$:/SiteTitle}}/>
```
Python
```
<$let test="Tiger">
<$codeblock code=<<test>>/>
</$let>
That renders as:
≤Kangaroo≥
≤TiddlyWiki≥
≤Python≥
≤Tiger≥