Lifecycle

These methods get called upon the spirit by the framework. You should not call them yourself.

onconstruct

This is called when the spirits gets newed up. The spirit is in a primitive state at this point, so you would probably catch a later event. Note also that the spirit may not exist in the page DOM at this point.

onconfigure

This gets called immediately after onconstruct. The spirit will initialize plugins and parse special config attributes on it's DOM element.

onenter

This gets called when the spirit element is first encounted in the page DOM. Either it was there when the page loaded or somebody put it there.

onattach

This gets called when the spirit is encountered in the DOM. But unlike onenter, it also gets called whenever the spirit is moved to a new position in the DOM.

onready

This is the final event during the standard initialization of a spirit. It's a good time for the spirit to start acting out on the page, because at this point we know that all descendant spirits are also ready (see the lifecycle sequence).

onasync

This get's called some milliseconds after the onready event. If the spirit needs to perform processor intensive stuff that would delay percieved load time, like simulating a supernova explosion before it can be shown to the user, this might be a good time time.

oninit

TODO: This event is not supported at all. But it's supposed to be an event that occurs after onready unless something (perhaps the spirit itself) has blocked it. Something can unblock it at a later point; and the event will occur as soon as nothing is left to block.

ondetach

This gets called whenever the spirit is removed from it's position in the DOM. Note that unless the spirit is attached somewhere more or less immediately, the spirit will be nuked by a machine that nulls all it's properties, see ondestruct.

ondestruct

The spirit becomes scheduled for destruction. This could be a consequence of a DOM update that removes the spirit element from the document. After a short pause, all properties will be deleted to assist the garbage collector. To forcibly trigger this process, you can call the spirits dispose() method.

The sequence of life

It's really more of a sequence than a cycle. When the page loads, a machine will crawl the document from top to bottom looking for elements that match a spirit. A new spirit is created when:

1. The gui attribute is specified on the element
2. The element matches a channeled CSS selector

The onconstruct method gets called before the machine continues. When there are no more elements to crawl, the machine will call onconfigure, onenter and onattach in that order. Finally it will call onready and oninit in reverse order, first created spirits last. It looks something like this.

The procedure is repeated whenever elements gets added to the document. A separate procedure runs whenever something is removed from the document.

Summarize separate procedure

This turn of events implies that when onenter is called on a spirit, we can safely assume that oneneter has already been called on all ancestor spirits. Whenever onready is called on a spirit, we can assume that onready has already been called on all descendant spirits. This will come in handy when we setup spirits that interact with each other, because we don't have to send and receive special events to control the timing of things.

Handling own life

For a spirits to handle it's own lifecycle, simply override the associated method.

gui.Spirit.extend({
	onready: function() {
		this.super.onready();
		console.log('Ready');
	}
});

Unless you really mean it, always call this.super.onready() when you override eg. the onready event. Spirits will not do anything with these methods by default, so nothing terrible is bound to happen if you forget about it. But since you never know when something interesting may be added to the super method, it's a good idea to onsider this a boilerplate formula.

The life plugin exposes a set of boolean flags that reflect the lifecycle status of the spirit. See a complete list of flags.

gui.Spirit.extend({
	onenter: function() {
		this.super.onenter();
		console.log(this.life.entered); // true
		console.log(this.life.ready); // false
	}
});

The life of others

To handle lifecycle events of other spirits, or to intercept a spirits lifecycle from within a plugin, there's a special type of event you can listen for using the life plugin. To add a lifecycle listener to a spirit from anywhere on the page:

var spirit = gui.get('#otherspirit');
console.log(spirit.life.ready); // true
spirit.life.add('destruct', {
	onlife: function(life) {
		console.log(life.target, life.type);
	}
});

The spirit can of course also add listeners for it's own lifecycle events as an alternative to method overriding. See a complete list of events.