wire.md

Using wire.js

1. As a module
   1. AMD
   2. CommonJS
2. As an AMD plugin
3. As a factory
4. By injecting wire

Module

Wire can be used as a module in AMD or CommonJS environments. You can install it using one of the supported methods.

In either environment, wire is simply a function.

AMD

Once you've installed wire into your AMD environment and configured your loader, you can load wire as you would any other module:

// Using pure AMD
// List wire as a dependency
define(['wire'], function(wire) {
	// use wire()
});

// Using AMD-wrapped CommonJS
define(function(require) {
	// Use the standard AMD local require to load wire
	var wire = require('wire');
});

CommonJS

Similarly, once you've installed wire into your CommonJS environment, simply load it:

var wire = require('wire');

AMD plugin

Wire can be used as an AMD plugin in any AMD loader that supports the AMD plugin API, for example: curl, RequireJS, and Dojo. This can be a very convenient way to bootstrap a front-end application.

Once you've installed wire into your AMD environment and configured your loader:

// Assume app/main is the main wire spec that bootstraps the application
curl(['wire!app/main']);

You should concatenate all the modules of your app before deploying it to production. Wire's AMD plugin supports AMD bundling via cujoJS's cram. For RequireJS (r.js) people have reported success using Pieter Vanderwerff's wire-rjs-builder plugin.

For more examples of using wire as an AMD plugin to bootstrap applications, see the Example Apps

Factory

Wire can be used as a factory from within a wire spec to wire other specs and use them as components. This makes it easy to modularize applications into higher level units that can be packaged and tested independently.

Here is a simple example excerpt from a wire spec:

// aComplexView is defined by its own wire spec that pulls together
// many components, e.g. html templates, css, internationalization files,
// and Javascript behavior, into a single component.
aComplexView: {
	wire: 'app/ComplexView/spec'
},

// an application-level controller that needs to interact with aComplexView
myController: {
	create: 'app/Controller',
	properties: {
		_view: { $ref: 'aComplexView' }
	}
},

// other components

Go to the full documentation for the wire factory

Injecting wire

Syntax: { $ref: 'wire!' }

Sometimes it is convenient to use wire programmatically, and for some situations, such as bootstrapping, you can simply use wire as a module. Unfortunately, this creates a dependency within your application code on wire.

One core principle of wire is that, beyond an initial bootstrap, your application code should never have a hard dependency on wire itself. For example, your AMD business logic modules should never list wire as an AMD dependency.

Instead of loading wire as a module, you can inject it as a function using the wire! resolver. This has several advantages:

1. The injected wire function is contextual. More on this below.
2. It removes the hard dependency of loading wire as a module. During testing you can simply use a fake/mock function instead.
3. Because it injects a function, your code is not dependent on an API name. For example, if you inject wire as a property, you can name it whatever makes sense for your application.

Here is a simple example of injecting the contextual wire function in a wire spec:

myController: {
	create: 'app/Controller',
	properties: {
		// Inject the contextual wire function as a property
		// You control the property name, so you can call this
		// whatever makes sense for your app.
		_loadApplicationSection: { $ref: 'wire!' }
	}
}

Contextual-ness

The reference { $ref: 'wire!' } resolves to a wire function that has been bound to the current wire context. It will wire new contexts as children of the current context. This allows you to modularize your application at a high level, and manage the relationships between the components in these high level areas.