Application

The core application object where components are registered and managed

init

Description

Initializes the application. This will start modules on the page.

Usage

Parameter Type Description
config Object Used to pass configuration information to services. See getGlobalConfig.
config.debug boolean If true, will print exceptions in console. Otherwise, will catch all exceptions and hide them from users.
config.eventTypes string[] A list of event types that T3 should respond to. This overrides the default event type list. Event types specified MUST bubble. Available in v2.4.0+

Returns

The Box.Application object (for chaining purposes).

Example

Box.Application.init();

or

Box.Application.init({
    debug: true,
    foo: { ... },
    bar: "baz"
});

Default Event Types

var eventTypes = [
    'click', 'mouseover', 'mouseout', 'mousedown',
    'mouseup', 'mouseenter', 'mouseleave', 'mousemove',
    'keydown', 'keyup', 'submit', 'change', 'contextmenu',
    'dblclick', 'input', 'focusin', 'focusout'
];

Example

Box.Application.init({
    eventTypes: ['click', 'touchstart', 'touchend']
});

Please remember that the events specified must bubble in order to be handled correctly by T3.


destroy

Description

Destroys the application. This will stop modules on the page and unregister modules, services, and behaviors.

Returns

The Box.Application object (for chaining purposes).

Example

Box.Application.destroy();

addService

Description

Register a T3 Service component.

Usage

Parameter Type Description
name string Name of service.
creator Function Creator function for the service.

Returns

The Box.Application object (for chaining purposes).

Example

Box.Application.addService('some-service', function(application) {
    return {
        foo: function() { ... }
    };
});

addModule

Description

Register a T3 Module component.

Usage

Parameter Type Description
name string Name of module.
creator Function Creator function for the module.

Returns

The Box.Application object (for chaining purposes).

Example

Box.Application.addModule('some-module', function(context) {
    return {
        init: function() { ... },
        destroy: function() { ... }
    };
});

addBehavior

Description

Register a T3 Behavior component.

Usage

Parameter Type Description
name string Name of behavior.
creator Function Creator function for the behavior.

Returns

The Box.Application object (for chaining purposes).

Example

Box.Application.addBehavior('some-behavior', function(context) {
    return {
        init: function() { ... },
        destroy: function() { ... }
    };
});

getService

Description

Retrieves an instance of a registered service.

Usage

Parameter Type Description
service string Name of service.

Returns

T3 Service or throws an error if it does not exist.


hasService

Description

Checks if a service has been registered.

Usage

Parameter Type Description
service string Name of service.

Returns

True if the service exists, false otherwise.


getGlobal

Description

Returns a global variable. This function exists to make accessing globals more explicit.

Usage

Parameter Type Description
name string Name of global.

Returns

The global variable if it exists or null.

Example

var navigator = Box.Application.getGlobal('navigator');
console.log(navigator.userAgent);

getGlobalConfig

Description

Retrieves a configuration value that was passed through init.

Usage

Parameter Type Description
key string Config key.

Returns

Object.

Example

Box.Application.init({
    username: 'bob'
});

console.log(Box.Application.getGlobalConfig('username')); // Outputs "bob"

getModuleConfig

Description

Retrieves a module’s configuration data from embedded JSON in a ‘text/x-config’ script tag. See Context.getConfig.

Usage

Parameter Type Description
element HTMLElement Module root element.
name string Specific configuration value to retrieve.

Example

<div id="mod-test-module" data-module="test-module">
    <script type="text/x-config">{"foo": "bar"}</script>
    ...
</div>

Returns

Object.

var moduleEl = document.getElementById('mod-test-module');

// outputs {"foo": "bar"}
console.log(Box.Application.getModuleConfig(moduleEl));

// outputs "bar"
console.log(Box.Application.getModuleConfig(moduleEl, 'foo'));

// outputs null
console.log(Box.Application.getModuleConfig(moduleEl, 'baz'));

start

Description

Begins the lifecycle of a module (registers and binds listeners).

Usage

Parameter Type Description
element HTMLElement DOM element associated with module to be started

Returns

The Box.Application object (for chaining purposes).

Example

<div id="mod-test-module" data-module="test-module">
    ...
</div>
var moduleEl = document.getElementById('mod-test-module');

Box.Application.start(moduleEl);

startAll

Description

Starts all modules contained within an element.

Usage

Parameter Type Description
element HTMLElement DOM element which contains modules

Returns

The Box.Application object (for chaining purposes).

Example

<div id="content">
    <div id="mod-test-module" data-module="test-module">
        ...
    </div>
    <div id="mod-another-module" data-module="another-module">
        ...
    </div>
</div>
var contentEl = document.getElementById('content');

Box.Application.startAll(contentEl); // starts both modules

stop

Description

Ends the lifecycle of a module (unregisters and unbinds listeners).

Usage

Parameter Type Description
element HTMLElement DOM element associated with module to be stopped

Returns

The Box.Application object (for chaining purposes).

Example

<div id="mod-test-module" data-module="test-module">
    ...
</div>
var moduleEl = document.getElementById('mod-test-module');

Box.Application.stop(moduleEl);

stopAll

Description

Stops all modules contained within an element.

Usage

Parameter Type Description
element HTMLElement DOM element which contains modules

Returns

The Box.Application object (for chaining purposes).

Example

<div id="content">
    <div id="mod-test-module" data-module="test-module">
        ...
    </div>
    <div id="mod-another-module" data-module="another-module">
        ...
    </div>
</div>
var contentEl = document.getElementById('content');

Box.Application.stopAll(contentEl); // stop both modules

isStarted

Description

Determines if a module represented by the HTML element is started. If the element doesn’t have a data-module attribute, this method always returns false.

Usage

Parameter Type Description
element HTMLElement DOM element which contains modules

Returns

Returns true if module is started. False, otherwise.

Example

<div id="mod-test-module" data-module="test-module">
    ...
</div>
var moduleEl = document.getElementById('mod-test-module');

console.log(Box.Application.isStarted(moduleEl)); // Returns false

Box.Application.start(moduleEl);

console.log(Box.Application.isStarted(moduleEl)); // Returns true

broadcast

Description

Broadcasts a message to all registered listeners

Usage

Parameter Type Description
name string Name of the message
data any Custom parameters for the message

Returns

The Box.Application object (for chaining purposes).

Example

<div id="mod-test-module" data-module="test-module">
    ...
</div>
Box.Application.broadcast('some-message');
Box.Application.broadcast('statechanged', {
    foo: 'search',
    bar: 'home'
});

reportError

Description

Signals that an error has occurred. If in debug mode, an error is thrown. Otherwise, an “error” event is fired.

Usage

Parameter Type Description
exception Error An error object

Example

Box.Application.reportError(new Error('Invalid User ID'));

reportWarning

Description

Signals that a warning has occurred. If in debug mode, console.warn is called. Otherwise, a “warning” event is fired. Available in v2.4.0+

Usage

Parameter Type Description
data * An arbitrary string or object

Example

Box.Application.reportWarning('Line is almost full!');

Additional Methods

on

See EventTarget.on

off

See EventTarget.off

fire

See EventTarget.fire