SetWidget

20th July 2023 at 5:47pm

Introduction

The set variable widget assigns a value to a specified variable. The new value of the variable is available to the content within the set variable widget.

Content and Attributes

The content of the <$set> widget is the scope for the value assigned to the variable.

Attribute	Description
name	The name of the variable to assign (defaults to "currentTiddler")
value	The value to assign to the variable if the `filter` attribute is missing or not empty
tiddler	Introduced in v5.1.15 Optional title of the tiddler from which to read the value
subtiddler	Introduced in v5.1.16 Optionally specifies the title of a subtiddler within a plugin tiddler identified by the tiddler attribute
field	Introduced in v5.1.15 Optional field of the tiddler from which to read the value (only used if tiddler is used)
index	Introduced in v5.1.15 Optional index of the tiddler from which to read the value (only used if tiddler is used)
filter	An optional filter to be evaluated and assigned to the variable (see "Filtered List Variable Assignment" below). The variable can be used with the `enlist` operator
select	Introduced in v5.1.14 An optional zero-based index of the item to return from the filter output (see below)
emptyValue	The value to assign to the variable if the specified value is missing or empty (see below)

Tip

If the value of your variable is enclosed in double square brackets this might indicate that you are returning a list of values from the filter. To use a single title from the filter output without the double square brackets see Filtered Item Variable Assignment below.

Examples

Simple Variable Assignment

The simplest way of using set variable widget assigns a string to a variable. The following example assigns a literal string

<$set name="myVariable" value="Some text">
<$text text=<<myVariable>>/>
</$set>
That renders as:
Some text

Both the name and value attributes can be transcluded. For example:

<$set name=anotherVariable value="myVariable">
  <$set name=<<anotherVariable>> value={{$:/language/DefaultNewTiddlerTitle}}>
    <$text text=<<myVariable>>/>
  </$set>
</$set>

That renders as:

New Tiddler

Conditional Variable Assignment

This form of the set variable widget chooses one of two specified values according to whether a filter evaluates to an empty list. Here's an example that sets a variable according to whether the current tiddler is called "myMagicTitle":

<$set name="myVariable" filter="[all[current]field:title[myMagicTitle]]" value="It's magic" emptyValue="It's not magic">
<$text text=<<myVariable>>/>
</$set>

That renders as:

It's not magic

Filtered List Variable Assignment

This form of the set variable widget evaluates the filter and assigns the result to the variable as a space-separated list (using double square brackets for titles containing spaces).

Warning

The Title List format cannot reliably represent items that contain certain specific character sequences such as ]] . Thus it should not be used where there is a possibility of such sequences occurring.

<$set name="myVariable" filter="[tag[HelloThere]]">
<$text text=<<myVariable>>/>
</$set>
That renders as:
[[A Gentle Guide to TiddlyWiki]] [[Discover TiddlyWiki]] [[Some of the things you can do with TiddlyWiki]] [[Ten reasons to switch to TiddlyWiki]] Examples [[What happened to the original TiddlyWiki?]] [[Funding TiddlyWiki]] [[Open Collective]]

Filtered Item Variable Assignment Single Element

Introduced in v5.1.14 This form of the set variable widget evaluates the filter and assigns the specified result to the variable as a single item (ie, not using double square brackets for titles containing spaces).

<$set name="myVariable" filter="[tag[HelloThere]]" select="0">
<$text text=<<myVariable>>/>
</$set>
That renders as:
A Gentle Guide to TiddlyWiki

Transcluded Variable Assignment

Introduced in v5.1.15 This form of the set variable widget obtains the value to assign to the variable from a value in a tiddler field or index. For example:

<$set name="myVariable" tiddler="HelloThere" field="list">
<$text text=<<myVariable>>/>
</$set>
That renders as:
[[A Gentle Guide to TiddlyWiki]] [[Discover TiddlyWiki]] [[Some of the things you can do with TiddlyWiki]] [[Ten reasons to switch to TiddlyWiki]] Examples [[What happened to the original TiddlyWiki?]]

The example above could also be written as <$set name="myVariable" value={{HelloThere!!list}}>. The advantage of using the tiddler attribute is that the tiddler title and field or index can themselves be computed. For example:

<$set name="myTiddler" value="HelloThere">
  <$set name="myVariable" tiddler=<<myTiddler>> field={{$:/docs/anyField!!field}}>
    <$text text=<<myVariable>>/>
  </$set>
</$set>
That renders as:
[[A Gentle Guide to TiddlyWiki]] [[Discover TiddlyWiki]] [[Some of the things you can do with TiddlyWiki]] [[Ten reasons to switch to TiddlyWiki]] Examples [[What happened to the original TiddlyWiki?]]

Using the Set Widget to Create Global Variables

There are times when it makes sense to use the features of the SetWidget rather than procedures or functions to create global variables. This can be accomplished by placing the set variable widget in a tiddler that is tagged $:/tags/Global. If multiple variables are required, the set variable widget can be nested as shown here:

<$set name="myGlobalVariable" value="I am global">
    <$set name="myOtherGlobalVariable" value="I am also a global variable.">
    </$set>
</$set>