Introduction

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