4.0 - Extending JS controllers using Mixins

Reminder: this blog covers the technical details of 4.0's programming. For details on 4.0's features, follow our main blog.

Reviewing controllers

Some time ago, I blogged about the javascript framework we've built for IPS4. In it, I covered the most important component: controllers. To recap, a controller is a special object within the framework, and is applied on specific elements. That element is the controller's scope, and the controller works on it to provide its functionality. For example, a simple controller might look like this:

ips.controller.register('core.global.core.example', {

	initialize: function () {
		this.on( 'click', this.showAlert );
	},

	showAlert: function (e) {
		alert( "This button's text is: " + this.scope.html() );
	}
});

It would be used on an element like so:

<button data-controller='core.global.core.example'>Click me</button> 

Here we're registering core.global.core.example as a controller. This represents the controller path - it's in the format app.module.group.controllerName. Though it seems longwinded, this allows IPS4 to dynamically load controllers on-demand, rather than loading them all when the page is loaded. In the initialize method (called automatically), we set up an event handler for a click. When the element is clicked, you'd see an alert saying "This button's text is: Click me".

So, that's how controllers work. Almost all page behavior in IPS4 is handled through controllers. But how would you change a method in an existing controller, say if you were writing an addon, or if you had two controllers that were fairly similar, and wanted to provide a base controller they both shared?

Mixins

To enable that, we have mixins. Mixins allow you to specify functions which are inherited by objects - in this case, our controller objects. This means, using mixins we can add new functions to a controller without needing to edit the controller itself.

A mixin is defined like so:

ips.controller.mixin('addAnotherMethod', 'core.global.core.example', true, function () {

	this.anotherMethod = function () {
		alert('Inside anotherMethod');
	};

});

The ips.controller.mixin method takes up to 4 parameters:

ips.controller.mixin( name, controller, automaticallyExtend, fnDefinition )

name: Name to identify this mixin
controller: The controller this mixin extends
automaticallyExtend: [optional, default false] Does this mixin automatically extend the controller (more on that below)
fnDetinition: The function definition applied to the controller

In this example, our mixin adds a method named anotherMethod to our core.global.core.example controller shown earlier.

Let's talk more about the automaticallyExtend parameter. Mixins can be applied to controllers in one of two ways - either automatically on a global basis, or manually on a case-by-case basis. Mixins are manually specified like so:

<button data-controller='core.global.core.example( addAnotherMethod )'>Click me</button>

This means the mixin is used on this element - but another element using core.global.core.example wouldn't get it. This is useful when you're building your own apps or addons; you can write simple controllers that implement base functionality, then extend them with functionality for specific cases by specifying the mixin name in your HTML. We use this ourselves - for example, we have a base table controller that handles sorting, filtering and so forth. We then have a mixin for AdminCP tables, and a mixin for front-end tables, which add functionality specific to those areas, reducing code duplication.

If you're extending an IPS controller in an IPS app, though, modifying the HTML isn't typically an option. Instead, you can specify the mixin as global, and it will be applied to all elements where that controller is used. This means you can write your own mixins that work with our default controllers without having to touch our controller code (and that's a good thing).

Advice

So that shows how to add new methods to a controller. But what if you want to work with the methods that already exist in the controller? In the above example you'd only be able to overwrite an existing method - certainly not ideal, because 1) you would break any other mixins using the default method, 2) if we made an update to a method in a later release, your mixin would break it.

To facilitate working with existing controller methods, we're using a model called advice. This adds three special methods to a mixin: before, after and around. These let you 'hook into' existing methods and provide additional code for them. Let's rewrite our example mixin from above to take advantage of it:

ips.controller.mixin('changeBackground', 'core.global.core.example', function () {

	this.before('showAlert', function () {
		this.scope.css({ background: 'red' });
	};

});

Here, I'm using the before method. I'm hooking into showAlert method (from the controller), and changing the background color of the scope element. So what happens when the link is clicked? First the background changes to red, and then an alert box is shown. We've added the background changing functionality without needing to edit the controller at all. Here's two other ways of doing the same thing, using the other two special methods:

ips.controller.mixin('changeBackground', 'core.global.core.example', function () {

	this.after('showAlert', function () {
		this.scope.css({ background: 'red' });
	};

	this.around('showAlert', function (origFn) {
		this.scope.css({ background: 'red' });
		origFn();	
	};

});

The after method is fairly self-evident. With the around method, the original function is passed in as an argument, allowing you to determine when it is executed by your mixin.

All three of these methods will stack, so multiple mixins can hook into the same method, and they'll be executed in order, each receiving the previous.

Conclusion

I hope this introduction to mixins proves useful to developers; it shows how our core app controllers can be extended in a non-destructive way, but also how your own apps can use the mixin functionality to create an inheritance model to make your life easier.

Javascript in IPS4 makes extensive use of custom events, so the preferred way of adding new functionality is to listen for appropriate events and act on them - but the mixin support described above provides a mechanism by which you can adapt existing event handlers.