Behaviors

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

Behaviors are extensions of modules with very similar interfaces. They add common functionality and event handling to modules but do not actually interact with the original module. For example, two modules can use an “item” behavior to handle complex click actions but the behavior itself does not care which module is using it. It does it’s own thing and that is it.


init

Description

Initializes the behavior. This method is fired automatically when Box.Application.start is called on the related module.

Example

<div id="mod-item-list" data-module="item-list">
    ...
</div>
Box.Application.addBehavior('item-menu', function(context) {
    var menu;

    return {
        init: function() {
            menu = context.getService('menus').create();
            menu.init();
        }
    };
});

Box.Application.addModule('item-list', function(context) {
    return {
        behaviors: ['item-menu']
    };
});

var moduleEl = document.getElementById('mod-item-list');

// Will fire menu.init()
Box.Application.start(moduleEl);

destroy

Description

Destroys the behavior. This method is fired automatically when Box.Application.stop is called on the related module.

Example

<div id="mod-item-list" data-module="test-item-list">
    ...
</div>
Box.Application.addBehavior('item-menu', function(context) {
    var menu;

    return {
        destroy: function() {
            menu.destroy();
        }
    };
});

Box.Application.addModule('item-list', function(context) {
    return {
        behaviors: ['item-menu']
    };
});

var moduleEl = document.getElementById('mod-item-list');
Box.Application.start(moduleEl);

// Calls menu.destroy();
Box.Application.stop(moduleEl);

Message Handling

Message handlers for behaviors are the same as Module.messages. Each one is handled separately and both can execute off the same message.

messages

Description

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

Example

Box.Application.addBehavior('test-behavior', function(context) {
    return {
        messages: ['some-message'],
        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

Box.Application.addBehavior('item', function(context) {

    return {
        messages: ['itemdeleted', 'itemshared'],
        onmessage: function(name, data) {

            switch (name) {

                case 'itemdeleted':
                    console.log('Item has been deleted!');
                    break;

                case 'itemshared':
                    console.log(data.name + ' shared.');
                    break;

            }
        }
    };

});

// Triggers output of "Item has been deleted!"
Box.Application.broadcast('itemdeleted');

// Triggers output of "My Pictures shared."
Box.Application.broadcast('itemshared', {
    name: "My Pictures"
});

Event Handlers

Description

Handles specific DOM events that are fired within the module behavior. 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.

Note: Behavior event handlers are processed after the module event handler. Handlers should not overlap so be careful of default case handling.

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

Box.Application.addBehavior('item-menu', function(context) {
    var menu;

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

            switch (elementType) {

                case 'options-btn':
                    menu.open();
                    break;

                // Behaviors should not have default handling

            }
        }
    };

});