Monthly Archives: November 2009

Custom Modules in YUI 3

YUI 3 uses modules to group functionality and to only load what is used. This post describes how to create custom modules.

The typical way modules are used is within the use() statement:

YUI().use('node', 'event', function(Y) {
    // your stuff here
});

In the above example the modules node and event are loaded. Let’s see how custom modules may be included in the same way.

To define a new module the add() statement is used (note that it is a class and not instance method of the YUI object):

YUI.add('my_module', function(Y) {
    Y.myFunction = function() {
        var privateFunc = function() {
            // ...
        };

        return {
            publicFunc: function() {
                // ...
            }
        }
    }();
}, '0.0.1', { requires: ['node'] });

A common way to share functionality among different YUI instances is to use the YUI namespace when assigning the function. If you do not recognize the structure of the above function definition you may find out more by reading about the module pattern.

If the file containing the custom module code is loaded, the custom module may be used in any use() statements as normal YUI modules, i.e. use(‘my_module’, …).

To leverage the power of the YUI loader to dynamically load the custom module a configuration object may be created.

YUI({
    modules: {
       'my_module': {
           fullpath: "http://mydomain.com/js/my_module.js",
           requires: ['node']
       }
    }
}).use('node', 'my_module, function(Y) {
    // access functionality of custom module
    Y.myFunction.publicFunc();
});

One thing to note is that YUI currently only makes one request to fetch dependencies. That is why the module’s requires array must be specified in the configuration object as well, in addition to what is in the last parameter of the add() statement.

Instance and class based plugins in YUI 3

Using plugins in YUI 3 is a way to add functionality to existing objects in YUI (very much like you would use prototype to augment a function to a normal JavaScript object). Objects in YUI all derive from Y.Base.

Note that this post is about YUI 3 and not YUI 2.

However, the current YUI 3 documentation does really only get into how to add a plugin to a current instance. What about adding functionality to the class level so all instances of the same type of objects automatically get it?

First an example of how a simple plugin may look like:

NodePlugin = function(config) {
    this._node = config.host;
}

NodePlugin.NS = 'vis';
NodePlugin.NAME = 'NodeVisibiltyPlugin';

NodePlugin.prototype = {
    show: function() {
        this._node.setStyle('display', 'block');
        return this_node;
    },

    hide: function() {
        this._node.setStyle('display', 'none');
        return this_node;
    }
};

What this plugin does it to add hide() and show() functions to the vis namespace (as specified in the code) of Y.Node.

This plugin would typically be used like this:

var node = Y.one('#myElement');
node.plug(NodePlugin); // add plugin functionality
node.vis.hide();

If you would like to use the plugin functionality for all node objects it would be somewhat tedious to invoke plug() for each and every instance. The way to get around this, which is not really documented except in the API reference, is to use the static method Y.Plugin.Host.plug.

Y.Plugin.Host.plug(Y.Node, NodePlugin); // plug once ...

var node = Y.one('#myElement');
node.vis.hide(); // ... use anywhere

Now any new instances of Y.node have access to the plugin methods through the specified namespace. I also discovered that in order for this to work the static NAME property must be defined in the plugin object.