API

From Gaia Framework Wiki

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.

getDefaultFlow

getDefaultFlow():String

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

getGlobalVolume

getGlobalVolume():Number

Returns the current global volume.

getAvailableFonts (AS3 Only)

getAvailableFonts():Array

Returns an Array of the class names of all the fonts that were successfully registered using Runtime Font Loading.

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.

back():Void

forward():Void

getTitle():String

setTitle(title:String):Void

href(url:String, target:String):Void

popup(url:String, name:String, options:String, handler:String):Void

setHistory(b:Boolean):Void

getHistory():Boolean

setTracker(s:String):Void

getTracker():String

getBaseURL():String

Gaia.TOP
Gaia.MIDDLE
Gaia.BOTTOM
Gaia.PRELOADER

Gaia.NORMAL
Gaia.PRELOAD
Gaia.REVERSE
Gaia.CROSS

Gaia.DOMAIN_CURRENT
Gaia.DOMAIN_NULL
Gaia.DOMAIN_NEW