Modules

The following methods are optional for you to implement per module.

Modules are only accessible by Box.Application which opens up the possibility of a less strict interface for the module’s definition. For example, if you have complex logic for modules, you may place the function in the public API for unit testing. This is a completely different methodology than normal and should not be applied to services.


init

Description

Initializes the module. This method is fired automatically by Box.Application.start

Example

<div id="mod-test-module" data-module="test-module">
    ...
</div>
Box.Application.addModule('abc', function(context) {
    return {
        init: function() {
            // Outputs "foo"
            console.log('foo');
        }
    };
});

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

destroy

Description

Destroys the module. This method is fired automatically by Box.Application.stop

Example

<div id="mod-test-module" data-module="test-module">
    ...
</div>
Box.Application.addModule('abc', function(context) {
    return {
        destroy: function() {
            // Outputs "bar"
            console.log('bar');
        }
    };
});

var moduleEl = document.getElementById('mod-test-module');
Box.Application.start(moduleEl);
Box.Application.stop(moduleEl);

Message Handling

Messages are part of the built-in T3 pub/sub system for module events. Each module can broadcast information about events that have happened whlie other modules can subscribe to those messages via the ‘onmessage’ handler. As a rule of thumb, message names should be describe what event has taken place and not be used as a RPC call to other modules. A good name for a message would be ‘keywordchanged’ which aptly names what specific event has occurred. A bad message name would be ‘updateheader’ since it implies what action to be taken as a result of an event. Modules are isolated and should never be aware of other modules on the page!

messages

Description

List of messages that this module will listen for. This is used by Box.Application to fire onmessage handlers. You should place this at the top of the module API so it is easy to find.

Example

Box.Application.addModule('abc', function(context) {
    return {
        messages: ['statechanged', 'searchcomplete'],
        onmessage: ... see below ...
    };
});

onmessage

Description

Handles application messages.

This message handler function should be placed above event handlers.

Usage

Parameter Type Description
name string The message name.
data any Related data for the message.

Example

<div id="mod-test-module" data-module="test-module">
    ...
</div>
Box.Application.addModule('abc', function(context) {

    return {
        messages: ['statechanged', 'searchcomplete'],
        onmessage: function(name, data) {

            switch (name) {

                case 'statechanged':
                    console.log('Navigating somewhere!');
                    break;

                case 'searchcomplete':
                    console.log('Found ' + data.numResults + ' results.');
                    break;

            }
        }
    };

});

// Triggers output of "Navigating somewhere!"
Box.Application.broadcast('statechanged');

// Triggers output of "Found 100 results."
Box.Application.broadcast('searchcomplete', {
    numResults: 100
});

Alternate Usage (v2.3.0+)

Description

You may now specify message names as keys in an onmessage object. You do not need to use the messages array with this approach.

Example

Box.Application.addModule('abc', function(context) {

    return {
        onmessage: {

            statechanged: function() {
                console.log('Navigating somewhere!');
            },

            searchcomplete: function(data) {
                console.log('Found ' + data.numResults + ' results.');
            }

        }
    };

});

// Triggers output of "Navigating somewhere!"
Box.Application.broadcast('statechanged');

// Triggers output of "Found 100 results."
Box.Application.broadcast('searchcomplete', {
    numResults: 100
});

Functions will be called with the corresponding module context.


Event Handlers

Description

Handles specific DOM events that are fired within the module. These handlers follow the on convention. For example, 'onclick' handles click events and 'oncontextmenu' handles right click.

List of handled events:

Note: blur/focus events are very flaky and are not supported by Box.Application. For special events, you should define regular JavaScript event handlers in init() and remove them in destroy()

The handler function should delegate complex logic to other functions. As a rule of thumb, try NOT to pass the event object around.

Usage

Parameter Type Description
event Event A DOM-normalized event object.
element HTMLElement The nearest HTML element with a data-type attribute specified or null if there is none.
elementType string The value of data-type for the nearest element with that attribute specified or null if there is none.

Example

<div id="mod-test-module" data-module="test-module">
    <button data-type="okay-btn">Okay</button>
    <button data-type="cancel-btn">Cancel</button>
</div>
Box.Application.addModule('abc', function(context) {

    return {
        onclick: function(event, element, elementType) {

            switch (elementType) {

                case 'okay-btn':
                    console.log('OK!');
                    break;

                case 'cancel-btn':
                    console.log('NO!');
                    break;

            }
        }
    };

});

Behaviors

Description

Behaviors work in parallel with modules. They are intended to be drop-in functionality that needs little additional interaction with the module. For example, a tabbed UI view where the UI logic is not necessarily important to the module.