Add notes about subfilter expressions (#7667)

editions/tw5.com/tiddlers/widgets/ActionListopsWidget.tid

@@ -1,6 +1,6 @@
 caption: action-listops
 created: 20141025120850184
-modified: 20230301183438774
+modified: 20230805103548113
 myfield: 
 tags: ActionWidgets Widgets
 title: ActionListopsWidget
@@ -22,6 +22,28 @@ The ''action-listops'' widget is invisible. Any content within it is ignored.
 |$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="-[[List Item]]"/>
+<$action-listops $subfilter="+[remove[List Item]]"/>
+```
+
+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.
@@ -103,4 +125,4 @@ Add 'abc' to 'myfield'
 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)]]
+! [[Examples|ActionListopsWidget (Examples)]]

editions/tw5.com/tiddlers/widgets/examples/ActionListopsWidget (Examples).tid

@@ -1,8 +1,9 @@
 created: 20230301174431218
 list: efg hlm pqr
-modified: 20230301174431218
+modified: 20230805103601224
 myfield: 
 revision: 0
+tags: ActionListopsWidget
 title: ActionListopsWidget (Examples)
 type: text/vnd.tiddlywiki
 
@@ -47,6 +48,16 @@ Unmangle List
 
 </$list>"""/>
 
+---
+The following example toggles the tag <<.value Examples>> for the current tiddler.
+
+<$macrocall $name='wikitext-example-without-html'
+src="""<$button>
+<$action-listops $tags="+[toggle[Examples]]"/>
+Toggle 'Examples' tag
+</$button>
+"""/>
+
 ---
 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.