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.