Using dojo/aspect

Simply put: the Dojo Toolkit has tools that other JavaScript toolkits don't. One of those tools includes Dojo 1.7's aspect, a module that allows developers to react to function calls by executing another function before or after that call. This aspect resource originates from Dojo's awesome connect mechanism. Let's check out how it works!

aspect Basics

The idea and value of aspect is that it allows you to be notified of function calls without needing to modify the original function's contents. You also don't need to implement pub/sub to know when methods are called. The basic setup looks like:

// Load the dojo/aspect dependency
require(["dojo/aspect"], function(aspect) {
	
	// Create an object and method to spy on
	var original = {
		someMethod: function(arg1, arg2) {
			console.warn("original.someMethod called: ", arg1, arg2);
			return "Hello " + arg1 + " " + arg2;
		}
	};
	
	// Use aspect.after ("before" also available)
	aspect.after(original, "someMethod", function(arg1, arg2) {
		console.warn("After method called with arguments: ", arg1, arg2);
	}, true);
	
	// ...and a while later, call the original method
	original.someMethod("David", "Walsh");
	
});

The first argument is the origin object, the second argument is the method to listen in on, and the third is the function to fire before or after, depending on which aspect method you call.

aspect.before

The before method will fire before the originally called method fires:

// Fire a function before the original
aspect.before(original, "someMethod", function(arg1, arg2) {
	console.warn("aspect.before: ", arg1, arg2);
});

// "aspect.before: ", David, Walsh
// "original.someMethod called:", David, Walsh

Since this method is fired before the original function call, the arguments passed to the original method are automatically received by the aspect method.

aspect.after

The after method fires after the original method fires, and accepts an extra parameter called receiveArguments, where you may direct the second method to receive the original method's arguments, or the return value of the original method.

receiveArguments = true

Passing the receiveArguments as true will pass the two arguments from the original function call to the aspect method:

// First scenario:  aspect.after that accepts the same arguments as the origin function
// because the fourth argument is passed as "true"
aspect.after(original, "someMethod", function(arg1, arg2) {
	console.warn("After method called with arguments: ", arg1, arg2);
}, true);

// Call the original method, see what happens!
original.someMethod("David", "Walsh");

// "original.someMethod called:", David, Walsh
// "aspect.after: ", David, Walsh

Removing the last argument instead allows the aspect method to receive the return value of the original function call:

// Second scenario: aspect.after that accepts the result of the original function call
aspect.after(original, "someMethod", function(arg1, arg2) {
	console.warn("aspect.after: ", arg1, arg2);
	
	// "arg2" will be "undefined" since only the return value is provided 
	
}); // No "true"

// Call the original method, see what happens!
original.someMethod("David", "Walsh");

// "original someMethod: David Walsh"
// "aspect.after: ", David Walsh

In most cases, aspect.after is what you will want to use. An object with a remove method will be returned, allowing you to remove the connection whenever you'd like.

aspect.around

What if you want to execute code both before and after the original method? Simple: use aspect.around. The around method allows you to call the original function when you want, within your listener:

// Call the around method, which gets one argument, the original method
aspect.around(original, "someMethod", function(originalMethod) {
	// Return a new method, which receives the same arguments as the original, just like "aspect.after"
	return function(arg1, arg2) {
		// Execute "before" functionality
		console.warn("before!", arg1, arg2);
		
		// Execute the original method as desired
		originalMethod.apply(this, arguments);
		
		// Execute "after" functioanlity
		console.warn("after!");
	};
});

// Call the original method, see what happens!
original.someMethod("David", "Walsh");

// "before!", David, Walsh
// "original someMethod: David Walsh"
// "after! David Walsh"

The idea behind aspect.around is very much like using this.inherited(arguments) within Dojo classes; you can make that call any time you'd like, so other code may run before or after.

Real Use of aspect

One realistic use of aspect relates to extending Dijit widgets, or building a Dijit layout that uses multiple widgets. Often you'll see something like:

// When the onChange event fires
aspect.after(this.dropdown, "onChange", function(value) {
	// ...fire an xhr request to get information about it
	dojo.xhrGet({
		url: "/data.php?value=" + value
	}).then(function(data) { 
		// Do something with it.
	});
}, true);

When the dropdown's value changes, an XHR request is fired to get information about that value.

Explaining aspect and the value of function-to-function connections can be difficult. I usually try a parent-to-child analogy that just further confuses people. Think of it this way: aspect allows you to know when other functions are called, without needing to modify the other function. This happens all over the Dijit UI framework, Brilliant!