Packagecom.gaiaframework.api
Interfacepublic interface IGaia

This is the interface of the Gaia API. The Gaia API simplifies the way you interact with the framework. Most of the power of Gaia comes from how you structure your site.xml and how you handle its events.

See also

API Documentation
Events and Hijacking Documentation

Public Methods
 MethodDefined by
  
addAssets(nodes:XMLList, page:IPageAsset):void
This method is used to add externalized dynamic assets to a page at runtime.
IGaia
  
addCustomAsset(assetClass:Class, type:String):void
IGaia
  
addDeeplinkListener(target:Function):void
The deeplink event occurs whenever the SWFAddress class updates, either from the browser or from a goto event.
IGaia
  
afterComplete(target:Function, onlyOnce:Boolean = false):Function
The afterComplete event fires after the flow is complete.
IGaia
  
afterGoto(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function
The afterGoto event fires after the goto event succeeds and before the flow begins.
IGaia
  
afterPreload(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function
The afterPreload event fires after the preloading of the new branch is finished.
IGaia
  
afterTransitionIn(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function
The afterTransitionIn event fires after the transition in phase is finished.
IGaia
  
afterTransitionOut(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function
The afterTransitionOut event fires after the transition out phase is finished.
IGaia
  
back():void
Loads the previous URL in the history list.
IGaia
  
beforeGoto(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function
The beforeGoto event fires before the goto event gets dispatched to the framework.
IGaia
  
beforePreload(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function
The beforePreload event fires before the preloading of the new branch starts.
IGaia
  
beforeTransitionIn(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function
The beforeTransitionIn event fires before the transition in phase begins.
IGaia
  
beforeTransitionOut(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function
The beforeTransitionOut event fires before the transition out phase begins.
IGaia
  
forward():void
Loads the next URL in the history list.
IGaia
  
getAssetPreloader():IMovieClip
Returns the asset preloader MovieClipAsset.
IGaia
  
getAvailableFonts():Array
IGaia
  
getBaseURL():String
Returns the base URL of the website.
IGaia
  
getContextMenu():ContextMenu
Returns the ContextMenu attached to GaiaMain by Gaia, making it easier to modify the custom items in the ContextMenu, such as adding custom menu items that are not Gaia pages.
IGaia
  
getCurrentBranch():String
Returns the current valid branch.
IGaia
  
getDeeplink():String
Returns the deep link from the GaiaSWFAddress class that goes beyond the realm of the site.xml.
IGaia
  
getDefaultFlow():String
Returns the current default flow for any pages that do not have a flow defined (returns "normal", "preload", "reverse" or "cross").
IGaia
  
getDepthContainer(name:String):Sprite
Returns the Sprite or MovieClip depth container.
IGaia
  
getFontName(className:String):String
IGaia
  
getGlobalVolume():Number
Returns the global volume of the entire site.
IGaia
  
getHeight():int
Returns the fixed height of the Gaia site as defined in Main.
IGaia
  
getMenuArray():Array
Returns an array of all the pages in the site.xml with menu="true" and that have a title.
IGaia
  
getPage(branch:String):IPageAsset
Returns the instance of the PageAsset for that page.
IGaia
  
getPreloader():IMovieClip
Returns the preloader MovieClipAsset.
IGaia
  
getSitePosition():Object
Returns the current Site View x,y position as an object with properties x and y.
IGaia
  
getSiteTitle():String
Returns the value of the title attribute of the site node with the %PAGE% token still inside it.
IGaia
  
getSiteTree():IPageAsset
Returns the PageAsset instance of the index page.
IGaia
  
getSiteXML():XML
Returns the raw site.xml
IGaia
  
getTitle():String
Returns the current title of the browser window.
IGaia
  
getValidBranch(branch:String):String
Returns a valid branch for whatever branch you pass it.
IGaia
  
getValue():String
Calls SWFAddress.getValue() via a proxy so it always works even at site launch
IGaia
  
getWidth():int
Returns the fixed width of the Gaia site as defined in Main.
IGaia
  
goto(branch:String, flow:String = null):void
goto is the primary method you will be using in Gaia.
IGaia
  
gotoRoute(route:String, deeplink:String = null, flow:String = null):void
gotoRoute is an alternative to goto().
IGaia
  
href(url:String, target:String = null):void
This method is a substitute for getURL.
IGaia
  
popup(url:String, name:String, options:String, handler:String = null):void
Opens a browser popup window.
IGaia
  
refreshContextMenu():void
If you change the titles of pages or the site title, call this method to refresh the context menu to show the new values.
IGaia
  
removeAfterComplete(target:Function):void
Removes the afterComplete event listener
IGaia
  
removeAfterGoto(target:Function):void
Removes the afterGoto event listener
IGaia
  
removeAfterPreload(target:Function):void
Removes the afterPreload event listener
IGaia
  
removeAfterTransitionIn(target:Function):void
Removes the afterTransitionIn event listener
IGaia
  
removeAfterTransitionOut(target:Function):void
Removes the afterTransitionOut event listener
IGaia
  
removeBeforeGoto(target:Function):void
Removes the beforeGoto event listener
IGaia
  
removeBeforePreload(target:Function):void
Removes the beforePreload event listener
IGaia
  
removeBeforeTransitionIn(target:Function):void
Removes the beforeTransitionIn event listener
IGaia
  
removeBeforeTransitionOut(target:Function):void
Removes the beforeTransitionOut event listener
IGaia
  
removeDeeplinkListener(target:Function):void
Removes a deeplink listener.
IGaia
  
setAssetPreloader(asset:IMovieClip = null):void
This allows you to override the AssetPreloader MovieClipAsset to use the MovieClipAsset you pass (by default it uses the current site preloader).
IGaia
  
setDefaultFlow(flow:String):void
Allows you to set the default flow for any pages that do not have a flow defined.
IGaia
  
setDelimiter(value:String):void
Sets the delimiter for the site if you setSiteTitle with a different delimiter.
IGaia
  
setGlobalVolume(value:Number, duration:Number = 0, onComplete:Function = null):void
Sets the global volume of the entire site.
IGaia
  
setHistory(value:Boolean):void
Turns history tracking in the browser on and off by passing true or false.
IGaia
  
setLoadTimeout(value:int):void
When a branch is loading, each file must show progress within a certain amount of time before Gaia will attempt to reload the file.
IGaia
  
setPreloader(asset:IMovieClip = null):void
Override the preloader MovieClipAsset with a reference to an already loaded MovieClipAsset.
IGaia
  
setPreloaderDelay(value:int):void
IGaia
  
setSiteTitle(value:String):void
Sets the title of the site.
IGaia
  
setTitle(title:String):void
Allows you to set the title of the browser.
IGaia
  
setTracker(value:String):void
Sets a function for page view tracking.
IGaia
Method detail
addAssets()method
public function addAssets(nodes:XMLList, page:IPageAsset):void

This method is used to add externalized dynamic assets to a page at runtime.

Parameters
nodes:XMLList — An XMLList of nodes with id and src attributes.
 
page:IPageAsset — The PageAsset to add the assets to.

See also

Dynamic Externalized Assets Documentation
addCustomAsset()method 
public function addCustomAsset(assetClass:Class, type:String):void

Parameters
assetClass:Class — The Class that refers to the custom asset class - Class MUST extend AbstractAsset
 
type:String — The type that the custom asset class is associated with in the asset node type attribute.
addDeeplinkListener()method 
public function addDeeplinkListener(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.

Parameters
target:Function — A function that is the listener.
afterComplete()method 
public function afterComplete(target:Function, onlyOnce:Boolean = false):Function

The afterComplete event fires after the flow is complete. This event cannot be hijacked as it's forced to be false by the API. This is because the afterComplete event fires at the end of the flow so hijacking would be pointless.

Parameters
target:Function — A function that is the listener.
 
onlyOnce:Boolean (default = false) — Only listen for this event once and then automatically remove the target as a listener.

Returns
Function
afterGoto()method 
public function afterGoto(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function

The afterGoto 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.

Parameters
target:Function — A function that is the listener.
 
hijack:Boolean (default = false) — Make the framework wait for you to tell it to continue by calling the function that is returned with this function.
 
onlyOnce:Boolean (default = false) — Only listen for this event once and then automatically remove the target as a listener.

Returns
Function — If hijack is true, returns the function that will release Gaia, otherwise returns null.
afterPreload()method 
public function afterPreload(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function

The afterPreload event fires after the preloading of the new branch is finished.

Parameters
target:Function — A function that is the listener.
 
hijack:Boolean (default = false) — Make the framework wait for you to tell it to continue by calling the function that is returned with this function.
 
onlyOnce:Boolean (default = false) — Only listen for this event once and then automatically remove the target as a listener.

Returns
Function — If hijack is true, returns the function that will release Gaia, otherwise returns null.
afterTransitionIn()method 
public function afterTransitionIn(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function

The afterTransitionIn event fires after the transition in phase is finished.

Parameters
target:Function — A function that is the listener.
 
hijack:Boolean (default = false) — Make the framework wait for you to tell it to continue by calling the function that is returned with this function.
 
onlyOnce:Boolean (default = false) — Only listen for this event once and then automatically remove the target as a listener.

Returns
Function — If hijack is true, returns the function that will release Gaia, otherwise returns null.
afterTransitionOut()method 
public function afterTransitionOut(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function

The afterTransitionOut event fires after the transition out phase is finished.

Parameters
target:Function — A function that is the listener.
 
hijack:Boolean (default = false) — Make the framework wait for you to tell it to continue by calling the function that is returned with this function.
 
onlyOnce:Boolean (default = false) — Only listen for this event once and then automatically remove the target as a listener.

Returns
Function — If hijack is true, returns the function that will release Gaia, otherwise returns null.
back()method 
public function back():void

Loads the previous URL in the history list.

beforeGoto()method 
public function beforeGoto(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function

The beforeGoto 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).

Parameters
target:Function — A function that is the listener.
 
hijack:Boolean (default = false) — Make the framework wait for you to tell it to continue by calling the function that is returned with this function.
 
onlyOnce:Boolean (default = false) — Only listen for this event once and then automatically remove the target as a listener.

Returns
Function — If hijack is true, returns the function that will release Gaia, otherwise returns null.
beforePreload()method 
public function beforePreload(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function

The beforePreload event fires before the preloading of the new branch starts.

Parameters
target:Function — A function that is the listener.
 
hijack:Boolean (default = false) — Make the framework wait for you to tell it to continue by calling the function that is returned with this function.
 
onlyOnce:Boolean (default = false) — Only listen for this event once and then automatically remove the target as a listener.

Returns
Function — If hijack is true, returns the function that will release Gaia, otherwise returns null.
beforeTransitionIn()method 
public function beforeTransitionIn(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function

The beforeTransitionIn event fires before the transition in phase begins.

Parameters
target:Function — A function that is the listener.
 
hijack:Boolean (default = false) — Make the framework wait for you to tell it to continue by calling the function that is returned with this function.
 
onlyOnce:Boolean (default = false) — Only listen for this event once and then automatically remove the target as a listener.

Returns
Function — If hijack is true, returns the function that will release Gaia, otherwise returns null.
beforeTransitionOut()method 
public function beforeTransitionOut(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function

The beforeTransitionOut event fires before the transition out phase begins.

Parameters
target:Function — A function that is the listener.
 
hijack:Boolean (default = false) — Make the framework wait for you to tell it to continue by calling the function that is returned with this function.
 
onlyOnce:Boolean (default = false) — Only listen for this event once and then automatically remove the target as a listener.

Returns
Function — If hijack is true, returns the function that will release Gaia, otherwise returns null.
forward()method 
public function forward():void

Loads the next URL in the history list.

getAssetPreloader()method 
public function getAssetPreloader():IMovieClip

Returns the asset preloader MovieClipAsset. You can use this to call custom methods inside your asset preloader swf (via the .content property), reposition the preloader clip, etc.

Returns
IMovieClip

See also

IMovieClip.html
getAvailableFonts()method 
public function getAvailableFonts():Array

Returns
Array — An Array of the class names of all available fonts in the swf. This array only contains the names of fonts that successfully registered. These names can be passed to getFontName().
getBaseURL()method 
public function getBaseURL():String

Returns the base URL of the website. This means everything before the # hash symbol that SWFAddress uses for deeplinking.

Returns
String
getContextMenu()method 
public function getContextMenu():ContextMenu

Returns the ContextMenu attached to GaiaMain by Gaia, making it easier to modify the custom items in the ContextMenu, such as adding custom menu items that are not Gaia pages.

Returns
ContextMenu
getCurrentBranch()method 
public function getCurrentBranch():String

Returns the current valid branch.

Returns
String
getDeeplink()method 
public function getDeeplink():String

Returns the deep link from the GaiaSWFAddress class that goes beyond the realm of the site.xml. When you have a page that needs to know the deeplink when it first opens, use getDeeplink() since it won't be open when the event fires.

Returns
String
getDefaultFlow()method 
public function getDefaultFlow():String

Returns the current default flow for any pages that do not have a flow defined (returns "normal", "preload", "reverse" or "cross").

Returns
String
getDepthContainer()method 
public function getDepthContainer(name:String):Sprite

Returns the Sprite or MovieClip depth container. Pass one of the depth constants when using this method.

var top:Sprite = getDepthContainer(Gaia.TOP);

Parameters
name:String — A depth constant

Returns
Sprite
getFontName()method 
public function getFontName(className:String):String

Parameters
className:String — The class name assigned to the font

Returns
String — Returns the runtime name of the font for use with TextFormat
getGlobalVolume()method 
public function getGlobalVolume():Number

Returns the global volume of the entire site.

Returns
Number
getHeight()method 
public function getHeight():int

Returns the fixed height of the Gaia site as defined in Main. Useful if the stage is set to 100% height.

Returns
int
getMenuArray()method 
public function getMenuArray():Array

Returns an array of all the pages in the site.xml with menu="true" and that have a title. The pages are returned in order from top to bottom.

Returns
Array
getPage()method 
public function getPage(branch:String):IPageAsset

Returns the instance of the PageAsset for that page. You pass it a branch and it returns the PageAsset of the final page of that branch. If the final leaf of the branch you passed is not a valid page id, it will return null.

PageAsset has a property called children, which is an object which contains properties that match the ids of the pages of those children, and the values of those properties are the PageAssets themselves. PageAssets are aware of who their parent is, and pages also store their branch as a public property.

If you need to target the timeline of a page for custom properties, functions, or MovieClips, use the "content" property of the PageAsset.

Gaia.api.getPage("index/nav/home").content.myProp = value;
Gaia.api.getPage("index/nav/home").content.myFunc();
Gaia.api.getPage("index/nav/home").content.MC_Movieclip.x = 10;

More information about page properties can be found in the PageAsset, Pages and Site XML sections of the documentation.

Parameters
branch:String — The branch

Returns
IPageAsset
getPreloader()method 
public function getPreloader():IMovieClip

Returns the preloader MovieClipAsset. You can use this to call custom methods inside your preloader swf (via the .content property), reposition the preloader clip, etc.

Returns
IMovieClip

See also

IMovieClip.html
getSitePosition()method 
public function getSitePosition():Object

Returns the current Site View x,y position as an object with properties x and y. This is useful when using site centering code.

Returns
Object
getSiteTitle()method 
public function getSiteTitle():String

Returns the value of the title attribute of the site node with the %PAGE% token still inside it.

Returns
String
getSiteTree()method 
public function getSiteTree():IPageAsset

Returns the PageAsset instance of the index page.

Returns
IPageAsset
getSiteXML()method 
public function getSiteXML():XML

Returns the raw site.xml

Returns
XML
getTitle()method 
public function getTitle():String

Returns the current title of the browser window.

Returns
String
getValidBranch()method 
public function getValidBranch(branch:String):String

Returns a valid branch for whatever branch you pass it. A valid branch is one that can be resolved in the site.xml.

Parameters
branch:String — The branch

Returns
String
getValue()method 
public function getValue():String

Calls SWFAddress.getValue() via a proxy so it always works even at site launch

Returns
String — The string value in the address bar after the #
getWidth()method 
public function getWidth():int

Returns the fixed width of the Gaia site as defined in Main. Useful if the stage is set to 100% width.

Returns
int
goto()method 
public function goto(branch:String, flow:String = null):void

goto is the primary method you will be using in Gaia. It requires at least one argument and that is a string of the branch you want to navigate to. The optional second argument is for overriding the flow for the goto event. Use the flow constants for these: Gaia.NORMAL, Gaia.PRELOAD, and Gaia.REVERSE. Gaia will use that and ignore the page's flow type as well as the site's default flow. This feature is primarily used for testing during development only. If you pass a flow, and then use the browser to navigate back and forward, the passed flow will not be used again because SWFAddress is what is calling goto then, not your original goto. For production, you should set the flow on the page either through site.xml or at runtime.

Parameters
branch:String — The branch to navigate to
 
flow:String (default = null) — The flow override to use
gotoRoute()method 
public function gotoRoute(route:String, deeplink:String = null, flow:String = null):void

gotoRoute is an alternative to goto(). It allows you to pass a route instead of a full branch. If you pass an invalid route, Gaia will goto("index").

Parameters
route:String — The branch to navigate to
 
deeplink:String (default = null) — The flow override to use
 
flow:String (default = null)
href()method 
public function href(url:String, target:String = null):void

This method is a substitute for getURL.

Parameters
url:String — The url to navigate to.
 
target:String (default = null) — The target window ("_self", "_blank", etc.).
popup()method 
public function popup(url:String, name:String, options:String, handler:String = null):void

Opens a browser popup window.

Parameters
url:String — The url of the popup window.
 
name:String — The name of the popup window.
 
options:String — The options of the popup window.
 
handler:String (default = null) — The handler of the popup window.
refreshContextMenu()method 
public function refreshContextMenu():void

If you change the titles of pages or the site title, call this method to refresh the context menu to show the new values.

removeAfterComplete()method 
public function removeAfterComplete(target:Function):void

Removes the afterComplete event listener

Parameters
target:Function — A function that is the listener.
removeAfterGoto()method 
public function removeAfterGoto(target:Function):void

Removes the afterGoto event listener

Parameters
target:Function — A function that is the listener.
removeAfterPreload()method 
public function removeAfterPreload(target:Function):void

Removes the afterPreload event listener

Parameters
target:Function — A function that is the listener.
removeAfterTransitionIn()method 
public function removeAfterTransitionIn(target:Function):void

Removes the afterTransitionIn event listener

Parameters
target:Function — A function that is the listener.
removeAfterTransitionOut()method 
public function removeAfterTransitionOut(target:Function):void

Removes the afterTransitionOut event listener

Parameters
target:Function — A function that is the listener.
removeBeforeGoto()method 
public function removeBeforeGoto(target:Function):void

Removes the beforeGoto event listener

Parameters
target:Function — A function that is the listener.
removeBeforePreload()method 
public function removeBeforePreload(target:Function):void

Removes the beforePreload event listener

Parameters
target:Function — A function that is the listener.
removeBeforeTransitionIn()method 
public function removeBeforeTransitionIn(target:Function):void

Removes the beforeTransitionIn event listener

Parameters
target:Function — A function that is the listener.
removeBeforeTransitionOut()method 
public function removeBeforeTransitionOut(target:Function):void

Removes the beforeTransitionOut event listener

Parameters
target:Function — A function that is the listener.
removeDeeplinkListener()method 
public function removeDeeplinkListener(target:Function):void

Removes a deeplink listener.

Parameters
target:Function — A function that is the listener.
setAssetPreloader()method 
public function setAssetPreloader(asset:IMovieClip = null):void

This allows you to override the AssetPreloader MovieClipAsset to use the MovieClipAsset you pass (by default it uses the current site preloader). If you want to revert to the site preloader, call this method with no parameters.

Parameters
asset:IMovieClip (default = null) — A MovieClipAsset whose content implements IPreloader. Pass null to revert to the site preloader.
setDefaultFlow()method 
public function setDefaultFlow(flow:String):void

Allows you to set the default flow for any pages that do not have a flow defined. Use one of the flow constants: Gaia.NORMAL, Gaia.PRELOAD, Gaia.REVERSE or Gaia.CROSS.

Parameters
flow:String — One of the flow constants.
setDelimiter()method 
public function setDelimiter(value:String):void

Sets the delimiter for the site if you setSiteTitle with a different delimiter. You need to call refreshContextMenu() to have this change reflected in the ContextMenu.

Parameters
value:String — The delimiter value
setGlobalVolume()method 
public function setGlobalVolume(value:Number, duration:Number = 0, onComplete:Function = null):void

Sets the global volume of the entire site. Passing a duration will fade the global volume. Passing an onComplete function will call it when the fade is complete.

Parameters
value:Number — 0-1 The value you want to set the global volume to
 
duration:Number (default = 0) — The duration in seconds you want to fade the global volume to value
 
onComplete:Function (default = null) — The function you want to call when the global volume fade is complete
setHistory()method 
public function setHistory(value:Boolean):void

Turns history tracking in the browser on and off by passing true or false. It is turned on by default, unless you set history="false" in the site.xml site node.

Parameters
value:Boolean — A Boolean of "true" to turn history on, and "false" to turn it off.
setLoadTimeout()method 
public function setLoadTimeout(value:int):void

When a branch is loading, each file must show progress within a certain amount of time before Gaia will attempt to reload the file. This method allows you to adjust how long Gaia waits until a file shows progress. Default: 10000ms Minimum: 3000ms

Parameters
value:int — The time in milliseconds to wait for a file in a branch load to show progress
setPreloader()method 
public function setPreloader(asset:IMovieClip = null):void

Override the preloader MovieClipAsset with a reference to an already loaded MovieClipAsset. If you want to revert to the default preloader, call this method without passing anything.

Parameters
asset:IMovieClip (default = null) — A MovieClipAsset whose content implements IPreloader. Pass nothing or null to revert to the original preloader.
setPreloaderDelay()method 
public function setPreloaderDelay(value:int):void

Parameters
value:int — The time in milliseconds to delay the preloader transitionIn call (so it doesn't show up for cached content). The default value is 150.
setSiteTitle()method 
public function setSiteTitle(value:String):void

Sets the title of the site. You should include the %PAGE% token if you want it.

Parameters
value:String — The title of the site.
setTitle()method 
public function setTitle(title:String):void

Allows you to set the title of the browser. The string you pass will be the entire title, so if you want to append something to or alter the current title, you should getTitle() or getSiteTitle(), modify that and pass it to setTitle().

Parameters
title:String — The title of the browser.
setTracker()method 
public function setTracker(value:String):void

Sets a function for page view tracking. The default value is 'urchinTracker'.

Parameters
value:String — The tracker function name.