5. API Event Hooks - Glidias/Kilogaiajax GitHub Wiki

Event hooks allows the frontend scripter to listen in on events within transition flow to perform relevant actions in response to these events. Unlike the original Gaia Flash Framework though, I didn't provide support for hijackable events and there's no way to adjust the default flow control of "TRANSIT_OUT -> PRELOAD -> TRANSIT_IN". However, some form of hijacking/adjusting flow can still be done using page transitions, since they provide explicit callback methods to call in order to continue the flow.

The basic flow whenever an ajax link is clicked, aGaiajax.api.goto() is called or back-forward history navigation occurs, and a new valid branch is found that can be navigated to, is:

  1. (goto event gets dispatched to framework). Navigate to targeted new page branch if available, else exit flow.
  2. Transition out existing page's contents phase, waiting for transition-complete callback before continuing.
  3. Preload new page branch assets.
  4. Once preload done, place new page contents into DOM and ready (ie. initialize the new page) by calling global method "gaiaReady" if found.
  5. Transition in the new page contents phase, waiting for transition-complete callback before continuing.
  6. If targeted branch isn't the one we're at due to interrupted navigational changes while preloading/transitioning, transition out content from step 2 and repeat.
  7. As long as we've arrived at the required new branch destination, the flow has completed!

Event-dispatchers in Gaia uses a class called GaiaSignal. This class basically have 2 basic methods for the end user:

  • add(handler:Function)
  • remove(handler:Function)

It also has a method:

  • dispatch(...params) To allow broadcasting the signal to all subscribers. The parameters are passed over to the subscriber handlers. This should not be used except for your own instances of GaiaSignal (ie. if you intend to use the class for your own use...).

The Gaiajax.api object contains the GaiaSignal instances directly. So, to listen in on an event, you just use Gaiajax.api./*nameOfSignal*/.add( function() {} ); like eg. Gaiajax.api.onAfterGoto.add(myMethod);. Remember to remove any listeners that you registered for pages, when you transition out. These are global listeners, so make sure you unbind them upon leaving a page. eg. Gaiajax.api.onAfterGoto.remove(myMethod);.

Below are the names of available flow signals:

  • onBeforeGoto This event fires before the goto event gets dispatched to the framework, regardless of whether the branch is external or the branch is the current branch.
  • onAfterGoto This event fires after the goto event succeeds and before the flow begin .
  • onBeforePreload This event fires before the preloading of the new branch starts. (after preloader has shown itself)
  • onAfterPreload This event fires after the preloading of the new branch is finished. (after preloader has vanished).
  • onBeforeReady Always triggers right after adding page's contents to DOM, hooking up any ajax links, just before current page's gaiaReady method (if available) is called.
  • onBeforeTransitionIn This event fires before the transition in phase begins.
  • onAfterTransitionIn This event fires after the transition in phase is finished.
  • onAfterComplete This event fires after the flow is complete. Flow completes after the transition in phase is finished, and it's confirmed that the current page is at the intended destination for viewing.
  • onBeforeTransitionOut This event fires before the transition out phase begins.
  • onAfterTransitionOut This event fires after the transition out phase is finished, just before page's contents leaves the DOM.

Below are names of available initialization signals:

  • onSiteXMLReady This triggers once the Site XML has finished loading and parsing.

Below are some signals for deeplinking within a page branch.

  • onChange This happens just before the framework itself handles any History API (or for HTML4 browsers only: hashbang) url navigation changes.
  • onDeeplink This is triggered by the framework whenever a hash change occurs. It passes a (deeplink:String) parameter as well like eg. /deeplink for something like index.html#/deeplink. The value of the deeplink could also be empty like /.