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.

1. Download Source Code

Download the source files for this tutorial here.

2. 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 “../as“. This tells the Flash compiler that the src/as folder is where you’ll look for the class files for this application.

3. Examining the PureMVC package

The PureMVC package org.puremvc.as3 (version 2.0.3) is located at src/as/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.

4. 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.

5. 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.

6. 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;
    }
  }
}

7. 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 = "SpriteDataProxy";
    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.

8. 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;
    }
  }
}

9. 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 ));
    }
  }
}

10. 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!

The first 3 articles are:

Why PureMVC Kicks Ass
How to Setup Your First PureMVC Application
Reusable Components using PureMVC

In five lessons, Tucker leads the student from setting up the ModelLocator, Events, Commands and Controller classes, to using Business Delegates and Value Objects in the Service-to-Worker design pattern, finally ending with Best Practices. Each tutorial begins with some theory and explanations, then quickly segues to a hands-on video tutorial which demonstrates in great detail how all this is put together.

Apart from being unsuccessful in getting Coldfusion 8 to run on Leopard, which is a whole other issue completely (hello, Adobe?), these tutorials proved to be immensely helpful in getting me acquainted with the Cairngorm framework.

Check it out at http://www.davidtucker.net/category/cairngorm/.

While I personally have never been able to make the configuration files work in the user directory, I’ve had success setting my environment paths in /etc/.profile. However, along with many other components that got shuffled around in the latest release of OSX, those profile settings are no longer found in the same locations. Oh why o why, Apple?

In Leopard, the road to setting environment paths is a rather convoluted one. I wish Apple had made it easier but to date, I haven’t come across any other simpler solution. Here are the few steps that I took to resolve the issue:

1. If you open /etc/.profile in a text editor, you’d see that the Terminal now loads the environment paths via a configuration file in /usr/libexec/path_helper.
2. Opening the path_helper file reveals that environment paths are now collectively stored in a file aptly named paths in the etc directory. Open /etc/paths and you’d see that all the environment paths are neatly listed here. You can simply add your desired paths such as /usr/local/mysql/bin to this list.
3. Relaunch the Terminal and test.

Please note that root user needs to be enabled in order for you to edit the /etc/paths file. To enable the root user, see this article.

Total Training™ for Adobe® Flex 2: Rich Internet Applications
by James Talbot and

Total Training™ for Adobe® Flex 2: Advanced Visual Programming
by Leo Schuman.

The tutorials are presented at a brisk pace and provide a highly immersive experience as you follow along and learn to build your own applications. Highly recommended for Flash/Actionscript developers looking to learn Flex.

Download the latest Flash Player update and check out this sample video which my friend Colin has kindly uploaded.

Download and install the latest Flash Player 9 debugger version (9.0.r47).

Install the Flash Tracer extension for Firefox.

In the Preference settings for Flash Tracer, set the path to your flashlog:
Macintosh HD:Users:YourUserName:Library:Preferences:Macromedia:Flash Player:Logs:flashlog.txt

In XP, you’d find flashlog.txt here:
C:\Documents and Settings\YourUserName\Application Data\Macromedia\Flash Player\Logs\flashlog.txt

Fire up Flash Tracer from the Tools menu in Firefox.

Go to Adobe’s home page and voila! Enjoy the debugger in its full glory!

You wouldn’t think that Adobe’s developers would be so careless to leave their trace statements running in their published files, but I guess they’re only human like the rest of us.

If you are intent on trying out the AS3 Preview on an Intel-Mac, there are ways of getting around the problem such as installing the PC version on your Parallels-Windows VM or Bootcamp-Windows. Or you may just decide to stick with Flex Builder 2 for now, which is exactly what I’m going to do.