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

created: 20221007144237585
modified: 20230419103154328
tags: Concepts Reference
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`).

!! 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>""">>