With the standard Robotlegs MVCS implementation you leverage the events provided by Actionscript 3 to communicate amongst the various actors of an application. From models and services dispatching notifications of their actions to triggering commands, events are a core piece of the implementation. To facilitate the use of Signals within MVCS it was necessary to create an extension to allow for Signals to be registered as Command triggers. This need spawned the SignalCommandMap utility.

The SignalCommandMap extends the normal MVCS context and creates a SignalContext. The SignalContext instantiates and provides access to the SignalCommandMap alongside the other maps that are standard to Robotlegs. The SignalCommandMap allows you to map Signal classes and instances to commands that will be executed when the Signal dispatch() method is called. The value objects that are passed in the dispatch are then injected into the command alongside any other mapped injections you have created.

Let’s take a look at a simple example that makes use of the SignalCommandMap and discuss some of the underlying code to see how it works:

Source available on Github (zip)

The example is a menu that allows you to add food which is displayed in a list. The total cost of your selected items is displayed and you can remove items from your order. First let’s get started by taking a look at the context of the Application, which extends SignalContext:

SignalCafeContext.as Bootstraps the Application

public class SignalCafeContext extends SignalContext
{
    override public function startup():void
    {
      injector.mapSingleton(FoodOrderModel);
      injector.mapSingleton(FoodOrderUpdated);
      injector.mapSingleton(FoodItemAddedToOrder);
 
      signalCommandMap.mapSignalClass(AddFoodItemToOrder, AddFoodItemToOrderCommand);
      signalCommandMap.mapSignalClass(FoodItemSelected, FoodItemSelectedCommand);
      signalCommandMap.mapSignalClass(RemoveAllOfSelectedItem, RemoveAllSelectedItemCommand);
      signalCommandMap.mapSignalClass(NoFoodItemSelected, NoFoodItemSelectedCommand);
 
      mediatorMap.mapView(FoodSelectionView, FoodSelectionViewMediator);
      mediatorMap.mapView(CurrentOrderView, CurrentOrderViewMediator);
      mediatorMap.mapView(FoodOrderSummaryView, FoodOrderSummaryViewMediator);
      mediatorMap.mapView(FoodItemRemovalView, FoodItemRemovalViewMediator);
    }
}

A SignalContext is structured exactly the same as a standard Robotlegs MVCS Context class. You override the startup() method and bootstrap your application. The major difference here is that you are mapping signals to commands instead of mapping events to commands. With the SignalCommandMap you are not restricted to just using Signals for triggering commands. You could mix events and Signals liberally as your needs or requirements dictated. As a warning, this could quickly became confusing and choosing one or the other might be a saner choice.

SignalCafeContext is mapping 4 Signals to 4 commands. The Signals are typed extensions of the base Signal class. This is necessary to provide Robotlegs (and more specifically in this case SwiftSuspenders) object types to differentiate for the purposes of injection. You could use named injections, but this would rapidly riddle your application with strings that would need to be laboriously checked for accuracy. Avoiding strings in favor of compiler-checked object types is always a good choice.

The strongly typed Signals are relatively simple. They contain a constructor and no additional methods or properties are added to the Signal. You can of course add properties and methods to the extended Signals,, but it wasn’t necessary for this example. The SignalCommandMap will accept any class that implements the ISignal interface. Let’s take a look at one of the commands triggered by a Signal mapped in the SignalCafeContext:

AddFoodItemToOrder.as triggers the AddFoodItemToOrderCommand

public class AddFoodItemToOrder extends Signal
{
	public function AddFoodItemToOrder()
	{
		super(FoodType);
	}
}

That is the whole of the extended Signal. As mentioned, it is not very complex at all. You will notice that super(FoodType) is being called. Signals take constructor arguments consisting of classes or interfaces that will be used as the value objects transmitted via the dispatch() method. In this case we are using FoodType as this value to ensure that our Signal will carry the payload that the mapped command is expecting.

Command signals are named a bit differently than standard reaction Signals. A Signal that is triggering a command is “requesting action” or specifying an action that needs to occur. Standard signals are typically past tense, or informative, describing an action that has occurred. By using this standard it is much easier to differentiate quickly what each Signal’s purpose is. This can help with overall clarity within your application.

The AddFoodItemToOrder signal is dispatched by the FoodSelectionViewMediator which is mediating the DropDownList of FoodTypes and the “Add Some Food” button:

FoodSelectionViewMediator.as mediates a view and dispatches a Signal when the user has clicked the “Add Some Food” button

	public class FoodSelectionViewMediator extends Mediator
	{
		[Inject]
		public var view:FoodSelectionView;
 
		[Inject]
		public var addItem:AddFoodItemToOrder;
 
		override public function onRegister():void
		{
			view.itemTypeAdded.add(handleItemTypeAdded);
		}
 
		protected function handleItemTypeAdded(itemType:FoodType):void
		{
			addItem.dispatch(itemType);
		}
	}

When the AddFoodItemToOrder Signal’s dispatch(aFoodTypeInstance) is called the AddFoodItemToOrderCommand is triggered:

AddFoodItemToOrderCommand.as is executed in response to AddFoodItemToOrder Signal dispatch

public class AddFoodItemToOrderCommand extends SignalCommand
{
	[Inject]
	public var itemType:FoodType;
 
	[Inject]
	public var model:FoodOrderModel;
 
	override public function execute():void
	{
		model.addItemToOrder(itemType);
	}
}

AddFoodItemToOrderCommand has two public properties that are marked for injection. The itemType property is a FoodType object. As you will recall, FoodType is the parameter that was passed to the AddFoodItemToOrder Signal super constructor. The AddFoodItemToOrder Signal dispatch() included an instance of a FoodType object which will be injected into the AddFoodItemToOrderCommand alongside any other injections that have been mapped and specified. In this case we are also injecting the FoodOrderModel instance that was mapped as a singleton in the SignalCafeContext.

The AddFoodItemToOrderCommand has a simple job. It accesses the FoodOrderModel instance and calls its addItemToOrder method adding the FoodType parameter that was dispatched with the Signal to trigger the command.

That covers the basics of using the SignalCommandMap within a Robotlegs application. There are options that this example doesn’t cover. I would recommend looking through the SignalCommandMap unit test suite for a thorough review of its capabilities. There are several more commands and Signals in the example for you to look over as well. Additionally the example uses Signals within views and the model to dispatch notifications. Outside of binding and UI events, no events are being passed within the application.

Hopefully this will give you the basic understanding of using the SignalCommandMap in a Robotlegs application. Let me know if you have any criticisms, comments, suggestions, or ideas regarding the utility’s implementation at http://knowledge.robotlegs.org

Related posts:

1. Robotlegs Image Gallery Example using AS3-Signals and the Presentation Model
2. Robotlegs AS3: A Dependency Injection Driven MVCS Framework for Flash/Flex – Inspired by PureMVC
3. Robotlegs IoC/DI Flex Framework Examples Updated

No related posts.

These conversations are always good natured. While we work on (or use) “competing” frameworks there is always a sense of mutual respect. We like our tools but have obvious inclinations towards the projects that we’ve invested our hearts and souls into.

Ben Clinkinbeard has pointed out (several times!) that Robotlegs is all about extending the MVCS classes. My stock answer is that there is a clear separation between the framework and the concrete MVCS implementation. To paraphrase Ben, “Well show it to me then!”

All of the “official” Robotlegs examples are making use of the MVCS implementation. Why? Because it is solid, recognizable, and fairly easy to get one’s head around. It provides a common ground for developers and a set architectural structure which is a huge advantage in any team environment. It is important to make the distinction between the framework and the MVCS implementation. What does that even mean? At the core, Robotlegs is a modular set of tools to provide a convenient mechanism for wiring applications. Robotlegs is not doing class reflection. Robotlegs is not an automated dependency injection solution. Robotlegs is an adapter to a dependency injection solution,by default the lightweight SwiftSuspenders library. Through a set of tools, namely the MediatorMap, CommandMap, ViewMap, and the injection adapter Robotlegs provides a robust starting place to begin coding your application.

The MVCS implementation is a set of base classes loosely modeled on PureMVC. At the heart of the implementation is the Context. The Context creates instances of the various mapping classes, the injection adapter, and gives the developer a centralized IEventDispatcher that can be used for messaging between application tiers.. The other three classes, Actor, Mediator, and Command, reduce boiler plate and provide convenient access to injected dependencies typically used in the the MVCS tiers.

What if you hate PureMVC, don’t want to extend any framework classes, or generally just want to work in a different way outside of a prescribed MVCS architecture?

No problem.

Here’s the deal. Robotlegs, the framework, is a set of interfaces. You can effectively do whatever you want with these interfaces. You can make use of the base concrete implementations of the core interfaces, use a class from the MVCS implementation, implement your own concrete classes based on the framework core, bring in other libraries or any combination you can think of. In terms of a framework, Robotlegs can be whatever you want/need it to be.

Man Joel, that was a long intro. Where’s the freaking code??!?

So, to that end, I sat down to rework my first (and still favorite) Robotlegs example application and demonstrate this concept a bit.

I’ve stripped the example down slightly, using just the XMLImageService and not connecting to Flickr (in an effort to keep it simple).

Get the source on GitHub
Download the full source as a Zip

This example requires:
Robotlegs
AS3-Signals
SignalsCommandMap library
Flex 4 SDK (a fairly recent version)

The example should be familiar if you’ve looked at the Image Gallery previously. It loads images from a service and displays them. This version is much different on the code level however. Instead of mediators and data models, the gallery is using presentation models and AS3-Signals. It still uses the Context from the MVCS implementation. it’s so f’n handy and I don’t want to manually instantiate the maps.

ImageGalleryContext

public class ImageGalleryContext extends Context
{
	private const VIEW_PACKAGE:String = "org.robotlegs.examples.imagegallery.view.components";
	private const LOAD_GALLERY:String = "loadGallery";
 
	override public function startup():void
	{
		//map the views
		viewMap.mapPackage(VIEW_PACKAGE);
 
		//map the presentation models
		injector.mapSingletonOf( IGalleryViewPresentationModel, GalleryViewPresentationModel );
		injector.mapSingletonOf( IGalleryThumbnailsPresentationModel, GalleryThumbnailsPresentationModel );
 
		//map the services and their factories
		injector.mapSingletonOf( IGalleryImageService, XMLImageService );
		injector.mapSingletonOf( IGalleryFactory, XMLGalleryFactory );
 
		//map the signals
		injector.mapSingleton(GalleryUpdatedSignal);
		injector.mapSingleton(GalleryImageSelectedSignal);
 
		//map the command
		commandMap.mapEvent( LOAD_GALLERY, LoadGalleryCommand );
 
		//go!!
		eventDispatcher.dispatchEvent(new Event(LOAD_GALLERY));
	}
}

As you can see here the context is performing the duty of mapping the injections the application will use.

Automated Dependency Injected View

<s:Group xmlns:fx="http://ns.adobe.com/mxml/2009" 
		 xmlns:s="library://ns.adobe.com/flex/spark" 
		 xmlns:mx="library://ns.adobe.com/flex/halo" width="100%" height="100">
	<fx:Script>
		<![CDATA[
			import org.robotlegs.examples.imagegallery.view.models.IGalleryThumbnailsPresentationModel;
 
			private var _model:IGalleryThumbnailsPresentationModel;
 
			public function get model():IGalleryThumbnailsPresentationModel
			{
				return _model;
			}
 
			[Inject]
			[Bindable]
			public function set model(value:IGalleryThumbnailsPresentationModel):void
			{
				_model = value;
			}
		]]>
	</fx:Script>
	<s:Rect width="100%"
			height="100%">
		<s:fill>
			<s:SolidColor color="#111111"/>
		</s:fill>
	</s:Rect>
	<s:Group width="100%" height="100%">
		<s:layout>
			<s:VerticalLayout gap="0"/>
		</s:layout>
		<s:DataGroup id="dgThumbnails"
					 clipAndEnableScrolling="true"
					 dataProvider="{model.dataProvider}"
					 width="100%"
					 height="85" 
					 itemRenderer="org.robotlegs.examples.imagegallery.view.components.renderers.GalleryImageThumbnailItemRenderer">
			<s:layout>
				<s:HorizontalLayout gap="0"/>
			</s:layout>
		</s:DataGroup>
		<s:HScrollBar id="thumbScrollBar"
					  viewport="{dgThumbnails}"
					  width="100%"
					  smoothScrolling="true"/>
	</s:Group>
</s:Group>

The viewMap is set to map the entire components folder. This is a convenient way to provide automated dependency injection to a large number of views. It also maps views in any sub-package of the mapped package.

GalleryViewThumbnailsPresentationModel

[Bindable]
public class GalleryThumbnailsPresentationModel implements IGalleryThumbnailsPresentationModel
{
	[Inject]
	public var updated:GalleryUpdatedSignal;
 
	[Inject]
	public var imageSelected:GalleryImageSelectedSignal;
 
	[PostConstruct]
	public function mapSignalListeners():void
	{
		updated.add(galleryUpdated);
		imageSelected.add(updateImageSelectionState);
	}
 
	private var _dataprovider:ArrayCollection;
 
	public function get dataProvider():ArrayCollection
	{
		return _dataprovider;
	}
 
	public function set dataProvider(v:ArrayCollection):void
	{
		_dataprovider = v;
	}
 
	private function galleryUpdated(gallery:Gallery):void
	{
		dataProvider = gallery.photos;
		if(gallery.photos[0])
		{
			imageSelected.dispatch(gallery.photos[0]);
		}
	}
 
	private function updateImageSelectionState(image:GalleryImage):void
	{
		for each(var galleryImage:GalleryImage in dataProvider)
		{
			galleryImage.selected = galleryImage == image;
		}
	}
}

IGalleryViewThumbnailsPresentationModel

/**
 * This interface is simple because the application is simple. Obviously in
 * a large application you'd get more complex interfaces. 
 */	
public interface IGalleryThumbnailsPresentationModel
{
	function get dataProvider():ArrayCollection;
}

The presentation models are provided as singletons. The application will only display one of each view that requires the model. They are also mapped as interfaces with the interfaces being injected into the views. With the presentation model, the view does not update the model directly. By using interfaces we can supply read-only contracts between the presentation models and the views they control:

XMLImageService

public class XMLImageService implements IGalleryImageService
{
	protected static const BASE_URL:String = "assets/gallery/";
 
	[Inject]
	public var galleryFactory:IGalleryFactory;
 
	[Inject]
	public var galleryUpdated:GalleryUpdatedSignal;
 
	public function XMLImageService()
	{
		super();
	}
 
	public function loadGallery():void
	{
		var service:HTTPService = new HTTPService();
		var responder:Responder = new Responder(handleServiceResult, handleServiceFault);
		var token:AsyncToken;
		service.resultFormat = "e4x";
		service.url = BASE_URL+"gallery.xml";
		token = service.send();
		token.addResponder(responder);
	}
 
	protected function handleServiceResult(event:Object):void
	{
		var gallery:Gallery = galleryFactory.createGallery(event.result.image, BASE_URL);
		galleryUpdated.dispatch( gallery );
	}
 
	protected function handleServiceFault(event:Object):void
	{
		trace(event);
 
	}
}

IGalleryImageService

public interface IGalleryImageService
{
	function loadGallery():void;
}

The service and its factory class are also mapped as singleton interfaces. This makes it really easy to swap out services (to add a Flickr service for example).

GalleryUpdatedSignal

public class GalleryUpdatedSignal extends Signal
{
	public function GalleryUpdatedSignal()
	{
		super(Gallery);
	}
}

The signals are simple classes that merely extend the Signal class and declare their payload type in the super() of the constructor. Signals are a really marvelous concept and provide a lot of very nice functionality. They make a great companion to Robotlegs and I think you will see some really cool stuff being done with Signals and Robotlegs in the very near future.

LoadGalleryCommand

public class LoadGalleryCommand
{
	[Inject]
	public var service:IGalleryImageService;
 
	public function execute():void
	{
		service.loadGallery();
	}
}

The application has a single command, LoadGalleryCommand, that is used to actually load the initial images from service and is only called once. In fact, the event that is fired to launch this command in the context startup method is the only event that this application uses (outside of the Flex events on the UI items). That is awesome!

Something you will notice right away looking at the source is that the ImageGalleryContext is the only class that extends a Robotlegs class. You could do without that too, frankly, and create your own context that created the maps and injector instances. I’m not a masochist however, and I will use the provided context for this example. There is a huge amount of potential there for implementing your own custom contexts. I think an interesting implementation might pitch Flash Events altogether and use only Signals for communication between application actors. This example is essentially doing that, but I’d like to get rid of that single event in startup too!

Download the full source as a Zip

Let me know if you make something cool with Robotlegs and post details about it, I’ve got a stack of these to give away:

Related posts:

1. Robotlegs, AS3-Signals and the SignalCommandMap Example
2. Robotlegs AS3: A Dependency Injection Driven MVCS Framework for Flash/Flex – Inspired by PureMVC
3. Continuous scrolling image thumbnail component for Flex.

I’ve finally found the opportunity to rewrite the continuous scrolling thumbnail view portion of the slideshow and I am much happier with the results. Now, instead of resembling an application it is structured like a standard Flex 3 List based component. You supply it with a dataProvider and an itemRenderer (IListItemRenderer) and it acts as you would expect it to.

This approach is much nicer, as the data is cleanly decoupled from the component implementation and it opens up the doors for reuse.

The code is available on Github. If you have any suggestions or would like to add to the component, fork it and let me know!

Related posts:

1. Continuous scrolling image thumbnail component for Flex.
2. Continuous scrolling image thumbnail and slideshow component for Flex.
3. Updated: Continuous scrolling image thumbnail and slideshow component for Flex.

Related posts:

1. Robotlegs IoC/DI Flex Framework Examples Updated
2. Robotlegs, AS3-Signals and the SignalCommandMap Example
3. Robotlegs AS3: A Dependency Injection Driven MVCS Framework for Flash/Flex – Inspired by PureMVC

Here is the “completed” project on Github.

This is a roughly 25 minute walkthrough of wiring together a Twitter client using the Robotlegs AS3 Micro-Architecture MVCS implementation. It covers setting up the context, using commands, mediating composite view component, granular view component mediation, and retrieving data from a service.

Apologies in advance for the ambient noise. 4 kids, 2 dogs, and a busy wife does not make the perfect sound booth

I am considering expanding on this example and creating a start to finish video series creating a full Twitter client with Robotlegs. This would cover the actual component building, wiring everything together, working with data models (local storage, etc), and refining the application to use the advanced features available with the Twitter API using TDD the whole time for development. Is this something that you’d be interested in?

Related posts:

1. Robotlegs AS3: A Dependency Injection Driven MVCS Framework for Flash/Flex – Inspired by PureMVC
2. Complex DataGrid filterFunction in Flex/Air
3. VEsession – Flex photography studio management and client ordering application

The solution was to simply skip the middle man and go at the database directly. Now it is lightening fast using this AMFPHP service endpoint:

<?php
class GalleryService
{
 
    function GalleryService()
    {
        $this->methodTable = array
        (
            "getAlbumById" => array
            (
                "access" => "remote",
                "description" => "Pings back a message"
            )
        );
    }
 
    function getAlbumById($albumNumber)
    {
		$dbhost = 'YOUR_MYSQL_HOST';
		$dbuser = 'YOUR_USER_NAME';
		$dbpass = 'YOUR_PASSWORD';
                $dbname = 'YOUR_SSP_DATABASE_NAME';
		$result_array = array();
		$conn = mysql_connect($dbhost, $dbuser, $dbpass) or die                      ('Error connecting to mysql');
 
		$dbname = 'slideshow';
		mysql_select_db($dbname);
                //be sure to guard against injection by casting the album id to int (thanks Shaun!)
		$query = "SELECT * FROM ssp_images WHERE aid=" . (int) $albumNumber;
 
		$result = mysql_query($query);
		while($row = mysql_fetch_array($result)){
			$result_array[] = 'YOUR_PATH_TO_SSP_ROOT/albums/album-' . $row['aid'] . '/lg/' . $row['src'];
		}
		mysql_close();
 
        return $result_array; //an array of url strings
    }
}
?>

There are all sorts of options you could do for this. You could set up value objects and send those back to Flash. All I needed for my purposes was the array of url strings. Simple, fast, and effective. Now we can manage our galleries with Director, and are free from the constraints of the official SlideshowPro for presentation.

What I really want is an official AMF service through Director. They are using CakePHP, and there are AMF solutions for that. Hopefully that would supply a fast, officially sanctioned AMF solution. Until than, the above works just fine.

No related posts.

Acme Widget Factory:
The Acme Widget Factory is modular example and deals with loading multiple modules into a shell and communicating between those modules. The shell and each module has its own context.

Lazy Stack:
Lazy Stack is an example of deferred instantiation of Flex components, and how this is handled by the Robotlegs framework.

Wheres Window:
Where’s Window is a simple example to show how to mediate and communicate between a set of instances of the same view component that have individual mediators. In this case, the view components are windows in an AIR application. This uses a proxy to register and manage the currently open unique windows. I am going to write a more detailed breakdown of this particular example soon.

The Elevator Pitch

Robotlegs is an IoC/DI container that is modeled on the PureMVC application structure. It is designed to be MVCS, model-view-controller-service, providing metadata dependency injection across these layers. While following the well organized approach of PureMVC, it eliminates the use of framework singletons and takes full advantage of the Flash Platform to keep the dreaded boiler plate code to a minimum. Eliminating these singletons makes unit testing and TDD much easier, which can be a real struggle when trying to isolate classes for testing where these singleton dependencies exist. Robotlegs is fast, clean, and perhaps more importantly fun to work with. There is a smorgasbord of architectural frameworks available for Flex/AS3, but Robotlegs is worth a look even if you are sick of looking at architectural frameworks.

Related posts:

1. FlexUnit – Some useful examples and tutorials covering unit testing in Flex and Actionscript 3.0
2. Unit Testing: IoC/DI, Robotlegs and FlexUnit 4
3. Flex – Preventing DataGrid scrolling when the dataprovider is updated.

In computer programming, unit testing is a software verification and validation method in which a programmer tests that individual units of source code are fit for use. A unit is the smallest testable part of an application. In procedural programming a unit may be an individual program, function, procedure, etc., while in object-oriented programming, the smallest unit is a class, which may belong to a base/super class, abstract class or derived/child class.

Ideally, each test case is independent from the others: substitutes like method stubs, mock objects, fakes and test harnesses can be used to assist testing a module in isolation. Unit tests are typically written and run by software developers to ensure that code meets its design and behaves as intended. Its implementation can vary from being very manual (pencil and paper) to being formalized as part of build automation. -wikipedia unit testing entry

To effectively unit test classes, we want them to be as isolated as possible. The class needs to stand on its own and have its functionality vetted to ensure that it behaves as expected. When we start to test how our classes behave together, we have entered the land of integration testing. Integration testing is a worthwhile pursuit also, but before we get to that point, we really want to ensure that our classes are solid by themselves.

Using the example in this Robotlegs Image Gallery demonstration, we are going to test a couple of the classes that make up the application. The demo isn’t complex. It has a very simple model, a single service, and just a few views. In fact, it might even seem like a waste of time to unit test a simple example such as this, but the concepts are applicable to larger applications where the benefits of this type of testing really start to pay off.

FlexUnit 4 is the framework that is used here. It provides very handy asynchronous testing, meta data support, and a whole bucket of stellar features that I won’t even begin to scratch the surface of. FlexUnit 4 also comes with a graphical testrunner interface:

On to the code…

full source is here…

This test runner interface is added to the RobotlegsImageGalleryTestRunner.mxml application:

<?xml version="1.0" encoding="utf-8"?>
<s:Application 
	xmlns:fx="http://ns.adobe.com/mxml/2009" 
	xmlns:s="library://ns.adobe.com/flex/spark" 
	xmlns:mx="library://ns.adobe.com/flex/halo" 
	xmlns:flexUnitUIRunner="http://www.adobe.com/2009/flexUnitUIRunner" 
	creationComplete="onCreationComplete()">
	<s:layout>
		<s:BasicLayout/>
	</s:layout>
	<fx:Script>
		<![CDATA[
			import org.robotlegs.demos.imagegallery.test.suites.RobotlegsImageGalleryTestSuite;
			import org.flexunit.listeners.UIListener;
			import org.flexunit.runner.FlexUnitCore;
 
			private var core:FlexUnitCore;
			private function onCreationComplete():void
			{
				this.core = new FlexUnitCore();
				core.addListener( new UIListener( uiListener ));	
				core.run( RobotlegsImageGalleryTestSuite )
			}
		]]>
	</fx:Script>
 
 
	<flexUnitUIRunner:TestRunnerBase id="uiListener" width="100%" height="100%"/>
</s:Application>

The core runs our test suites, in this case we are only running a single suite: the RobotlegsImageGalleryTestSuite. The test suite carries metadata that identifies it as a FlexUnit suite. There is no need to extend TestSuite as in previous version of FlexUnit:

package org.robotlegs.demos.imagegallery.test.suites
{
	import org.robotlegs.demos.imagegallery.test.cases.TestFlickrService;
	import org.robotlegs.demos.imagegallery.test.cases.TestGalleryProxy;
 
	[Suite]
	[RunWith("org.flexunit.runners.Suite")]
	public class RobotlegsImageGalleryTestSuite
	{
		public var testFlickrService:TestFlickrService;
		public var testGalleryProxy:TestGalleryProxy;
	}
}

The suite further defines the test cases that we are going to run, TestFlickrService and TestGalleryProxy. Any other test cases would also be included in this suite. TestFlickrService extends the Robotlegs Service class. It makes an asyncronous call to the Flickr API and retrieves images via the ‘interestingness’ category, as well as through a text search. The Service class has a dependency that is injected by the framework on its eventBroadcaster property. EventBroadcaster simply wraps an event dispatcher to provide a simplified interface for the framework to access. Service also provides a dispatch(event) convenience method for sending event notifications to the framework context. Our tests are not run within this context, however, so we have run into a problem. Since the framework injects the EventDispatcher into the EventBroadcaster automatically, we apparently have no way to access it and we can’t receive framework notifications.

As it happens, we can simply inject our dependencies manually. The TestFlickrService case has a serviceDispatcher property that extends EventDispatcher. In our setUp() method that is called prior to every test, we create a new EventBroadcaster (which takes our serviceDispatcher as an argument) and add it to our fresh FlickrImageService instance. Now the test case has access to the injected dispatcher, and we can listen for our normal flash events that Robotlegs uses for notifications.

package org.robotlegs.demos.imagegallery.test.cases
{
	import flash.events.EventDispatcher;
 
	import org.flexunit.Assert;
	import org.flexunit.async.Async;
	import org.robotlegs.demos.imagegallery.events.GalleryEvent;
	import org.robotlegs.demos.imagegallery.remote.services.FlickrImageService;
	import org.robotlegs.mvcs.EventBroadcaster;
 
	public class TestFlickrService
	{
		private var service:FlickrImageService;
		private var serviceDispatcher:EventDispatcher = new EventDispatcher();
 
		[Before]
		public function setUp():void
		{
			serviceDispatcher = new EventDispatcher();
			service = new FlickrImageService();
			service.eventBroadcaster = new EventBroadcaster(this.serviceDispatcher);;
		}
 
		[After]
		public function tearDown():void
		{
			this.serviceDispatcher = null;
			this.service.eventBroadcaster = null;
			this.service = null;
		}
 
		[Test(async)]
		public function testRetreiveImages():void
		{
			this.serviceDispatcher.addEventListener( GalleryEvent.GALLERY_LOADED, Async.asyncHandler(this, handleImagesReceived, 3000, null, handleServiceTimeout), false, 0, true);
			this.service.loadGallery();
		}
 
		[Test(async)]
		public function testSearchImages():void
		{
			this.serviceDispatcher.addEventListener( GalleryEvent.GALLERY_LOADED, Async.asyncHandler(this, handleImagesReceived, 3000, null, handleServiceTimeout), false, 0, true);
			this.service.search("robotlegs");
		}
 
		protected function handleServiceTimeout( object:Object ):void
		{
	    	        Assert.fail('Pending Event Never Occurred');
		}
 
		protected function handleImagesReceived(event:GalleryEvent, object:Object):void
		{
			Assert.assertEquals("The gallery should have some photos: ", event.gallery.photos.length > 0, true)	
		}
 
 
	}
}

After each test is run, our tearDown method is called by FlexUnit which sets our service and its eventBroadcaster to null in preparation for the next test in this case to be run. While this example isn’t very complex, it is easy to see how this could be extended to a much more complicated service.

The GalleryProxy class is tested in much the same way, though it doesn’t have any async methods:

package org.robotlegs.demos.imagegallery.test.cases
{
	import org.flexunit.Assert;
	import org.robotlegs.demos.imagegallery.models.proxies.GalleryProxy;
	import org.robotlegs.demos.imagegallery.models.vo.Gallery;
	import org.robotlegs.demos.imagegallery.models.vo.GalleryImage;
 
	public class TestGalleryProxy
	{
		private var galleryProxy:GalleryProxy;
 
		[Before]
		public function setUp():void
		{
			this.galleryProxy = new GalleryProxy()
		}
 
		[After]
		public function tearDown():void
		{
			this.galleryProxy = null;
		}
 
		[Test]
		public function testSetGallery():void
		{
			var gallery:Gallery = new Gallery();
			this.galleryProxy.gallery = gallery;
			Assert.assertEquals("GalleryProxy should have a gallery", this.galleryProxy.gallery != null, true );
		}
 
		[Test]
		public function testSetSelectedImage():void
		{
			var image1:GalleryImage = new GalleryImage()
			var image2:GalleryImage = new GalleryImage()
			var gallery:Gallery = new Gallery()
			this.galleryProxy.gallery = gallery;
			gallery.photos.addItem(image1);
			gallery.photos.addItem(image2);
			image1.selected = false;
			image2.selected = true;
			this.galleryProxy.setSelectedImage(image1);
			Assert.assertEquals("Image1 should be selected", image1.selected, true);
			Assert.assertEquals("Image 2 should NOT be selected", image2.selected, false);
		}
	}
}

With these simple tests we are 100% certain that our classes function as expected on their own, completely isolated from the rest of the application.

You really should call your mom…

We are all unit testing our code and following strong Agile/TDD processes, right…. right? I don’t know how much unit testing is going on in the Flash/Flex world, but my guess that the overall test coverage percentage is very small. RIAs are here. They are becoming full fledged applications that people rely on to do business. There will come a time in your RIAs life that you will need to get in there and do some refactoring. It might be for performance, fixing bugs, or adding some new kickass feature to push your app to the next level. Fact, without unit testing:

you’re not refactoring; you’re just changing shit. -Hamlet D’Arcy

There are many, many arguments for unit testing your code, but for me this is the most compelling. At some point in the future, you are going to want to get in there and make some changes. If your application is important to your users, you want to make sure those changes don’t break everything. It is guaranteed that they will break something, the question is will you know immediately what happened, or at least where to look?

We are getting the proper tools for the job. FlexUnit 4 is an incredible project. There is a robust selection of frameworks that all have merits and can facilitate structured, well designed applications. I’m personally out of excuses. I want to develop applications that my users can trust and rely on to do business, and unit testing is a part of that recipe.

Related posts:

1. FlexUnit – Some useful examples and tutorials covering unit testing in Flex and Actionscript 3.0
2. Robotlegs IoC/DI Flex Framework Examples Updated
3. Robotlegs AS3: A Dependency Injection Driven MVCS Framework for Flash/Flex – Inspired by PureMVC

robotlegs best practices

The quest for a Dependency Injection container continues. The most recent stop on this exploration of the available options has been Robotlegs. Robotlegs AS3 is a DI driven MVCS framework for Flash/Flex inspired by PureMVC. Being a huge fan of PureMVC, this caught my attention immediately. Robotlegs professes to be a framework like PureMVC, but without all the Singeltons, Service Locators, casting and boiler plate we have all come to love. Better yet, it delivers on these claims.

Source for this demo available on github…

Brief Code Walkthrough

I’m using the same gallery example I used for Parsley, with some enhancements. The basic structure is like a typical PureMVC application. We’ve divided our packages up into model, view, controller, and events. Instead of extending Facade to bootstrap our application we need to instantiate a Context in our Applications main mxml/as file:

import com.joelhooks.robotlegs.demos.imagegallery.ImageGalleryContext;
import mx.events.FlexEvent;
 
private var galleryContext:ImageGalleryContext;
 
protected function creationCompleteHandler(event:FlexEvent):void
{
	this.galleryContext = new ImageGalleryContext( this );
}

The Context defines which IoC adapter to use (currently SmartyPants-IoC is the only available adapter, but a SpringAS adapter is in the works). It also fires its startup method which registers a series of commands and dispatches a Startup event.

The Context for the application defines a series of Commands to fire in sequence to get the application

public class ImageGalleryContext extends Context
{
	public function ImageGalleryContext(contextView:DisplayObjectContainer)
	{
		super( contextView, new SmartyPantsInjector(), new SmartyPantsReflector() );
		// Keep SmartyPants quiet
		NoSmartyPantsLogging;
	}
 
	override public function startup():void
	{
		// Map our startup commands
		commandFactory.mapCommand( ContextEvent.STARTUP, PrepModelCommand, true );
		commandFactory.mapCommand( ContextEvent.STARTUP, PrepServicesCommand, true );
		commandFactory.mapCommand( ContextEvent.STARTUP, PrepViewCommand, true );
		commandFactory.mapCommand( ContextEvent.STARTUP, StartupCommand, true );
		// And away we go!
		eventBroadcaster.dispatchEvent( new ContextEvent( ContextEvent.STARTUP ) );
	}
}

These Commands are very similar to PureMVC commands. The Startup commands are used to define the initial injected classes and relationships between view components and their mediators.

Mediation is particularly sweet with Robotlegs. Once a view component has been associated with a mediator, it will be registered automatically:

mediatorFactory.mapMediator( GalleryView, GalleryViewMediator );

avoiding the need for facade.registerMediator… as well as skipping around the deferred instantiation/lifecycle issues that plague Flex applications. because we are injecting into our mediators, there is no need to have the mediator ask for its dependencies. We tell it what it needs and it does its work with what it is provided:

public class GalleryViewMediator extends Mediator
{
	[Inject]
	public var galleryView:GalleryView;
 
	[Inject]
	public var galleryProxy:GalleryProxy;
 
	[Inject]
	public var imageService:IGalleryImageServiceDelegate;

Mediating view components is hands down my favorite aspect of PureMVC, and Robotlegs enhances that pattern by removing the egregious boiler plate. It allows my view components to be completely isolated and ignorant of the surrounding framework. I don’t want to inject data directly into the components or bind them to the Model. They need to display information to and collect input from the user.

Robotlegs has eliminated the Notifications of PureMVC, using AS3 events instead. Most of the current crop of IoC containers for Actionscript do this also, but Robotlegs has avoided using the Display List as the Event Bus or requiring a central Event Map. This is huge. There are no confusing issues with bubbling, or the need to pass around a reference to THE view component.

from the GalleryViewMediator.as:

override public function onRegisterComplete():void
{
	addEventListenerTo( galleryView, GalleryImageEvent.SELECT_GALLERY_IMAGE, onImageSelected )
	addEventListenerTo( eventDispatcher, GalleryEvent.GALLERY_LOADED, onGalleryLoaded )
	this.imageService.loadGallery();
}

The core Robotlegs classes have an eventDispatcher that is the central event management aperatus. You then dispatch events using the dispatch() method on Proxy, Mediator, and Command classes and any interested party will respond.

ANOTHER micro-architecture framework?!

Well, yes. Shaun makes several compelling arguments for pursuing another framework. I personally like options. A full toolbox. The landscape of AS3/Flex frameworks is looking mighty fine, with players to suit almost any style and approach. Instead of griping about the deficits in the available architectural frameworks, he’s made an attempt to bring the good parts of the available frameworks together while eliminating the various anti-patterns that caused him grief.

I haven’t made much of an effort to conceal the fact that I am very much a PureMVC fan boy. I like the structure, I like mediating my views as a mechanism for separation of responsibilities, and cliff Hall is one helluva guy. This isn’t to say that PureMVC doesn’t have its faults. The 4 Singletons that comprise the heart of the System, namely Facade, Model, View and Controller make for some difficult testing. The boiler plate is tedious, though at this point I just blindly type it, use a generator, or use TextExpander. None of these have been deal breakers for me, and I have worked on half a dozen large scale production projects with PureMVC. All of them have been succesful, scaled well, and were easy to manage from a development perspective.

That said, given the opportunity to eliminate the drawbacks of PureMVC, while still retaining the scalability and general workflow, I am all over it.

Sounds great, what’s the catch?

Robotlegs actively defines a PureMVC style MVC structure to your application. You are extending framework classes with your actors instead of using plain-old-actionscript objects. Other frameworks avoid this, but at the cost of convenience in a lot of cases. If you like the PureMVC structure, this isn’t going to be a big deal. If you hate it, you might hate Robotlegs (but should give it a try anyway). Robotlegs has done a great job of reducing the pain involved by addressing the major complaints that I’ve seen publicly in various critiques of PureMVC.

Robotlegs is still very young and hasn’t been thoroughly peer reviewed. My guess is that you will start to hear more about this framework soon. It is already kickass, even at this early stage. Certainly one to keep your eye on.

Resources:
Robolegs Google Group
Robolegs Screencasts
Robolegs Source

Related posts:

1. Inversion of Control and Dependency Injection with Flex using the Parsley Application Framework – Part 2
2. Renju – AS3 board game built with the PureMVC framework.
3. Inversion of Control and Dependency Injection in Flex using the Parsley Application Framework – Part 1