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/>

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>

≤Kangaroo≥

≤TiddlyWiki @@font-size:small; v<<version>>@@≥

≤Python≥

≤Tiger≥