-
Notifications
You must be signed in to change notification settings - Fork 27
How gaia works
com.gaiaframework.core
The heart of Gaia resides in the core package. For the most part, you will never need to touch or access these classes. This thread covers how each class works and how they work with each other step by step. Reading this technical documentation is not necessary for using Gaia. This documentation assumes you have a solid understanding of event-based systems, OOP, design patterns, etc.
GaiaMain sets up the framework. It is instantiated by main.fla.
First, it creates a MovieClip for the site, instantiates the API, the SiteModel, which loads and parses the site.xml file, and the SiteView.
Once the site.xml is loaded and parsed, GaiaMain instantiates GaiaHQ, GaiaSWFAddress, GaiaContextMenu and SiteController. SiteController loads the default preloader.
When the Default Preloader finishes loading, GaiaMain listens for the afterComplete method with an onlyOnce listener. If the indexFirst attribute is "true", it loads only the index page first. Once the index is loaded, the afterComplete event fires, and Main instantiates the SWFAddress class which tells the framework which branch to start with. Right from the start, Gaia uses its powerful Event Hijacking engine. If indexFirst is not set, it skips this step and goes straight to loading the first branch.
GaiaMain also has centering code in it if the Project was set to be 100% width/height and centered in the browser. It manually fires onResize for two frames to ensure that the site is centered correctly (limitation of Flash).
The SiteModel loads and parses the site.xml file and creates the site tree, which is a PageAsset. The exact parsing logic is readily apparent looking at the class and is out of the scope of this document.
The SiteView is the primary container for the site. In AS3, it's a Sprite. In AS2, it's a composed MovieClip. It generates the four depth container clips (TOP. MIDDLE, BOTTOM, and PRELOADER), and manages adding pages and assets to the display stack in their proper depth container.
This class is the life force of the Gaia Framework. It is instantiated by GaiaMain. Here's how it works.
It instantiates TransitionController, BranchLoader and PreloadController and communicates directly with them.
When the SiteController receives the goto event, it first checks to see if the page is external and opens an external page if it is. If it's internal, it checks to see if it's already where it is supposed to go and ignores the goto if it is.
Assuming it's a new destination, it checks to see if it is currently transitioning or loading. If it is, it overwrites the queuedBranch with the new branch and fires the appropriate interrupt (preload or transition). Otherwise, it clears the queuedBranch, and determines the flow by locating the root of the changing branch by using the BranchTools class.
If the index page is not active yet and indexFirst is "true", it forces just the index page to load (covered above in GaiaMain.as). It tells BranchManager to cleanup any lingering transitioned out pages, and tells FlowManager to start.
At this point, based on the first changing page of the new branch's flow, the sequence of events are different so I'll cover the Normal Flow sequence. Regardless of flow, here's how the communication works:
- SiteController tells FlowManager what it has just finished doing.
- FlowManager tells GaiaHQ what event to broadcast next.
- GaiaHQ handles any hijacks and then sends the event, which is received by the SiteController.
FlowManager tells GaiaHQ to fire the preload event. SiteController dispatches an event to the BranchLoader, which is covered in detail below. The BranchLoader fires events to the SiteController to load pages and assets for the new branch.
SiteController tells SiteView to create containers for the page or asset and starts the load for each one. When the branch is finished loading, the BranchLoader fires a complete event to the PreloadController, which handles it and passes the event to SiteController which tells FlowManager the preload is complete.
FlowManager tells GaiaHQ to fire the transitionIn event. SiteController tells BranchManager to cleanup all transitioned out clips and then tells TransitionController to transition in the new branch. Once TransitionController is done, it fires an event received by SiteController, which tells FlowManager. FlowManager tells GaiaHQ that the Flow is complete.
At every event along the way, including the complete event, the SiteController checks to see if a goto event was received while it was going through the flow. When interrupts occur, it tells TransitionController or BranchLoader to interrupt and, after the interrupts are handled, it dispatches a redirect to GaiaHQ, which is just a goto event with the queued branch, and this starts the flow over again.
The BranchLoader works directly with the SiteController and PreloadController. When it receives a branch to load, it uses the BranchIterator class to determine every file that needs to load to display that branch. The BranchIterator uses the Iterator design pattern and BranchLoader calls the next() method which returns the next page/asset that needs to be loaded.
The BranchLoader sets up the progress and complete event listeners on the individual Asset instances and receives those events itself. For every page or asset from the Iterator that is not currently active, it broadcasts a loadPage or loadAsset event, which is received by the SiteController, as outlined above.
As each file's progress and complete are received, the BranchLoader calculates the overall progress and dispatches that, as well as a reference to the individual Asset, the current file number and the total number of files. When all files are loaded, or an interrupt occurs, it fires its complete event.
If a file fails to load, the BranchLoader will attempt to load it again three times by calling retry() on the asset. If the asset fails to load after three retry() calls, the BranchLoader calls abort() on the asset and loads the next file.
In AS3, if there is an IOErrorEvent, it throws an error, calls abort() and loads the next file.
This class does one thing and one thing only. It controls transitioning pages in and out. It receives arrays of Page assets from the SiteController and transitions them in the order given. It assigns itself as a listener to each Page's transition complete events. When it receives the event, it removes itself as a listener, and moves on to the next page. When all pages are done or an interrupt occurs, it dispatches an event to the SiteController that it is complete.
This is a static class used by SiteController. Its specific purpose is to manage the pages in the active branch. When pages are loaded, they are added to the activePages hash. It determines which pages need to be transitioned out by iterating through the activePages hash and seeing if each page's branch is contained within the new branch by using indexOf. Pretty nifty! Pages are self-cleaning in that they destroy themselves after they transition out, so BranchManager regularly deletes any pages from the activePages hash that are no longer active (i.e. destroyed).
Another static class used by many classes in the framework. It contains utility functions that return something based on passing them a branch. The methods are pretty self-explanatory so I'll leave it to you to check them out. The Gaia API class exposes most of these methods for you.
Almost all events in Gaia are routed through GaiaHQ. The exceptions are individual asset loading, SiteController to TransitionController events, SiteController to BranchLoader events and PreloadController to SiteController events.
GaiaHQ has three methods which are publicly exposed to the Gaia API class. The first is goto, which is the start of all flows. The goto method uses BranchTools to calculate all of the different types of branch data that is needed by different parts of the framework. This occurs here for optimization. Classes that respond to goto events, such as SiteController and SWFAddress, each need to run some of the same BranchTools calculations on a branch, so all of these are calculated and stored by GaiaHQ just the one time. Additionally, it saves the overhead if you need to access any of these variables yourself.
The other two exposed methods of GaiaHQ are for adding and removing flow event listeners and hijackers. FlowManager directly calls the other public but not exposed methods of GaiaHQ.
GaiaHQ's reason for living is to handle listeners and hijackers of Gaia Flow events. GaiaHQ maintains nine hashes, one for each flow event. For each event listener/hijacker added, GaiaHQ instantiates a GaiaHQListener class, gives it a unique id and assigns it to the appropriate event hash. A GaiaHQListener can either listen to an event or also be an event hijacker.
When an event comes through, GaiaHQ fires the onEvent handler. onEvent checks to see if there are any listeners and/or hijackers to that event. If there are listeners, it dispatches the event with the stored goto information. If there are no hijackers, it dispatches that it is done handling that event, received by the SiteController.
If there are hijackers, that is, listeners that want Gaia to stop running until they say to move on, it refrains from calling the event done function and defers to the event hijackers to tell it when they're all done. It also removes any listeners from that event's hash that are set to only fire only once.
The onHijackComplete method is passed to event hijackers when a listener is added with hijack=true. When it is fired, it checks to see if all event hijackers are done, and, if so, resets them, removes any onlyOnce hijackers and calls the event done method.
This class manages the Preloader and AssetLoader for the site. It handles loading the default Preloader, transitioning the current Preloader/AssetLoader, receives an onProgress event and passes it to it to the IPreloader clip.
It has a public getter method get clip() which returns a reference to the Preloader MovieClip. To access the MovieClipAsset currently assigned, use the getter method get asset(). The Gaia API has a method getPreloader() which returns the clip reference which allows you to target its timeline if you need to.
SWFAddress is a publicly available class written by Rostislav Hristov, and is implemented seamlessly into the Gaia Framework. When Gaia initializes Gaia SWFAddress, it checks for a branch, first from FlashVars, then from the address bar, and calls a goto on that branch, or the index branch if no branch is found.
It also handles dispatching deeplink strings and validates browser address bar branches in case the user types an invalid branch into the browser's address bar. It updates the browser address bar with the current Gaia branch when goto events occur.
Additionally, GaiaSWFAddress handles Routing in tandem with the SiteModel, which is covered under the SEO thread in the documentation.
If you turn on the context menu in the site.xml, Gaia will add pages to the context menu for right-click navigation. It traverses the site tree, adding the pages you specify in the site.xml, using their titles and branches. It calls Gaia.goto with the page's branch. Pretty simple and straightforward. Much of the code for this class was found on the web.