Support specifying insertbefore position title as parameter (#6477)

* Support specifying insertbefore position title as parameter

Closes: #6133

* Update insertbefore calls with new variable parameter syntax

See-also: 96b52606a (Support specifying insertbefore position title as parameter, 2022-02-21)

core/modules/filters/insertbefore.js

@@ -20,7 +20,7 @@ exports.insertbefore = function(source,operator,options) {
 	source(function(tiddler,title) {
 		results.push(title);
 	});
-	var target = options.widget && options.widget.getVariable(operator.suffix || "currentTiddler");
+	var target = operator.operands[1] || (options.widget && options.widget.getVariable(operator.suffix || "currentTiddler"));
 	if(target !== operator.operand) {
 		// Remove the entry from the list if it is present
 		var pos = results.indexOf(operator.operand);

core/ui/SideBar/Open.tid

@@ -6,7 +6,7 @@ caption: {{$:/language/SideBar/Open/Caption}}
 \define lingo-base() $:/language/CloseAll/
 
 \define drop-actions()
-<$action-listops $tiddler=<<tv-story-list>> $subfilter="+[insertbefore:currentTiddler<actionTiddler>]"/>
+<$action-listops $tiddler=<<tv-story-list>> $subfilter="+[insertbefore<actionTiddler>,<currentTiddler>]"/>
 \end
 
 \define placeholder()

core/wiki/macros/list.tid

@@ -17,7 +17,7 @@ tags: $:/tags/Macro
 \end
 
 \define list-links-draggable-drop-actions()
-<$action-listops $tiddler=<<targetTiddler>> $field=<<targetField>> $subfilter="+[insertbefore:currentTiddler<actionTiddler>]"/>
+<$action-listops $tiddler=<<targetTiddler>> $field=<<targetField>> $subfilter="+[insertbefore<actionTiddler>,<currentTiddler>]"/>
 \end
 
 \define list-links-draggable(tiddler,field:"list",type:"ul",subtype:"li",class:"",itemTemplate)
@@ -61,7 +61,7 @@ tags: $:/tags/Macro
 <$action-deletefield $field="list-after"/>
 </$list>
 <!-- Save the new order to the Tag Tiddler -->
-<$action-listops $tiddler=<<__tag__>> $field="list" $filter="+[enlist<order>] +[insertbefore:currentTiddler<actionTiddler>]"/>
+<$action-listops $tiddler=<<__tag__>> $field="list" $filter="+[enlist<order>] +[insertbefore<actionTiddler>,<currentTiddler>]"/>
 <!-- Make sure the newly added item has the right tag -->
 <!-- Removing this line makes dragging tags within the dropdown work as intended -->
 <!--<$action-listops $tiddler=<<actionTiddler>> $tags=<<__tag__>>/>-->

editions/dynaviewdemo/tiddlers/SideBar-Open.tid

@@ -5,7 +5,7 @@ caption: {{$:/language/SideBar/Open/Caption}}
 \define lingo-base() $:/language/CloseAll/
 
 \define drop-actions()
-<$action-listops $tiddler="$:/StoryList" $subfilter="+[insertbefore:currentTiddler<actionTiddler>]"/>
+<$action-listops $tiddler="$:/StoryList" $subfilter="+[insertbefore<actionTiddler>,<currentTiddler>]"/>
 \end
 
 <$list filter="[list[$:/StoryList]]" history="$:/HistoryList" storyview="pop">

editions/test/tiddlers/tests/test-filters.js

@@ -755,16 +755,27 @@ Tests the filtering mechanism.
 			rootWidget.setVariable("tidTitle","e");
 			rootWidget.setVariable("tidList","one tid with spaces");
 			
+			// Position title specified as suffix.
 			expect(wiki.filterTiddlers("a b c d e f +[insertbefore:myVar[f]]",anchorWidget).join(",")).toBe("a,b,f,c,d,e");
 			expect(wiki.filterTiddlers("a b c d e f +[insertbefore:myVar<tidTitle>]",anchorWidget).join(",")).toBe("a,b,e,c,d,f");
 			expect(wiki.filterTiddlers("a b c d e f +[insertbefore:myVar[gg gg]]",anchorWidget).join(",")).toBe("a,b,gg gg,c,d,e,f");
-			
 			expect(wiki.filterTiddlers("a b c d e +[insertbefore:myVar<tidList>]",anchorWidget).join(",")).toBe("a,b,one tid with spaces,c,d,e");
 			expect(wiki.filterTiddlers("a b c d e f +[insertbefore:tidTitle{TiddlerOne!!tags}]",anchorWidget).join(",")).toBe("a,b,c,d,one,e,f");
+
+			// Position title specified as parameter.
+			expect(wiki.filterTiddlers("a b c d e +[insertbefore[f],[a]]",anchorWidget).join(",")).toBe("f,a,b,c,d,e");
+			expect(wiki.filterTiddlers("a b c d e +[insertbefore[f],<myVar>]",anchorWidget).join(",")).toBe("a,b,f,c,d,e");
+
+			// Parameter takes precedence over suffix.
+			expect(wiki.filterTiddlers("a b c d e +[insertbefore:myVar[f],[a]]",anchorWidget).join(",")).toBe("f,a,b,c,d,e");
 	
-			// Next 2 tests do weired things, but will pass - there for compatibility reasons
+			// No position title.
 			expect(wiki.filterTiddlers("a b c [[with space]] +[insertbefore[b]]").join(",")).toBe("a,c,with space,b");
-			expect(wiki.filterTiddlers("a b c d e +[insertbefore:2[b]]").join(",")).toBe("a,c,d,e,b");
+
+			// Position title does not exist.
+			expect(wiki.filterTiddlers("a b c d e +[insertbefore:foo[b]]").join(",")).toBe("a,c,d,e,b");
+			expect(wiki.filterTiddlers("a b c d e +[insertbefore[b],[foo]]").join(",")).toBe("a,c,d,e,b");
+			expect(wiki.filterTiddlers("a b c d e +[insertbefore[b],<foo>]").join(",")).toBe("a,c,d,e,b");
 		});
 	
 		it("should handle the move operator", function() {

editions/tw5.com/tiddlers/filters/examples/insertbefore Operator (Examples).tid

@@ -0,0 +1,28 @@
+created: 20220223004441865
+modified: 20220223004441865
+tags: [[Operator Examples]] [[insertbefore Operator]]
+title: insertbefore Operator (Examples)
+type: text/vnd.tiddlywiki
+
+\define before-title() Friday
+\define missing-title() Yesterday
+\define display-variable(name)
+''<$text text=<<__name__>>/>'': <code><$text text={{{ [<__name__>getvariable[]] }}}/></code>
+\end
+
+These examples use the following predefined variables:
+
+* <<display-variable before-title>>
+* <<display-variable missing-title>>
+
+<<.operator-example 1 """[list[Days of the Week]insertbefore[Today]]""">>
+
+<<.operator-example 2 """[list[Days of the Week]insertbefore[Today],[Tuesday]]""">>
+
+<<.operator-example 3 """[list[Days of the Week]insertbefore[Today],<before-title>]""">>
+
+<<.operator-example 4 """[list[Days of the Week]insertbefore:before-title[Today]]""">>
+
+<<.operator-example 5 """[list[Days of the Week]insertbefore[Today],<missing-title>]""">>
+
+<<.operator-example 6 """[list[Days of the Week]insertbefore:missing-title[Today]]""">>

editions/tw5.com/tiddlers/filters/insertbefore Operator.tid

@@ -1,15 +1,31 @@
 caption: insertbefore
 created: 20170406090122441
-modified: 20170406091248994
+modified: 20220223004441865
 op-input: a [[selection of titles|Title Selection]]
 op-output: the input tiddler list with the new entry inserted
-op-parameter: the title of the tiddler to insert
-op-parameter-name: T
+op-parameter: <<.from-version "5.2.2">> the <<.op insertbefore>> operator accepts 1 or 2 parameters, see below for details
 op-purpose: insert an item <<.place T>> into a list immediately before an item <<.place B>>
-op-suffix: the name of a variable containing the title of the tiddler before which this one should be inserted
-op-suffix-name: B
+op-suffix: (optional) the name of a variable containing the title of the tiddler before which this one should be inserted
 tags: [[Filter Operators]] [[Order Operators]] [[Listops Operators]]
 title: insertbefore Operator
 type: text/vnd.tiddlywiki
 
+<<.from-version "5.2.2">>
+
+The <<.op insertbefore>> operator requires at least one parameter which specifies the title to insert into the input list. A second parameter can be used to specify the title before which the new title should be inserted.
+
+```
+insertbefore:<before-title-variable>[<title>],[<before-title>]
+```
+
+* ''title'' : a title <<.place T>> to insert in the input list.
+* ''before-title'' : (optional). Insert <<.place T>> before this title <<.place B>> in the input list.
+* ''before-title-variable'' : (optional). The name of a variable specifying <<.place B>> instead of the `before-title` parameter.
+
 If the item <<.place B>> isn't present in the input list then the new item is inserted at the end of the list.
+
+<<.tip "Either [[parameter|Filter Parameter]] can be a string, a text reference or a variable">>
+
+<<.tip "If <<.place B>> is specified as both a suffix and a parameter, the parameter takes precedence">>
+
+<<.operator-examples "insertbefore">>