Plugin format

Brian Cavalier edited this page Oct 20, 2011 · 2 revisions

A wire plugin is any module that defines an object with the following method property:

wire$plugin: function(ready, destroyed, options) {

    // Parameters:

    // ready: a Promise that will resolve when the current wire spec
    // has been wired.

    // destroy: a Promise that will resolve when the context created from
    // the current wire spec is destroyed.

    // options: plugin-specific options declared in the plugin definition
    // in the current wire spec.

    // return a plugin instance for the wire spec currently
    // being wired.

    return {
        // See below for plugin instance format
    };
}

The wire$plugin method should return a plugin instance. Wire will invoke the wire$plugin method before wiring the wire spec where the plugin is loaded.

The plugin instance returned by the wire$plugin method can provide lifecycle listeners, Factories, Facets, and Reference resolvers. A plugin can define as many or as few of these things as needed.

Here is the full format for everything a plugin instance can define:

// return a plugin instance
wire$plugin: function(ready, destroyed, options) {
    return {
        // Lifecycle listeners
        // Each component declared in a wire spec will pass through these
        // functions as it moves through its lifecycle.
        create:     function(resolver, proxy, wire) {},
        configure:  function(resolver, proxy, wire) {},
        initialize: function(resolver, proxy, wire) {},
        ready:      function(resolver, proxy, wire) {},
        destroy:    function(resolver, proxy, wire) {},

        // Reference resolvers
        // Custom reference resolvers that will be called to resolve
        // references with the key names.  E.g. a reference like:
        // { $ref: 'resolver1!referenceId' }
        // will be resolved by resolver1 below
        resolvers: {
            resolver1: function(resolver, refName, refObj, wire) {},
            resolver2: function(resolver, refName, refObj, wire) {}
            // ... more resolvers ...
        },

        // Factories
        // Factories create components.  A factory will be invoked to create
        // a component when it's key is present in the component's wire spec:
        // myComponent: {
        //   factory1: // factory1 options
        //   ... more myComponent facets here ...
        // }
        // NOTE: Exactly 1 factory will be invoked for each component
        factories: {
            factory1: function(resolver, spec, wire) {}
            // ... more factories ...
        },

        // Facets
        // Facets add behavior to components.  A facet will be invoked for
        // a component when the facet's key is present in the component's wire
        // spec:
        // myComponent: {
        //   facet1: // facet1 options
        //   ... more myComponent facets here ...
        // }
        // A facet can touch a component at any lifecycle stage by defining
        // a method with the corresponding lifecycle stage name.  For example,
        // if a facet defines a 'configure' method, that method will be invoked
        // during the 'configure' stage for each component with the facet's key.
        facets: {
            facet1: {
                create:     function(resolver, proxy, wire) {},
                configure:  function(resolver, proxy, wire) {},
                initialize: function(resolver, proxy, wire) {},
                ready:      function(resolver, proxy, wire) {},
                destroy:    function(resolver, proxy, wire) {},
            }
            // ... more facests ...
        }
    }
}