Introduced in v5.1.23The action-confirm widget is an action widget that prompts the user for confirmation and invokes other action widgets contained within it only if the user confirms. ActionWidgets are used within triggering widgets such as the ButtonWidget.

Content and Attributes

The action-confirm widget is invisible. Any content within it is only processed if the user confirms the action, or the confirmation has been disabled by the $prompt attribute.

Examples

Here is an example of a button that asks the user for confirmation, before deleting the caption and tags fields of the current tiddler:

<$button>
<$action-confirm $message="Do you wish to delete the caption and tags?">
<$action-deletefield caption tags/>
Delete "caption" and "tags"
</$action-confirm>
</$button>

Here is an example of a button that uses the optional $prompt attribute to control whether to prompt the user before deleting the text field of the tiddler HelloThere:

<$button>
<$action-confirm $message="Do you wish to delete the text field?" $prompt={{$:/state/promptUser}}>
<$action-deletefield $tiddler="HelloThere" $field="text"/>
</$action-confirm>
Delete text from ~HelloThere
</$button>

The $action-createtiddler widget is an action widget that creates new tiddlers. Action widgets are used within triggering widgets such as the ButtonWidget.

There are several differences from the tm-new-tiddler message:

• The new tiddler is not automatically displayed in the story river
• The title of the new tiddler is made available for subsequent operations

Content and Attributes

The action-createtiddler widget is invisible.

Variables

Introduced in v5.2.0 The content of the $action-createtiddler widget is executed after the new tiddler has been created. The title of the newly created tiddler is stored in the variable createTiddler-title.

Examples

The action-deletefield widget is an action widget that deletes specified fields of a tiddler. ActionWidgets are used within triggering widgets such as the ButtonWidget.

Content and Attributes

The action-deletefield widget is invisible. Any content within it is ignored.

Examples

The action-deletetiddler widget is an action widget that deletes tiddlers. ActionWidgets are used within triggering widgets such as the ButtonWidget.

There are several differences compared to the WidgetMessage: tm-delete-tiddler:

• The user is not prompted to confirm the deletion
• No automatic updating of the story list
• No special handling of draft tiddlers

Content and Attributes

The action-deletetiddler widget is invisible. Any content within it is ignored.

Examples

The action-listops widget is an action widget that manipulates user lists in any field or data index. ActionWidgets are used within triggering widgets such as the ButtonWidget.

Content and Attributes

The action-listops widget is invisible. Any content within it is ignored.

Note on subfilter expressions

If the manipulation depends on the current contents of the list, e.g. when using the toggle operator to toggle the presence of an element, the Filter Run would be prefixed with the + / :and filter run prefix so that it properly receives the list as input.

<$action-listops $subfilter="+[toggle[List Item]]"/>

The above widget will toggle the presence of the element List Item in the field list of the current tiddler, removing or adding the element as necessary.

Similarly, if an element is to always be removed when it is present, the - / :except filter run prefix can be used. Both of the following yield the same result:

<$action-listops $subfilter="-[[ListItem]]"/>
<$action-listops $subfilter="+[remove[ListItem]]"/>

Without any prefixes, the filter run output is simply dominantly appended to the list.

See also the Examples.

Using $filter or $subfilter

Standalone use of the $subfilter attribute can be replaced by using a (more complicated) $filter attribute value.

For example, the items "abc" and "123" can be appended to the field myfield using the $subfilter attribute:

<$action-listops $field="myfield" $subfilter="abc 123"/>

The same can be achieved using the $filter attribute and prepending the Filter Run [enlist{!!myfield}] to the Filter Expression:

<$action-listops $field="myfield" $filter="[enlist{!!myfield}] abc 123"/>

The short form is more convenient, but the long form is useful for live-debugging complicated $subfilter values using the filter tab of $:/AdvancedSearch. By using $:/AdvancedSearch, the Filter Expression can be tested before using action-listops to modify actual tiddler fields. For this use case, the all[current] portion of the expression needs to be changed to select the proper test tiddler.

Using $tags or $subfilter

Tagging is implemented using a tiddler's 'tags' field, so appending the tags "abc" and "123" using the $tags attribute like this:

<$action-listops $tags="abc 123"/>

is mostly equivalent to using $subfilter along with "tags" for the value of $field:

<$action-listops $field="tags" $subfilter="abc 123"/>

Comparison to ActionSetFieldWidget

In general, ActionSetFieldWidget is better for setting multiple fields at once and for replacing the value of a field, which can also be a list. The ActionListopsWidget is better for modifying a list field based on the existing list and for using a Filter Expression to derive the value of the field.

The ActionSetFieldWidget sets the value of a field using $field and $value attribute pairs or attributes that do not start with a $. A single ActionSetFieldWidget can be used to set any number of fields of a single tiddler.

The ActionListopsWidget replaces or modifies a single field's value using filter expressions.

The following widgets are functionally equivalent:

<$action-setfield $field="myfield" $value="abc 123"/>
<$action-setfield myfield="abc 123"/>
<$action-listops $field="myfield" $filter="abc 123"/>

Note that abc 123 in the first two cases is a literal string that is assigned to the field myfield, but in the third case a filter expression which evaluates to the same string.

Extended Filter Operators

A number of Extended Listops Filters are necessary for the manipulation of lists. These operators have been designed primarily for use in subfilter expressions whereby the modified current list is returned in place of the current list.

Notes on de-duplication

In some cases, there may occur unexpected de-duplication of lists.

Assignments to the list field

When assigning filter results to the list field (default), the generated list is automatically de-duplicated, so

<$action-listops $filter="[[1]] :and[[1]]"/>

will result in the list field of the current tiddler containing the string 1, but not 1 1.

Input to the subfilter expression

The input to the subfilter expression in the $subfilter attribute is also de-duplicated. If you rely on lists containing duplicates, consider using this alternative using the $filter attribute:

<$button>
<$action-listops $field="myfield" $filter="[enlist:raw{!!myfield}] :all[[abc]]" />
Add 'abc' to 'myfield'
</$button>

<$list filter="[enlist:raw{!!myfield}]" template="$:/core/ui/ListItemTemplate" />

Examples

The action-navigate widget is an action widget that sends a tm-navigate message back up the widget tree. ActionWidgets are used within triggering widgets such as the ButtonWidget.

Content and Attributes

The action-navigate widget is invisible. Any content within it is ignored.

Scroll handling

The optional $scroll attribute can be set to "yes" to force scrolling to occur to bring the target tiddler into view. If set to "no" then scrolling does not occur. If the $scroll attribute is omitted then scrolling occurs unless either:

• the control key is pressed
• the action was initiated with the middle mouse button (if available)

Note that if navigating to multiple tiddlers at once you should use the same $scroll setting for all of them.

Examples

Here is an example of button that navigates to two different tiddlers at once:

<$button>
<$action-navigate $to="ButtonWidget"/>
<$action-navigate $to="ActionWidgets"/>
Click me!
</$button>

The action-popup widget is an action widget that triggers the display of a popup defined via a state tiddler, or clears all displayed popups. ActionWidgets are used within triggering widgets such as the ButtonWidget.

Content and Attributes

The action-popup widget is invisible. Any content within it is ignored.

Introduced in v5.1.23 If the $coords attribute is missing or empty then all popups are cancelled.
Introduced in v5.2.4 The $coords attribute supports absolute and relative coordinates. See Coordinate Systems for more information.

Examples

Here is an example of button that triggers the "more" button in the sidebar "Tools" tab. You may need to scroll to see the popup

<$button>
<$action-setfield $tiddler="$:/state/tab/sidebar--595412856" $value="$:/core/ui/SideBar/Tools"/>
<$action-popup $state="$:/state/popup/more--810643385" $coords="(0,20,0,0)"/>
Click me!
</$button>

The action-sendmessage widget is an action widget that sends a message back up the widget tree. ActionWidgets are used within triggering widgets such as the ButtonWidget.

Content and Attributes

The action-sendmessage widget is invisible. Any content within it is ignored.

Examples

Here is an example of button that displays both a notification and a wizard, and creates a new tiddler with tags and text:

<$button>
<$action-sendmessage $message="tm-modal" $param="SampleWizard"/>
<$action-sendmessage $message="tm-notify" $param="SampleNotification"/>
<$action-sendmessage $message="tm-new-tiddler" title="This is newly created tiddler" tags="OneTag [[Another Tag]]" text=<<now "Today is DDth, MMM YYYY">>/>
Click me!
</$button>

The action-setfield widget is an action widget that assigns values to the fields of a tiddler. ActionWidgets are used within triggering widgets such as the ButtonWidget.

Content and Attributes

The action-setfield widget is invisible. Any content within it is ignored.

Examples

Here is an example of a pair of buttons that open the control panel directly to specified tabs. They work by using action-setfield to set the state tiddler for the control panel tabs.

<$button>
<$action-setfield $tiddler="$:/state/tab-1749438307" text="$:/core/ui/ControlPanel/Appearance"/>
<$action-navigate $to="$:/ControlPanel"/>
Go to Control Panel "Appearance" tab
</$button>

<$button>
<$action-setfield $tiddler="$:/state/tab-1749438307" text="$:/core/ui/ControlPanel/Settings"/>
<$action-navigate $to="$:/ControlPanel"/>
Go to Control Panel "Settings" tab
</$button>

Here is an example of a button that assigns tags and fields to the tiddler HelloThere, and then navigates to it and opens the tiddler info panel on the "Fields" tab:

<$button>
<$action-setfield $tiddler="HelloThere" tags="NewTag [[Another New Tag]]" color="red"/>
<$action-setfield $tiddler="$:/state/popup/tiddler-info--1779055697" text="(568,1443,33,39)"/>
<$action-setfield $tiddler="$:/state/tab--1890574033" text="$:/core/ui/TiddlerInfo/Fields"/>
<$action-navigate $to="HelloThere"/>
Modify ~HelloThere
</$button>

Here is an example of a button that assigns tags and fields to the tiddler HelloThere, and then initiates editing it:

<$button>
<$action-setfield $tiddler="HelloThere" tags="MoreTag [[Further More Tags]]" color="green"/>
<$action-sendmessage $message="tm-edit-tiddler" $param="HelloThere"/>
Edit ~HelloThere
</$button>

Here is an example of a button that opens the control panel directly to the "Appearance" tabs:

<$button>
<$action-setfield $tiddler="$:/state/tab-1749438307" $field="text" $value="$:/core/ui/ControlPanel/Appearance"/>
<$action-navigate $to="$:/ControlPanel"/>
Go to Control Panel "Appearance" tab
</$button>

The action-setmultiplefields widget is an action widget that assigns multiple fields to a tiddler where the names and values of the fields are specified as separate filters. ActionWidgets are used within triggering widgets such as the ButtonWidget.

Content and Attributes

The action-setmultiplefields widget is invisible. Any content within it is ignored.

Examples

Here is an example of button that uses the data in Days of the Week to assign fields day-Monday, day-Tuesday etc. to the tiddler "HelloThere":

<$button>
<$action-setmultiplefields $tiddler="HelloThere" $fields="[list[Days of the Week]addprefix[day-]]" $values="[list[Days of the Week]]"/>
Click me!
</$button>