Packagecom.soma.assets
Classpublic class NodeParser
InheritanceNodeParser Inheritance flash.events.EventDispatcher
ImplementsIDisposable

Author: Romuald Quantin - www.soundstep.com

Information:
Blog page - SomaUI
How does it work - Soma Protest
Project Host - Google Code
Documentation - Soma ASDOC
Class version: 2.0
Actionscript version: 3.0

Copyright:

The contents of this file are subject to the Mozilla Public License
Version 1.1 (the "License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at

http://www.mozilla.org/MPL/

Software distributed under the License is distributed on an "AS IS" basis,
WITHOUT WARRANTY OF ANY KIND, either express or implied.
See the License for the specific language governing rights and
limitations under the License.

The Original Code is Soma.
The Initial Developer of the Original Code is Romuald Quantin.
Initial Developer are Copyright (C) 2008-2009 Soundstep. All Rights Reserved.

Usage:
A NodeParser instance is creating assets, loading external files and applying properties dynamically from XML nodes describing each asset.

Many NodeParser instances are automatically created by Soma: in the background manager (to instantiate the nodes children of the "backgrounds" node of the XML Site definition), in the base manager (to instantiate the nodes children of the "base" node of the XML Site definition) and in the Page superclass (to instantiate the nodes children the "content" node of each page node).

All the following XML nodes can be used in these 3 places in the XML Site Definition: background node, base node, content node in any page node (Soma Protest XML Site Definition).

  
private function createParser():void {
    
    var parser:NodeParser = new NodeParser(Soma.getInstance().library);
    
    var xml:XML = <myAssets>
        <video id="myVideo" url="video/video.flv" x="50" alpha=".5" verticalCenter="0" volume="0" />
        <image id="myImage" file="image.png" scaleX=".5" scaleY=".5" blendMode="multiply" ratio="ratio_in"/>
        <bitmap id="myBitmap" linkage="AssetClassNameBitmap" x="170" y="170" blendMode="multiply" scaleX=".3" scaleY=".3"/>
        <movieclip id="myMovieClip" linkage="AssetClassNameMovieClip" x="170" y="280" scaleX=".3" scaleY=".3"/>
        <text id="myText" style="body" x="10" y="10" width="200"><![CDATA[Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer sed massa turpis, sit amet ornare nisl.]]></text>
        <xml id="myXML" file="sample.xml"/>
    </myAssets>;
    
    parser.add(xml.children());
    
    // you can also use a single XML node to add an asset to the parser instance:
    //parser.add(new XML ('<xml id="myXML" file="data/sample.xml"/>'));
    
    // this implies that you have created a CircleSimple class (class instantiated)
    // an IAsset class CircleAsset (class that instantiates CircleSimple)
    // and that you have added it to the Library used by the parser, example:
    // Soma.getInstance().config.registerClass(CircleSimple);
    // Soma.getInstance().library.registerAsset("circleParam", CircleAsset);
    // See the Soma Protest code source to find an example.
    //parser.add(new XML ('<circle id="myCustomAsset" classname="CircleSimple" width="100" height="100" alpha=".5" right="10" bottom="10"/>')); 
    
    parser.addEventListener(ParserEvent.WILL_PARSE, events);
    parser.addEventListener(ParserEvent.WILL_LOAD, events);
    parser.addEventListener(ParserEvent.WILL_SET_PROPERTIES, events);
    parser.addEventListener(ParserEvent.WILL_SET_BASEUI_PROPERTIES, events);
    parser.addEventListener(ParserEvent.ASSET_LOADED, events);
    parser.addEventListener(ParserEvent.COMPLETE, events);
    var myAssets:Array = parser.run(this, Soma.getInstance().baseUI, Soma.getInstance().loader);
    trace(myAssets);
}

private function events(e:ParserEvent):void {
    trace("Event received: ", e);
    if (e.type == ParserEvent.COMPLETE) e.parser.dispose();
}
  
A custom asset example can be found in the Library documentation (link below).

See also

Library
NodeParser
AssetFactory
BitmapAsset
MovieClipAsset
TextAsset
VideoAsset
IAsset
ILibrary


Public Properties
 PropertyDefined by
  assetFactory : AssetFactory
[read-only] Gets the assets factory instance.
NodeParser
  baseUI : BaseUI
BaseUI instance that will be used if BaseUI properties have been found in a node.
NodeParser
  library : ILibrary
[read-only] Gets the library instance used.
NodeParser
  loader : SomaLoader
SomaLoader instance that will be used to load external assets.
NodeParser
  nodes : Array
[read-only] Gets a copy of the Array of nodes.
NodeParser
  target : DisplayObjectContainer
Container target that will hold the assets created.
NodeParser
Public Methods
 MethodDefined by
  
Creates a NodeParser instance.
NodeParser
  
add(node:*):void
Add a node or a list of nodes to be parsed, instantiated and loaded if it is an external file.
NodeParser
  
contains(node:XML):Boolean
Whether or not the NodeParser instance contains an specific node.
NodeParser
  
dispose():void
Clean the parser (remove event listeners).
NodeParser
  
info():String
Print information about the nodes contained.
NodeParser
  
remove(node:XML):Boolean
Removes a node previously added.
NodeParser
  
removeAll():void
Removes all nodes.
NodeParser
  
removeByIndex(index:Number):Boolean
Removes a node using its position in the list.
NodeParser
  
run(target:DisplayObjectContainer, baseUI:BaseUI = null, loader:SomaLoader = null):Array
Starts the NodeParser instance to parse the XML nodes added, instantiate and load the assets.
NodeParser
Events
 EventSummaryDefined by
   Indicates when an external asset has been loaded (other assets are returned in an array by the run method).NodeParser
   Indicates when the parser has finished parsing, creating and loading assets.NodeParser
   Indicates that the NodeParser instance is about to load external assets.NodeParser
   Indicates that the NodeParser is about to parse the XML nodes.NodeParser
   Indicates when BaseUI properties from a XML node are about to be applied to the asset.NodeParser
   Indicates when properties from a XML node are about to be applied to the asset.NodeParser
Property detail
assetFactoryproperty
assetFactory:AssetFactory  [read-only]

Gets the assets factory instance.

Implementation
    public function get assetFactory():AssetFactory
baseUIproperty 
baseUI:BaseUI  [read-write]

BaseUI instance that will be used if BaseUI properties have been found in a node.

Implementation
    public function get baseUI():BaseUI
    public function set baseUI(value:BaseUI):void
libraryproperty 
library:ILibrary  [read-only]

Gets the library instance used.

Implementation
    public function get library():ILibrary
loaderproperty 
loader:SomaLoader  [read-write]

SomaLoader instance that will be used to load external assets.

Implementation
    public function get loader():SomaLoader
    public function set loader(value:SomaLoader):void
nodesproperty 
nodes:Array  [read-only]

Gets a copy of the Array of nodes.

Implementation
    public function get nodes():Array
targetproperty 
target:DisplayObjectContainer  [read-write]

Container target that will hold the assets created.

Implementation
    public function get target():DisplayObjectContainer
    public function set target(value:DisplayObjectContainer):void
Constructor detail
NodeParser()constructor
public function NodeParser(library:ILibrary)

Creates a NodeParser instance.

Parameters
library:ILibrary — instance of Library class that can contains custom assets, the global Soma library is accessible using Soma.getInstance().library.
Method detail
add()method
public function add(node:*):void

Add a node or a list of nodes to be parsed, instantiated and loaded if it is an external file.

Parameters
node:* — (XML) or list of nodes (XMLList)
contains()method 
public function contains(node:XML):Boolean

Whether or not the NodeParser instance contains an specific node.

Parameters
node:XML — node to search in the list.

Returns
Boolean — a Boolean.
dispose()method 
public function dispose():void

Clean the parser (remove event listeners).

info()method 
public function info():String

Print information about the nodes contained.

Returns
String — a string describing the content of the NodeParser instance.
remove()method 
public function remove(node:XML):Boolean

Removes a node previously added.

Parameters
node:XML — XML Node

Returns
Boolean
removeAll()method 
public function removeAll():void

Removes all nodes.

removeByIndex()method 
public function removeByIndex(index:Number):Boolean

Removes a node using its position in the list.

Parameters
index:Number — position of the node in a Array.

Returns
Boolean
run()method 
public function run(target:DisplayObjectContainer, baseUI:BaseUI = null, loader:SomaLoader = null):Array

Starts the NodeParser instance to parse the XML nodes added, instantiate and load the assets.

Parameters
target:DisplayObjectContainer — that will hold the assets created (example: a Sprite).
 
baseUI:BaseUI (default = null) — BaseUI instance that will be used if BaseUI properties have been found in the nodes.
 
loader:SomaLoader (default = null) — SomaLoader instance that will be used if external assets have been found in the nodes.

Returns
Array — an Array of assets created (or container for external assets). XML assets are not returned in the array, you must listen to a ParserEvent.ASSET_LOADED to get the XML data.
Event detail
ASSET_LOADEDevent 
Event object type: com.soma.events.ParserEvent.ASSET_LOADED

Indicates when an external asset has been loaded (other assets are returned in an array by the run method).

COMPLETEevent  
Event object type: com.soma.events.ParserEvent.COMPLETE

Indicates when the parser has finished parsing, creating and loading assets.

WILL_LOADevent  
Event object type: com.soma.events.ParserEvent.WILL_LOAD

Indicates that the NodeParser instance is about to load external assets.

WILL_PARSEevent  
Event object type: com.soma.events.ParserEvent.WILL_PARSE

Indicates that the NodeParser is about to parse the XML nodes.

WILL_SET_BASEUI_PROPERTIESevent  
Event object type: com.soma.events.ParserEvent.WILL_SET_BASEUI_PROPERTIES

Indicates when BaseUI properties from a XML node are about to be applied to the asset.

WILL_SET_PROPERTIESevent  
Event object type: com.soma.events.ParserEvent.WILL_SET_PROPERTIES

Indicates when properties from a XML node are about to be applied to the asset.