TiddlyWiki5/editions/tw5.com/tiddlers/widgets/ActionListopsWidget.tid

caption: action-listops
created: 20141025120850184
modified: 20230301183438774
myfield: 
tags: ActionWidgets Widgets
title: ActionListopsWidget
type: text/vnd.tiddlywiki

! Introduction

The ''action-listops'' widget is an [[action widget|ActionWidgets]] 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.

|!Attribute |!Description |
|$tiddler |The title of the tiddler whose lists are to be modified (if not provided defaults to the [[current tiddler|Current Tiddler]]) |
|$field |The name of a field to be manipulated as a list (defaults to 'list') |
|$index |Optional index of a property in a [[data tiddler|DataTiddlers]] index to be manipulated as a list |
|$filter |An optional filter expression, the output of which will be saved to the field/index being manipulated |
|$subfilter |An optional subfilter expression, which takes the list being manipulated as input, and saves the modified list back to the field/index being manipulated |
|$tags |An optional subfilter expression, which takes the <<.field tags>> field of the target tiddler as input, and saves the modified list of tags back to the <<.field tags>> field |

!! 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 <<.value "abc 123">> in the first two cases is a literal string that is assigned to the field <<.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 <<.field list>> field

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

```
<$action-listops $filter="[[1]] :and[[1]]"/>
```
will result in the <<.field list>> field of the current tiddler containing the string <<.value 1>>, but not <<.value "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:

<$macrocall $name='wikitext-example-without-html'
src="""<$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" />
"""/>
The [[enlist Operator]] with `raw` suffix will enlist the list saved in <<.field myfield>> of the current tiddler without de-duplication, while e.g. the [[list Operator]] will always de-duplicate. The widget then adds the item <<.value abc>> -- whether or not it is already included in the list -- and replaces the original list in <<.field myfield>>.


! [[Examples|ActionListopsWidget (Examples)]]