usage

$.invert is a simple wrapper around the configuration for the IoC container (Inversion-of-Control). The concept of inversion is very simple, it simply allows you to wire together existing application components.

Inverting your objects can be useful, though often it is just as clear to uses $.$ to set references to other application object compenents in the constuctor and simply use $.scan to keep configuration to a minimum. That said $.invert is a powerful little tool which can be used to very clearly describe application objects without the boiler plate code that goes along with creating a new application component.

There are two distint ways to use this plugin.

• instance
  The instance pattern uses 'new' to create the object from its constructor.
• factory
  The factory pattern allows another object to manage the creation of the object.

instance

Inversion of Control is a powerful tool for removing hard wiring of dependencies from code and allowing the instance to remain 'dormant' until the application framework detects it's needed, creating it on-the-fly and decorating with knowledge of other run time application components, or simply making use of highly configurable objects with unique options.

Name	Type
id	String
An unique, preferably human readable name
clazz	String
Dot-delimited name of the class (constructor)
selector	String
A jQuery selector used to bind the object to a dom node(or nodes)
active	Boolean
Is the selector live
options	Array
An array treated as arguments for construction
inject	Object
An hash of values or references to other application objects to be attached to the instance after it is constructed

In the following example we use all the bells and whistles. We create an instance #wikipadView thats attached to the dom node with the id #wikipad . The dom element doesn't need to be present when the application starts, or even when the instance is created, it will be bound to the element when ever it's appended to the dom.

We also provide the class name as a string, claypool will resolve it, so the class doenst even have to exist when the application is started. The options will be passes as arguments when the class is created with new .

Finally, the wiki parser is injected , meaning the parser property is set after the instance is created. The ref:// prefix let's claypool know the object it's injecting is another application managed component, so it will create it if it hasn't been created before.

/*
 * @file app/configs/config.js
 * @description If you need to integrate some legacy code
 *     or have written some highly reusable code that
 *     provides some flexible abstraction the instance
 *     configuration is what you'll want to use.
 */

(function($){
    
    $.invert([{
        
         id:"#wikipadView",
         selector:"#wikipad",
         active: true,
         clazz: "MyApp.Views.WikiPad",
         options: [{safeStripHtml: true}],
         inject: {
             parser:"ref://#creoleParser"
         }

    },{
    
         id:"#creoleParser",
         clazz:"Parse.Simple.Creole",
         options: [{
             interwiki: {
                 WikiCreole: 'http://www.wikicreole.org/wiki/',
                 Wikipedia: 'http://en.wikipedia.org/wiki/'
             },
             linkFormat: ''
         }]
    }]);
    
})(jQuery);
        

The important options for the configuration of the parser is floated to the configuration, which is assumed to be important for the purpose of this example.

factory

The factory pattern allows the construction of the application managed object to be delegated to another class. The factory class may either be specified as dot-delimited String so claypool can resolve it, or it can be a reference to another application managed object by prefixing it's name with ref:// .

Name	Type
id	String
An unique, preferably human readable name
factory	String
Dot-delimited name of the factory class (constructor) or a ref:// to another application managed object
factoryMethod	String	Default: 'create'
Optionally, the method claypool will call on the factory. The returned value is the new object

In the following example have two separate factory patterns. The first illustrates the use of a factory that is itself an application managed object (presumably the factory is doing something like detecting what wiki parser is available or something)

The second example shows the use of a factory specified by class name with a custom create method connect . This factory might detect network status and use an offline datastore.

/*
 * @file app/configs/config.js
 * @description If you want to have special control over the
 *     construction of you application object, you can use 
 *     the factory pattern.  Factories can be classes or 
 *     application managed components.
 */

(function($){
    
    $.invert([{
        
         id:"#wikipadView",
         selector:"#wikipad",
         active: true,
         factory: "ref://#wikipadFactory"

    },{
         
         id:"#wikipadFactory",
         clazz:"MyApp.Utils.WikiPadFactory"

    },{
        
         id:"#addressBookModel",
         factory: "MyApp.Utils.NetworkAdaptorFactory",
         factoryMethod: "connect"

    }]);
    
})(jQuery);
        

examples

A very good example of the power of invert is shows how jquery-claypool uses it to define the server-side plugin $.proxy . This is taken directly from the source:

    proxy: function(options)[{
        return $.invert([[{ 
            id:options.id||'proxy_'+$.guid(),    
            clazz:"Claypool.Server.WebProxyServlet", 
            options:[[{
                rewriteMap:options.rewrites
            }]
        }]);
    }
        

Which means we can very simply create new proxies like

    $.proxy([{
        id:'feedProxy',
        rewrites:[
            { urls:'^/share/', rewrite:'http://someotherhost.com/foo' },
            { urls:'^/feeds/', rewrite:'http://blogs.otherhost.org/' }
        ]
    });