Events and Hijacking

Introduction
Gaia's Event and Event Hijacking engine is one of the most powerful and time-saving features of Gaia, and is one of the fundamental concepts it is based on.

Gaia has ten events in total. There are nine flow events, eight of which are hijackable events. What "hijackable event" means is you can set up a listener that will pause the Gaia framework until you tell the framework you are done. This allows you to run asynchronous code or timeline animations while the framework waits. Very powerful.

You can assign any number of listeners and/or hijackers to a single event. If you assign multiple hijackers, it will wait until all hijackers are completed before moving on.



Flow Event Method Arguments
Each of the nine flow event methods take three arguments. One is required, the second two are optional, and set to false by default. The method returns a function if you set the second argument to true, null otherwise.

target
target:Function A function that is the listener. In AS2, you should use a Delegate, not a direct function reference.

hijack
hijack:Boolean Make the framework wait for you to tell it to continue by calling the function that is returned with this function.

onlyOnce
onlyOnce:Boolean Only listen for this event once and then automatically remove the target as a listener.

Example:

AS2 var myListener:Function = Delegate.create(this, onBeforeTransitionOut); var releaseGaia:Function = Gaia.api.beforeTransitionOut(myListener, true); function onBeforeTransitionOut(event:GaiaEvent):Void {    releaseGaia; }

AS3 var releaseGaia:Function = Gaia.api.beforeTransitionOut(onBeforeTransitionOut, true); function onBeforeTransitionOut(event:GaiaEvent):void {    releaseGaia; }

You can optionally pass true in the method that releases Gaia if you want the hijacker to remove itself afterwards. This saves you from having to manually remove a hijacker that isn't an onlyOnce but needs to be removed under certain circumstances (such as it exists within a MovieClip or Page that is about to unload).

Example:

AS3 var releaseGaia:Function = Gaia.api.beforeTransitionOut(onBeforeTransitionOut, true); function onBeforeTransitionOut(event:GaiaEvent):void {    releaseGaia(true); }



GaiaEvent
The GaiaEvent that is passed on all events contains the following properties:

validBranch
validBranch:String The valid branch of the goto - a vaild branch is a branch that exists in the site.xml

fullBranch
fullBranch:String The full branch is a valid branch plus any deep link outside the scope of the valid branch

external
external:Boolean If the page is external, this will be true. Only beforeGoto would ever have this as true.

src
src:String The src of the page that is loading, external or internal

flow
flow:String If there is a flow override on the goto event, it is passed here



Gaia Flow Events
Here are the nine Gaia events which you can listen to and/or hijack.

beforeGoto
beforeGoto(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function This event fires before the goto event gets dispatched to the framework. beforeGoto occurs whenever a goto is called, regardless of whether the branch is external or the branch is the current branch (which Gaia ignores - check the How Gaia Works section of the documentation for more information).

afterGoto
afterGoto(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function This event fires after the goto event succeeds and before the flow begins. afterGoto and the events that follow occur only when the goto is an internal page that is different than the current page.

beforeTransitionOut
beforeTransitionOut(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function This event fires before the transition out phase begins.

afterTransitionOut
afterTransitionOut(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function This event fires after the transition out phase is finished.

beforePreload
beforePreload(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function This event fires before the preloading of the new branch starts.

afterPreload
afterPreload(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function This event fires after the preloading of the new branch is finished.

beforeTransitionIn
beforeTransitionIn(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function This event fires before the transition in phase begins.

afterTransitionIn
afterTransitionIn(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function This event fires after the transition in phase is finished.

afterComplete
afterComplete(target:Function, onlyOnce:Boolean = false):Function This event fires after the flow is complete. You cannot hijack afterComplete because the event fires at the end of the flow so hijacking would be pointless.



Remove Methods
Each of these hijack events have a remove method if you want to manually remove the listener. They are: removeBeforeGoto(target:Function) removeAfterGoto(target:Function) removeBeforeTransitionOut(target:Function) removeAfterTransitionOut(target:Function) removeBeforePreload(target:Function) removeAfterPreload(target:Function) removeBeforeTransitionIn(target:Function) removeAfterTransitionIn(target:Function) removeAfterComplete(target:Function)



Deeplink Event
There is an event for deeplinks and it accepts a single argument.

addDeeplinkListener(target:Function):Void removeDeeplinkListener(target:Function):Void The deeplink event occurs whenever the SWFAddress class updates, either from the browser or from a goto event. The event passes any deep link beyond the scope of the current branch in the event object as a property called "deeplink".

For instance, if you have a page branch of "index/home/photos" and you want to be able to deep link to and bookmark a specific photo, such as "index/home/photos/4", the deeplink event will pass you "/4". In this example, the user could type different numbers into the address bar, so your code would need to handle deeplink values that are invalid.

Most of the time, you will never need to use the addDeeplinkListener method, as Pages are automatically set up to receive onDeeplink events. Detailed information on how to leverage SWFAddress and deep linking can be found in the SEO documentation here.



Important Note About Event Hijacking
Event hijacking can lock up a site if you're not careful (I've done it myself). Just make sure if you add a hijacker that you only do it once per callback function. For instance, if you have a frame with Actionscript on it and you will be going back and forth from that frame, make sure you write your hijacking code similarly to this:

function init {    if (!inited) {        inited = true; releaseGaia = Gaia.api.beforeTransitionOut(Delegate.create(this, doSomething), true, true); } } init;

This ensures that the hijacker only gets added once. While Gaia prevents the same listener from being added again, in the above example, a Delegate is created each time, which is why you need to be careful. This tip will help you avoid weird behavior and save you time when they happen. This even happens to me, the author, so this will probably happen to you, too. Just be careful. Event Hijacking is extremely powerful, and with great power comes great responsibility. :)