Writing Hitches

Writing Hitches

Users can create one or more new hitch definitions and register them with the hitch engine. Definitions are object literals containing the following properties:

• name: The prefixed name of your hitch. This is what will be exposed for use.

• filter: (optional) A test function which is called by the engine when necessary according to the hitch's use in CSS. The truthfulness of the rule is determined by the function's return value. Filters are passed the matched element, any arguments to the filter as a String and a third argument containing various meta data described |here|.

• init: (optional) A function which is called once during the initial application. It is passed the matching element.

• base: (optional) You can potentially improve the performance of your hitch and terseness of rules that use them by providing a base selector.

Below is a sample (from the -math-* library posted |here|) of a filter which allows filtering of elements based on whether they have a particular attribute, that attribute is numeric and above a certain threshold...

Hitch.add([{  
	name: '-my-lessthan',
	filter: function(match, argsString){
		var args = argsString.split(",");
		var value = match.getAttribute(args[0]);
		if(!isNaN(value) && !isNaN(args[1])){
			return (value > parseInt(args[1],10));
		};
		return false;
	}
}]);

Definitions can also provide an optional 'base' property whose value is a selector list which must apply in order for the filter to be called - it is essentially an optimization. The advantage of using a base selector is that the engine can potentially better optimize the work/scope that needs to be done, limiting the number of calls to the filter regardless of how the rule is written. In the case of the example above, if we knew that this filter would only ever apply to something with the 'score' attribute, we might choose to optimize it by adding a base:

Hitch.add([{  
	name: '-my-lessthan',   
	base: '[score]',
	filter:   function(match, argsString){
		var args = argsString.split(",");
		var value = match.getAttribute(args[0]);
		if(!isNaN(value) && !isNaN(args[1])){
	        return (value > parseInt(args[1],10));
		};
		return false;
	}
}]);