Add new parameters to fields-widget and fields-operator. (#4433)

* add a new-line before the log text to increase readability of the test output

* make eslint, jslint happy

* extend fields-widget with include/exclude/sort/reverse and fields-filter with include and exclude params plus DOCS

* remove new-line

* remove eslint settings

* restore old eslint settings

* remove typo

core/modules/filters/fields.js

@@ -16,13 +16,28 @@ Filter operator for returning the names of the fields on the selected tiddlers
 Export our filter function
 */
 exports.fields = function(source,operator,options) {
-	var results = [];
+	var results = [],
+		fieldName,
+		suffixes = (operator.suffixes || [])[0] || [],
+		operand = $tw.utils.parseStringArray(operator.operand);
+	
 	source(function(tiddler,title) {
 		if(tiddler) {
-			for(var fieldName in tiddler.fields) {
-				$tw.utils.pushTop(results,fieldName);
-			}
-		}
+			if(suffixes.indexOf("include") !== -1) {
+				for(fieldName in tiddler.fields) {
+					(operand.indexOf(fieldName) !== -1) ? $tw.utils.pushTop(results,fieldName) : "";
+				}
+			} else if (suffixes.indexOf("exclude") !== -1) {
+				for(fieldName in tiddler.fields) {
+					(operand.indexOf(fieldName) !== -1) ? "" : $tw.utils.pushTop(results,fieldName);
+				}
+			} // else if
+			else {
+				for(fieldName in tiddler.fields) {
+					$tw.utils.pushTop(results,fieldName);
+				}
+			} // else
+		} // if (tiddler)
 	});
 	return results;
 };

core/modules/widgets/fields.js

@@ -42,44 +42,53 @@ FieldsWidget.prototype.execute = function() {
 	// Get parameters from our attributes
 	this.tiddlerTitle = this.getAttribute("tiddler",this.getVariable("currentTiddler"));
 	this.template = this.getAttribute("template");
+	this.sort = this.getAttribute("sort","yes") === "yes";
+	this.sortReverse = this.getAttribute("sortReverse","no") === "yes";
 	this.exclude = this.getAttribute("exclude");
+	this.include = this.getAttribute("include",null);
 	this.stripTitlePrefix = this.getAttribute("stripTitlePrefix","no") === "yes";
 	// Get the value to display
 	var tiddler = this.wiki.getTiddler(this.tiddlerTitle);
-	// Get the exclusion list
-	var exclude;
-	if(this.exclude) {
-		exclude = this.exclude.split(" ");
-	} else {
-		exclude = ["text"]; 
-	}
+
+	// Get the inclusion and exclusion list
+	var excludeArr = (this.exclude) ? this.exclude.split(" ") : ["text"];
+	// Include takes precedence
+	var includeArr = (this.include) ? this.include.split(" ") : null;
+
 	// Compose the template
 	var text = [];
 	if(this.template && tiddler) {
 		var fields = [];
-		for(var fieldName in tiddler.fields) {
-			if(exclude.indexOf(fieldName) === -1) {
-				fields.push(fieldName);
+		if (includeArr) { // Include takes precedence
+			for(var i=0; i<includeArr.length; i++) {
+				if(tiddler.fields[includeArr[i]]) {
+					fields.push(includeArr[i]);
+				}
+			}
+		} else {
+			for(var fieldName in tiddler.fields) {
+				if(excludeArr.indexOf(fieldName) === -1) {
+					fields.push(fieldName);
+				}
 			}
 		}
-		fields.sort();
-		for(var f=0; f<fields.length; f++) {
+		if (this.sort) fields.sort();
+		if (this.sortReverse) fields.reverse();
+		for(var f=0, fmax=fields.length; f<fmax; f++) {
 			fieldName = fields[f];
-			if(exclude.indexOf(fieldName) === -1) {
-				var row = this.template,
-					value = tiddler.getFieldString(fieldName);
-				if(this.stripTitlePrefix && fieldName === "title") {
-					var reStrip = /^\{[^\}]+\}(.+)/mg,
-						reMatch = reStrip.exec(value);
-					if(reMatch) {
-						value = reMatch[1];
-					}
+			var row = this.template,
+				value = tiddler.getFieldString(fieldName);
+			if(this.stripTitlePrefix && fieldName === "title") {
+				var reStrip = /^\{[^\}]+\}(.+)/mg,
+					reMatch = reStrip.exec(value);
+				if(reMatch) {
+					value = reMatch[1];
 				}
-				row = $tw.utils.replaceString(row,"$name$",fieldName);
-				row = $tw.utils.replaceString(row,"$value$",value);
-				row = $tw.utils.replaceString(row,"$encoded_value$",$tw.utils.htmlEncode(value));
-				text.push(row);
 			}
+			row = $tw.utils.replaceString(row,"$name$",fieldName);
+			row = $tw.utils.replaceString(row,"$value$",value);
+			row = $tw.utils.replaceString(row,"$encoded_value$",$tw.utils.htmlEncode(value));
+			text.push(row);
 		}
 	}
 	this.text = text.join("");
@@ -90,11 +99,13 @@ Selectively refreshes the widget if needed. Returns true if the widget or any of
 */
 FieldsWidget.prototype.refresh = function(changedTiddlers) {
 	var changedAttributes = this.computeAttributes();
-	if(changedAttributes.tiddler || changedAttributes.template || changedAttributes.exclude || changedAttributes.stripTitlePrefix || changedTiddlers[this.tiddlerTitle]) {
-		this.refreshSelf();
-		return true;
+	if( changedAttributes.tiddler || changedAttributes.template || changedAttributes.exclude ||
+		changedAttributes.include || changedAttributes.sort || changedAttributes.sortReverse ||
+		changedTiddlers[this.tiddlerTitle] || changedAttributes.stripTitlePrefix) {
+			this.refreshSelf();
+			return true;
 	} else {
-		return false;	
+		return false;
 	}
 };
 

editions/tw5.com/tiddlers/filters/examples/fields.tid

@@ -1,8 +1,12 @@
 created: 20150118134611000
-modified: 20150118183206000
+modified: 20200129165627964
 tags: [[fields Operator]] [[Operator Examples]]
 title: fields Operator (Examples)
 type: text/vnd.tiddlywiki
 
 <<.operator-example 1 "[[HelloThere]fields[]]" "fields of HelloThere">>
-<<.operator-example 2 "[tag[Common Operators]fields[]]" "fields of all tiddlers tagged as [[Common Operators]]">>
+<<.operator-example 2 "[[HelloThere]fields:include[list title text non-existing]]" """fields of HelloThere using a "short list" of fields. Fields are only shown, if they exist""">>
+<<.operator-example 3 "[[HelloThere]fields:include[list title text]sortby[title list text]]" "fields of HelloThere special sorting">>
+<<.operator-example 4 "[[HelloThere]fields:exclude[list title text]]" "fields of HelloThere using the exclude suffix">>
+<<.operator-example 5 "[[HelloThere]fields[]] -list -title -text" "fields of HelloThere, using several filter runs instead of exclude suffix">>
+<<.operator-example 6 "[tag[Common Operators]fields[]]" "fields of all tiddlers tagged as [[Common Operators]]">>

editions/tw5.com/tiddlers/filters/fields.tid

@@ -1,14 +1,17 @@
+caption: fields
 created: 20140924115616653
-modified: 20150203184828000
+modified: 20200129165038748
+op-input: a [[selection of titles|Title Selection]]
+op-output: all the field names contained in the input tiddlers
+op-parameter: <<.from-version "5.1.22">> optional: a [[list of field names|TiddlerFields]]
+op-purpose: select all field names of the input titles
+op-suffix: <<.from-version "5.1.22">> optional: `include`, `exclude` parameter list
 tags: [[Filter Operators]] [[Field Operators]]
 title: fields Operator
 type: text/vnd.tiddlywiki
-caption: fields
-op-purpose: select all field names of the input titles
-op-input: a [[selection of titles|Title Selection]]
-op-parameter: none
-op-output: all the field names contained in the input tiddlers
 
-Each input title is processed in turn. Its list of field names is retrieved (in no particular order) and then [[dominantly appended|Dominant Append]] to the operator's output.
+Each input title is processed in turn. Its list of field names is retrieved (in no particular order) and then [[dominantly appended|Dominant Append]] to the operator's output. 
+
+<<.from-version "5.1.22">> If the `include` suffix is used, fields are only included, if they exist. It doesn't matter, if fields have a value. The `exclude` suffix is there for convenience, since it would be possible to use a second filter run. For more info see the examples.
 
 <<.operator-examples "fields">>

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

@@ -25,6 +25,9 @@ The content of the `<$fields>` widget is ignored.
 |tiddler |Title of the tiddler from which the fields are to be displayed (defaults to the [[current tiddler|Current Tiddler]]) |
 |template |Text of the template (see above) |
 |exclude |Lists of fields to be excluded (defaults to "text") |
+|include |Lists of fields to be included, if the field exists. This parameter takes precedence over "exclude" |
+|sort |Sorts the fields by name (defaults to "yes"). Set to "no", if "include" order should be retained! |
+|sortReverse |Reverses the sort order|
 |stripTitlePrefix |If set to "yes" then curly bracketed prefixes are removed from titles (for example `{prefix}HelloThere` converts to `HelloThere`) |
 
 The `stripTitlePrefix` attribute is used when building TiddlyWiki Classic; see `editions/tw2` in the TiddlyWiki5 repo.