TiddlyWiki5/editions/tw5.com/tiddlers/widgets/Custom Widgets.tid

created: 20221007144237585
modified: 20240422084734129
tags: Concepts
title: Custom Widgets
type: text/vnd.tiddlywiki

!! Introduction

<<.from-version "5.3.0">> A <<.def "custom widget">> is a special kind of [[procedure|Procedures]] 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 <<.wlink SlotWidget>> widget is used as the default content if the widget was called without any content.

For example:

<<wikitext-example-without-html """\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|Variables]]. 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 <<.wlink "GenesisWidget">> widget to invoke the original widget, bypassing the override. For example, here we override the <<.wlink CodeBlockWidget>> widget to add `≤≥` symbols around each string of text.


<<wikitext-example-without-html """\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>""">>