Add support for ordering tags by the 'list-before' and 'list-after' fields

See the discussion here:

https://groups.google.com/d/topic/tiddlywikidev/AXDJEjcAphs/discussion

core/modules/wiki.js

@@ -554,7 +554,31 @@ exports.sortByList = function(array,listTitle) {
 		for(t=0; t<array.length; t++) {
 			title = array[t];
 			if(list.indexOf(title) === -1) {
-				titles.push(title);
+				// Entry isn't in the list yet, so either append or insert;
+				// obey list-before and list-after if present for relative insertion point
+				var tiddler = this.getTiddler(title),
+					pos = -1;
+				if(tiddler) {
+					var beforeTitle = tiddler.fields["list-before"];
+					if(beforeTitle === "") {
+						pos = 0;
+					} else if(beforeTitle) {
+						pos = list.indexOf(beforeTitle);
+					} else {
+						var afterTitle = tiddler.fields["list-after"];
+						if(afterTitle) {
+							pos = list.indexOf(afterTitle);
+							if(pos >= 0) {
+								++pos;
+							}
+						}
+					}
+				}
+				if(pos >= 0) {
+					titles.splice(pos,0,title);
+				} else {
+					titles.push(title);
+				}
 			}
 		}
 		return titles;

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

@@ -0,0 +1,91 @@
+/*\
+title: test-tags.js
+type: application/javascript
+tags: [[$:/tags/test-spec]]
+
+Tests the tagging mechanism.
+
+\*/
+(function(){
+
+/*jslint node: true, browser: true */
+/*global $tw: false */
+"use strict";
+
+describe("Tag tests", function() {
+
+	// Create a wiki
+	var wiki = new $tw.Wiki();
+
+	// Add a few  tiddlers
+	wiki.addTiddler({
+		title: "TiddlerOne",
+		text: "The quick brown fox in $:/TiddlerTwo",
+		tags: ["one","TiddlerSeventh"],
+		modifier: "JoeBloggs",
+		modified: "201304152222"});
+	wiki.addTiddler({
+		title: "$:/TiddlerTwo",
+		text: "The rain in Spain\nfalls mainly on the plain and [[a fourth tiddler]]",
+		tags: ["two"],
+		modifier: "JohnDoe",
+		modified: "201304152211"});
+	wiki.addTiddler({
+		title: "Tiddler Three",
+		text: "The speed of sound in light\n\nThere is no TiddlerZero but TiddlerSix",
+		tags: ["one","two","TiddlerSeventh"],
+		modifier: "JohnDoe",
+		modified: "201304162202"});
+	wiki.addTiddler({
+		title: "a fourth tiddler",
+		text: "The quality of mercy is not drained by [[Tiddler Three]]",
+		tags: ["TiddlerSeventh"],
+		modifier: "JohnDoe"});
+	wiki.addTiddler({
+		title: "one",
+		text: "This is the text of tiddler [[one]]",
+		list: "[[Tiddler Three]] [[TiddlerOne]]",
+		modifier: "JohnDoe"});
+	wiki.addTiddler({
+		title: "$:/TiddlerFive",
+		text: "Everything in federation",
+		tags: ["two"]});
+	wiki.addTiddler({
+		title: "TiddlerSix",
+		text: "Missing inaction from TiddlerOne",
+		tags: []});
+	wiki.addTiddler({
+		title: "TiddlerSeventh",
+		text: "",
+		list: "TiddlerOne [[Tiddler Three]] [[a fourth tiddler]] MissingTiddler",
+		tags: []});
+	wiki.addTiddler({
+		title: "Tiddler8",
+		text: "Tidd",
+		tags: [],
+		"test-field": "JoeBloggs"});
+	wiki.addTiddler({
+		title: "Tiddler9",
+		text: "Another tiddler",
+		tags: ["TiddlerSeventh"],
+		"list-before": "a fourth tiddler"});
+	wiki.addTiddler({
+		title: "Tiddler10",
+		text: "Another tiddler",
+		tags: ["TiddlerSeventh"],
+		"list-before": ""});
+	wiki.addTiddler({
+		title: "Tiddler11",
+		text: "Another tiddler",
+		tags: ["TiddlerSeventh"],
+		"list-after": "Tiddler Three"});
+
+	// Our tests
+
+	it("should handle custom tag ordering", function() {
+		expect(wiki.filterTiddlers("[tag[TiddlerSeventh]]").join(",")).toBe("Tiddler10,TiddlerOne,Tiddler11,Tiddler Three,Tiddler9,a fourth tiddler");
+	});
+
+});
+
+})();

editions/tw5.com/tiddlers/concepts/TiddlerTags.tid

@@ -0,0 +1,46 @@
+created: 20140312124037773
+modified: 20140312124106267
+tags: concepts
+title: TiddlerTags
+type: text/vnd.tiddlywiki
+
+! Introduction
+
+Tiddlers can be assigned categories by assigning one or more tags. For example, tiddlers representing individuals might be tagged ''friend'', ''family'', ''colleague'' etc to indicate the relationship to the author.
+
+Multiple tags can be applied to the same tiddler. Used effectively they provide a powerful way to explore content related to a tiddler.
+
+TiddlyWiki offers several useful features based on the convention that a tag itself can be interpreted as the title of a tiddler.
+
+! Using Tags
+
+Tags are displayed at the top of the tiddler as coloured pills. Clicking on a tag pill drops down a menu showing links to all the tiddlers that carry that tag, along with a link to the tiddler representing the tag itself.
+
+When editing a tiddler, the tags pills have a small ''x'' icon that allows them to be removed individually. There is also a text box to type the name of a new tag to be added, and a dropdown autocomplete list that shows matching tags that are in use.
+
+! Tag Manager
+
+The tag manager is available via a button at the top of the sidebar tab "Tabs", or you can link directly to [[$:/TagManager]].
+
+! Assigning Colours and Icons to Tag
+
+The colour used to draw a tag pill is taken from the ''color'' field of the tiddler titled with the tag. The colour can be specified as any CSS value (more modern browsers show a colour picker for the ''color'' field).
+
+An icon can be associated with a tag by placing the title of the tiddler containing the image into the ''icon'' field of th etiddler titled with the tag.
+
+See the tag {{done||$:/core/ui/TagTemplate}} for an example.
+
+! Tag Ordering
+
+The ordering used to return a list of the tiddlers with a particular tag is determined by the following rules:
+
+* First, any tiddlers that are listed in the ListField of the tag tiddler are placed into a new list in the same order
+* Second, any unplaced tiddlers that have the field ''list-before'' are placed before the tiddler specified in the field
+** (if the ''list-before'' field is empty then the unplaced tiddler is placed at the start of the list)
+* Third, if any unplaced tiddlers have the field ''list-after'' then they placed immediately after the tiddler specified in the field
+* Finally, any remaining unplaced tiddlers are placed at the end of the list
+
+! System Tags
+
+See SystemTags for information about the special system tags that TiddlyWiki uses for configuration.
+

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

@@ -1,10 +1,12 @@
-created: 201308300925
+created: 20130830092500000
-modified: 201308300927
+modified: 20140312122907113
 tags: fields
 title: ListField
+type: text/vnd.tiddlywiki
 
 The `list` [[field of a tiddler|TiddlerFields]] is an optional feature that can be used to help structure your content. It is defined as an ordered sequence of tiddler titles, and it can be used in several ways:
 
+* The `list` field of a tiddler that is being used as a tag determines the ordering of the tiddlers that carry that tag - see TiddlerTags for details
 * The `list` [[filter|TiddlerFilters]] selects the entries from a list
 * The `listed` [[filter|TiddlerFilters]] selects the tiddlers that list the selected tiddler(s)
 * The NavigatorWidget manipulates a StoryList tiddler containing a `list` field of the tiddlers that are displayed in the main story column