Events and Hijacking

From Gaia Framework Wiki

Contents 1 Introduction 2 Flow Event Method Arguments 2.1 target 2.2 hijack 2.3 onlyOnce 3 GaiaEvent 3.1 validBranch 3.2 fullBranch 3.3 external 3.4 src 3.5 flow 4 Gaia Flow Events 4.1 beforeGoto 4.2 afterGoto 4.3 beforeTransitionOut 4.4 afterTransitionOut 4.5 beforePreload 4.6 afterPreload 4.7 beforeTransitionIn 4.8 afterTransitionIn 4.9 afterComplete 5 Remove Methods 6 Deeplink Event 7 Important Note About Event 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.  :)