action
The action
plugin manages dispatching and handling of actions. Actions work much like DOM events or jQuery triggers. Despite the name, they don't actually do anything. They are simply objects with a type
and
an optional data
property.
gui.Spirit.extend({
onready: function() {
this.super.onready();
this.action.dispatch('mytype','mydata');
}
});
The action takes the form of a gui.Action
. Once dispatched, it will crawl upwards though the DOM structure until a spirit intercepts it and calls the consume
method.
gui.Spirit.extend({
onenter: function() {
this.super.onenter();
this.action.add('mytype');
},
onaction: function(a) {
this.super.onaction(a);
if(a.type === 'mytype') {
console.log(a.data); // ''mydata'
a.consume();
}
}
});
Multiple listeners
You can add and remove multiple action listeners with an array or space-separated string. Just make sure that the individual action types don't contain spaces.
this.action.add([ACTION1, ACTION2, ACTION3]);
this.action.remove('action1 action2 action3');
When adding a listener, you can setup up to automatically remove it once the action is received.
this.action.one('myaction'); // TODO: implement!
Descending actions
When you dispatch
an action, it naturally crawls upwards in the DOM tree until it hits HTML, but you can force it to crawl downwards.
this.action.descend('mytype');
You can use ascend
as an alias to dispatch
if you care to make the direction explicit.
Get the dispatcher
When you catch an action, you can identify the dispatcher using the target
property. The dispatcher is always another spirit.
gui.Spirit.extend({
onaction: function(a) {
this.super.onaction(a);
console.log(a.target); // [object gui.Spirit]
}
});
Change the handler
You can add a second argument to the add
and remove
methods to specify whoever should handle the action. This can be anything that implements onaction
, perhaps another spirit. It defaults to this
,
the spirit itself, but sometimes you'll want to specify this
explicitely.
var otherspirit = gui.get('#thatspirit');
otherspirit.action.add('myaction', this);
Without specifying this
, the the handler of the action would otherwise fall back to otherspirit
.
Global actions
You can dispatch actions across iframes
using the methods outlined below. Spiritual GUI must be loaded in all frames for this to work.
this.action.addGlobal('myaction');
this.action.oneGlobal('myaction');
this.action.dispatchGlobal('myaction');
this.action.ascendGlobal('myaction');
this.action.descendGlobal('myaction');
It's important to synchronize addGlobal
and dispatchGlobal
. You cannot intercept a global action using a local listener, even if receiver and sender is in the same window.
Implement "one
" methods if not already.