Support specifying insertbefore position title as parameter

Closes: #6133

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);

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

@@ -752,16 +752,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");
 
-			// Next 2 tests do weired things, but will pass - there for compatibility reasons
+			// 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");
+	
+			// 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">>