Create The Extended Listops Filters.tid

Supplementary documentation for the ActionListops widget -- examples using the extended filters

editions/tw5.com/tiddlers/widgets/The Extended Listops Filters.tid

@@ -0,0 +1,113 @@
+created: 20151014170727812
+creator: matabele
+days: Fri Wed Mon Tue
+dofwks: Mon Tue Wed Thu Fri Sat Sun
+item1: six
+item2: seven
+item3: eight
+list: Yesterday Today Tomorrow
+marker: Thursday
+modified: 20151108054957921
+modifier: matabele
+myfield: Monday Tuesday [[Middle of the Week]] Thursday Friday Saturday Sunday
+numbers: 1 2 3 4 five 6 7 8 9
+title: The Extended Listops Filters
+
+! Introduction
+
+A number of extended filters are necessary to manipulate lists. The first set of filters are designed to move items from the tail of the list and insert them at specified locations in the list. 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 (defaults to 1.) 
+
+A second set of filters are designed to either add or remove from the list, a selected range of items from an array. These filters are best used with a reference to an array, stored in a field or data indexe 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 (defaults to All.)
+
+! 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. 
+
+<$macrocall $name='wikitext-example-without-html'
+src="""<$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}}"""/>
+
+---
+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.
+
+<$macrocall $name='wikitext-example-without-html'
+src="""<$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}}"""/>
+
+---
+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.
+
+<$macrocall $name='wikitext-example-without-html'
+src="""<$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}}"""/>
+
+---
+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.
+
+<$macrocall $name='wikitext-example-without-html'
+src="""|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}}"""/>
+
+---
+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.
+
+<$macrocall $name='wikitext-example-without-html'
+src="""<$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}}"""/>