Assets

From Gaia Framework Wiki

Jump to: navigation, search

Contents

Overview

The other node type in the site.xml is Asset. Assets belong to pages, and are external files which are associated with the page they belong to. Using Assets, Gaia makes it easy to manage and access external files.

AS2 and AS3 Assets

  • NetStreamAsset - flv or m4a files
  • XMLAsset - XML files
  • SoundAsset - mp3 files
  • StyleSheetAsset - css files


AS3 Assets

These mirror the AS3 DisplayObject inheritance tree.

  • DisplayObjectAsset - This is the base class for DisplayObject assets
  • BitmapAsset - Images will load as BitmapAssets by default (png, jpg, gif, etc.)
  • BitmapSpriteAsset - This asset is a BitmapAsset that is wrapped in a Sprite for interactivity.
  • SpriteAsset - This is included to mirror the AS3 DisplayObject inheritance tree.
  • MovieClipAsset - By default, swfs will load as MovieClipAssets.
  • TextAsset - For .txt files and also the base class for XMLAsset, StyleSheetAsset and JSONAsset
  • JSONAsset - For .json files


AS2 Assets

  • MovieClipAsset - Anything that natively loads into a MovieClip (swf, png, jpg, gif, etc.)
  • SoundClipAsset - External swf with embedded sound (for perfect loops)


How To Use Assets

By default, Assets load with a Page as part of the preloading process. This behavior can be overridden on a per asset basis, if you like (see below).

*** IMPORTANT NOTE ABOUT ACCESSING ASSETS***

The assets object is not available on a Page until transitionIn() is called. This is because the actionscript on the first frame of a loaded Page runs before the assets object is assigned to the Page, much less any assets loaded. Wait until after transitionIn() is called before attempting to access any assets.

Here's a quick overview of how assets are used. 

<site title="Gaia Scaffold Site: %PAGE%">
    <page id="index" src="background.swf">
        <page id="nav" src="nav.swf" depth="top">
            <page id="home" title="Home" src="home.swf">
                <asset id="myMusic" src="homepage.mp3"/>
                <asset id="myCopy" src="homepage.xml"/>
                <asset id="myImage" src="homepage.jpg"/>
                <asset id="mySWF" src="something.swf"/>
            </page>
        </page>
    </page>
</site>


In this example, the page home has four assets with the ids myMusic, myCopy, myImage and mySWF. Assets are made available to your page swfs in a property called "assets" in the page document class or on the root timeline of your page swf.

You access the assets directly by their ids and the majority of the native methods of that type of Flash asset are available directly on the asset, via the Proxy design pattern.

Assets in Gaia mirror the asset classes in Flash.

Note: Image and swf assets have their visible = false when they load and are positioned at 0,0. If you want the image or swf to display on the stage, you need to set its visible = true.


MovieClipAsset

You can access a MovieClipAsset directly using most native MovieClip methods and properties.

Here is some example syntax. Notice you can access the asset exactly like any other MovieClip.

AS2 

assets.myImage._x = 50;
assets.myImage._y = 100;
assets.myImage._visible = true;
trace(assets.myImage._parent);   // returns the _parent of the MovieClip
//
assets.mySWF.gotoAndPlay(10);
assets.mySWF.onRelease = function() {};


AS3 does not require casting, but if you want strict typing for code hints and performance, cast the assets to their interface. MovieClipAssets use IMovieClip, images use IBitmap, sprites use ISprite, and they all inherit from IDisplayObject. Also important to note is that the parent property returns the parent of the loader, not the content.

AS3 

IDisplayObject(assets.myImage).x = 50;
IDisplayObject(assets.myImage).y = 100;
IDisplayObject(assets.myImage).visible = true;
//
IMovieClip(assets.mySWF).gotoAndPlay(10);
trace(IMovieClip(assets.mySWF).parent); // returns the parent of the loader, not the loader.content
//
// AS3 also works without casting
//
assets.mySWF.gotoAndStop(5);
assets.myImage.scaleX = 0.5;
trace(assets.myImage.parent); // BitmapSpriteAsset.parent returns the parent of the Sprite it is nested in

In AS3, if small file size is important, only use the interface closest to IAsset that has the methods you need. For instance, if you only need to set the x and y, use IDisplayObject.


Targeting the timeline of MovieClipAssets

If you have a swf asset and you want to target something in its document class or on its timeline, e.g. custom methods, properties, MovieClips, etc., you need to target the class/timeline directly and you can do that by using the content property, which returns a MovieClip.

AS2 

assets.mySWF.content.someMethod()
assets.mySWF.content.someMovieClip._x = 10;


In AS3, you can cast a MovieClipAsset as IMovieClip or not.

AS3 

 assets.mySWF.content.someMethod();
 IMovieClip(assets.mySWF).content.someMovieClip.x = 10;


The same holds true for Pages (PageAsset extends MovieClipAsset).

AS2 

Gaia.api.getPage("index/nav").content.someMovieClip._visible = true;

or 

_global.Gaia.getPage("index/nav").content.someMovieClip._visible = true;


AS3 

Gaia.api.getPage("index/nav").content.someMovieClip.visible = true;


BitmapAsset (AS3 only)

BitmapAsset extends DisplayObjectAsset. In AS3, any image assets in the site.xml, such as jpg, gif, or png, will be loaded in as BitmapAssets. 

import com.gaiaframework.api.IBitmap;
import flash.display.BitmapData;
//
IBitmap(assets.myBitmap).x = 50;
var myBitmapData:BitmapData = IBitmap(assets.myImage).bitmapData;


BitmapSpriteAsset (AS3 only)

This is a version of the BitmapAsset that you can add interactivity to because BitmapSpriteAssets are wrapped inside a Sprite container, and the asset provides a proxy to the Sprite methods. Set the type="sprite" in the asset node to turn a BitmapAsset into a BitmapSpriteAsset. 

import com.gaiaframework.api.IBitmapSprite;
//
IBitmapSprite(assets.myBitmap).buttonMode = true;
IBitmapSprite(assets.myBitmap).addEventListener(MouseEvent.CLICK, onClickBitmap);


SpriteAsset (AS3 only)

SpriteAsset extends DisplayObjectAsset. SpriteAsset is provided for parity with AS3's inheritance tree and is not a settable asset type. The ISprite interface is used to keep file size smaller if you do not need the methods in IMovieClip.

container

SpriteAsset has a property called container that targets the loader of MovieClipAssets and the container Sprite created for BitmapSpriteAssets. You will generally use IBitmapSprite (which extends ISprite). 

import com.gaiaframework.api.IBitmapSprite
//
TweenLite.to(IBitmapSprite(assets.myBitmap).container, 2, {alpha:0});


SoundAsset

A SoundAsset has the same native methods as the Sound object in Flash.

For instance, if you wanted the mp3 asset with the id "myMusic" to play, you would use the following syntax on the root timeline of your page clip.

AS2 

assets.myMusic.start();
assets.myMusic.start(4, 5); // if you wanted it to start 4 seconds in and loop 5 times


AS3 uses the ISound interface.

AS3 

ISound(assets.myMusic).play();
ISound(assets.myMusic).play(4, 5); // if you wanted it to start 4 seconds in and loop 5 times

In AS2, Sound Assets are set to event by default. Set the streaming attribute in the asset node to "true" for Sound Assets you would like to play as streaming audio. You should also set preload="false" most of the time for streaming audio.

In AS3, there are no loaded event sounds, so the "streaming" attribute is not used and all Sound Assets are treated as streaming. If you set preload="true", it will preload the entire sound as part of the Page, and it will not play until you tell it to.

Finally, Gaia fixes AS2's native limitation of not being able to loop streaming sounds and allows you to do it by setting the loops value. Read more about this functionality in the Load On Demand section below.

SoundAssets have three helper methods for your convenience.

pause 

pause(flag:Boolean)

Pass true to pause and false (or nothing) to unpause and begin playing from the last position.

fadeTo 

fadeTo(value:Number, duration:Number, [onComplete:Function])  // AS2
fadeTo(value:Number, duration:Number, onComplete:Function = null)  // AS3

Value is the volume you want to fade to, duration is the number of seconds for the fade, and you can optionally pass a function to be called when the fade is complete.

panTo 

panTo(value:Number, duration:Number, [onComplete:Function])  // AS2
panTo(value:Number, duration:Number, onComplete:Function = null)  // AS3

Value is the pan value you want to pan to (-100 to 100 in AS2, -1 to 1 in AS3), duration is the number of seconds for the pan, and you can optionally pass a function to be called when the pan is complete.


SoundClipAsset (AS2 only)

A SoundClipAsset is nearly identical to a SoundAsset, and has most of the same native methods as the Sound Asset. SoundClipAssets are primarily used for mp3 files which you need to be perfectly looped.

To create a SoundClipAsset for Gaia, first, you create a new Flash file and import your audio file. Give your audio file any linkage ID you like and put the following code in the timeline. 

sound = new Sound(this);
sound.attachSound("YOUR_LINKAGE_ID");


In your site.xml, you will need to set the asset type attribute to "soundclip". Example: 

<asset id="mySound" src="music.swf" type="soundclip"/>

That's all you need to do and Gaia does the rest.

SoundClipAssets behave just like SoundAssets with the exception that they cannot be set to streaming. Other than that, you access them exactly the same as normal Sound Assets. You can add them to SoundGroups, as well.


NetStreamAsset

NetStreamAssets have all of the methods available to the NetStream class available to them. A NetStreamAsset also has a property "ns" which is the reference to the NetStream instance itself.

In AS3, NetStreamAssets use the INetStream interface. 

INetStream(assets.myFLV).play();
INetStream(assets.myFLV).attach(video);

In both AS2 and AS3, NetStreamAssets have two convenience properties and one method.

duration 

get duration():Number

Returns the duration of a loaded NetStreamAsset, extracted from the metaData.

metaData 

get metaData():Object

Returns the metaData object of a loaded NetStreamAsset.

attach() 

attach(video:Video)

This helper method lets you pass a video instance to attach() and Gaia handles attaching the NetStream to the Video.


In AS3 only, NetStreamAssets have four additional convenience properties/methods.

volume (AS3 only) 

get volume():Number
set volume(value:Number):void

This setter property accesses the volume on the NetStreamAsset, a floating point value from 0 to 1.

pan (AS3 only) 

get pan():Number
set pan(value:Number):void

This getter/setter property accesses the pan on the NetStreamAsset, a floating point value from -1 to 1.

fadeTo (AS3 only) 

fadeTo(value:Number, duration:Number, onComplete:Function = null)

Value is the volume you want to fade to, duration is the number of seconds for the fade, and you can optionally pass a function to be called when the fade is complete.

panTo (AS3 only) 

panTo(value:Number, duration:Number, onComplete:Function = null)

Value is the pan value you want to pan to (-100 to 100 in AS2, -1 to 1 in AS3), duration is the number of seconds for the pan, and you can optionally pass a function to be called when the pan is complete.



NetStreamAssetEvent

NetStreamAsset also dispatches events for the client "events" including onMetaData and onCuePoint. You can add a listener for these events to the NetStreamAsset, and the Event passes the "info" property for your use. 

// AS3
INetStream(assets.myFLV).addEventListener(NetStreamAssetEvent.METADATA, onMetaData);
// AS2
assets.myFLV.addEventListener(NetStreamAssetEvent.METADATA, Delegate.create(this, onMetaData));

To listen to the onMetaData event, the NetStreamAsset must be set to preload="false", otherwise, the metadata will already be available by the time you can access the asset.

These are all the NetStreamAsset events you can listen for. Consult the Actionscript NetStream documentation for more information about these events.

AS3 and AS2 

* NetStreamAssetEvent.METADATA
* NetStreamAssetEvent.CUEPOINT

AS3 only 

* NetStreamAssetEvent.IMAGE_DATA
* NetStreamAssetEvent.TEXT_DATA
* NetStreamAssetEvent.XMP_DATA

AS2 only 

* NetStreamAssetEvent.STATUS


XMLAsset

In AS2, XML assets have two ways of accessing them. You can either get the xml raw in the property xml or as an XML2AS Actionscript object in the property obj.

AS2 

assets.myCopy.xml.firstChild.firstChild.attributes.id;
assets.myCopy.obj.site[0].page[0].attributes.id;


In AS3, the XML is stored in the xml property, and you can use E4X syntax to parse through it. AS3 uses the IXml interface.

AS3 

var myXML:XML = IXml(assets.myCopy).xml;
trace(myXML.child[0].anotherChild[0].@someAttribute);


StyleSheetAsset

StyleSheetAsset is for .css files. It contains proxy methods for the StyleSheet class, has a property "style" to get the StyleSheet instance, and one helper method, transformStyle, which combines two native StyleSheet methods into one that returns a TextFormat.

transformStyle 

myFormat:TextFormat = assets.myStyle.transformStyle(styleName);

AS3 uses the IStyleSheet interface. 

myFormat:TextFormat = IStyleSheet(assets.myStyle).transformStyle(styleName);


TextAsset (AS3 only)

TextAsset is for .txt files, and is also the base class for StyleSheetAsset, JSONAsset and XMLAsset. It uses the IText interface and has a property "text" to get the raw text.

AS3 uses the IText interface. 

var str:String = IText(assets.myFLV).text;


JSONAsset (AS3 only)

JSONAsset extends TextAsset and uses the IJson interface. It has one property "json" which returns a deserialized JSON object using the com.serialization.json.JSON class. 

IJson(assets.myJson).json;


ByteArrayAsset (AS3 only)

ByteArrayAsset loads in raw byte data, which is avaiable in the public property "data" which returns the ByteArray. One use for this is if you want to load in the raw bytes of a file to create multiple instances of it, such as a Bitmap or swf file. 

IByteArray(assets.myByteArray).data;


DisplayObjectAsset (AS3 only)

DisplayObjectAsset extends AbstractAsset and is the base asset for SpriteAsset (and thus, MovieClipAsset), BitmapAsset and BitmapSpriteAsset.


Load-On-Demand Assets

In the site.xml, by setting the preload attribute to "false", assets can be set to not preload with a page and instead be loaded on demand. To load assets on demand, you use the load() method. You can load on demand any number of assets at once, and Gaia will automatically queue them to load two at a time (the maximum number of simultaneous HTTP requests). 

assets.mySWF.load();
assets.myMusic.load();

In AS3, use the appropriate interface class. 

IMovieClip(assets.mySWF).load();
ISound(assets.myMusic).load();

Sound And NetStream Assets

Sound and NetStream assets will immediately start streaming when load() is called on them. If the Sound is an event sound or a SoundClipAsset, it will load first and immediately play.

load()

Sound Assets accept two parameters on the load() method, just like the Sound.start() method. 

SoundAsset.load(startTime:Number, loops:Number);

If the SoundAsset is not streaming, it will load the entire sound file and then play it. If it is streaming, it will play it immediately. Unlike the (AS2) native loadSound() method, you can loop streaming audio files by passing the number of loops you want. For example, this code will start streaming a sound asset and loop it 999 times: 

assets.myStreamingMusic.load(0, 999);

loadWithoutPlaying()

Sound Assets also have a method to load without playing. 

SoundAsset.loadWithoutPlaying();


Other Asset Types

Image, swf, and xml assets will load like they normally do, with image and swf assets being invisible upon load.


Progress Attribute

By setting the progress attribute to "true" in the site.xml, you can use the preloader to display the loading progress of the asset (this does not work for NetStream or streaming sound assets), set it to "false" to not show progress. The asset loader uses the site preloader by default, but this behavior can be changed at runtime. Read the Preloader and API documentation for more information.


How To Know When An Asset Is Done Loading

If you want to know when an asset is done loading, assign an AssetEvent.ASSET_COMPLETE event listener to the asset. Make sure you remove the event listener when it's done!

AS3 

// replace this IAsset import with whatever specific asset interface you're using
import com.gaiaframework.events.AssetEvent;
import com.gaiaframework.api.IAsset;
//
var myAsset:IAsset = Gaia.api.getPage("index").assets.mySWF;
myAsset.addEventListener(AssetEvent.ASSET_COMPLETE, onAssetLoaded, false, 0, true);
myAsset.load();
//
private function onAssetLoaded(event:AssetEvent):void
{
    myAsset.removeEventListener(AssetEvent.ASSET_COMPLETE, onAssetLoaded);
    // access your asset OR event.target, which is also your asset
}


AS2 

import com.gaiaframework.assets.AbstractAsset;
import com.gaiaframework.events.AssetEvent;
import mx.utils.Delegate;
//
var myAsset:AbstractAsset = Gaia.api.getPage("index").assets.mySWF;
var completeDelegate:Function = Delegate.create(this, onAssetLoaded);
myAsset.addEventListener(AssetEvent.ASSET_COMPLETE, completeDelegate);
myAsset.load();
//
private function onAssetLoaded(event:AssetEvent):Void
{
    myAsset.removeEventListener(AssetEvent.ASSET_COMPLETE, completeDelegate);
    // access your asset OR event.target, which is also your asset
}


Re-Parenting DisplayObjectAssets (AS3 Only)

If you want to put a BitmapAsset or MovieClipAsset into a MovieClip or Sprite that you create, wait until transitionIn() is called and use the loader property. 

myContainer.addChild(assets.myAsset.loader);

If you want to reparent a BitmapSpriteAsset or MovieClipAsset, use the container property. 

myContainer.addChild(assets.myAsset.container);


Other Uses For Assets

Another use for assets is to preload and cache assets you want to load yourself manually. Just get the src property of the asset.

One example use case is for sound assets you want to persist after the page goes away.

AS2 

var mc:MovieClip = _root.createEmptyMovieClip("MC_Music", _root.getNextHighestDepth());
_root.music = new Sound(mc);
_root.music.loadSound(assets.myMusic.src);
_root.music.onLoad = function()
{
    _root.music.start();
};


Accessing Assets On Other Pages

If you are inside one page and want to access assets on another loaded page in the branch, you have two options.

The recommended way is to use the API method, getPage. 

Gaia.api.getPage(branch).assets

which you can read more about in the API section of the documentation.

The other way is to access the page's parent or children properties, such as: 

page.getParent().assets

OR 

page.children.somePageID.assets


Preloader Asset

You can use a MovieClipAsset as a preloader for the site. Most of the time, you'll want to set its depth="preloader" to load it into the right depth. It's best to make this an asset of a page that will not unload (e.g. the index page). If your MovieClipAsset unloads, the PreloadController will revert to using the default site preloader. Make sure that the MovieClipAsset is loaded before you override the preloader with this asset. You can read more about this in the Preloader documentation.


Dynamic Externalized Assets

This is an advanced technique and you should be completely familiar with how Gaia's assets work before using it.

You can create asset xml files and assign assets to a page dynamically at runtime using the Gaia API method addAssets. All you have to do is make sure the nodes you pass have the minimum required asset attributes of id and src. This makes creating image galleries with Gaia much simpler and allows you to use the AssetLoader or Gaia's preloading engine for dynamic lists of assets.

A recommended practice is to have your xml file with assets in it as an asset of the index page (using indexFirst="true", see example below), and call addAssets inside the index page's transitionIn() method on the page you want to add the assets to. You can also addAssets to a page that is already loaded.

You can add the assets as on-demand (preload="false") or, if you want them to preload with the page, set preload="true".

To use addAssets, pass a list of valid asset nodes and a reference to the PageAsset you want to add them to. Gaia will warn you if you try to add an asset that already exists on a page so make sure you use unique IDs for your external assets and do not add the same assets multiple times. Adding assets to a page using addAssets is permanent, not temporary.

How To Use External Assets 

Gaia.api.addAssets(nodes:XMLList, page:IPageAsset):void  // AS3
Gaia.api.addAssets(nodes:Array, page:PageAsset):Void  // AS2

Here's an example of how it works:

Example site.xml 

 <site title="Gaia Scaffold Site: %PAGE%" menu="true" indexFirst="true">
    <page id="index" src="index.swf">
	<asset id="homeAssets" src="homeAssets.xml"/>
        <page id="nav" src="nav.swf" depth="top">
            <page id="home" title="Home" src="home.swf" menu="true" />
        </page>
    </page>
 </site>

As you can see, the index page has an XMLAsset, homeAssets, and indexFirst is set to true. This is so the index page and the xml will be loaded before Gaia attempts to load the home page branch.


Example homeAssets.xml 

<assets>
   <asset id="asset1" src="image1.jpg"/>
   <asset id="asset2" src="image2.jpg"/>
   <asset id="asset3" src="image3.jpg"/>
   <asset id="asset4" src="image4.jpg"/>
</assets>


Example IndexPage.as

AS3 

 override public function transitionIn():void 
 {
    super.transitionIn();
    var assetNodes:XMLList = IXml(assets.homeAssets).xml.asset;
    var homePage:IPageAsset = Gaia.api.getPage("index/nav/home");
    Gaia.api.addAssets(assetNodes, homePage);
    TweenLite.to(this, 0.3, {alpha:1, onComplete:transitionInComplete});
 }

AS2 

 public function transitionIn():Void 
 {
    super.transitionIn();
    var assetNodes:Array = assets.homeAssets.obj.assets[0].asset;
    var homePage:PageAsset = Gaia.api.getPage("index/nav/home");
    Gaia.api.addAssets(assetNodes, homePage);
    TweenLite.to(this, 0.3, {_alpha:100, onComplete:Delegate.create(this, transitionInComplete)});
 }


Explanation

The above code will add all the assets in the homeAssets.xml file to the "home" Page before it loads, and will preload them with the page since these assets are being added before the "index/nav/home" branch is loaded.

If you do not need to preload the assets with the page, set preload="false" in each of your external asset nodes and you can load them yourself in the HomePage class, if you like.

Note that the nodes themselves do not need to be named "asset". You could have many pages of asset nodes in a single external xml file. Just pass the list of nodes you want to the addAssets() API method and the page they belong to and Gaia will iterate through that list.


Adding Assets To Pages That Are Already Loaded

If you choose to add assets to a page that is in the currently loaded branch, you will need to manually call load() on them if you want them to load at that time, even if they're set to preload with the branch. The reason is because Gaia loads all the files associated with a branch when it first loads the branch, and since you have added assets to the branch after this load has occurred, Gaia won't load them until the next time it loads the branch.

Again, it is recommended that you addAssets to a page BEFORE it is loaded in to avoid having to write conditional statements to check if the page already has the assets you're trying to add and whether or not you should load() them manually. It's possible to do it, it just takes more work to do so. So, unless you have a really good reason for not adding them ahead of time, you really should do it that way, instead.

This technique is not supported. If you do it, you are on your own. You never have to do this. There is no scenario where this is the only solution. Just because you can do it, doesn't mean you should.


Update File Bytes

If you want the Gaia Panel to update the "bytes" attribute for external assets, you will need to set assets="true" on the xml asset for the panel to update it.


Duplicating Assets

If you want to duplicate an asset, you can simply duplicate its node, change the id, and dynamically add it.

AS3 

var node:XML = assets.myAsset.node.copy();  // duplicate the node
node.@id = "newAssetID";  // give the asset a new id
var xml:XML = <assets/>;  // create a root node for an XMLList
xml.appendChild(node);  // add the asset to the root node
Gaia.api.addAssets(xml.asset, page);  // add the duplicated asset to the page


More Information On Assets

To see all of the methods available to assets, check out their individual class files in the com.gaiaframework.assets package. Most, if not all, native methods are available directly.

In AS3, make sure to look at the individual asset interface classes in the com.gaiaframework.api package.

You should use these interfaces when casting assets you access to keep your file sizes considerably smaller.

AS3 

import com.gaiaframework.api.ISound;
var myMusic:ISound = assets.myMusic as ISound;
myMusic.play();

import com.gaiaframework.api.INetStream;
var myVideo:INetStream = assets.myVideo as INetStream;
myVideo.play();


node

All assets (including Pages) have a property node. This contains the xml node of the page or asset in the site.xml. Because it's XML, you can put custom attributes on your page or asset nodes, and even custom child nodes that are not <page> or <asset> nodes. In AS3, node is XML which can be accessed via E4X. In AS2, it's an XML2AS object.

Retrieved from "http://www.gaiaflashframework.com/wiki/index.php?title=Assets"