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.