direct link to the video (42mb QT)

Resources

IntelliJ IDEA EAP Download Page
Jesse Freeman's IDEA Workflow series on InsideRIA

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

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

1
2
3
4
5
6
7

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

	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

1
2
3
4
5
6
7
8
9
10
11
12
13

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

<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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

[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

1
2
3
4
5
6
7
8

/**
 * 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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

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

1
2
3
4

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

1
2
3
4
5
6
7

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

1
2
3
4
5
6
7
8
9
10

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:

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!

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?

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.

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

<?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:

1
2
3
4
5
6
7
8
9
10
11
12
13

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

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.

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:

1
2
3
4
5
6
7
8
9

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

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:

1

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:

1
2
3
4
5
6
7
8
9
10

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:

1
2
3
4
5
6

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

Here's the source on github...

Less talk. More Code.

One aspect of an IoC/DI container that is consistent across frameworks is the need to bootstrap the configuration. Parsley provides several ways to accomplish this.

from the docs:

Configuring and initializing the Parsley Framework usually consists of the following steps:

Step 1: Telling the IOC Container which classes it should manage. This can be done with MXML, XML files or in ActionScript. All three mechanisms will be described in the following sections.

Step 2: Configure the container services like Dependency Injection or Messaging for each individual class. This can be done with the mechanism you had chosen for step 1 (e.g. with MXML or XML configuration tags) or - in most cases - conveniently with AS3 Metadata Tags right within the classes themselves.

Step 3: Initialize the IOC Container (usually on application startup). In Parsley 2 this is a one-liner in most cases. See the sections below for examples.

In the image gallery sample step one is accomplished in Beans.mxml. Beans is, I assume, a throwback to Java that I don't fully understand, but it seems to be a popular convention and I'm not here to rock the boat.

Beans.mxml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

<?xml version="1.0" encoding="utf-8"?>
<!--
	Inversion of Control/Dependency Injection Using Parsley
	Image Gallery
 
	Any portion of this demonstration may be reused for any purpose where not
	licensed by another party restricting such use. Please leave the credits intact.
 
	Joel Hooks
	http://joelhooks.com
	joelhooks@gmail.com
-->
<mx:Object
    xmlns:mx="http://www.adobe.com/2006/mxml"
    xmlns="http://www.spicefactory.org/parsley"
    xmlns:models="com.joelhooks.parsley.example.models.*"
    xmlns:controllers="com.joelhooks.parsley.example.controllers.*"
    xmlns:presentation="com.joelhooks.parsley.example.models.presentation.*">
 
    <mx:Script>
    	<![CDATA[
    		import com.joelhooks.parsley.example.delegates.FlickrImageServiceDelegate;
    	]]>
    </mx:Script>
 
    <!-- Service Delegate -->
    <object id="photoServiceDelegate" type="{FlickrImageServiceDelegate}">
    	<property name="apiKey" value="YOUR_KEY_HERE"/>
    	<property name="secret" value="YOUR_SECRET_HERE"/>
    </object>
 
    <!-- Model -->
    <presentation:FlickrGalleryPresentationModel id="galleryPresentationModel"/>
 
    <!-- Actions -->
    <controllers:RetrieveGalleryAction />
    <controllers:DisplayGalleryAction />
    <controllers:SelectImageAction />
 
</mx:Object>

The application has several actors that Parsley needs to be aware of, and this is where you let the container know what they are. In most cases we can simple use MXML notation to include our classes in the configuration. The photo service, in this case Flickr, needs additional configuration so it is added a bit differently utilizing the Parsley Object and Property tags. When using this method the class needs to be imported as above to provide a reference. In addition to the service the presentation model is also added to the configuration, as well as several actions that will react to various events. The Model and Controller of the MVC triad are what we are configuring here. The View is handled a bit differently.

The configuration is loaded in the preinitialize handle of the main application MXML.

ParsleyGallery.mxml:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

<?xml version="1.0" encoding="utf-8"?>
<!--
	Inversion of Control/Dependency Injection Using Parsley
	Image Gallery
 
	Any portion of this demonstration may be reused for any purpose where not
	licensed by another party restricting such use. Please leave the credits intact.
 
	Joel Hooks
	http://joelhooks.com
	joelhooks@gmail.com
-->
<s:Application
	xmlns:fx="http://ns.adobe.com/mxml/2009"
	preinitialize="onPreInitialize()"
	xmlns:s="library://ns.adobe.com/flex/spark"
	xmlns:mx="library://ns.adobe.com/flex/halo"
	minWidth="1024" minHeight="768"
	xmlns:tag="org.spicefactory.parsley.flex.tag.*"
	xmlns:spicefactory="http://www.spicefactory.org/parsley/flex"
	addedToStage="this.addedToStageHandler(event)"
	applicationComplete="trace('application complete');"
	xmlns:views="com.joelhooks.parsley.example.views.*"
	xmlns:delegates="com.joelhooks.parsley.example.delegates.*">
	<s:layout>
		<s:VerticalLayout/>
	</s:layout>
	<fx:Script>
		<![CDATA[
			import com.joelhooks.parsley.example.delegates.FlickrImageServiceDelegate;
			import mx.controls.Button;
			import org.spicefactory.lib.reflect.types.Void;
			import org.spicefactory.lib.logging.Logger;
			import mx.logging.LogEventLevel;
			import com.joelhooks.parsley.example.events.GalleryImageServiceEvent;
			import org.spicefactory.parsley.flex.FlexContextBuilder;
 
			protected function onPreInitialize():void
			{
				this.logTarget.level = LogEventLevel.ALL;
				FlexContextBuilder.build(Beans);
			}
 
			protected function addedToStageHandler(event:Event):void
			{
				//Let the container know that this component is ready to be added
				//to the view context
				dispatchEvent(new Event('configureIOC', true));
			}
 
		]]>
	</fx:Script>
	<fx:Declarations>
		<mx:TraceTarget id="logTarget"/>
	</fx:Declarations>
	<views:GalleryView/>
</s:Application>

We want to make sure that the Parsley container is configured at the first opportunity, and preinitialize provides this hook. After the application has been added to the stage, we need to dispatch a message to the container so that it can be added to the ViewContext allowing the visual components to interact with the container. This is done by dispatching a bubbling 'configureIOC' event in the addedtoStage handler.

This needs to be done for all viewComponents that require access to the container as you will see in the child GalleryView. At this point, the application is fully configured within the IoC Container. Our actors that have been configured in Beans.mxml have had their appropriate dependencies injected, and our Actions are ready to receive messages from the other objects in the container.

DisplayGalleryAction.as:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

/*
	Inversion of Control/Dependency Injection Using Parsley
	Image Gallery
 
	Any portion of this demonstration may be reused for any purpose where not
	licensed by another party restricting such use. Please leave the credits intact.
 
	Joel Hooks
	http://joelhooks.com
	joelhooks@gmail.com
*/
package com.joelhooks.parsley.example.controllers
{
	import com.joelhooks.parsley.example.events.GalleryEvent;
	import com.joelhooks.parsley.example.events.GalleryImageEvent;
	import com.joelhooks.parsley.example.models.presentation.IGalleryPresentationModel;
	import com.joelhooks.parsley.example.models.vo.GalleryImage;
 
	import flash.events.EventDispatcher;
 
	[Event(name="selectGalleryImage", type="com.joelhooks.parsley.example.events.GalleryImageEvent")]
	[ManagedEvents("selectGalleryImage")]
	public class DisplayGalleryAction extends EventDispatcher
	{
		[Inject(id="galleryPresentationModel")]
		public var galleryPresentationModel:IGalleryPresentationModel;
 
		public function DisplayGalleryAction()
		{
		}
 
		[MessageHandler(selector="galleryLoaded")]
		public function handleGalleryLoaded(event:GalleryEvent):void
		{
			this.galleryPresentationModel.gallery = event.gallery
			trace(event.gallery.photos.length);
			this.dispatchEvent(new GalleryImageEvent(GalleryImageEvent.SELECT_GALLERY_IMAGE,
				event.gallery.photos[0] as GalleryImage));
		}
	}
}

The DisplayGalleryAction class is wired to listen for the system message (event) galleryLoaded. It has no interest in where this message originates, and simply responds as instructed when the message is received. The handleGalleryLoaded method is designated as the MessageHandler for the galleryLoaded message. The message is an actionscript event that has been intercepted by the container and routed to interested parties. You will notice that the handleGalleryLoaded method is constructed exactly like any other Actionscript event handler (with the addition of the Parsley metadata). In this case it receives the custom GalleryEvent that carries some information.

Additionally, DisplayGalleryAction has been injected with our FlickrGalleryPresentationModel from Beans.mxml. FlickrGalleryPresentationModel implements IGalleryPresentationModel, and Parsley will inject any class that implements this interface and has the appropriate ID 'galleryPresentationModel'.

DisplayGalleryAction also dispatches the ManagedEvent 'selectGalleryImage'. Any container actor that dispatches events that need to be distributed to other interested parties need to let the container know. The class is annotated with AS3 metadata designating which ManagedEvent the class will be sending to the container.

DisplayGalleryAction receives Messages from FlickrImageServiceDelegate. it could, of course, receive its Messages from any class that is managed by the container, but in this case it is only interested in the data loaded by the delegate.

FlickrImageServiceDelegate.as:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

/*
	Inversion of Control/Dependency Injection Using Parsley
	Image Gallery
 
	Any portion of this demonstration may be reused for any purpose where not
	licensed by another party restricting such use. Please leave the credits intact.
 
	Joel Hooks
	http://joelhooks.com
	joelhooks@gmail.com
*/
package com.joelhooks.parsley.example.delegates
{
	import com.adobe.webapis.flickr.FlickrService;
	import com.adobe.webapis.flickr.Photo;
	import com.adobe.webapis.flickr.events.FlickrResultEvent;
	import com.adobe.webapis.flickr.methodgroups.Photos;
	import com.adobe.webapis.flickr.methodgroups.helpers.PhotoSearchParams;
	import com.joelhooks.parsley.example.events.GalleryEvent;
	import com.joelhooks.parsley.example.events.GalleryImageServiceEvent;
	import com.joelhooks.parsley.example.models.vo.Gallery;
	import com.joelhooks.parsley.example.models.vo.GalleryImage;
 
	import flash.events.Event;
	import flash.events.EventDispatcher;
 
	import mx.collections.ArrayCollection;
 
	[Event(name="serviceReady", type="com.joelhooks.parsley.example.events.GalleryImageServiceEvent")]
	[Event(name="galleryLoaded",type="com.joelhooks.parsley.example.events.GalleryEvent")]
	[ManagedEvents("galleryLoaded,serviceReady")]
	public class FlickrImageServiceDelegate extends EventDispatcher implements IGalleryImageServiceDelegate
	{
		private var service:FlickrService;
		private var photos:Photos;
 
		public var apiKey:String;
		public var secret:String;
		public var NSID:String;
 
		public function FlickrImageServiceDelegate()
		{
		}
 
		[PostConstruct]
		public function init():void
		{
			trace("Configuring Service");
			this.service = new FlickrService(this.apiKey);
			this.photos = new Photos(this.service);
			this.dispatchEvent(new GalleryImageServiceEvent(GalleryImageServiceEvent.SERVICE_READY));
		}
 
		public function loadGallery():void
		{
			service.addEventListener(FlickrResultEvent.INTERESTINGNESS_GET_LIST, handleSearchResult);
			service.interestingness.getList()
		}
 
		protected function handleSearchResult(event:FlickrResultEvent):void
		{
			this.processFlickrPhotoResults(event.data.photos.photos);
		}
 
		protected function processFlickrPhotoResults(results:Array):void
		{
			var gallery:Gallery = new Gallery();
			gallery.photos = new ArrayCollection();
			for each(var flickrPhoto:Photo in results)
			{
				var photo:GalleryImage = new GalleryImage()
				var baseURL:String = 'http://farm' + flickrPhoto.farmId + '.static.flickr.com/' + flickrPhoto.server + '/' + flickrPhoto.id + '_' + flickrPhoto.secret;
				photo.thumbURL = baseURL + '_s.jpg';
				photo.URL = baseURL + '.jpg';
				gallery.photos.addItem( photo );
			}
 
			this.dispatchEvent(new GalleryEvent(GalleryEvent.GALLERY_LOADED, gallery));
		}
	}
}

As we've seen, the FlickrImageServiceDelegate is an implementation of the IGalleryImageServiceDelegate interface. This allows us to program to an interface instead of an implementation for that loose coupling goodness we all crave. This will come in very handy when we want to modify the application to handle multiple services or build mock objects for the purpose of unit testing (the subject of part 3).

As with the DisplayGalleryAction class, FlickrImageServiceDelegate is configured to send ManagedEvent messages to the container. One of these events is 'serviceReady'. FlickrImageServiceDelegate utilizes the [PostConstruct] annotation on its init method. When this class was configured, we injected properties (the apiKey and secret), and the service cannot be configured without these. Using [PostConstruct] the container is ordered to run the annotated method after the class has been configured thus ensuring our properties have been injected as expected. FlickrImageServiceDelegate then dispatches the 'serviceReady' Message so that the actors waiting to get to work can do what they need to do.

The GalleryView is responsible for displaying the data and accepting user interaction.

GalleryView.mxml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

<?xml version="1.0" encoding="utf-8"?>
<!--
	Inversion of Control/Dependency Injection Using Parsley
	Image Gallery
 
	Any portion of this demonstration may be reused for any purpose where not
	licensed by another party restricting such use. Please leave the credits intact.
 
	Joel Hooks
	http://joelhooks.com
	joelhooks@gmail.com
-->
<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="500" height="600"
	addedToStage="dispatchEvent(new Event('configureIOC', true));" creationComplete="creationCompleteHandler(event)" xmlns:display="com.joelhooks.display.*">
 
	<s:layout>
		<s:BasicLayout/>
	</s:layout>
	<fx:Metadata>
		[Event(name="selectGalleryImage", type="com.joelhooks.parsley.example.events.GalleryImageEvent")]
		[ManagedEvents("selectGalleryImage")]
	</fx:Metadata>
 
	<fx:Script>
		<![CDATA[
			import org.spicefactory.lib.reflect.types.Void;
			import mx.events.FlexEvent;
			import com.joelhooks.parsley.example.events.GalleryImageEvent;
			import com.joelhooks.parsley.example.models.presentation.IGalleryPresentationModel;
			import com.joelhooks.parsley.example.views.renderers.GalleryImageThumbnailItemRenderer;
			import mx.collections.ArrayCollection;
 
			[Bindable]
			[Inject(id="galleryPresentationModel")]
			public var model:IGalleryPresentationModel;
 
 
			protected function creationCompleteHandler(event:FlexEvent):void
			{
				this.dgThumbnails.addEventListener( GalleryImageEvent.SELECT_GALLERY_IMAGE, handleSelectImage);
			}
 
			protected function handleSelectImage(event:GalleryImageEvent):void
			{
				this.dispatchEvent(event);
			}
 
		]]>
	</fx:Script>
	<s:Group width="100%" height="100%">
		<s:Rect width="100%" height="100%">
			<s:fill>
				<mx:SolidColor color="#000000"/>
			</s:fill>
		</s:Rect>
	</s:Group>
	<s:Group width="100%"  height="100%">
		<s:layout>
			<s:VerticalLayout gap="0"/>
		</s:layout>
		<display:ImageSwap id="image" width="100%" height="100%" source="{this.model.selectedImage.URL}" />
 
		<s:DataGroup
			id="dgThumbnails"
			clipAndEnableScrolling="true"
			width="500"
			height="85" mouseEnabled="{!image.changingImages}" mouseChildren="{!image.changingImages}"
			dataProvider="{this.model.gallery.photos}"
			itemRenderer="com.joelhooks.parsley.example.views.renderers.GalleryImageThumbnailItemRenderer">
			<s:layout>
				<s:HorizontalLayout gap="0"/>
			</s:layout>
		</s:DataGroup>
		<s:HScrollBar viewport="{this.dgThumbnails}" width="500"/>
	</s:Group>
</s:Group>

As with the main application MXML, the GalleryView sends a 'configureIOC' event to the container when it is added to the stage. This allows it to participate in the Messaging system and have its dependencies injected. GalleryView dispatches one message, 'selectGalleryImage', when a user clicks a thumbnail. It is also injected with a reference to the applications IGalleryPresentationModel (FlickrGalleryPresentationModel) where it accesses the array collection containing the objects presented in the thumbnail DataGroup.

There are two more Actions, RetreiveGalleryAction and SelectImageAction that function as their names imply. In addition the project has several custom events that are used for messaging. I'm not going to detail these as it would be repetitive, but it is worth noting that this only scratches the surface of the features that are available in Parsley. The docs are extensive, and the API is extremely robust. Typically you won't ever need to access the API directly after you make the call in the preinitialize method to bootstrap the container. After that it does its work silently in the background.

So I think...

Parsley could be considered a 'magical' black box framework. This is the trade off you get removing all of the boiler plate code you see in other frameworks. Looking at the extent of classes and libraries that make up Parsley is intimidating. You are placing a lot of trust in a complicated framework and have to hope that trust isn't misplaced. There is something to be said for a simple 'non-magical' framework like PureMVC. Yes, it comes at the cost of boiler plate code, but comprehension is less of a concern.

The biggest challenge Parsley presents to learning the framework is that code examples are scarce (at best) outside of the out of context examples in the (excellent otherwise) documentation and a couple blog posts. Researching the framework, I actually found myself referring to SWiZ examples to understand some of the applied concepts. This is interesting in that the SWiZ examples really do carry over, as the frameworks have significant overlap in scope and functionality. There is a thread on the SWiZ Google Group that goes into this, and I was surprised to see the complete lack of knowledge even to the existence of Parsley. I've been aware of the framework since early 2008, but didn't take time to get my head around it. It really is perplexing as to why there aren't more examples floating around, as Parsley is very mature and robust at this stage in its development. That is something that I really love about PureMVC. Cliff has done such an excellent job centralizing the examples and framework tutorials with the manifold project. The effort it takes to maintain are huge, so I understand that most don't have the time or inclination to do so, but it is much appreciated to be sure.

In Part 3 we will go into swapping out the service and get a little unit testing coverage on the application.