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!

Now, if you’re a fan of FDT, there’s no need to worry that you need to switch over to Flex Builder for your AS3 projects. The latest version of FDT (ver. 3), provides a way to compile your AS3 projects using the open source Flex SDK via the fcsh script. Instructions for doing so are available on the FDT forums. In this tutorial, I’m going to show you how to do so step-by-step.

1. Downloading and Installing the Flex SDK

• First you need to download and install a copy of the Flex SDK from Adobe.
• Unzip the archive and place the folder in a directory where its path contains no space. In OSX, I recommend using /usr/local/flex_sdk_3. In Windows, you may use C:\flex_sdk_3.

I also highly recommend creating a new Workspace for your AS3 projects if you haven’t done so already.

2. Set up Eclipse/FDT Preferences

• In Eclipse, open the Preferences panel.
• In the FDT->Core Libraries settings, select the AS3 Core Libraries tab.
• Click the Fast Add… button.
• In the Type drop-down menu, select Pure AS3 (Flex 3) and for the Path field, browse to the directory where you installed the Flex SDK. In my case, I use /usr/local/flex_sdk_3 (figure 1). Click OK.
• Back in the Preferences panel, make sure the Pure_AS3_Flex_3_0 core library is checked (figure 2). Click OK to exit the Preferences panel.

3. Creating a New AS3 Project

• In the Flash Explorer panel, right-click and select New->New Flash Project.
• In the New Project Wizard, make sure that in the Project Language settings, Action Script 3 is selected and set to Pure_AS3_Flex_3_0 in the drop-down menu (figure 3). Click Next.
• In the next window (figure 4), you will see that your project is automatically linked to playerglobal.swc in the Core Library. This SWC contains the Flash core library classes that you would need in order to compile an AS3 application. Click Finish.
• Next, create a source folder by right-clicking on your project and selecting New->Source Folder. Name this folder src and place it in the root of your project directory.
• Create your application (document) class by right-clicking on your project and selecting New->Class. Name your file MyApp.as and make sure that it extends flash.display.Sprite. Click Finish.
• Create a folder named build in the root of your project by right-clicking your project and selecting New->Folder. This will be the output folder for your SWF.
• In my example, I’ve typed in some code to draw a 100×100 red square graphic (figure 5).

4. Setting up your Run Configurations

• Right-click on the MyApp.as file and select Run As->Run Configurations…
• In the Run panel, with FDT AS3 Application selected, click the New icon to create a new configuration for your build setup.
• With the new configuration selected, in the Main tab, browse to your project MyAS3Project for the Project field, your class src/MyApp.as for the Main Class field and type in build/MyApp.swf for the Output field. Click Apply and then click Run. This will create a default SWF in the build folder (figure 6).
• In the Start SWF tab, check the Start SWF after compilation box and browse to build/MyApp.swf. This will allow FDT to auto-launch your SWF in the built-in SWF Viewer once it’s compiled (figure 7). Close the Run panel.

5. Compiling your SWF

• In the Flash Explorer panel, you may now compile your SWF by simply right-clicking on MyApp.as and selecting Run As->FDT AS3 Application.
• Select the SWF Viewer tab and review your SWF (figure 8).

Unlike Flex Builder, this build set up does not automatically create a html wrapper for your swf. You will have to create it yourself or use an ANT build script to automate that.

Migrating Existing AS3 Projects

If possible, change your Default Core Library to the Flex SDK as described in Section 2. This will globally set up your workspace to use the Flex SDK as the default compiler. If you do not wish to do so, you may still set it for each project by right-clicking your project and selecting Properties. Select FDT Source Folder and click the Change Core Library button to change the core library as you would in the Preferences panel (figure 9).

In addition to setting up your Run Configurations as mentioned above, also make sure that in the Flex SDK tab that the Use Default SDK radio button is checked and that its value is set to Pure_AS3_Flex_3_0 (figure 10).

Good luck and happy coding!