Custom action methods in a few simple steps

Adamantium.js was built with the intention of giving each developer power to easily extend the framework with custom action methods to process the matched set, a.k.a. context. In this short guide we’ll cover the basics of this, while creating a method that replaces a defined string in any Label with another string.

Please observe that this guide applies to the syntax of Adamantium.js version 0.1, so read up on any changes if a new version has been released.

.replace( oldString [string], newString [string] );

$(":Label").replace("war", "peace");

So this chain would effectively select all Labels, replace each occurrence of the string “war” with the string “peace” and return the context.

Prototype a new method

It all begins with a core method in Adamantium.js that allows us to extend the framework and manipulate each component or element in the matched set, before passing the entire context on to the next action method in the chain.

$.extend("replace", function (component, oldString, newString) {
	return component;
});

The extend method takes the name of the new action method and the function to execute as arguments and expects you to return the component at the end of the method.

We start off by creating a conditional statement, as this method only will apply to Label elements.

$.extend('replace', function (component, oldString, newString) {
	if (component && component.type == 'Label') {
		// Here's where the magic will happen...
	}
    return component;
});

We also need to be sure that we have both the “oldString” and the “newString” string, otherwise our method really doesn’t need to do anything. And of course, for this to work, the “text” attribute on our Label should not be empty.

$.extend('replace', function (component, oldString, newString) {
	if (component && component.type == 'Label') {
		var full = $(component).attr('text');
		if (typeof full == 'string' && typeof oldString == 'string' && typeof newString == 'string') {
			// Okey, here's where the magic really happens. really...
		}
	}
    return component;
});

Now that we know that we have the three pieces we need to execute the method, let’s just do it using the String objects own replace method and a simple regexp. Then we simply update the attribute using the .attr( attribute, value ) method to allow any attribute change event handlers to react to this change.

$.extend('replace', function (component, oldString, newString) {
	if (component && component.type == 'Label') {
		var full = $(component).attr('text');
		if (typeof full == 'string' && typeof oldString == 'string' && typeof newString == 'string') {
			var re = new RegExp(oldString, 'g');
			var changed = full.replace(re, newString);
			$(component).attr('text', changed);
		}
	}
    return component;
});

There it is, framework extended with a custom action method in a few simple steps. Start experimenting yourself and please share anything you developed that you feel would benefit other users of Adamantium.js. Until I get another solution for “community components” going, posting links to pasties works just fine.