Introduction
A number of filters are used to manipulate lists.
Some filters are designed to move items from the tail of the list and insert them at specified locations in the list, e.g. putafter or putbefore. Items are often appended to the list before using these filters. In general, these filters accept a suffix specifying the number of items to move (default to 1.)
Some filters are designed to either add or remove from the list, a selected range of items from an array, e.g. append or remove. These filters are best used with a reference to an array, stored in a field or data index elsewhere in the wiki (they may be used with a simple list of items, provided the items do not include white space.) In general, these filters accept a suffix specifying the number of items to move (default to All.)
| 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 the titles specified in the first parameter in a cyclical manner | ||
| insertafter | insert an item T into a list immediately after an item A |
||
| 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 parameter from the input | ||
| replace | replace marker with N trailing items | ||
| sortby | sort the current list in the order of the list referenced in the parameter | ||
| toggle | toggle the title specified in the parameter in the input | ||
| unique | remove all duplicate items from the current list | ||
Examples
In this example we shall populate the 'DataIndex' index of the tiddler 'MyData' with the names of the days of the week, then clear this list.
<$button>
<$action-listops $tiddler="ListopsData" $index="DataIndex" $filter="[list[Days of the Week]]"/>
Get days-of-the-week
</$button>
<$button>
<$action-listops $tiddler="ListopsData" $index="DataIndex" $filter="[[]]"/>
Clear
</$button>
{{ListopsData}}That renders as:
DataIndex:
In this example we shall slice the populated list from the 'DaysOfTheWeek' index of the tiddler 'MyData' in order to insert items before and after a marker item (Wednesday) that are first appended to the list.
<$button>
<$action-listops $tiddler="ListopsData" $index="DataIndex" $subfilter="one two +[putbefore:2[Wednesday]]"/>
Put 2 Items Before Wednesday
</$button>
<$button>
<$action-listops $tiddler="ListopsData" $index="DataIndex" $subfilter="four five +[putafter:2[Wednesday]] three +[putbefore[Wednesday]]"/>
Put One Item Before & Two Items After Wednesday
</$button>
{{ListopsData}}That renders as:
DataIndex:
In this example we shall slice the populated list from the 'DaysOfTheWeek' index of the tiddler 'MyData' in order to replace the marker item (Wednesday) with items which are first appended to the list. We shall then move 3 items to the head of the list which have first been appended to the list from referenced fields.
<$button>
<$action-listops $tiddler="ListopsData" $index="DataIndex" $subfilter="[[---o]] [[o---]] +[replace:2{!!marker}]"/>
Replace '!!marker' with 2 Items
</$button>
<$button>
<$action-listops $tiddler="ListopsData" $index="DataIndex" $subfilter="[{!!item1}] [{!!item2}] [{!!item3}] +[putfirst:3[]]"/>
Put 3 Items First
</$button>
{{ListopsData}}That renders as:
DataIndex:
In this example we shall slice the populated list from the 'DaysOfTheWeek' index of the tiddler 'MyData' in order to append to the truncated list, items from a referenced field. We shall then remove the first two of the items added.
|list: |<$view field="list"/> |
<$button>
<$action-listops $tiddler="ListopsData" $index="DataIndex" $subfilter="+[allbefore:include[Wednesday]] +[prepend{!!list}]"/>
Prepend '!!list' to items before 'Wednesday'
</$button>
<$button>
<$action-listops $tiddler="ListopsData" $index="DataIndex" $subfilter="+[remove:2{!!list}]"/>
Remove first two items in '!!list' from current list
</$button>
<$button>
<$action-listops $tiddler="ListopsData" $index="DataIndex" $subfilter="+[!remove:1{!!list}]"/>
Remove last item in '!!list' from current list
</$button>
{{ListopsData}}That renders as:
| list: | Yesterday Today Tomorrow |
DataIndex:
In this example we shall populate the list with numbers, then move items one by one from the head to the tail and from the tail to the head (best seen by clicking the lower buttons several times.)
This example illustrates that the append[] and prepend[] operators do not enforce unique instances of an item and that, with the next run, any duplicates are removed.
<$button>
<$action-listops $tiddler="ListopsData" $index="DataIndex" $filter="[[]]" $subfilter="+[append:3{!!numbers}]"/>
Setup some numbers
</$button>
<$button>
<$action-listops $tiddler="ListopsData" $index="DataIndex" $subfilter="+[!append:6{!!numbers}]"/>
Append more numbers
</$button>
<$button>
<$action-listops $tiddler="ListopsData" $index="DataIndex" $subfilter="+[putfirst:2[]]"/>
Move last 2 items to the head
</$button>
<$button>
<$action-listops $tiddler="ListopsData" $index="DataIndex" $subfilter="+[putlast[]]"/>
Move the head to the last item
</$button>
{{ListopsData}}That renders as:
DataIndex: