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.
Initializes the module. This method is fired automatically by Box.Application.start
<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);
Destroys the module. This method is fired automatically by Box.Application.stop
<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);
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!
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.
Box.Application.addModule('abc', function(context) {
return {
messages: ['statechanged', 'searchcomplete'],
onmessage: ... see below ...
};
});
Handles application messages.
This message handler function should be placed above event handlers.
Parameter | Type | Description |
---|---|---|
name | string | The message name. |
data | any | Related data for the message. |
<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
});
You may now specify message names as keys in an onmessage
object. You do not need to use the messages
array with this approach.
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.
Handles specific DOM events that are fired within the module. These handlers follow the on
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.
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. |
<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 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.