wire dom

Brian Cavalier edited this page Sep 28, 2011 · 1 revision

wire/dom

The wire/dom plugin provides basic DOM integration for wire.js. It provides a reference resolver for DOM nodes that makes it easy to inject DOM nodes into your components, and options for adding and removing classes from the html element during wiring, when wiring has completed, and when destroying a Context.

Options

{
    module: 'wire/dom',

    // classes
    // The init and ready values are space-separated lists of classes to 
    // add to and remove from the <html> element during wiring.
    classes: {
        // These init classes will be added when wiring begins, and removed
        // when wiring completes.
        init: 'loading another-class',

        // These ready classes will be added once when wiring completes, that is,
        // when the wired context is ready.
        // They will be removed when the wired context is destroyed.
        ready: 'app-ready'
    }
}

dom! References

The wire/dom plugin provides a simple way to reference DOM nodes in a wire spec. This allows you create views and widgets that are more reusable by not being tied to HTML ids or classes, and inject the DOM node you want for the specific situation.

Syntax

The following is a reference to a DOM node whose id="my-dom-node-id", using wire's standard JSON-reference-like syntax:

{ $ref: 'dom!my-dom-node-id' }

Examples

Here is an example of a wire spec that creates a simple view component (using the builtin create syntax, and supplies a DOM node to the view's constructor.

{
    plugins: [
        {
            module: 'wire/dom',

            // Let wire/dom add a class during wiring, and then remove it
            // when wiring completes, so we can, for example, add a nifty
            // loading animation
            classes: {
                init: 'loading-my-view'
            }
        }
    ],

    // Create a view component, calling its constructor with a single arg,
    // the DOM node whose id="my-view-node-id"
    // Think of this as similar to
    // new MyView(document.getElementById('my-view-node-id'))
    myView: {
        create: {
            module: 'my/View',
            // Array of Constructor args.  In this case, the DOM node
            // as the only argument.
            args: [{ $ref: 'dom!my-view-node-id' }]
        }
    }
}

You can create top-level references to DOM nodes and use them like variables as well. This can provide an extra level of abstraction, or make it easier to inject the same DOM node into multiple components.

Let's say in this case our views append themselves into a supplied DOM node container.

{
    plugins: [
        {
            module: 'wire/dom',
            // The classes option is entirely optional (hence the name "option"!).
            // In this case, maybe we don't need to do any fancy animation or
            // transitions, so we can leave it out.
        }
    ],

    // viewContainer will be the DOM node with id="my-view-container-id"
    viewContainer: { $ref: 'dom!my-view-container-id' },

    // Create a view component, supplying the viewContainer DOM node as a
    // constructor arg
    myView: {
        create: {
            module: 'my/View',
            args: [{ $ref: 'viewContainer' }]
        }
    },

    // Create another view component, again supplying the same DOM node as a
    // constructor arg
    anotherView: {
        create: {
            module: 'my/OtherView',
            args: [{ $ref: 'viewContainer' }]
        }
    }
}