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.
|$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 |
If the manipulation depends on the current contents of the list, e.g. when using the <<.olink toggle>> operator to toggle the presence of an element, the [[Filter Run]] would be prefixed with the `+` / `:and` [[filter run prefix|Filter Expression]] so that it properly receives the list as input.
The above widget will toggle the presence of the element <<.value "List Item">> in the field <<.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|Filter Expression]] can be used. Both of the following yield the same result:
<<.infoBox """Note that the parameter of the [[remove Operator]] is a [[Title List]]. To remove one or more titles containing spaces the individual titles must be wrapped in double square brackets, usually via a soft [[Filter Parameter]]. See //Filtered List Variable Assignment// in the [[SetWidget]] documentation to learn more.""">>
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.
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.
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.
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.
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:
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>>.
