This page is part of a static HTML representation of the TiddlyWiki at https://tiddlywiki.com/

ActionListopsWidget

28th December 2015 at 8:33am

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.

AttributeDescription
$tiddlerThe title of the tiddler whose lists are to be modified (if not provided defaults to the current tiddler
$fieldThe name of a field to be manipulated as a list (defaults to 'list')
$indexOptional index of a property in a data tiddler index to be manipulated as a list
$filterAn optional filter expression, the output of which will be saved to the field/index being manipulated
$subfilterAn optional subfilter expression, which takes the list being manipulated as input, and saves the modified list back to the field/index being manipulated
$tagsAn optional subfilter expression, which takes the 'tags' field of the target tiddler as input, and saves the modified list of tags back to the 'tags' field

$filter vs. $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 [all[current]get[myfield]enlist-input[]] to the Filter Expression:

<$action-listops $field="myfield" $filter="[all[current]get[myfield]enlist-input[]] 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.

$tags vs. $field + $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"/>

$action-listops widget vs. $action-setfield widget

The ActionSetFieldWidget replaces a field's value using $field/$value attributes. A single ActionSetFieldWidget can be used to set any number of fields by using attributes not starting with $.

The ActionListopsWidget replaces or modifies a single field's value. The new value is generated using filters.

The following two examples are functionally equivalent:

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

In general, ActionSetFieldWidget is better for setting multiple fields at once and for replacing a field's value. The ActionListopsWidget is better for modifying a field based on the field's existing value and for using a Filter Expression to derive the value.

Extended Filter Operators

A number of extended filter operators 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.

Listops Operators
Operator Purpose
allafter discard all items except those after the marker
allbefore discard all items except those before the marker
append append a range of items from an array to the list
cycle toggle in the input, the titles specified in the first operand in a cyclical manner
insertbefore insert an item T into a list immediately before an item B
move move marker N places in the list
prepend prepend a range of items from an array to the list
putafter move N trailing items after the marker
putbefore move N trailing items before the marker
putfirst move N trailing items to the head of the list
putlast move N leading items to the tail of the list
remove remove a list of titles specified in the operand from the input
replace replace marker with N trailing items
sortby sort the current list in the order of the list referenced in the operand
toggle toggle the title specified in the operand in the input
unique remove all duplicate items from the current list

Examples

In this example we shall populate and then clear a list in an ordinary field (myfield) of this tiddler (the default.)

<$button>
<$action-listops $field="myfield" $subfilter="efg hlm pqr"/>
Populate 'myfield'
</$button>
<$button>
<$action-listops $field="myfield" $subfilter="abc xyz"/>
Append More Items
</$button>
<$button>
<$action-listops $field="myfield" $subfilter="-abc -hlm"/>
Remove Items
</$button>
<$button>
<$action-listops $field="myfield" $filter="[[]]"/>
Clear 'myfield'
</$button>

<$list filter="[list[!!myfield]]">

</$list>

That renders as:


In this example we shall append and remove items from a list in an ordinary field (myfield) of this tiddler (the default) and sort the resultant list. We shall then remove some of the appended items and sort the resulting list in reverse order.

<$button>
<$action-listops $field="myfield" $subfilter="-efg ijk xyz [[this is a title]] +[sort[]]"/>
Mangle List
</$button>
<$button>
<$action-listops $field="myfield" $subfilter="-xyz -[[this is a title]] +[!sort[]]"/>
Unmangle List
</$button>

<$list filter="[list[!!myfield]]">

</$list>

That renders as:


In this example we shall append a few tags to the 'tags' field of this tiddler (the default.) We shall then remove some of the appended tags.

<$button>
<$action-listops $tags="+[append{Days of the Week!!short}] $:/tag1 $:/tag2 $:/tag3"/>
Populate 'tags'
</$button>
<$button>
<$action-listops $tags="+[!remove:2{!!tags}]"/>
Remove Last Two Tags
</$button>
<$button>
<$action-listops $tags="+[!prefix[$:/]]"/>
Remove System Tags
</$button>
<$button>
<$action-listops $tags="-Mon -Tue"/>
Remove Mon and Tue
</$button>
<$button>
<$action-listops $tags="+[prefix[$:/]] ActionWidgets Widgets"/>
Remove User Tags
</$button>
<$button>
<$action-listops $tags="+[[]] ActionWidgets Widgets"/>
Clear Tags
</$button>

<$list filter="[list[!!tags]]">

</$list>

That renders as:

ActionWidgets
Widgets