API

Introduction
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.



How To Use The Gaia API
This is the preferred method of using the Gaia API in AS2 and AS3:

import com.gaiaframework.api.Gaia; Gaia.api.methodName;

Gaia implements the IGaia interface, located in the com.gaiaframework.api package.

In AS2, you can also use the deprecated:

_global.Gaia.methodName;



Gaia API Methods
Here is a description of all the methods available in the Gaia API.



goto
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.

AS3 and AS2 Gaia.api.goto("index/nav/people/friends"); Gaia.api.goto("index/nav/about");

AS2 only _global.Gaia.goto("index/nav/people");

Gaia will determine the nearest valid branch to what you passed. Passing "index" will result in Gaia going to the first valid branch under index. Also, if you pass a branch that doesn't exist, it will recurse up the branch until it finds a valid branch, and then back down to the termination of that branch. This might end up being the index branch.

For instance, if the valid branch is "index/nav/people/friends" and you pass "index/nav/people/free", it will find the nearest branch to what you passed "index/nav/people" and since people has a child page, it will terminate the branch at "index/nav/people/friends".

If you navigate to somewhere deeper than the last child of a branch in the site.xml, such as "index/nav/people/friends/john", Gaia stores "/john" and you can access it through the API directly via the method getDeeplink.

Gaia sends out a deeplink event when there is a branch beyond the valid branch, which you can listen to through the API.

Pages are automatically set up to listen to this event through the onDeeplink method. See the Pages section of the documentation for more information.

To update the browser address bar with a deep link beyond the last child of the branch, call goto with the page's branch appended with your deep link. Example:

Gaia.api.goto("index/nav/people/friends/john");

If Gaia is already at the valid page "index/nav/people/friends", it will simply update the address bar in the browser with your custom deep link. Deep links do not have to be separated by slashes. More about this topic is covered in the SEO section of the documentation.

The optional "flow" 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.

Pages Class
Gaia generates a class called Pages when it scaffolds your site. This class is located inside the class package you specify when you scaffold. Inside the Pages class are public static variables named after the routes, titles or ids of all the pages in the site.xml, and their associated branches are the values.

Using the Pages class is the preferred way of calling goto and getPage.

AS3 and AS2 Gaia.api.goto(Pages.HOME); // goes to "index/nav/home" Gaia.api.goto(Pages.FRIENDS); // goes to "index/nav/people/friends"

Gaia.api.getPage(Pages.INDEX); // returns the IndexPage Asset

By using this class with goto, changes to your site.xml architecture will have no effect on your goto calls throughout your site. It also makes it easier to write your goto calls.



getPage
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 undefined (AS2) or null (AS3).

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.

AS3 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;

AS2 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.

You can also use the Pages Class with getPage in the same way you use it for goto.



getDepthContainer
getDepthContainer(depth:String):Sprite // AS3 getDepthContainer(depth:String):MovieClip // AS2 Returns the Sprite or MovieClip depth container. Pass one of the depth constants when using this method.

var top:Sprite = getDepthContainer(Gaia.TOP); // AS3 var middle:MovieClip == getDepthContainer(Gaia.MIDDLE); // AS2



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



setSiteTitle
setSiteTitle(value:String):void Sets the title of the site. You should include the %PAGE% token if you want it.



setDelimiter
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.



getValidBranch
getValidBranch(branch:String):String Returns a valid branch for whatever branch you pass it.



getSiteTree
getSiteTree:PageAsset Returns the PageAsset instance of the index page.



getMenuArray
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.



getSiteXML
getSiteXML:XML Returns the raw site.xml



getCurrentBranch
getCurrentBranch:String Returns the current valid branch.



getDeeplink
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.



getPreloader
getPreloader:IMovieClip Returns the preloader MovieClipAsset (IMovieClip in AS3) for direct targeting. You can use this to call custom methods inside your preloader swf, reposition the preloader clip, etc.



setPreloader
setPreloader(asset:MovieClipAsset):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.

<br style="clear:both" />

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

<br style="clear:both" />

setDefaultFlow
setDefaultFlow(flow:String):Void Allows you to set the default flow at runtime 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. To define a default flow for your site initially, use the flow attribute of the site node in the site.xml.

<br style="clear:both" />

getAssetPreloader
getAssetPreloader:IMovieClip Returns the asset preloader MovieClipAsset (IMovieClip in AS3) for direct targeting. You can use this to call custom methods inside your asset preloader swf, reposition the preloader clip, etc.

<br style="clear:both" />

setAssetPreloader
setAssetPreloader(asset:MovieClipAsset):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.

<br style="clear:both" />

getContextMenu
getContextMenu:ContextMenu (AS3 only) 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.

<br style="clear:both" />

refreshContextMenu
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.

<br style="clear:both" />

addAssets
Gaia.api.addAssets(nodes:XMLList, page:IPageAsset):void // AS3 Gaia.api.addAssets(nodes:Array, page:PageAsset):Void // AS2 This method is used to add externalized dynamic assets to a page at runtime. More information on how to use this method can be found in the Assets documentation.

<br style="clear:both" />

getWidth
getWidth:int Returns the original width of the stage when the site is set to 100% width or height. Useful for centering and other positioning code.

<br style="clear:both" />

getHeight
getHeight :int Returns the original height of the stage when the site is set to 100% width or height. Useful for centering and other positioning code.

<br style="clear:both" />

getSitePosition
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.

<br style="clear:both" />

setLoadTimeout
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, in milliseconds, until a file shows progress. The default is 10000.

<br style="clear:both" />

setPreloaderDelay
setPreloaderDelay(value:int):void This allows you to override the default 150ms delay before the preloader transitionIn method is called. This delay is to help prevent the preloader from showing up when loading from the cache. The smallest value you can pass is 1.

<br style="clear:both" />

setGlobalVolume
setGlobalVolume(value:Number, duration:Number = 0; onComplete:Function = null):void The method is used to set the global volume of the entire site. If you pass an optional duration argument, it will fade the volume to the value over that many seconds. If you pass an optional onComplete function, it will call that function when the fade is finished.

<br style="clear:both" />

getGlobalVolume
getGlobalVolume:Number Returns the current global volume.

<br style="clear:both" />

getAvailableFonts (AS3 Only)
getAvailableFonts:Array Returns an Array of the class names of all the fonts that were successfully registered using Runtime Font Loading.

<br style="clear:both" />

getFontName (AS3 Only)
getFontName(className:String):String Pass the font class name and this returns the runtime name of the font for use in a TextFormat, node in htmlText, and StyleSheets. This only works with Gaia's Runtime Font Loading.

<br style="clear:both" />

SWFAddress Proxy Methods
More detailed information on these methods can be found at http://www.asual.com/swfaddress/docs/en/

<br style="clear:both" />

back
back:Void Loads the previous URL in the history list.

<br style="clear:both" />

forward
forward:Void Loads the next URL in the history list.

<br style="clear:both" />

getTitle
getTitle:String Returns the current title of the browser window.

<br style="clear:both" />

setTitle
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.

<br style="clear:both" />

href
href(url:String, target:String):Void Due to the bug in AS2 with mixing ExternalInterface and getURL, this method is a substitute for getURL.

<br style="clear:both" />

popup
popup(url:String, name:String, options:String, handler:String):Void Opens a browser popup window.

<br style="clear:both" />

setHistory
setHistory(b: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.

<br style="clear:both" />

getHistory
getHistory:Boolean Returns the current status of history tracking.

<br style="clear:both" />

setTracker
setTracker(s:String):Void Sets a function for page view tracking. The default value is 'urchinTracker'.

<br style="clear:both" />

getTracker
getTracker:String Returns the tracker function.

<br style="clear:both" />

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

<br style="clear:both" />

Depth And Flow Run-Time Constants
The Gaia API has some constants for depths and flows. Use these when you are getting/setting depths and flows at runtime.

Depth Constants
Gaia.TOP Gaia.MIDDLE Gaia.BOTTOM Gaia.PRELOADER

Flow Constants
Gaia.NORMAL Gaia.PRELOAD Gaia.REVERSE Gaia.CROSS

Domain Constants
Gaia.DOMAIN_CURRENT Gaia.DOMAIN_NULL Gaia.DOMAIN_NEW