added special tag ahndling + docs...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>

ui (gen4)/imagegrid/tags.js

@@ -1496,59 +1496,95 @@ object.makeConstructor('BaseTags',
 var TagsWithHandlersPrototype = {
 	__proto__: BaseTagsPrototype,
 
-	// XXX docs...
+	//
-	__special_tag_handlers__: {
+	// Example handlers:
-		// print and remove tag...
+	// 	{
-		'test': function(tag, action, value){
+	//		// remove the 'test' tag...
-			console.log('TEST TAG:', tag, action, value)
+	//		//
-			return this.removeTag('test', tag)[0]
+	//		'test': function(tag, action, ...other){
-		},
+	//		    return this.removeTag('test', tag)[0] },
-		// terminate handling...
+	//
-		'stop': function(tag, action, value){
+	//		// terminate handling on 'stop'...
-			console.log('STOP:', tag, action, value)
+	//		//
-			return false 
+	//		// NOTE: this will not prevent the method execution, only special
-		},
+	//		// 		tag handling will be stopped...
-		// print the tag...
+	//		'stop': function(tag, action, ...other){
-		'*': function(tag, action, value){
+	//			return false },
-			console.log('TAG:', tag, action, value)
+	//
-			return tag 
+	//		// print the tag operation info...
-		},
+	//		//
-	},
+	//		'*': function(tag, action, ...other){
+	//			console.log('TAG:', action, tag, ...other)
+	//			return tag },
+	//
+	//		...
+	//	}
+	//
+	__special_tag_handlers__: null,
+
 
 	// NOTE: handlers are called in order of handler occurrence and not 
 	// 		in the order the tags are in the given chain/path...
-	handleSpecialTag: function(tag, ...args){
+	handleSpecialTag: function(tags, ...args){
 		var that = this
-		var handlers = this.__special_tag_handlers__
+		var handlers = this.__special_tag_handlers__ || {}
-		tag = this.normalize(tag)
+		tags = this.normalize(tags)
-		return Object.keys(handlers)
+		return tags instanceof Array ?
-				.filter(function(p){
+			tags.map(function(tag){
-					// keep only valid tag patterns...
+				return that.handleSpecialTag(tag, ...args) })
-					// NOTE: this enables us to create special handlers 
+			: (Object.keys(handlers)
-					// 		that will not be used for matching but are more 
+					.filter(function(p){
-					// 		mnemonic...
+						// keep only valid tag patterns...
-					return p == that.normalize(p)
+						// NOTE: this enables us to create special handlers 
-						// get the matching handler keys...
+						// 		that will not be used for matching but are more 
-						&& that.directMatch(p, tag)
+						// 		mnemonic...
-				})
+						return p == that.normalize(p)
-				// resolve handler aliases...
+							// get the matching handler keys...
-				.map(function(match){
+							&& that.directMatch(p, tags)
-					do {
+					})
-						match = handlers[match]	
+					// resolve handler aliases...
-					} while(!(match instanceof Function) && match in handlers)
+					.map(function(match){
-
+						do {
-					return match instanceof Function ? 
+							match = handlers[match]	
-						match 
+						} while(!(match instanceof Function) 
-						// no handler...
+							&& match in handlers)
-						: [] })
+						return match instanceof Function ? 
-				.flat()
+							match 
-				// call the handlers...
+							// no handler...
-				// NOTE: we are threading tag through the handlers...
+							: [] })
-				.reduce(function(tag, handler){
+					.flat()
-					return tag && handler.call(that, tag, ...args) }, tag) 
+					// call the handlers...
-			// no handlers -> return as-is...
+					// NOTE: we are threading tag through the handlers...
-			|| tag },
+					.reduce(function(tag, handler){
+						return tag 
+							&& handler.call(that, tag, ...args) }, tags) 
+				// no handlers -> return as-is...
+				|| tags) },
 
+	//
+	// Handler actions: 
+	// 	[method]		[action]
+	// 	.tag(..)		-> 'tag'
+	// 	.untag(..)		-> 'untag'
+	// 	.rename(..)		-> 'rename'
+	// 					-> 'remove'
+	//
+	tag: function(tags, value){
+		var that = this
+		return TagsWithHandlersPrototype.__proto__.tag.call(this, 
+			that.handleSpecialTag(tags, 'tag', value),
+			...[...arguments].slice(1)) },
+	untag: function(tags, value){
+		var that = this
+		return TagsWithHandlersPrototype.__proto__.untag.call(this, 
+			that.handleSpecialTag(tags, 'untag', value),
+			...[...arguments].slice(1)) },
+	rename: function(tag, to, ...tags){
+		return TagsWithHandlersPrototype.__proto__.rename.call(this,
+			tags.length == 0 ?
+				this.handleSpecialTag(tag, to == '' ? 'remove' : 'rename', to)
+				: tag,
+			...[...arguments].slice(1)) },
 }
 
 
@@ -1565,7 +1601,10 @@ object.makeConstructor('TagsWithHandlers',
 //---------------------------------------------------------------------
 
 var Tags =
-module.Tags = TagsWithHandlers
+module.Tags = 
+	TagsWithHandlers
+	//BaseTags
+