SomaAssets

soundstep edited this page Jun 3, 2011 · 30 revisions
Clone this wiki locally

Tables of contents

Introduction

The SomaAssets plugin is a wrapper to the AssetLoader library and makes you able to easily load multiple assets (such as images, video, sounds, XML, SWF files, and so on) as well as having an easy access to the assets with or without injection enabled.

Note: The AssetLoader library is a port based on Flash built-in events from the original Matan’s AssetLoader that is written with signals.

Create the plugin instance

The SomaAssets instance can be created using the createPlugin method of the SomaCore application facade.

A SomaAssets instance is a wrapper and it will automatically create one instance of the AssetLoader.

createPlugin(SomaAssets, new SomaAssetsVO(this))
package {

	import com.soma.plugins.assets.vo.SomaAssetsVO;
	import com.soma.plugins.assets.SomaAssets;
	import com.soma.core.Soma;
	import com.soma.core.interfaces.ISoma;

	import flash.display.Stage;

	public class SomaApplication extends Soma implements ISoma {

		public function SomaApplication(stage:Stage) {
			super(stage);
		}
		
		override protected function registerPlugins():void {
			var assets:SomaAssets = createPlugin(SomaAssets, new SomaAssetsVO(this)) as SomaAssets;
		}
	}
}

Loader architecture

Find more details about the AssetLoader library.

This wiki will be more about the plugin SomaAssets rather than the loader AssetLoader but as a simple overview, the AssetLoader library is made of elements (parent and children) that are ILoader and IAssetLoader (which extends ILoader).

The difference between the two interfaces is that the IAssetLoader is a container that can also contain other ILoader (and IAssetLoader).

--- main loader (AssetLoader - IAssetLoader/ILoader)
         |--- image asset (ImageLoader - ILoader)
         |--- sound asset (SoundLoader - ILoader)
         |--- child loader (AssetLoader - IAssetLoader/ILoader)
                   |--- flash asset (SWFLoader - ILoader)
                   |--- css asset (CSSLoader - ILoader)

All these elements are ILoader instances, but only the main loader and child loader are IAssetLoader.

You can listen to the same events on any kind of ILoader instance (complete, progress, error, and so on).

Difference between the SomaAssets plugin and the AssetLoader loader

The SomaAssets instance is the plugin and is only a wrapper, it will not load anything into your application. It provides shortcuts, frameworks events and easy ways to access to the loader instance and its content.

The AssetLoader instance is the class that will load your assets, it can contains assets (ILoader) or other loader instances (IAssetLoader).

They both do different jobs and dispatch their own events.

The plugin will dispatch framework-wise events (that can also becomes commands):

SomaAssetsEvent.LOADER_READY
SomaAssetsEvent.LOADER_COMPLETE
SomaAssetsEvent.ASSET_LOADED
SomaAssetsEvent.CONFIG_LOADED
SomaAssetsEvent.ERROR

A loader will dispatch loading state and progress events:

AssetLoaderEvent.CHILD_OPEN
AssetLoaderEvent.CHILD_COMPLETE
AssetLoaderEvent.OPEN
AssetLoaderEvent.START
AssetLoaderEvent.STOP
AssetLoaderEvent.COMPLETE
AssetLoaderEvent.CONFIG_LOADED
AssetLoaderEvent.ADDED_TO_PARENT
AssetLoaderEvent.REMOVED_FROM_PARENT
AssetLoaderEvent.ID3
AssetLoaderEvent.NET_STREAM_READY
AssetLoaderProgressEvent.PROGRESS
AssetLoaderErrorEvent.ERROR
AssetLoaderErrorEvent.CHILD_ERROR
AssetLoaderHTTPStatusEvent.STATUS
AssetLoaderNetStatusEvent.INFO

Destroy the plugin instance

The plugins are not managed by the framework and it is your matter to destroy them if you need to.

_assets = createPlugin(SomaAssets, new SomaAssetsVO(this)) as SomaAssets;
// destroying
_assets.dispose();
_assets = null;

Add a config

A configuration file is not required, you can manually add the items you want to load, but it is an easy way to set up your assets, and/or group of assets.

Here is an example of config file:

<?xml version="1.0" encoding="UTF-8"?>
<loader connections="3">
	<group id="group0" connections="1" preventCache="true">
		<group id="group00" connections="1" preventCache="true">
			<asset id="img0" src="assets/img/image00.jpg" smoothing="true" transparent="true" weight="174015"/>
			<asset id="img1" src="assets/img/image01.jpg" smoothing="true" transparent="true" weight="165158"/>
		</group>
		<asset id="img2" src="assets/img/image02.jpg" fillColor="0xFF0000" smoothing="true" transparent="true" weight="156926"/>
		<asset id="img3" src="assets/img/image03.jpg" fillColor="0xFF0000" smoothing="true" transparent="true" weight="177053"/>
	</group>
	<group id="group1" connections="2" preventCache="true">
		<asset id="swf0" src="assets/swf/flash0.swf" priority="1" weight="1915"/>
		<asset id="swf1" src="assets/swf/flash1.swf" priority="2" weight="2005"/>
	</group>
	<asset id="css" src="assets/css/stylesheet.css" preventCache="true" weight="352"/>
	<asset id="json" src="assets/json/data.json" preventCache="true" weight="582"/>
	<asset id="sound" src="assets/sounds/sample.mp3" preventCache="true" weight="16718"/>
	<asset id="text" src="assets/text/text.txt" preventCache="true" weight="574"/>
	<asset id="xml" src="assets/xml/sample.xml" preventCache="true" weight="79"/>
	<asset id="video" src="assets/video/sample.flv" weight="1550580"/>
	<asset id="zip" src="assets/zip/file.zip" weight="3493"/>
</loader>

There are 3 ways to add a XML config:

  • passing a URL or XML to the VO when the plugin is created
createPlugin(SomaAssets, new SomaAssetsVO(this, "xml/assets_config.xml"))
createPlugin(SomaAssets, new SomaAssetsVO(this, myXML))
  • passing a URL or XML to the SomaAssets instance
_assets = createPlugin(SomaAssets, new SomaAssetsVO(this)) as SomaAssets;
_assets.addConfig("xml/assets_config.xml");
_assets.addConfig(myXML);
  • passing a URL or XML to the AssetLoader instance
_assets = createPlugin(SomaAssets, new SomaAssetsVO(this)) as SomaAssets;
var loader:AssetLoader = _assets.loader;
_loader.addConfig("xml/assets_config.xml");
_loader.addConfig(myXML);

Starting the loader when the config is ready

Inline XML

When an XML instance is passed to either the plugin or the loader, there’s nothing to load. You can verify that the config is ready this way:

var configLoaded:Boolean = assets.addConfig(myXML);
// or
_assets.configLoaded

You can also get the config back (note that the XML returned is a copy of the original config):

var config:XML = assets.config;

External XML

The config can be loaded before doing anything else with the same method:

assets.addConfig("xml/assets/xml");

You can use 2 types of events to know the config has been loaded.

  • The plugin framework-wise event

For example, in a wire or a mediator:

override protected function initialize():void {
	addEventListener(SomaAssetsEvent.CONFIG_LOADED, configLoadedHandler);
}

private function configLoadedHandler(event:SomaAssetsEvent):void {
	trace("config loaded:", event.config.toXMLString());
}

The SomaAssetsEvent can also be used to create commands:

addCommand(SomaAssetsEvent.CONFIG_LOADED, AssetsCommands);
  • The loader event

The main loader itself can also be listened to:

_assets = createPlugin(SomaAssets, new SomaAssetsVO(this)) as SomaAssets;
_assets.loader.addEventListener(AssetLoaderEvent.CONFIG_LOADED, configLoadedHandler);

private function configLoadedHandler(event:AssetLoaderEvent):void {
	trace("config loaded:", IAssetLoader(event.currentTarget).config.toXMLString());
}
  • Finally starting the loader
_assets.loader.start();

Monitoring the loading

The loaders are dispatching AssetLoaderEvent events so you can find out when a loading has started, the progress of the loading and when an asset has been loaded.

The SomaAssets plugin only provides few events to monitor the loading.

  • SomaAssetsEvent.LOADER_READY: the main loader has been created
  • SomaAssetsEvent.LOADER_COMPLETE: all assets have been loaded
  • SomaAssetsEvent.ASSET_LOADED: one the assets has been loaded
  • SomaAssetsEvent.CONFIG_LOADED: the config has been loaded
  • SomaAssetsEvent.ERROR: an error has occured (at any kind of level)

Retrieving the loaders

Retrieving the loaders from the plugin

The following examples will be based on the above XML config.
The assets instance will refer to be a SomaAssets instance.
The loader instance will refer to the main AssetLoader instance created by the plugin.

You can retrieve the main loader this way:

var mainLoader:IAssetLoader = assets.loader;
// or
var mainLoader:IAssetLoader = assets.getLoader("main") as IAssetLoader;
// or
var mainLoader:IAssetLoader = assets.getLoader(SomaAssets.LOADER_PRIMARY_GROUP_NAME) as IAssetLoader;

The SomaAssets plugin makes you able to use paths to retrieve the loaders which is very handy to retrieve children. From an IAssetLoader instance it would look like this:

var childLoader:IAssetLoader = IAssetLoader(loader.getLoader("group0")).getLoader("group00") as IAssetLoader;

From the plugin you can use paths (ids delimited by a string):

var childLoader:IAssetLoader = assets.getLoader("group0/group00") as IAssetLoader;
var assetLoader:ImageLoader = assets.getLoader("group0/group00/img0") as ImageLoader;

Note: the delimiter “/” can be changed to something else using the class variable SomaAssets.LOADER_PATH_DELIMITER;

Retrieving the loaders with events

Different ways to add a listener to an ILoader instance:

var child:ILoader = IAssetLoader(loader.getLoader("group0")).getLoader("group00");
child.addEventListener(AssetLoaderEvent.COMPLETE, loaderComplete);

private function loaderComplete(event:AssetLoaderEvent):void {
	var loader:ILoader = event.currentTarget as ILoader;
}
var child:ILoader = assets.getLoader("group0/group00");
child.addEventListener(AssetLoaderEvent.COMPLETE, loaderComplete);

private function loaderComplete(event:AssetLoaderEvent):void {
	var loader:ILoader = event.currentTarget as ILoader;
}

Retrieving the assets

Retrieving the assets from the plugin

From an IAssetLoader instance it would look like this:

var image:Bitmap = IAssetLoader(loader.getLoader("group0")).getLoader("group00").data["img0"];

From the plugin you can also use paths:

var image:Bitmap = assets.getAssets("group0/group00/img0");

Retrieving the loaders with events

Different ways to add a listener to an ILoader instance:

var child:ILoader = IAssetLoader(IAssetLoader(loader.getLoader("group0")).getLoader("group00")).getLoader("img0");
child.addEventListener(AssetLoaderEvent.COMPLETE, assetComplete);

private function assetComplete(event:AssetLoaderEvent):void {
	var loader:ILoader = event.currentTarget as ILoader;
	var image:Bitmap = loader.data;
}
var child:ILoader = assets.getLoader("group0/group00/img0");
child.addEventListener(AssetLoaderEvent.COMPLETE, assetComplete);

private function assetComplete(event:AssetLoaderEvent):void {
	var loader:ILoader = event.currentTarget as ILoader;
	var image:Bitmap = loader.data;
}

Getting an asset from a framework-wise event:

addEventListener(SomaAssetsEvent.ASSET_LOADED, assetComplete);

private function assetComplete(event:SomaAssetsEvent):void {
	switch (event.path) {
		case "group0/group00/img0":
			var image:Bitmap = event.asset;
			break;
	}
}

Injection overview

Enabling the injection in a Soma application and using the SomaAssets plugin will be the easiest way to get back information from the plugin (assets, loaders, config, and so on).

Injection mapping names are automatically created from the config XML file you are going to use.

Inject the plugin

[Inject(name="assets")]
public var plugin:SomaAssets;

Inject the main loader

[Inject(name="assets")]
public var loader:IAssetLoader;

Inject the XML config

[Inject(name="assets")]
public var config:XML;

Inject a loader

Note: ILoader can also be used as a type)

[Inject(name="group0")]
public var group0:IAssetLoader;

[Inject(name="group0/group00")]
public var group00:IAssetLoader;

[Inject(name="group0/group00/img0")]
public var img0:ILoader;

Inject an asset loader

[Inject(name="group0/group00/img0")]
public var loaderType1:ImageLoader;
		
[Inject(name="group1/swf0")]
public var loaderType2:SWFLoader;
		
[Inject(name="css")]
public var loaderType3:CSSLoader;
		
[Inject(name="json")]
public var loaderType4:JSONLoader;
		
[Inject(name="sound")]
public var loaderType5:SoundLoader;
		
[Inject(name="text")]
public var loaderType6:TextLoader;
		
[Inject(name="xml")]
public var loaderType7:XMLLoader;
		
[Inject(name="video")]
public var loaderType8:VideoLoader;
		
[Inject(name="zip")]
public var loaderType9:BinaryLoader;

Inject an asset

[Inject(name="group0/group00/img0")]
public var assetType1:Bitmap;
		
[Inject(name="group1/swf0")]
public var assetType2:MovieClip;
		
[Inject(name="css")]
public var assetType3:StyleSheet;
		
[Inject(name="json")]
public var assetType4:Object;
		
[Inject(name="sound")]
public var assetType5:Sound;
		
[Inject(name="text")]
public var assetType6:String;
		
[Inject(name="xml")]
public var assetType7:XML;
		
[Inject(name="video")]
public var assetType8:NetStream;
		
[Inject(name="zip")]
public var assetType9:ByteArray;