Preloader
From Gaia Framework Wiki
Contents |
Introduction To Gaia's Preloader
Gaia's preloader is a smart multi-loader and a default preloader template is created for you in the src folder, called preload.fla, and Gaia loads preload.swf by default.
Gaia's preloader uses two different ways to track the progress of multiple files loading.
Split Percentage
Gaia divides 1 by the number of files to load, and displays their individual progress as a percentage of that split. For instance, if there are four files to load, each file would be given 0.25 of the total progress, and each of their 0-1 progress would go from 0 to 0.25.
Byte Accurate
If you define the bytes property for each page and asset in the site.xml, it will use this to determine the total size of the load and track the actual percentage of loaded and total. So, if you are loading two files and one of them is 900k and the other is 100k, it will give 90% of the bar to the 900k file, and 10% of the bar to the 100k file. Using Split Percentage, both the 900k and 100k would take 50% of the bar, resulting in the bar slowly climbing to 50% and then jumping to 100% very quickly. The Gaia Panel has a button that sets the bytes property for you.
Preloader Classes
The preload.fla document class is the scaffolded class named Preloader. Preloader extends AbstractPreloader and implements the IPreloader interface. Like pages, the Preloader must have the four required transition methods. Additionally, it has another method, onProgress.
onProgress(event:AssetEvent)
AssetEvent
AssetEvent is the event that is used to track an asset's loading and complete process. It has the following properties:
perc
perc:Number
perc is the overall percentage of the load for the entire branch, which is a floating point number from 0 to 1.
asset
asset:AbstractAsset
asset is a reference to the asset (pages are a type of asset) that is currently loading. In the default template, this information is used by the preloader to show the current asset being loaded and its individual progress.
bytes
bytes:Boolean
If the total bytes of all files are set in the xml, this flag lets you know the loaded and total properties are bytes.
loaded
loaded:Number
If bytes is true, this is the number of bytes loaded so far. If not, this is the count of the current page or asset in the branch that is loading.
total
total:Number
If bytes is true, this is the total number of bytes of all files loading. Otherwise, this is the total number of pages and/or assets in the branch that are loading.
onProgress
The onProgress method does not need to do anything. If you just want to show an animation without any specifics to the loading progress, that's entirely up to you.
If you have some custom behavior for your preloader swf that you need to access from elsewhere in your site, you can target the preloader MovieClipAsset via the Gaia API method getPreloader(). You can use this to position the preloader, set its alpha, etc.
Preloader Depth
You can set the depth of the preloader in the site.xml, using the site node's "preloaderDepth" attribute. You can set it to "middle" or "bottom". This will place it relative to the page container you target. Setting it to "middle" puts it above the middle container and below the top container, "bottom" is above the bottom container and below the middle container. If you leave it out, Gaia will default to having the preloader reside above all page containers.
Overriding The Preloader At Runtime
If you want to override the preloader at runtime, use API method, setPreloader.
setPreloader(asset:MovieClipAsset)
You can change the MovieClipAsset the preloader uses at runtime. Make sure your MovieClipAsset is already loaded (preferably into the "PRELOADER" depth, see Site XML documentation) and that it implements the IPreloader interface. Read more about this functionality in the API documentation. If the clip you assign to the preloader unloads or is removed for some reason, Gaia will automatically revert back to the default preloader.
Asset Loader
The AssetLoader class, used by on-demand assets, uses the default preloader at first. If you want to use a custom loader for showing on-demand asset progress, pass an already loaded MovieClipAsset to the API method setAssetPreloader(asset). The custom loader needs to be set up like any Gaia preloader. It needs to be a loaded MovieClipAsset that implements IPreloader. Read more about this functionality in the API documentation.
Unlike the Branch loader, which loads a single file at a time, the AssetLoader loads and tracks multiple assets at once. It dispatches an AssetEvent, with an important distinction.
The asset it passes is the asset with the highest percent loaded that is not completely loaded. This is only important if you track the percent loaded and name of each file being loaded, which is what the default scaffolded Preloader that comes with Gaia does.
Keep in mind that the default maximum number of simultaneous HTTP requests from the same domain is two, so it will only load assets two at a time until it is done. If you're loading more than two assets, you'll notice that the third asset doesn't begin loading until one of the first two is complete.
PreloaderScaffold
The Preloader template Flash file contains a MovieClip linked to the PreloaderScaffold class. This MovieClip and its class are simply for example and you are free to modify them or delete them and use your own.
The PreloaderScaffold has its own transitionIn and transitionOut methods which use TweenLite to fade in and out. It also centers the MovieClip to the stage.
Take a look at the PreloaderScaffold class file that is created during Scaffolding. Its onProgress event handler has examples and comments of how to leverage the data coming from the AssetEvent.
Note: The MovieClip inside the preload.fla that comes with Gaia has its Blend Mode set to "Invert" so it shows up on any color background. You will probably want to change this when you put your own graphics inside it.
Override Preloader
If you want to use a lightweight preloader for the initial load of the site, and then have a more robust preloader for the rest of the site, a common technique is to make an asset node inside the index page node for your rich preloader, and when transitionIn() is called on the index page, it sets the preloader to that MovieClipAsset.
Check out the API documentation for more information on overriding the default Preloader and Asset Preloader.
