mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-11-16 06:44:50 +00:00
130 lines
6.6 KiB
Plaintext
130 lines
6.6 KiB
Plaintext
caption: action-listops
|
|
created: 20141025120850184
|
|
modified: 20240509135041526
|
|
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 |
|
|
|
|
!! Note on subfilter expressions
|
|
|
|
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.
|
|
|
|
```
|
|
<$action-listops $subfilter="+[toggle[List Item]]"/>
|
|
```
|
|
|
|
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:
|
|
|
|
```
|
|
<$action-listops $subfilter="-[[ListItem]]"/>
|
|
<$action-listops $subfilter="+[remove[ListItem]]"/>
|
|
```
|
|
|
|
<<.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.""">>
|
|
|
|
Without any prefixes, the filter run output is simply [[dominantly appended|Dominant Append]] to the list.
|
|
|
|
See also the [[Examples|ActionListopsWidget (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 <<.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)]] |