If you’re familiar with PureMVC, you’ll find lots of similarities in Robotlegs and then some – cool features such as Dependency Injection. In this tutorial, I shall demonstrate how to build a typical Flash site with Robotlegs, similar to the one in my PureMVC Flash Site tutorial. The application begins by loading an xml document, parsing that data, and finally displaying a Flash site based on the dynamic data.

View Demo

Download Source Files

Using Robotlegs with Flash CS3 / CS4

Since Robotlegs relies on custom metadata for its dependency injection and Flash CS3/CS4 don’t support compiling custom metadata, Robotlegs is more suited for a workflow that doesn’t rely on the Flash IDE for compilation. However, the bundled SwiftSuspenders DI solution does provide a way to configure injection points using XML, allowing for Robotlegs usage in Flash CS3/CS4 compiled projects. Helmut Granda has written a detailed tutorial on how to configure the SwiftSuspenders XML_CONFIG to enable this.

Prerequisites

This tutorial shall assume that you are familiar with setting up an Actionscript only project in Flex/Flash Builder, FDT or Flash Develop. You must also be comfortable with compiling your AS3 project using the MXMLC compiler. If you must use the Flash IDE, please follow the suggested links above to set up your environment to support the dependency injection solution.

1. Examine the asset.fla

In this example, the FLA is purely used to generate a SWC containing the font assets which will be imported into the application.

2. The RobotlegsFlashSite document class

The document class registers the Georgia and Helvetica fonts by creating the respective font instances. It also creates an instance of the ApplicationContext class.

package
{
  import Georgia;
  import Helvetica;

  import flash.display.*;
  import flash.text.Font;

  import com.hubflanger.robotlegsdemo.ApplicationContext;

  public class RobotlegsFlashSite extends Sprite
  {
    protected var context:ApplicationContext;

    public function RobotlegsFlashSite()
    {
      stage.scaleMode = StageScaleMode.NO_SCALE;

      var georgia:Font = new Georgia();
      var helvetica:Font = new Helvetica();

      context = new ApplicationContext(this);
    }
  }
}

3. The ApplicationContext class

The Context lies in the heart of a Robotlegs implementation, providing the mechanism by which the implementation’s tiers will communicate. The Context provides three functions within an application: initialization, de-initialization, and creates the central event bus for communication. Although an application is not limited to a single Context, for many use cases one Context is sufficient.

The ApplicationContext class extends the base Context class in the Robotlegs framework. Its constructor accepts an instance of the RobotlegsFlashSite document class which is assigned to the variable contextView. Later on, we shall see how contextView is accessed throughout the application.

In a Robotlegs implementation, we typically override the startup() method to set up all the mappings for dependency injection, views and events. Here, we map a Singleton of SiteModel and an instance of SiteDataService which implements the ISiteDataService interface to the Injector. This makes them available to other classes in the application via the [Inject] metadata.

We then map 3 view classes (Header, Navigation and SectionContainer) to their respective Mediators by calling the mapView() method of the MediatorMap instance. In Robotlegs, a Mediator performs similar functions as ones in PureMVC. A Mediator provides a bridge between the framework and the View Component it’s responsible for. It passes along framework events to its view component and sends framework events in response to events dispatched by its view component. By putting application-specific logic in the Mediator, we de-couple the view component from the application’s implementation.

Finally, we call the mapEvent() method of the CommandMap instance to map 3 events to their respective Commands. The ContextEvent.STARTUP_COMPLETE event is dispatched by the framework upon completing execution of the Context’s startup() method. Here, we map the LoadDataCommand class to handle this event.

package com.hubflanger.robotlegsdemo
{
  import com.hubflanger.robotlegsdemo.model.SiteModel;
  import com.hubflanger.robotlegsdemo.controller.*;
  import com.hubflanger.robotlegsdemo.service.*;
  import com.hubflanger.robotlegsdemo.events.*;
  import com.hubflanger.robotlegsdemo.view.*;
  import com.hubflanger.robotlegsdemo.view.components.*;

  import flash.display.DisplayObjectContainer;

  import org.robotlegs.mvcs.Context;
  import org.robotlegs.base.ContextEvent;

  public class ApplicationContext extends Context
  {
    public function ApplicationContext(contextView:DisplayObjectContainer)
    {
      super(contextView);
    }

    override public function startup():void
    {
      injector.mapSingleton(SiteModel);

      injector.mapClass(ISiteDataService, SiteDataService);

      mediatorMap.mapView(Header, HeaderMediator);
      mediatorMap.mapView(Navigation, NavigationMediator);
      mediatorMap.mapView(SectionContainer, SectionContainerMediator);

      commandMap.mapEvent(ContextEvent.STARTUP_COMPLETE, LoadDataCommand, ContextEvent, true);
      commandMap.mapEvent(SystemEvent.INIT_VIEW, InitViewCommand, SystemEvent, true);
      commandMap.mapEvent(UserEvent.NAV_CLICK, SectionSelectedCommand, UserEvent, false);

      super.startup();
    }
  }
}

4. The LoadDataCommand class

As intended by the command mapping, the LoadDataCommand command responds to the Context’s STARTUP_COMPLETE event. It creates an instance of SiteDataService using the [Inject] metadata. In its execute() method, we call the loadData() method of the SiteDataService instance to initiate the loading of xml data.

package com.hubflanger.robotlegsdemo.controller
{
  import com.hubflanger.robotlegsdemo.service.ISiteDataService;

  import org.robotlegs.mvcs.Command;

  public class LoadDataCommand extends Command
  {
    [Inject]
    public var siteDataService:ISiteDataService;

    override public function execute():void
    {
      siteDataService.loadData();
    }
  }
}

5. The SiteDataService class

In Robotlegs, Model and Service classes extend the base Actor class to inherit functionality for communicating with the framework. A Model encapsulates and provides an API for data and sends event notifications when the data model has been changed. A Service communicates with the outside world through web services or file access and dispatches system events in response to external events.

In the SiteDataService class, we access the SiteModel singleton via the [Inject] metadata and assign it to the model variable. The loadData() method creates a URLLoader instance and loads the xml.

The loadCompleteHandler event handler parses the xml data, creates SectionVO objects for each section node and stores them in the SiteModel singleton. It then dispatches a SystemEvent.INIT_VIEW event to the framework, instructing the application to start its view construction.

package com.hubflanger.robotlegsdemo.service
{
  import com.hubflanger.robotlegsdemo.model.vo.SectionVO;
  import com.hubflanger.robotlegsdemo.model.SiteModel;
  import com.hubflanger.robotlegsdemo.events.SystemEvent;

  import flash.events.Event;
  import flash.net.*;

  import org.robotlegs.mvcs.Actor;

  public class SiteDataService extends Actor implements ISiteDataService
  {
    [Inject]
    public var model:SiteModel;

    public function SiteDataService()
    {
      //
    }

    public function loadData():void
    {
      var loader:URLLoader = new URLLoader();
      loader.addEventListener(Event.COMPLETE, loadCompleteHandler);
      loader.load(new URLRequest("assets/data.xml"));
    }

    private function loadCompleteHandler(event:Event):void
    {
      var loader:URLLoader = event.target as URLLoader;
      loader.removeEventListener(Event.COMPLETE, loadCompleteHandler);

      var xml:XML = new XML(event.target.data);
      model.header = xml.header.text();

      var sections:XMLList = xml.sections.section;

      for each (var section:XML in sections) {
        var sectionVO:SectionVO = new SectionVO(section.@id,
                            section.label.toString(),
                            section.content.toString());

        model.sectionsList.push(sectionVO);
        model.sectionsHash[sectionVO.id] = sectionVO;
      }

      model.defaultSection = model.sectionsList[0].id;

      dispatch(new SystemEvent(SystemEvent.INIT_VIEW, false));
    }
  }
}

6. The InitViewCommand class

The InitViewCommand command responds to the SystemEvent.INIT_VIEW event by instantiating 3 view components and adding them as children to the main display container. In Robotlegs, the mappings in the MediatorMap as shown in ApplicationContext allows a Mediator to be automatically created when its view component is instantiated.

package com.hubflanger.robotlegsdemo.controller
{
  import com.hubflanger.robotlegsdemo.model.SiteModel;
  import com.hubflanger.robotlegsdemo.view.components.*;

  import org.robotlegs.mvcs.Command;

  public class InitViewCommand extends Command
  {
    [Inject]
    public var model:SiteModel;

    override public function execute():void
    {
      contextView.addChild(new SectionContainer());
      contextView.addChild(new Header());
      contextView.addChild(new Navigation());
    }
  }
}

6. The NavigationMediator class

We won’t be getting into in-depth discussions of the view classes except to say they’re pretty generic display containers extending the Sprite class. Instead, we shall take a look at the NavigationMediator and see how it handles Mouse Click events dispatched by the NavButton instances in the Navigation view component.

Typically, one takes advantage of the onRegister() handler which is invoked when the Mediator has been registered with the framework, to perform set up tasks on the view component and map events with their event handlers. Here, we invoke the view component’s init() method and pass the SiteModel’s sectionsList array so that the Navigation view component will dynamically create a list of NavButton instances. Then we invoke the mapListener() method of the EventMap instance to map a SystemEvent.SECTION_CHANGED framework event and a NavButton.CLICK user event with their respective event handlers. Finally, it calls the dispatch() method sending a UserEvent.NAV_CLICK custom event with the default section’s ID to the framework.

The navClickHandler() responds to NavButton.CLICK events bubbled from the NavButton instances. It in turn dispatches a UserEvent.NAV_CLICK event to the framework. This is how user interactions with display objects are commonly handled in Robotlegs.

As you can see, NavigationMediator extends the base Mediator class of the Robotlegs framework and inherits from it a bunch of useful features. In addition to dependency injection, the EventMap instance is a built-in property and the dispatch() method allows the Mediator to communicate events to the framework.

package com.hubflanger.robotlegsdemo.view
{
  import com.hubflanger.robotlegsdemo.model.SiteModel;
  import com.hubflanger.robotlegsdemo.view.components.Navigation;
  import com.hubflanger.robotlegsdemo.view.components.NavButton;
  import com.hubflanger.robotlegsdemo.events.*;

  import flash.events.*;

  import org.robotlegs.mvcs.Mediator;

  public class NavigationMediator extends Mediator
  {
    [Inject]
    public var model:SiteModel;

    [Inject]
    public var nav:Navigation;

    public function NavigationMediator()
    {
      //
    }

    override public function onRegister():void
    {
      nav.init(model.sectionsList);

      eventMap.mapListener(eventDispatcher, SystemEvent.SECTION_CHANGED, sectionChangeHandler);
      eventMap.mapListener(nav, NavButton.CLICK, navClickHandler);

      dispatch(new UserEvent(UserEvent.NAV_CLICK, model.defaultSection));
    }

    private function navClickHandler(event:Event):void
    {
      event.stopPropagation();
      var btn:NavButton = event.target as NavButton;

      if (!btn.isSelected)
        dispatch(new UserEvent(UserEvent.NAV_CLICK, btn.id));
    }

    private function sectionChangeHandler(event:SystemEvent):void
    {
      nav.update(model.currentSection);
    }
  }
}

7. The SectionSelectedCommand class

Earlier in ApplicationContext, we see that the SectionSelectedCommand is mapped to the UserEvent.NAV_CLICK event. It assigns the event’s id’s property to the currentSection property of the SiteModel instance.

package com.hubflanger.robotlegsdemo.controller
{
  import com.hubflanger.robotlegsdemo.model.SiteModel;
  import com.hubflanger.robotlegsdemo.events.UserEvent;

  import org.robotlegs.mvcs.Command;

  public class SectionSelectedCommand extends Command
  {
    [Inject]
    public var model:SiteModel;

    [Inject]
    public var event:UserEvent;

    override public function execute():void
    {
      model.currentSection = event.id;
    }
  }
}

8. SiteModel’s currentSection setter

In the currentSection setter, upon updating the value of the _currentSection variable, the Model dispatches a SystemEvent.SECTION_CHANGED framework event. This event announces to the application that the Model has been changed and the views will then respond accordingly by updating their display states.

public function set currentSection(value:String):void
{
  _currentSection = value;
  dispatch(new SystemEvent(SystemEvent.SECTION_CHANGED, false));
}

8. NavigationMediator’s sectionChangeHandler

The NavigationMediator’s sectionChangeHandler() responds to the SystemEvent.SECTION_CHANGED event by invoking the view component’s update() method passing along the Model’s currentSection property. This causes the NavButton instances to update their display states to reflect the section selected.

9. The SectionContainerMediator class

The SectionContainerMediator is set up in a fashion similar to NavigationMediator. Here, we override the onRegister() handler to invoke the init() method of the view component passing the sectionsHash property of the SiteModel instance. It also maps sectionChangeHandler() to handle the SystemEvent.SECTION_CHANGED framework event.

As in NavigationMediator, the sectionChangeHandler() invokes the update() method of the view container passing the currentSection property of the SiteModel instance. This causes the SectionContainer view component to update the display of its content according to the section selected.

package com.hubflanger.robotlegsdemo.view
{
  import com.hubflanger.robotlegsdemo.model.SiteModel;
  import com.hubflanger.robotlegsdemo.view.components.SectionContainer;
  import com.hubflanger.robotlegsdemo.events.SystemEvent;

  import org.robotlegs.mvcs.Mediator;

  public class SectionContainerMediator extends Mediator
  {
    [Inject]
    public var model:SiteModel;

    [Inject]
    public var container:SectionContainer;

    public function SectionContainerMediator()
    {
      //
    }

    override public function onRegister():void
    {
      container.init(model.sectionsHash);
      eventMap.mapListener(eventDispatcher, SystemEvent.SECTION_CHANGED, sectionChangeHandler);
    }

    private function sectionChangeHandler(event:SystemEvent):void
    {
      container.update(model.currentSection);
    }
  }
}

Conclusion

There you have it – a simple Robotlegs implementation in a nutshell. In addition to the features used in this demo, there are many more available to you which I have not mentioned. Please consult the Robotlegs documentation for more details.

As someone who has worked with PureMVC extensively, I find Robotlegs a joy to use. Its dependency injection solution is elegant and removes a lot of the clunkiness that one often has to deal with in PureMVC, such as casting your datatypes:

var proxy:MyProxy = facade.retrieveProxy( MyProxy.NAME ) as MyProxy;

Also, unlike PureMVC, all events are Flash Events and there isn’t the confusion of when one must use a Notification or an Event. Although in Robotlegs, one must still distinguish between framework events and user events dispatched by the view components, it’s much easier to grasp conceptually, in my opinion. That said, I highly recommend that you give Robotlegs a try.

1. Download tutorial files

To begin this tutorial, please make sure you have set up your workspace as suggested in Part 1.

View Demo

Download Source Files

2. Examine preloaderAsset.fla

The preloaderAsset.fla has in its library a movieclip symbol named preloader, linked to a class PreloaderAsset. Note that there is no physical Actionscript file named “PreloaderAsset.as”. This class will be created by the Flash compiler when we run the compilePreloaderSWC JSFL script.

3. Examine the compilePreloaderSWC JSFL

This script retrieves the preloader library symbol and exports it as a SWC to a designated location in your file system. Update the path for libs/PreloaderAsset.swc to reference your project directory.

fl.getDocumentDOM().library.selectItem("preloader", true, true);
var currentSelection = fl.getDocumentDOM().library.getSelectedItems();
currentSelection[0].exportSWC("file:///Users/peng/Workspace/FlexBuilder/Hubflanger/AS3_Ant_Tutorial_5/libs/PreloaderAsset.swc");

4. Examine the compilePreloaderSWC Task

The compilePreloaderSWC task invokes the compilePreloaderSWC.jsfl script and compiles a SWC named PreloaderAsset.swc into the libs folder of your project directory using the Flash IDE.

<target name="compilePreloaderSWC" description="Compile the Preloader SWC with the Flash IDE">
  <echo>Flash IDE Compiler for file ${preloaderFLA}</echo>
  <echo message="|*|*|*| class cache clear | source save | compiler start |*|*|*|"/>
  <exec executable="open">
    <arg line="${compilePreloaderSWC_jsfl} ${preloaderFLA}"/>
  </exec>
</target>

5. Examine Preloader.as

Add the SWC into your classpath using the project’s Properties->Actionscript Build Path->Library Path panel. With the SWC added to the library path, the Preloader class can now reference the PreloaderAsset class and create an instance of the PreloaderAsset object. This allows you to add the visual asset into your Preloader display container. The Preloader class also provides functionality to update the properties of the PreloaderAsset instance.

package
{
  import flash.display.*;
  import flash.events.*;
  import flash.text.*;

  public class Preloader extends Sprite
  {
    private var _asset:PreloaderAsset;

    public function Preloader()
    {
      _asset = new PreloaderAsset();
      addChild( _asset );
    }

    public function updateProgress( bytesLoaded:uint, bytesTotal:uint ):void
    {
      var ratio:Number = bytesLoaded / bytesTotal;
      _asset.bar.scaleX = ratio;
      _asset.progessTxt.text = bytesLoaded + " kb / " + bytesTotal + " kb";
    }
  }
}

6. Examine Demo5.as

The document class Demo5 creates a Preloader instance and a Loader instance to load an external SWF. It responds to load progress events from the Loader by and calling the updateProgress() method of the Preloader instance.

package
{
  import flash.net.URLRequest;
  import flash.display.*;
  import flash.events.*;

  import Preloader;

  public class Demo5 extends Sprite
  {
    private var preloader:Preloader;
    private var loader:Loader;

    public function Demo5()
    {
      preloader = new Preloader();
      preloader.x = 150;
      preloader.y = 150;
      addChild( preloader );

      loader = new Loader();
      loader.contentLoaderInfo.addEventListener( Event.COMPLETE, loadCompleteHandler );
      loader.contentLoaderInfo.addEventListener( ProgressEvent.PROGRESS, loadProgressHandler );
      loader.load( new URLRequest( "externalAssets.swf" ));
    }

    private function loadProgressHandler( evt:ProgressEvent ):void
    {
      preloader.updateProgress( evt.bytesLoaded, evt.bytesTotal );
    }

    private function loadCompleteHandler( evt:Event ):void
    {
      removeChild( preloader );
      evt.target.removeEventListener( Event.COMPLETE, loadCompleteHandler );
      evt.target.removeEventListener( ProgressEvent.PROGRESS, loadProgressHandler );
      addChild( loader );
    }
  }
}

7. Wrapping it all up

The compileMain task includes the PreloaderAsset.swc by adding it to the compiler’s library-path option. This option will merge all classes embedded in the SWC into your SWF.

<compiler .library-path dir="${LIB_DIR}" append="true">
  <include name="PreloaderAsset.swc" />
</compiler>

I hope you’ve found this series of tutorial helpful in optimizing your Flash-Actionscript development workflow. Please leave any requests and suggestions in the comments.

1. Download tutorial files

To begin this tutorial, please make sure you have set up your workspace as suggested in Part 1.

View Demo

Download Source Files

2. Examine assets.fla

We begin by dragging an instance of the Button UI Component from the Components Panel. This creates a Button symbol in the library. Note that the Button symbol is linked to the fl.controls.Button class. The Publish Settings of the FLA are set to compile the SWF to the ../libs/ directory. Under the Flash tab, note that the Export SWC option is checked. This causes the Flash compiler to output a companion SWC whenever a SWF is being published.

3. Examine compileAssetsSWC.jsfl

As in previous examples, the compileAssetsSWC.jsfl script opens the assets FLA and tells it to compile its SWF.

4. Examine the compileAssetsSWC task in build.xml

As in previous examples, the compileAssetsSWC task calls the compileAssetsSWC.jsfl script passing along a reference to the assets FLA. Run the task by double-clicking compileAssetsSWC in the Ant panel in Flex Builder. Due to the publish settings, an assets.swc file will be published to the libs folder along with assets.swf. We can ignore assets.swf as it won’t be needed for this tutorial.

<target name="compileAssetsSWC" description="Compile the assets SWC with the Flash IDE">
  <echo>Flash IDE Compiler for file ${assetsFLA}</echo>
  <echo message="|*|*|*| class cache clear | source save | compiler start |*|*|*|"/>
  <exec executable="open">
    <arg line="${compileAssetsSWC_jsfl} ${assetsFLA}"/>
  </exec>
</target>

5. Adding assets.swc to your Classpath

Add the assets SWC to your classpath as described in Step 5 of tutorial Part 4a.

6. Examine Demo4.as

In addition to Square instance, Demo4.as creates an instance of the Button component and adds it to the stage.

package
{
  import flash.display.*;
  import fl.controls.Button;

  public class Demo4 extends Sprite
  {
    private var square:Square;
    private var button:Button;

    public function Demo4()
    {
      square = new Square();
      square.x = 200;
      square.y = 100;
      addChild( square );

      button = new Button();
      button.x = 200;
      button.y = 250;
      addChild( button );
    }
  }
}

7. Adding assets.swc to the MXMLC compiler

As in Part 4a, we add a reference to assets.swc for the MXMLC compiler with the code snippet below, in build.xml. Run the compileProject task and load index.html in your web browser. You’ll see a green square and a Button component in your SWF.

<compiler.library-path dir="${LIB_DIR}" append="true">
  <include name="assets.swc" />
</compiler.library-path>

Coming up

In the next and final installment of this series of tutorials on Ant, we shall explore using a SWC to create a Preloader for your application.

In Part 4a, I shall show you how to compile a Flash library symbol as a SWC, add this SWC to your Actionscript classpath and compile your application with the Flex MXMLC compiler.

1. Download tutorial files

To begin this tutorial, please make sure you have set up your workspace as suggested in Part 1.

View Demo

Download Source Files

2. Examine assets.fla

In fla/assets.fla, you’ll find in the library, a simple square graphic linked to a class named Square.

3. Examine compileSquareSWC.jsfl

This JSFL script targets the square symbol in the library, and exports it as a SWC into the specified directory. In this case, my target output directory is file:///Users/peng/Workspace/FlexBuilder/Hubflanger/
AS3_Ant_Tutorial_4a/libs/. You should enter the correct path to the libs folder in your project.

fl.getDocumentDOM().library.selectItem("square", true, true);
var currentSelection = fl.getDocumentDOM().library.getSelectedItems();
currentSelection[0].exportSWC("file:///Users/peng/Workspace/FlexBuilder/Hubflanger/AS3_Ant_Tutorial_4a/libs/square.swc");

4. Examine the compileSquareSWC task in build.xml

The build file contains a task named compileSquareSWC which calls the compileSquareSWC.jsfl script passing along a reference to the assets FLA. Run the task by double-clicking compileSquareSWC in the Ant panel in Flex Builder. You’ll see that a SWC named square has been exported to the libs folder.

<target name="compileSquareSWC" description="Compile the square SWC with the Flash IDE">
  <echo>Flash IDE Compiler for file ${assetsFLA}</echo>
  <echo message="|*|*|*| class cache clear | source save | compiler start |*|*|*|"/>
  <exec executable="open">
    <arg line="${compileSquareSWC_jsfl} ${assetsFLA}"/>
  </exec>
</target>

5. Adding square.swc to your Classpath

Before you can create a reference to the Square class, you need to add the SWC to your classpath. To do so, first right-click on your project and open the Properties panel. In ActionScript Build Path, select the Library Path tab. Click the Add SWC button, navigate to the libs folder and select the square.swc file. Alternatively, you can click the Add SWC Folder button and select the libs folder. This will add all the SWCs in that folder to your classpath.

By adding the SWC to your classpath in Flex Builder, you’ll be able to reference the Square class in your Actionscript classes along with code completion.

6. Examine Demo4.as

Demo4.as creates an instance of the Square object and adds it to the stage.

package
{
  import flash.display.*;

  public class Demo4 extends Sprite
  {
    private var square:Square;

    public function Demo4()
    {
      square = new Square();
      square.x = 200;
      square.y = 100;
      addChild( square );
    }
  }
}

7. Adding square.swc to the MXMLC compiler

In order to compile the application, we also need to add a reference to square.swc for the MXMLC compiler. The code snippet below found in build.xml does just that. Run the compileMain task and load index.html in your web browser. You’ll see a green square in your SWF. Similar to Part 3, the compileProject task allows you to execute both compileMain and compileSquareSWC in sequence with a simple double-click.

<compiler.library-path dir="${LIB_DIR}" append="true">
  <include name="square.swc" />
</compiler.library-path>

Coming up

In Part 4b, we’ll see how we can compile Flash UI Components to a SWC and reference them in our Actionscript classes.

1. Download tutorial files

To begin this tutorial, please make sure you have set up your workspace as suggested in Part 1.

View Demo

Download Source Files

2. Examine externalAssets.fla

In fla/externalAssets.fla, you’ll find a bitmap image in the first frame of the main timeline. This FLA is set up to publish a SWF named externalAssets.swf into the bin-debug folder.

3. Examine compileSWF.jsfl

You’ll notice that this JSFL script is exactly the same as the one in Part 1. As we shall soon see, this script is completely reusable and we shall use it to compile the externalAssets.swf.

4. Examine the compileAssetsSWF task in build.xml

The build file contains a task named compileAssetsSWF which is similar to the task named compileMain previously mentioned Part 1 of this tutorial. It reuses the compileSWF.jsfl script to compile a SWF by passing in assetsFLA as its argument.

<target name="compileAssetsSWF" description="Compile the Assets SWF with the Flash IDE">
  <echo>Flash IDE Compiler for file ${assetsFLA}</echo>
  <echo message="|*|*|*| class cache clear | source save | compiler start |*|*|*|"/>
  <exec executable="open">
    <arg line="${compileSWF_jsfl} ${assetsFLA}"/>
  </exec>
</target>

5. Examine Demo3.as

Demo3.as creates a Loader instance which loads in an external SWF called externalAssets.swf. The loadCompleteHandler then adds the Loader instance onto the main stage.

package
{
  import flash.display.*;
  import flash.events.Event;
  import flash.net.URLRequest;

  public class Demo3 extends Sprite
  {
    private var loader:Loader;

    public function Demo3()
    {
      loader = new Loader();
      loader.contentLoaderInfo.addEventListener( Event.COMPLETE, loadCompleteHandler );
      loader.load( new URLRequest( "externalAssets.swf" ));
    }    

    private function loadCompleteHandler( evt:Event ):void
    {
      evt.target.removeEventListener( Event.COMPLETE, loadCompleteHandler );
      addChild( loader );
    }
  }
}

6. Examine the compileMain task in build.xml

We also have a compileMain task which is the same as the one in Part 2 except that it passes in Demo3.as as the argument to the MXMLC compiler.

<target name="compileMain">
  <echo>Compiles Demo3.as file and outputs demo3.swf</echo>
  <mxmlc file="${SRC_DIR}/Demo3.as" output="${DEPLOY_DIR}/demo3.swf"
    actionscript-file-encoding="UTF-8"
    incremental="false"
    debug="true"
    default-frame-rate="31"
    default-background-color="0xCCCCCC">

    <load-config filename="${FLEX_HOME}/frameworks/flex-config.xml"/>
    <source-path path-element="${FLEX_HOME}/frameworks"/>
    <source-path path-element="${SRC_DIR}" />

    <!-- Set size of output SWF file. -->
    <default-size width="550" height="400" />
  </mxmlc>
</target>

7. Examine the compileProject task in build.xml

Finally, we have a composite task named compileProject which allows you to execute its dependent tasks ie. compileMain and compileAssetsSWF in sequence with just a double-click.

<target name="compileProject" depends="compileAssetsSWF, compileMain" />

Coming up

As you can see, Ant tasks are highly flexible – allowing you to customize your workflow by combining varies different techniques, whether you prefer the Flash IDE or the MXMLC compiler. In Part 4, we shall discuss using Ant to compile SWCs and how to add SWCs to your workflow.

1. Download tutorial files

To begin this tutorial, please make sure you have set up your workspace as suggested in Part 1.

View Demo

Download Source Files

2. Examine Demo2.as

Demo2.as is exactly the same as Demo1.as in Part 1 of this tutorial. Except this time around, we do not have an FLA linked to Demo2 as its document class.

package
{
  import flash.display.Sprite;
  import flash.text.TextField;
  import flash.text.TextFormat;

  public class Demo2 extends Sprite
  {
    public function Demo2()
    {
      var format:TextFormat = new TextFormat();
      format.font = "Arial";
      format.size = 16;
      format.color = 0x000000;

      var label:TextField = new TextField();
      label.width = 500;
      label.defaultTextFormat = format;
      label.text = "Welcome to my ANT Demo!";
      label.x = 100;
      label.y = 150;
      addChild( label );
    }
  }
}

3. Examine build.xml

The compileMain task here launches the MXMLC compiler with the Demo2.as file as its argument and outputs demo2.swf.

<target name="compileMain">
  <echo>Compiles Demo2.as file and outputs demo2.swf</echo>
  <mxmlc file="${SRC_DIR}/Demo2.as" output="${DEPLOY_DIR}/demo2.swf"
    actionscript-file-encoding="UTF-8"
    incremental="false"
    debug="true"
    default-frame-rate="31"
    default-background-color="0xCCCCCC">

    <load-config filename="${FLEX_HOME}/frameworks/flex-config.xml"/>
    <source-path path-element="${FLEX_HOME}/frameworks"/>
    <source-path path-element="${SRC_DIR}" />

    <!-- Set size of output SWF file. -->
    <default-size width="550" height="400" />
  </mxmlc>
</target>

Coming up

This is a quick and painless one, isn’t it? In Part 3, we’ll use a combination of the MXMLC compiler and JSFL script to compile an external SWF which will be loaded into your main SWF.

Apache Ant is a software tool for automating software build processes implemented using the Java language. Ant uses XML to describe the build process and its dependencies, so no knowledge of Java is necessary for running Ant in your Flex Builder environment. By default the XML file is named build.xml.

In this series of tutorials, I will show you how to use Ant to create a workflow between the Flash IDE and Flex Builder. In Part 1 of this tutorial, we shall use Ant and JSFL to launch a FLA to publish a SWF.

JSFL is a Javascript-based scripting language for scripting the Flash IDE, allowing you to do things such as publish a SWF, etc. just by launching a script from the command line. Documentation for JSFL can be found here: http://livedocs.adobe.com/flash/9.0/main/flash_cs3_extending.pdf.

Combined with Ant, they provide a powerful toolset for the aspiring Flash/Actionscript developer.

1. Setting up your workspace

The standalone Flex Builder install is built on top of a stripped down version of Eclipse and does not come with built-in support for Ant. To get Ant support in the Flex Builder, follow the instructions in these tutorials:

http://www.peterelst.com/blog/2006/09/03/flex-builder-2-ant-support/

http://blog.jodybrewster.net/2008/04/09/installing-ant-in-flex-builder-3/

If you’re using FDT or the Flex Builder plug-in for Eclipse, the standard Eclipse install comes with built-in support for Ant, so you’re good to go.

2. Download tutorial files

This tutorial assumes a working knowledge of Flex Builder. You should already know how to create an Actionscript project in Flex Builder. The directory structure is set up like a typical project in Flex Builder, with bin-debug as the output folder, src containing the Actionscript files and fla containing the FLAs.

View Demo

Download Source Files

3. Examine demo1.fla

demo1.fla is a simple FLA which points to Demo1.as as its document class. It is set up to publish a SWF named demo1.swf to the bin-debug folder.

The Demo1 class creates a textField containing “Welcome to my Ant Demo!” and adds it to the stage.

4. Examine compileSWF.jsfl

The JSFL script for launching demo1.fla and publishing demo1.swf resides in the jsfl folder. It starts off by clearing the ASO cache and Flash IDE’s Output Panel. Then it saves the FLA and publishes the SWF.

function clearASOCache( path ) {
  if (!FLfile.exists( path )) {
    fl.trace( path + "does not exist" );
    return;
  }
  FLfile.remove( path );
}

clearASOCache ( fl.configURI + "Classes/aso" );
fl.outputPanel.clear();
fl.getDocumentDOM().save();
fl.getDocumentDOM().publish();

5. Examine build.xml

This Ant build file contains a couple of references to demo1.fla and compileSWF.jsfl named demoFLA and compileSWF_jsfl respectively. These properties provide shortcuts to commonly referenced resources in your project and allows you define them in a single convenient location.

The target named compileMain is the Ant task that calls the compileSWF_jsfl script, passing it the property demoFLA. The JSFL script then takes over by launching the FLA and compiling the SWF.

<project name="Flex Ant Tasks Demo1" default="compileMain" basedir=".">>
  <property name="demoFLA" value="fla/demo1.fla" />
  <property name="compileSWF_jsfl" value="jsfl/compileSWF.jsfl" />

  <!-- This task launches the compileSWF.jsfl script to compile demo1.swf using the Flash IDE -->
  <target name="compileMain" description="Compile the demo1 SWF with the Flash IDE">
    <echo>Flash IDE Compiler for file ${mainFLA}</echo>
    <echo message="|*|*|*| class cache clear | source save | compiler start |*|*|*|"/>
    <exec executable="open">
      <arg line="${compileSWF_jsfl} ${demoFLA}"/>
    </exec>
  </target>
</project>

6. Using the Outline Panel

Launch the Outline Panel by selecting Window->Other Views->General->Outline from the top menu. In the Outline Panel, you’ll be able to browse the list of properties and targets defined in your build file. Clicking an item in the list will cause the the editor jump to the line where that particular item is defined, making it quick and easy to navigate and edit an Ant build file (fig. 1).

7. Using the Ant Panel

Next, we launch the Ant Panel by selecting Window->Other Views->Ant->Ant in the top menu. To see the list of Ant tasks available within build.xml, just drag the file into the Ant Panel (fig. 2). Now, whenever you need to execute an Ant task, just double-click the task or right-click on it and select Run As->Ant Build.

That’s it. As you can see, it’s quite easy to get started with Ant. Even better, Ant is a tool that grows with your project, becoming more powerful and complex as your project demands it.

Before we proceed to the next part of this tutorial, I would like to thank the kind folks at the New York City Flash User Group, FlashCodersNY, for sharing their knowledge on Ant. This tutorial would not be possible without their generosity.

Coming up

In Part 2 of this tutorial, we shall use Flex Ant Tasks to compile a SWF with the MXMLC compiler.

Turns out that when the stage is initialized, its stageWidth and stageHeight properties are 0 until a Stage RESIZE event is triggered. This event is dispatched when the scaleMode property of the Stage object is set to StageScaleMode.NO_SCALE and the SWF file is resized ie. when the stage is rendered by the Flash Player. So if you need to add a display object onto the stage and its positioning is dependent on the stageWidth or stageHeight properties at runtime, it’s best handled by a listener that is subscribed to the Stage RESIZE event.

Interestingly, despite universal claim that the Flash Player behaves exactly the same on all browsers, this problem only appears in a couple of browser/plugin configurations, namely FireFox/OSX and IE/Win. And strangely, on Safari and Firefox/Win, the RESIZE event is not even dispatched on page load, and neither does the Flash Player register the stageWidth and stageHeight properties as being 0. I have not tested the problem on other platforms but you are certainly welcome to do so yourselves and report your observations in the comments section. Eventually, it would be nice if we can get a straight answer from Adobe concerning this bug.

In the following demo code, I’ve attached a Sprite containing a Rectangle graphic and a TextField, to the stage once before the RESIZE event and once, after. You can see the results here.

package
{
  import flash.text.*;
  import flash.display.*;
  import flash.events.*;

  public class Demo extends Sprite
  {
    private var rect1:Sprite;
    private var rect2:Sprite;

    public function Demo()
    {
      rect1 = createNewRect("Before stage resize event.");
      rect1.x = 0;
      rect1.y = 0;
      addChild(rect1);

      stage.scaleMode = StageScaleMode.NO_SCALE;
      stage.align = StageAlign.TOP_LEFT;
      stage.addEventListener(Event.RESIZE, resizeHandler);
    }

    private function createNewRect(str:String):Sprite
    {
      var rect:Sprite = new Sprite();
      rect.graphics.beginFill(0x99CCFF);
      rect.graphics.drawRect(0, 0, 200, 100);
      rect.graphics.endFill();

      var fmt:TextFormat = new TextFormat();
      fmt.font = "Arial";
      fmt.size = 12;

      var tf:TextField = new TextField();
      tf.width = 200;
      tf.height = 100;
      tf.multiline = true;
      tf.defaultTextFormat = fmt;
      tf.text = str + "\n" + "stage.stageWidth: " + stage.stageWidth + "\n" +
            "stage.stageHeight: " + stage.stageHeight;

      rect.addChild(tf);
      return rect;
    }

    private function resizeHandler( event:Event ):void
    {
      if (rect2 != null && contains(rect2)) {
        removeChild(rect2);
      }

      rect2 = createNewRect("After stage resize event.");
      rect2.x = (stage.stageWidth - rect2.width) / 2;
      rect2.y = (stage.stageHeight - rect2.height) / 2;
      addChild(rect2);
    }
  }
}

Before proceeding with this tutorial, I highly recommend that you to read the Adobe Flash Player 9 Security White Paper. This 51-page document, although thorough in many aspects, unfortunately left out crucial details that one would need in order to successfully perform cross-domain scripting. Another indispensable reference would be Colin Moock’s Essential ActionScript 3.0, in particular, Chapter 19 on Flash Player Security Restrictions and Chapter 28 on Loading External Display Assets.

Let’s get started!

In this tutorial, we will load a SWF named domainB.swf from the domain http://sub.hubflanger.com into a SWF named domainA.swf located at http://hubflanger.com. In the Adobe Flash Player 9 security sandbox, a subdomain is treated like any domain separate from its parent domain, so cross-domain security policies apply. Here, we shall assume that domainA.swf does not have access to any of domainB.swf’s classes during compilation.

View Demo

Download Source Files

1. Setting up your URL policy file

The URL policy file named crossdomain.xml is located, by default, in the root directory of the target server (http://sub.hubflanger.com). This policy file gives the parent SWF permission to load the child SWF.

<?xml version="1.0" encoding="UTF-8" ?>
<cross-domain-policy>
  <allow-access-from domain="*" />
</cross-domain-policy>

2. Examining domainB.fla

In domainB.fla, the document class is linked to the class com.hubflanger.crossdomain.DomainB. In the constructor of the DomainB class, the Security.allowDomain("*"); statement enables scripting of this SWF from another domain (in this case, “*” denotes any domain). The class also has a public method named sayHello() which we will call from domainA.swf when domainB.swf is loaded.

package com.hubflanger.crossdomain
{
  import flash.text.TextField;
  import flash.display.MovieClip;
  import flash.system.Security;

  public class DomainB extends MovieClip
  {
    public var myText1:TextField;

    public function DomainB()
    {
      Security.allowDomain("*");
    }

    public function sayHello( str:String ):void
    {
      myText1.text = str;
    }
  }
}

On the stage, a dynamic textField named myText1 will display a text string passed to the sayHello() method.

In the library panel, a symbol named innerClip is linked to the class com.hubflanger.crossdomain.InnerClip. The InnerClip class has a public method named sayHello() which we will call from domainA.swf as well.

package com.hubflanger.crossdomain
{
  import flash.text.TextField;
  import flash.display.MovieClip;

  public class InnerClip extends MovieClip
  {
    public var myText2:TextField;

    public function InnerClip()
    {
      //
    }

    public function sayInnerHello( str:String ):void
    {
      myText2.text = str;
    }
  }
}

The innerClip symbol also contains a dynamic textField myText2 which will display a text string passed to the sayInnerHello() method.

2. Examining domainA.fla

The domainA.fla is linked to the document class DomainA. To import domainB.swf’s classes into domainA.swf’s application domain at runtime, we use a LoaderContext object when issuing the request to load domainB.swf. This makes domainB.swf’s classes directly accessible to domainA.swf.

In the initHandler() listener, we reference the DomainB class by calling the getDefinition() method of the Loader’s applicationDomain property by passing in the classpath com.hubflanger.crossdomain.DomainB. We can then gain access to domainB.swf’s sayHello() method by casting the Loader’s content to the DomainB type.

Similarly, we gain a reference to the InnerClip class and then create an InnerClip instance via this reference. We then call the sayInnerHello() method belonging to this instance.

package
{
  import flash.display.*;
  import flash.net.*;
  import flash.events.*;
  import flash.system.*;

  public class DomainA extends MovieClip
  {
	private static const PACKAGE:String = "com.hubflanger.crossdomain.";

    public function DomainA()
    {
      var loader:Loader = new Loader();
      loader.contentLoaderInfo.addEventListener( Event.INIT, initHandler );
      loader.contentLoaderInfo.addEventListener( IOErrorEvent.IO_ERROR, ioErrorHandler );
      loader.contentLoaderInfo.addEventListener( SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler );
      addChild(loader);

      var loaderContext:LoaderContext = new LoaderContext( false, ApplicationDomain.currentDomain );
      loaderContext.applicationDomain =  ApplicationDomain.currentDomain;
      loader.load( new URLRequest( "http://sub.hubflanger.com/crossdomain/domainB.swf" ), loaderContext );
    }

    private function initHandler( evt:Event ):void
    {
      var packagePath:String = "com.hubflanger.crossdomain.";

      var appDomain:ApplicationDomain = evt.target.applicationDomain;

      var domainBRef:Class = appDomain.getDefinition( PACKAGE + "DomainB" )  as  Class;
      var domainB:Object = domainBRef( evt.target.content );
      domainB.sayHello( "Hello World!" );

      var innerClipRef:Class = appDomain.getDefinition( PACKAGE + "InnerClip" )  as  Class;
      var innerClip:Object = new innerClipRef();
      innerClip.sayInnerHello( "Inner clip says Hello!" );
      addChild( innerClip as MovieClip );
    }

    private function ioErrorHandler( e:IOErrorEvent ):void
    {
      trace( e.text );
    }

    private function securityErrorHandler( e:SecurityErrorEvent ):void
    {
      trace( e.text );
    }
  }
}

That’s it. I hope this tutorial helped to clarify the confusion surrounding the daunting task of Cross-Domain Scripting. Happy coding!

Well, I’m not here to make the case for using MVC but if you have spent enough time struggling with structuring an application so that it’s clearly represented by a set of well-defined relationships and responsibilities, you would’ve likely tried to implement some kind of MVC pattern. Now, some design pattern is certainly better none. Trouble is, every developer has his or her own approach to MVC. When a team of developers are working on the same project, things can get confusing pretty quickly if there are no common standards to adhere to.

This brings us to the PureMVC framework. Created by Cliff Hall, this framework provides a set of well-defined protocols for implementing the MVC design pattern with your application, rendering the grunt work of manually hooking up an MCV structure a thing of the past. However, great as PureMVC may be, it does not present an easy learning curve for some, especially those who are just getting started with OOP and design patterns.

In this tutorial, I will show you how to build a Flash site using PureMVC. If you’re familiar with the Flash IDE and have some experience with OOP and writing classes, you’re pretty much ready to go.

View Demo

Download Source Files

1. Creating the Flash assets

Open fla/PureMVCSite.fla in the Flash IDE. In the Library Panel, you’ll see that I have created various assets for our Flash site:

• A site movieclip that serves as a container clip with the UI elements laid out in the desired fashion
• A header movieclip containing a dynamic textfield for the site header
• A nav movieclip containing 3 navButton instances
• A body movieclip containing a dynamic multiline textfield for the body content

The site movieclip symbol is linked to the class Site. The nav movieclip symbol is linked to the class MainNav. Both these classes belong to the package com.hubflanger.puremvc.view.component. In the PureMVC world, these are known as “view components”, not to be confused with the built-in Flash components. These components communicate with the PureMVC framework via their associated Mediators, allowing them to be “loosely-coupled”, thereby granting you great flexibility in changing their behavior without impacting the rest of your application.

In the ActionScript 3.0 Setting of the Publish Settings, you’ll see that Classpath has been set to point to “../src“. This tells the Flash compiler that the as folder is where you’ll look for the class files for this application.

2. Examining the PureMVC package

The PureMVC package org.puremvc.as3 (version 2.0.3) is located at src/org/puremvc/as3 and has been included for your convenience. The AS3 port of the PureMVC framework is hosted here. I strongly encourage you to spend some time reading the online documentation if possible.

At any time during this tutorial, if you feel the need for a clearer understanding of PureMVC terminologies such as Mediator, Proxy or Notification, please feel free to refer to these classes. Cliff Hall has done an excellent job of commenting them and the comments will provide a clear picture of each class’ role in the framework.

3. Examining PureMVCSite.as and ApplicationFacade.as

The main timeline of PureMVCSite.fla is linked to the document class PureMVCSite which is initialized when the application starts. PureMVCSite.as resides at the root of the as folder. When the application launches, PureMVCSite creates a Singleton instance of ApplicationFacade. The ApplicationFacade is the entry point to the PureMVC framework. When you instantiate ApplicationFacade, a whole slew of events take place behind the scenes to wire up your application with the PureMVC framework.

package
{
  import com.hubflanger.puremvcsite.ApplicationFacade;
  import flash.display.Sprite;

  public class PureMVCSite extends Sprite
  {
    private var facade:ApplicationFacade;

    public function PureMVCSite()
    {
      facade = ApplicationFacade.getInstance();
      facade.startup( this.stage );
    }
  }
}

Let’s first examine the static constants defined at the beginning of this class. STARTUP, INITIALIZE_SITE and SECTION_CHANGED represent the Notification names of the events that our application will be responding to. A Notification is the default messaging deployed by PureMVC to inform the framework of an event that has been dispatched. In PureMVC land, sending a Notification is synonymous with broadcasting an event. Only difference is, it does a little more than just broadcasting it to everyone, whether they want to hear it or not. PureMVC finds the select audience who are “ticket holders” to an event, and drives them to the venue. I will explain this in greater detail later.

package com.hubflanger.puremvcsite
{
  import org.puremvc.as3.interfaces.IFacade;
  import org.puremvc.as3.patterns.facade.Facade;
  import com.hubflanger.puremvcsite.controller.StartupCommand;

  public class ApplicationFacade extends Facade implements IFacade
  {
    public static const STARTUP:String      = "startup";
    public static const INITIALIZE_SITE:String  = "initializeSite";
    public static const SECTION_CHANGED:String  = "sectionChanged";

    public static function getInstance() : ApplicationFacade
    {
      if ( instance == null ) instance = new ApplicationFacade();
      return instance as ApplicationFacade;
    }

    override protected function initializeController() : void
    {
      super.initializeController();
      registerCommand( STARTUP, StartupCommand );
    }

    public function startup( stage:Object ):void
    {
      sendNotification( STARTUP, stage );
    }
  }
}

ApplicationFacade overrides initializeController() to register StartupCommand with the STARTUP Notification. Behind the scenes, the Controller adds StartupCommand to its commandMap array and notes that StartupCommand is interested in listening for the STARTUP notification event.

The startup() method in ApplicationFacade is then explicitly called by PureMVCSite, passing in a reference to the Stage. This creates a Notification object with the name “startUp” and a reference to the Stage assigned to the its body property.

4. Examining StartupCommand.as

Upon receiving the Notification, the Controller iterates through its commandMap and retrieves StartupCommand as an object that is interested in the STARTUP notification. This results in the execute() method in StartupCommand being called.

package com.hubflanger.puremvcsite.controller
{
  import flash.display.Stage;
  import org.puremvc.as3.interfaces.ICommand;
  import org.puremvc.as3.interfaces.INotification;
  import org.puremvc.as3.patterns.command.SimpleCommand;
  import com.hubflanger.puremvcsite.ApplicationFacade;
  import com.hubflanger.puremvcsite.view.StageMediator;
  import com.hubflanger.puremvcsite.model.SiteDataProxy;

  public class StartupCommand extends SimpleCommand implements ICommand
  {
    override public function execute( note:INotification ) : void
    {
      var stage:Stage = note.getBody() as Stage;
      facade.registerMediator( new StageMediator( stage ) );
      facade.registerProxy( new SiteDataProxy() );
    }
  }
}

The execute() method in StartupCommand retrieves the reference to the Stage from the Notification and passes that along to an instance of the StageMediator being created. It also creates an instance of SiteDataProxy.

facade is a built-in property of the Mediator and Proxy base classes from which StageMediator and SiteDataProxy extends respectively. It refers to the ApplicationFacade instance which extends the Facade base class.

facade.registerMediator() registers the newly created Mediator instance with the View which stores it in its mediatorMap. The Mediator instance can be retrieved during runtime via a simple reference of its static NAME property using facade.retrieveMediator().

Similarly, facade.registerProxy() registers the newly created Proxy instance with the Model which stores it in its proxyMap. The Proxy instance can also be retrieved by passing its NAME property to the facade.retrieveProxy() method.

At this point, you’ll probably start to notice a pattern here. The Model, View and Controller all have methods and properties that mirror each other, tying the Proxy to the Model, the Mediator to the View and the Command to the Controller. You’ll also notice that the Facade indeed provides a “shortcut” to accessing various parts of your application within the PureMVC framework. Nobody talks to the Model, View or Controller directly. Everybody goes through the middle man named Facade.

5. Examining StageMediator.as

The StageMediator facilitates the communication between the Stage and the PureMVC framework. The Stage instance is referenced via the viewComponent property inherited from the Mediator base class. In PureMVC convention, it is also commonplace to create an accessor method such as “get stage()“. Two very important methods of the Mediator instance are the listNotificationInterests() method and the handleNotification() method, which every Mediator subclass must override.

listNotificationInterests() returns an array of Notification names as defined in ApplicationFacade, representing events that this particular Mediator is interested in. When the View runs through its list of Observers, it checks each Mediator against its Notification interests. If there is a match pertaining to a specific Notification, the handleNotification() method of that Mediator is called. This is what I was referring to earlier by the select audience who are “ticket holders” to an event. In this case, our StageMediator is interested in the INITIALIZE_SITE Notification.

The Mediator base class extends Notifier which means that in addition to responding to Notifications, it is also capable of sending out Notifications via the sendNotification() method. In other words, it can dispatch events. Although, unlike a MovieClip, it can’t dispatch any Flash Events, instead, it dispatches Notification objects.

package com.hubflanger.puremvcsite.view
{
  import com.hubflanger.puremvcsite.ApplicationFacade;
  import com.hubflanger.puremvcsite.view.component.Site;
  import flash.display.Stage;
  import flash.events.MouseEvent;
  import org.puremvc.as3.interfaces.*;
  import org.puremvc.as3.patterns.mediator.Mediator;

  public class StageMediator extends Mediator implements IMediator
  {
    public static const NAME:String = "StageMediator";

    public function StageMediator( viewComponent:Object )
    {
      super( NAME, viewComponent );
    }

    override public function listNotificationInterests():Array
    {
      return [
          ApplicationFacade.INITIALIZE_SITE
          ];
    }

    override public function handleNotification( note:INotification ):void
    {
      switch ( note.getName() )
      {
        case ApplicationFacade.INITIALIZE_SITE:
          initializeSite();
          break;
      }
    }

    private function initializeSite():void
    {
      var site:Site = new Site();
      facade.registerMediator( new SiteMediator( site ) );
      facade.registerMediator( new NavMediator( site.nav ) );
      stage.addChild( site );

      var navMediator:NavMediator = facade.retrieveMediator( NavMediator.NAME ) as NavMediator;
      sendNotification( ApplicationFacade.SECTION_CHANGED, navMediator.currentSection );
    }

    protected function get stage():Stage
    {
    return viewComponent as Stage;
    }
  }
}

6. Examining SiteDataProxy.as

SiteDataProxy represents the data model for the application. It loads in dynamic data via xml and then parses and stores that information in a built-in property named “data“. Like the Mediator, the Proxy object also extends Notifier which makes it capable of sending out Notifications via the sendNotification() method. Unlike the Mediator, the Proxy does not have Notification interests and one can and should only update the Proxy via a Command.

package com.hubflanger.puremvcsite.model
{
  import com.hubflanger.puremvcsite.ApplicationFacade;
  import flash.events.Event;
  import flash.net.URLLoader;
  import flash.net.URLRequest;
  import org.puremvc.as3.interfaces.IProxy;
  import org.puremvc.as3.patterns.proxy.Proxy;

  public class SiteDataProxy extends Proxy implements IProxy
  {
    public static const NAME:String = "SiteDataProxy";
    public var navIDs:Array;

    public function SiteDataProxy( )
    {
      super( NAME, new Object() );

      var loader:URLLoader = new URLLoader();
      loader.addEventListener( Event.COMPLETE, onDataLoaded );

      try {
        loader.load( new URLRequest( "data.xml" ));
      } catch ( error:Error ) {
        trace( "Unable to load requested document." );
      }
    }

    private function onDataLoaded( evt:Event ):void
    {
      var xml:XML = new XML( evt.target.data );
      xml.ignoreWhitespace = true;

      data.header = xml.header.children().toXMLString();

      var sections:XMLList = xml.sections.section;
      navIDs = new Array();

      for ( var i:uint=0; i<sections.length(); i++ )
      {
        var section:XML = sections[ i ];
        var id:String = section.@id;
        navIDs[ i ] = id;

        var vo:SectionVO = new SectionVO( id,
                          section.@label,
                          section.content );
        data[ id ] = vo;
      }

      sendNotification( ApplicationFacade.INITIALIZE_SITE );
    }
  }
}

When SiteDataProxy is done parsing the xml data, it sends out a INITIALIZE_SITE Notification, resulting in the handleNotification() method of StageMediator being called. This in turn calls the initializeSite() method which initializes the SiteMediator and NavMediator instances. These two Mediators serve to facilitate communication between the Site movieclip and the MainNav movieclip with the framework.

7. Examining SiteMediator.as

SiteMediator retrieves data from SiteDataProxy and calls site.init() to initialize the header text. It also declares an interest in the SECTION_CHANGED Notification event and calls site.updateBody() to update its content when such an event is dispatched.

package com.hubflanger.puremvcsite.view
{
  import com.hubflanger.puremvcsite.ApplicationFacade;
  import com.hubflanger.puremvcsite.model.*;
  import com.hubflanger.puremvcsite.view.component.Site;
  import org.puremvc.as3.interfaces.*;
  import org.puremvc.as3.patterns.mediator.Mediator;

  public class SiteMediator extends Mediator implements IMediator
  {
    public static const NAME:String = "SiteMediator";
    private var _siteDataProxy:SiteDataProxy;

    public function SiteMediator( viewComponent:Object )
    {
      super( NAME, viewComponent );

      _siteDataProxy = facade.retrieveProxy( SiteDataProxy.NAME ) as SiteDataProxy;
      var data:Object = _siteDataProxy.getData();
      site.init( data.header );
    }

    override public function listNotificationInterests():Array
    {
      return [
          ApplicationFacade.SECTION_CHANGED
          ];
    }

    override public function handleNotification( note:INotification ):void
    {
      switch ( note.getName() ) {
        case ApplicationFacade.SECTION_CHANGED:
          update( note.getBody() as String );
          break;
      }
    }

    private function update( s:String ):void
    {
      var data:Object = _siteDataProxy.getData();
      var vo:SectionVO = data[ s ];
      var content:XMLList = vo.content;

      site.updateBody( content.toXMLString() );
    }

    protected function get site():Site
    {
      return viewComponent as Site;
    }
  }
}

8. Examining NavMediator.as and MainNav.as

NavMediator retrieves navigation id and label info from SiteDataProxy and passes that along to the MainNav instance, allowing MainNav to initialize its navButton instances. MainNav registers itself as an event listener of MOUSE_DOWN events triggered by the navButton instances.

NavMediator in turn registers itself as an event listener of the NAV_BUTTON_PRESSED UIEvent bubbled up by the MainNav instance. Upon receiving such an event, NavMediator checks it against its currentSection variable to determine if a SECTION_CHANGED Notification should be sent.

When the SECTION_CHANGED Notification is sent, SiteMediator will respond and update the content in the body movieclip, and NavMediator will update its navButton instances to display the correct state depending on each button’s id.

package com.hubflanger.puremvcsite.view
{
  import com.hubflanger.puremvcsite.ApplicationFacade;
  import com.hubflanger.puremvcsite.model.*;
  import com.hubflanger.puremvcsite.view.component.MainNav;
  import com.hubflanger.puremvcsite.view.event.UIEvent;
  import org.puremvc.as3.interfaces.*;
  import org.puremvc.as3.patterns.mediator.Mediator;

  public class NavMediator extends Mediator implements IMediator
  {
    public static const NAME:String = "NavMediator";
    private var _siteDataProxy:SiteDataProxy;
    public var currentSection:String;

    public function NavMediator( viewComponent:Object )
    {
      super( NAME, viewComponent );

      _siteDataProxy = facade.retrieveProxy( SiteDataProxy.NAME ) as SiteDataProxy;
      nav.addEventListener( UIEvent.NAV_BUTTON_PRESSED, onNavButtonPressed );

      var data:Object = _siteDataProxy.getData();
      var navIDs:Array = _siteDataProxy.navIDs;
      var navLabels:Array = new Array();

      currentSection = navIDs[ 0 ];

      for ( var i:uint=0; i<navIDs.length; i++ )
      {
        var id:String = navIDs[ i ];
        var vo:SectionVO = data[ id ];
        navLabels[ id ] = vo.label;
      } 

      nav.init( navIDs, navLabels );
    }

    override public function listNotificationInterests():Array
    {
      return [
          ApplicationFacade.SECTION_CHANGED
          ];
    }

    override public function handleNotification( note:INotification ):void
    {
      switch ( note.getName() ) {

        case ApplicationFacade.SECTION_CHANGED:
          nav.update( note.getBody() as String );
          break;
      }
    }

    private function onNavButtonPressed( evt:UIEvent ):void
    {
      if ( evt.id != currentSection ) {
        currentSection = evt.id;
        sendNotification( ApplicationFacade.SECTION_CHANGED, evt.id );
      }
    }

    protected function get nav():MainNav
    {
      return viewComponent as MainNav;
    }
  }
}

package com.hubflanger.puremvcsite.view.component
{
  import com.hubflanger.puremvcsite.view.event.UIEvent;
  import flash.display.MovieClip;
  import flash.events.*;

  public class MainNav extends MovieClip
  {
    public var btn0:MovieClip;
    public var btn1:MovieClip;
    public var btn2:MovieClip;
    private var navButtons:Array;

    public function MainNav()
    {
      navButtons = [ btn0, btn1, btn2 ];
    }

    public function init( navIDs:Array, labels:Array ):void
    {
      for ( var i:uint=0; i<navIDs.length; i++ )
      {
        var id:String = navIDs[ i ];
        var btn:MovieClip = navButtons[ i ];
        btn.id = id;
        btn.txt.text = labels[ id ];
        btn.buttonMode = true;
        btn.mouseChildren = false;
        btn.addEventListener( MouseEvent.MOUSE_DOWN, onMouseDownHandler );
      }
    }

    public function update( s:String ):void
    {
      for ( var i:uint=0; i<navButtons.length; i++ )
      {
        var btn:MovieClip = navButtons[ i ];

        if ( btn.id == s ) {
          btn.txt.textColor = 0x4B1E18;
        } else {
          btn.txt.textColor = 0xFFFFFF;
        }
      }
    }

    private function onMouseDownHandler( evt:Event ):void
    {
      dispatchEvent( new UIEvent( UIEvent.NAV_BUTTON_PRESSED, evt.target.id ));
    }
  }
}

9. In Closing

This is pretty much the gist of what happens within a PureMVC Flash application. It is my hope that this real-world example will help you get a jump start on using the PureMVC framework for your Flash projects. I also hope this tutorial managed to demonstrate the value and power of the MVC design pattern. As you start developing applications of greater complexity, using a framework such as PureMVC will help immensely in keeping your classes loosely-coupled, and easier to scale and maintain. Happy coding!