This is the third part in the introductory series covering Robotlegs AS3 here on InsideRIA. In the first part in the series we learned what Robotlegs AS3 is and had a brief "HelloWorld" introduction to the Robotlegs Context and Mediator classes. In the second part we explored Models. This article is going to expand on those concepts and introduce Services.

If you missed the first two parts I recommend looking at them first:

• Part One: Context and Mediators
• Part Two: Models

What is a Service?

The name of this website is InsideRIA. A Service is your application's link to the I in RIA. Services provide your application an API to access web services, data sources, and other applications. This could be accessing the Twitter API, your company/client's web server, the file system, or a host of other sources of data outside of your application.

A Service makes remote calls and parses the results. After the results are parsed, the service will notify the rest of the application that data is ready and/or update a Model with the results. We want external data to live as short of a life as possible within our applications. As soon as we get the results, they are converted to a format that is specific to the application domain. This might be XML, JSON, or typed Objects from an AMF source. When we are working in a "controlled" environment, meaning the server-side mid-tier is within our control, sometimes we can avoid parsing altogether because the returned objects are already part of the application domain. In many situations we are accessing third-party servers and receiving "foreign" data. This is what we want to parse.

Let's make something!

So with the definition behind us, lets look at how a Service functions within a Robotlegs AS3 application. This example is going to make use of the basic Twitter Search API.

The diagram above is the general overview of how our service will function. It receives a request, asks the server for some data, parses the results, and notifies the rest of the application. The requests are generally made from Mediators and Commands. In this example, we are going to keep it simple and make requests to the service from a Mediator. In the next article we will talk about how Commands are a great place to access services. Let's take a look at the finished widget and then build it from the ground up.

So it's not the next TweetDeck, but it is about as simple as it gets when accessing the Twitter API. The widget access the Twitter Search API and returns the current results for "robotlegs." We'll start simple, and add complexity later if we need to. Let's take a look at the pieces that go into to putting this together:

ServiceExample.mxml

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

<?xml version="1.0"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
               xmlns:s="library://ns.adobe.com/flex/spark"
               xmlns:service="robotlegs.examples.service.*" 
               xmlns:mx="library://ns.adobe.com/flex/mx"
               xmlns:view="robotlegs.examples.service.view.*"
               width="300"
               height="300">
    <fx:Declarations>
        <service:ServiceExampleContext contextView="{this}"/>
    </fx:Declarations>
    <view:SearchResultsView/>
</s:Application>

This is the main application view. You will notice that I have already made an instance of the ServiceExampleContext available in the Declarations tag. If you haven't had a chance to read parts 1 and 2 in the series, I recommend doing so now. They cover basics of creating and initializing the Context. In addition to the ServiceExampleContext, you see that the SearchResultView has also been added to the application. This example only has the one view. Take a look at the context:

ServiceExampleContext.as

1
2
3
4
5
6
7

public class ServiceExampleContext extends Context
{
    override public function startup():void
    {
        mediatorMap.mapView(SearchResultsView, SearchResultsViewMediator);
    }
}

In the SearchExampleContext we are mapping a mediator for the SearchResultsView. The SearchResultsView is a sub-class of the Spark List component:

SearchResultsView.mxml

1
2
3
4
5
6
7
8
9

<?xml version="1.0"?>
<s:List
        xmlns:fx="http://ns.adobe.com/mxml/2009"
        xmlns:s="library://ns.adobe.com/flex/spark"
        xmlns:mx="library://ns.adobe.com/flex/mx"
        itemRenderer="robotlegs.examples.service.view.renderers.SearchResultItemRenderer"
        height="100%" width="300">
    <s:layout><s:VerticalLayout gap="0" paddingBottom="10" paddingRight="10" paddingLeft="10" paddingTop="10"/></s:layout>
</s:List>

The SearchResultsView needs a mediator to allow it to communicate with the rest of the application:

SearchResultsViewMediator.as

1
2
3
4
5
6
7
8
9
10

public class SearchResultsViewMediator extends Mediator
{
    [Inject]
    public var view:SearchResultsView;
 
    override public function onRegister():void
    {
        //Make the magic!
    }
}

Now that the SearchResultsView is properly mediated, we are ready to start looking at the service that will connect to the remote Twitter server and return some data for us to list. If you were looking closely at the SearchResultsView you will see that we have also given it an ItemRenderer. We will be looking at that in just a bit. First, let's take a look at the basic service class that will connect to Twitter and fetch our data:

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

public class TwitterSearchService extends Actor implements ISearchService
{
    private var loader:URLLoader;
 
    public function TwitterSearchService()
    {
        loader = new URLLoader();
    }
 
    private const TWITTER_SEARCH_ENDPOINT:String = "http://search.twitter.com/search.json";
    public function getResults(forQuery:String = "robotlegs"):void
    {
        var urlRequest:URLRequest = new URLRequest(TWITTER_SEARCH_ENDPOINT);
        var params:URLVariables = new URLVariables();
 
        params.q = HTMLStringTools.htmlEscape(forQuery);
        params.rpp = 100;
        urlRequest.data = params;
 
        addLoaderListeners();
 
        loader.load(urlRequest);
    }
 
    private function handleError(event:SecurityErrorEvent):void
    {
        removeLoaderListeners();
    }
 
    private function handleLoadComplete(event:Event):void
    {
        removeLoaderListeners();
    }
 
    private function addLoaderListeners():void
    {
        loader.addEventListener(IOErrorEvent.IO_ERROR, handleError);
        loader.addEventListener(SecurityErrorEvent.SECURITY_ERROR, handleError);
        loader.addEventListener(Event.COMPLETE, handleLoadComplete);
    }
 
    private function removeLoaderListeners():void
    {
        loader.removeEventListener(IOErrorEvent.IO_ERROR, handleError);
        loader.removeEventListener(SecurityErrorEvent.SECURITY_ERROR, handleError);
        loader.removeEventListener(Event.COMPLETE, handleLoadComplete);
    }
}

TwitterSearchService has one public method, getResults(). It fetches results for a search string from the Twitter Search API. It is using the URLLoader to accomplish this and accessing the API directly. There are a number of excellent Twitter API libraries for Actionscript available. I'd highly recommend investigating them if you are trying to write the next TweetDeck. With the URLLoader the TwitterSearchService makes a simple request to the appropriate endpoint. Listeners are added to the URLLoader, and the fault/result handlers catch whatever is thrown back. Right now handleLoadComplete isn't actually doing anything except removing the listeners, which isn't very useful, but we will remedy that in just a moment.

Note that TwitterSearchService extends Actor and implements ISearchService. Actor simply provides convenient access to the EventDispatcher for this context. With services, it is generally considered best practice to implement an interface. Take a look at ISearchService:

ISearchService.as

1
2
3
4

public interface ISearchService
{
    function getResults(forQuery:String="robotlegs"):void;
}

When you implement an interface for a service class, it makes it really easy to swap the service out. Why would you want to do that? When connecting to remote services it is sometimes more effectiveduring development to create mock data services with 0 latency. You could make a MockTwitterJsonService that returned the same static, hardcoded results every time. This approach is critical for unit testing, which will be covered in another article, as well as just general development. Many times you are will find yourself developing in parallel to the team developing the service. The ability to create and replace mock services with live ones provides a lot of flexibility.

You will recall in the definition of a Robotlegs service above that we talked about parsing data as soon as it is returned from the remote service. In the case of the Twitter Search API endpoint we are using, we receive a JSON string as the result. JSON is a great format, but we don't want to start passing around raw JSON strings in our application. It loses the benefit of strong typing, and besides, we want to pick and choose what information we are going to use in our application. In this case, we only need the user name and actual tweet text.

Tweet.as

1
2
3
4
5

public class Tweet
{
    public var user:String;
    public var message:String;
}

This class needs a sandwich! Not a lot going on here, but we now have something to convert the results to.

TwitterSearchResultParser.as

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

public class TwitterSearchResultParser implements ISearchResultParser
{
    public function parseSearchResults(results:Object):Array
    {
        var decoder:JSONDecoder = new JSONDecoder(String(results));
        var resultObjects:Array = decoder.getValue().results;
        var tweets:Array = [];
        for each(var result:Object in resultObjects)
        {
            var tweet:Tweet = new Tweet();
            tweet.user = result.from_user;
            tweet.message = HTMLStringTools.htmlUnescape(result.text);
 
            tweets.push(tweet)
        }
        return tweets;
    }
}

The results parser is a straight forward utility class. For the same reasons the service implements an interface, the results parser does as well. It has one method, parseSearchResults() which takes a results argument. The results from Twitter will be a string, but other results might be XML if we were to use local mock data or change which Twitter service we were accessing. The JSON string is encoded into objects, which are then converted to our Tweet value object from above. The resulting Array is returned as the result. Now that the parser is ready to go, we want to supply it to the service so that it can parse the results.

You have several options for giving the service access to the parser class. You could make its methods static, you could create a new instance of the parser class within the service, or you can leverage dependency injection to supply the parser to the service class. The problem with the first two options is that it makes it a lot harder to swap out the parser class later if we needed to.

We are in the land of dependency injection now, so why not map the parser for injection? If we do this, it will be one single line in our context to change if we want to switch it out. There is no digging around in our classes commenting out lines and changing types. because both the parser and service conform to interfaces. If you'd like to see how easy it is to swap out a service, take a look at the Flickr Image Gallery in the Robotlegs Demo Bundle.

Let's look at mapping the service and parser interfaces in the context:

ServiceExampleContext.as

1
2
3
4
5
6
7

override public function startup():void
{
    mediatorMap.mapView(SearchResultsView, SearchResultsViewMediator);
 
    injector.mapSingletonOf(ISearchService, TwitterSearchService);
    injector.mapSingletonOf(ISearchResultParser, TwitterSearchResultParser);
}

This is the first time we have used the mapSingletonOf() method of the injector. It behaves much the same way as mapSingleton, with one critical difference. With mapSingletonOf() you are mapping the class you wish to inject via its interface or base class. Let's take a look at the TwitterSearchService and see how this is injected into our classes:

TwitterSearchService.as

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

private var _parser:ISearchResultParser;
 
[Inject]
public function set parser(value:ISearchResultParser):void
{
    _parser = value;
}
 
private var loader:URLLoader;
 
public function TwitterSearchService()
{
    loader = new URLLoader();
}

With the above code added to the TwitterSearchService you are now injecting the parser that was mapped into it. There are a couple of interesting things happening here. You will notice right away that the parser is of type ISearchResultParser. Since we used mapSingletonOf() to map our parser, it looks for a property of the base class or interface type that we mapped. It will actually inject the TwitterSearchResultParser, but we will access it via its interface. This approach is referred to as polymorphism and is a power object-oriented concept.

We are also placing the [Inject] tag above the setter function and not the property itself. In addition to property injection, which we have used up until now, Robotlegs supports setter and constructor injection. In this case we are using setter injection to supply the value to the parser property's setter function. Constructor injection doesn't even require the [Inject] metadata to function. We will talk about construction injection later, for now we need to remember to add the setter function to the ISearchService interface:

ISearchService.as

1
2
3
4
5
6

public interface ISearchService
{
    function getResults(forQuery:String="robotlegs"):void;
 
    function set parser(value:ISearchResultParser):void;
}

Now that the parser is all sorted out, we are ready to actually use it in the service. The result handler is the likely spot to make use of the parser, so we will add some code there:

TwitterSearchService.as

1
2
3
4
5
6
7

private function handleLoadComplete(event:Event):void
{
    var data:Object = loader.data;
    var results:Array = _parser.parseSearchResults(data);
    dispatch(new SearchResultEvent(SearchResultEvent.RECEIVED, results))
    removeLoaderListeners();
}

There we go, the data is extracted from the URLLoader, sent to the parser to be converted into an Array of Tweet objects, an event is dispatched notifying the rest of the app that we now have results, and the event listeners are removed. The SearchResultEvent is a simple custom event that has an array as its payload:

SearchResultEvent.as

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

public class SearchResultEvent extends Event
{
    public static const RECEIVED:String = "searchResultsReceived";
 
    private var _results:Array;
    public function get results():Array
    {
        return _results;
    }
 
    public function SearchResultEvent(type:String, results:Array = null)
    {
        super(type);
        _results = results;
    }
 
    override public function clone():Event
    {
        return new SearchResultEvent(type, results)
    }
}

At this point in development we have a service that should work, a mediated view component, and an event being dispatched to deaf ears. It would be more accurate to say an event that is never dispatched at all. We haven't wired the service anywhere to call getResult(). We will take care of that in the SearchResultViewMediator:

SearchResultsViewMediator.as

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

public class SearchResultsViewMediator extends Mediator
{
    [Inject]
    public var view:SearchResultsView;
 
    [Inject]
    public var service:ISearchService;
 
    override public function onRegister():void
    {
        service.getResults();
 
        addContextListener(SearchResultEvent.RECEIVED, handleResultsReceived)
    }
 
    private function handleResultsReceived(event:SearchResultEvent):void
    {
        view.dataProvider = new ArrayCollection(event.results);
    }
}

Now we are talking! Again the service is injected via its interface, and in the onRegister() we make a call to getResults(). The magical hamsters at Twitter HQ generate some content that our service parses and notifies the rest of the application with an event carrying the data. The mediator is listening for that event, and in handleResultsReceived it supplies the results to the view's dataProvider as an ArrayCollection. All we need to add is the ItemRenderer and we will have a fully semi-functional Twitter client:

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

<?xml version="1.0"?>
<s:ItemRenderer
        xmlns:fx="http://ns.adobe.com/mxml/2009"
        xmlns:s="library://ns.adobe.com/flex/spark"
        xmlns:mx="library://ns.adobe.com/flex/mx"
        width="260" height="85">
    <fx:Script><![CDATA[
        import robotlegs.examples.service.model.Tweet;
 
        override public function set data(value:Object):void
        {
            super.data = value;
            var searchResult:Tweet = value as Tweet;
            if(searchResult)
            {
                message.text = searchResult.message;
                username.text = searchResult.user;
            }
            else
            {
                message.text = "";
                username.text = "";
            }
        }
 ]]></fx:Script>
    <s:layout>
        <s:VerticalLayout paddingBottom="5" paddingRight="5" paddingLeft="5" paddingTop="5"/>
    </s:layout>
    <s:Label id="username" width="100%" maxDisplayedLines="1" fontWeight="bold"/>
    <s:Label id="message" width="100%" maxDisplayedLines="4" />
</s:ItemRenderer>

And there you have it. A list of tweets that mention Robotlegs. Glorious indeed! I would encourage you to play with this application a bit. Add a control bar to change the search terms. Add the ability to login, retrieve your timeline, and maybe post a Tweet. If you don't want to piss off all your nerd friends, start a new Twitter account to play with while you develop. I hear they have plenty of extras available.

Now that we have services, we've almost covered the full scope of tools for utilizing the Robotlegs MVC+S implementation. All that we have left to cover is Commands. Commands will let us decouple the code and provide re-usable "actions" that are triggered by events.

If you can't wait, there are articles on my blog (and lots of others across the internets) dealing with various Robotlegs topics including this 25 minute screencast. John Lindquist has a Hello World screencast on his blog. Additionally there is a Best Practices document that has proven helpful for many. You can always hit the Robotlegs Knowledge Base for help and support. It has an active group of community volunteers, including myself, that diligently answer questions regarding all things Robotlegs. Additionally I participated in writing Flex 4 in Action, which has 22 pages of Robotlegs material.

• Part One: Context and Mediators
• Part Two: Models

We are presented with lots of choices these days when it comes to frameworks for Actionscript 3 development. This is a good sign. The open source community is alive and vibrant, and tools that make development easier are a good thing. Over the course of the last year Robotlegs AS3 has seen rapid growth in adoption. It is being leveraged by major media corporations, independent game developers, startups, and enterprises of all sizes.

This is the first in a series of Robotlegs articles that will appear here on InsideRIA. In the coming weeks, more articles in the series will detail core Robotlegs concepts and work through some more advanced concepts involving third party utilities and libraries built to interact with them.

This article uses Flex. Don't worry straight AS3 developers, the second part uses an example that is pure AS3.

What is Robotlegs?

Simply put, Robotlegs is a mechanism for wiring your objects together. ObjectA needs to talk to ObjectB. ObjectA doesn't want, or need, to know that ObjectB even exists. How can they communicate? The simple answer is through Events. With Flash, we have a native event system that is used to facilitate this sort of communication. Likely you use Events on a daily basis. Objects on the display list communicate via events, and event bubbling allows distant objects to receive messages from other display objects. What about objects that aren't on the display list? This is where a framework such as Robotlegs can really make life easier for you.

At its core, Robotlegs is a set of modular utilities and interfaces that provide tools to ease these communication tasks, reduce repetitive coding tasks, and manage dependency injection within your application. In addition to this core set of tools, Robotlegs provides a lightly prescriptive MVC+S (Model, View, Controller, and Service) implementation to get you started. If you have any experience with PureMVC you will quickly recognize the use of Mediators and Commands within the Robotlegs MVC+S implementation. If not, don't worry, we will be looking at these classes in more depth soon.

This article is going to give an overview of Robotlegs through a simple "Hello World" example. You will probably look at the example and say, "Eh? I could have done this in a single MXML file without all the hassle!" While probably true with a trivial example, keep in mind that on a large project this structure quickly becomes invaluable. That is the benefit of development with a framework in general. It allows us to effectively communicate concepts and understand a code base much quicker than a slapped together application with no patterns and practices.

This is not going an exhaustive dissection of Robotlegs, but hopefully it is enough to spark your interest. I've posted resources at the end of the article for further investigation. That said, let's look at some code!

Basic Structure of a Robotlegs MVC+S Application

A typical Robotlegs MVC+S application is composed of several parts:

• Context - the Context is the bootstrapping mechanism that initializes dependency injection and the various core utilities that Robotlegs uses.
• Mediators - Mediators manage communication between your application's view components and other objects within your application.
• Commands - Commands represent individual actions that your application can perform. These are typically in response to user activity, but are not limited to that use case.
• Models - Models store data and represent the current state of your application.
• Services - Services are your application's gateway to the outside world.

Let's take a look at the Context and Mediators in more depth, starting with the Context.

The Context is at the heart of your application. It provides the central event bus that your other application objects will utilize to communicate with one another. Beyond the initial loading and bootstrapping of your application, you won't deal with the Context during regular development. It comes to life, does its job, and then quietly gets out of your way while you develop your heart out. The Context is not a Singleton. Your application can have any number of Contexts, which makes Robotlegs well suited for modular applications. We aren't going to explore modular applications here, but it will be the subject of a future article as it is an extremely powerful tool. To start off, let's look at the most basic Context.

HelloWorldContext.as

1
2
3
4
5
6
7
8
9

import org.robotlegs.mvcs.Context
 
public class HelloWorldContext extends Context
{
    override public function startup():void
    {
        //bootstrap here
    }
}

Inside of your Context you override the startup method. The startup() method is called when the Context has been fully initialized. Behind the scenes, prior to calling startup(), the Context is creating instances of all the core Robotlegs utilities, preparing to receive dependency injection mappings, and creating the event dispatcher that will be used to communicate amongst your application's objects.

Once your Context class has been created, your application needs a reference to it. In a Flex 4 Spark Application, this is generally done in the main MXML file that extends Application as seen below.

HelloWorld.mxml

1
2
3
4
5
6
7
8
9
10

<?xml version="1.0"?>
<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/mx" 
        xmlns:local="*">
    <fx:Declarations>
        <local:HelloWorldContext contextView="{this}"/>
    </fx:Declarations>
</s:Application>

Because the Context is a non-visual class, it must be placed in the Declarations tag. You should also note the contextView property bound to the application itself. The context view is the root view of the Context, and is used to provide automated assistance with view component mediation. We will look at that shortly when we discuss the relationships between views and mediators.

That is it for the Context. As mentioned, it has a very brief, but critical, role in the lifecycle of your application. With your Context ready, we can now add a few view components and get them speaking to one another via Robotlegs. Let's take a look at Mediators and their relationship to your application's view components now.

Mediators sit between your view components and the rest of the application. Put simply, Mediators listen for events. Your view components dispatch events when the user interacts with them or they are updated in some other way. These events need to be captured and delivered to the rest of the application. Perhaps the user has clicked a save button and some information needs to get sent to a server. The mediator listens for this event to occur, and when it does, the mediator gathers the appropriate information and sends an event that the rest of the application can utilize to perform some unit of work on the data. Likewise, a Mediator also listens to events from the rest of the application. If some data has been received from the server, parsed, and an event dispatched from a service class, the Mediator is the place where you will listen for that event and update its view component with the new data. Here is a view that will receive a Mediator.

MessageView.mxml

1
2
3
4
5
6

<?xml version="1.0"?>
<s:TextArea
        xmlns:fx="http://ns.adobe.com/mxml/2009"
        xmlns:s="library://ns.adobe.com/flex/spark"
        xmlns:mx="library://ns.adobe.com/flex/mx">
</s:TextArea>

This class is short. It is nothing more than a simple extension of a TextArea. Why not just use a TextArea? Dependency injection works better with unambiguous classes. What this means is that by extending TextArea into our new MessageView class, we are creating a specific view component for the dependency injection to act upon. This is important if our application were to have several TextAreas that served different purposes. By dividing up our classes in this way, we are clearly defining the intent of the class and allowing for the dependency injection tools to do their jobs effectively. With the MessageView, we might also add some additional functionality in the future. For this example, it will remain a simple TextArea, but you get the idea. Now we'll look at the mediator for the MessageView component.

MessageViewMediator.as

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

import org.robotlegs.mvcs.Mediator;
 
public class MessageViewMediator extends Mediator
{
    [Inject]
    public var view:MessageView;
 
    override public function onRegister():void
    {
         trace("I am registered!");
    }
}

The MessageViewMediator has two interesting features at this point. Right away, you will notice the first use of the [Inject] metadata tag. This tag is used by Robotlegs to identify properties and methods that it needs to perform injection on. With a mediator, the mediated view is always available for injection when the mediator is created. You don't need to make any special consideration for mapping the view for injection. That is taken care of for you when you map the view to its mediator. We will look at that in a moment, but first let's take a look at the second interesting feature of the basic mediator which is the onRegister() method.

The onRegister() method is the hook provided to you when the mediator has been fully initialized. The injections have occurred, the view is ready, and it is where you typically add your event listeners for both the view component and the application. You will typically override this method in every Robotlegs mediator you create.

Now that you have a view component and a mediator, they need to be registered, or mapped, with the Context. This is achieved through the MediatorMap. As the name suggests, the MediatorMap is a utility for mapping mediators to view components within the Context. In addition the MediatorMap by default listens to the contextView for ADDED_TO_STAGE and REMOVED_FROM_STAGE events to automatically create and destroy mediators as their corresponding view components are added and removed from the display list. It is worth noting that in graphics intensive applications with many display objects (1000s), this automatic mediation can be a performance issue. In a typical application it is very convenient and rarely causes performance issues. Here is how we map the MessageView to its MessageViewMediator within the HelloWorldContext.

1
2
3
4

override public function startup():void
{
    mediatorMap.mapView(MessageView, MessageViewMediator);
}

With that done, all that is left is to add the MessageView to the HelloWorld.mxml.

HelloWorld.mxml

1
2
3
4
5
6
7
8
9
10
11

<?xml version="1.0"?>
<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/mx"
        xmlns:local="*">
    <fx:Declarations>
        <local:HelloWorldContext contextView="{this}"/>
    </fx:Declarations>
    <local:MessageView top="40" width="100%" height="100%"/>
</s:Application>

Now, when you run your application in the debugger, you will see "I am registered!" printed to the console. Congratulations, you have a fully functional Robotlegs application. Granted, that functionality is limited to almost nothing right now, but we can change that. To give our application something to do besides just bootstrap, we will add a button called HelloButton that simply extends the Spark Button class, as well as a mediator for HelloButton called... HelloButtonMediator.

HelloButton.mxml

1
2
3
4
5
6

<?xml version="1.0"?>
<s:Button
        xmlns:fx="http://ns.adobe.com/mxml/2009"
        xmlns:s="library://ns.adobe.com/flex/spark"
        xmlns:mx="library://ns.adobe.com/flex/mx">
</s:Button>

HelloButtonMediator.as

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

import flash.events.MouseEvent;
 
import org.robotlegs.mvcs.Mediator;
 
public class HelloButtonMediator extends Mediator
{
    [Inject]
    public var view:HelloButton;
 
    override public function onRegister():void
    {
 
    }
 
}

Right now the HelloButtonMediator looks exactly like the MessageViewMediator above, except the classes are different. Your Context startup method will look like this once you have added the mapping for the HelloButton and its mediator.

1
2
3
4
5

override public function startup():void
{
    mediatorMap.mapView(MessageView, MessageViewMediator);
    mediatorMap.mapView(HelloButton, HelloButtonMediator);
}

You will also add the button to HelloWorld.mxml so that it will be added to the display list. You will probably want to add something wittier to the HelloButton's label property, but I will leave that up to you.

HelloWorld.mxml

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

<?xml version="1.0"?>
<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/mx"
        xmlns:local="*">
    <fx:Declarations>
        <local:HelloWorldContext contextView="{this}"/>
    </fx:Declarations>
    <local:HelloButton label="Say Hello"/>
    <local:MessageView top="40" width="100%" height="100%"/>
</s:Application>

At this point we have two fully mediated view components that are just dying to talk. I'm not one to deny my objects their desires, so lets do just that; starting with the custom event they will use to communicate.

HelloWorldMessageEvent.as

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

public class HelloWorldMessageEvent extends Event
{
    static const MESSAGE_DISPATCHED:String = "messageDispatched";
 
    private var _message:String;
    public function get message():String
    {
        return _message;
    }
 
    public function HelloWorldMessageEvent(type:String, message:String, bubbles:Boolean = false, cancelable:Boolean = false)
    {
        super(type, bubbles, cancelable);
        _message = message;
    }
 
    override public function clone():Event
    {
        return new HelloWorldMessageEvent(type, message, bubbles, cancelable)
    }
}

This is a simple custom event. Be sure to override the clone() method in your custom events. Events cannot be redispatched, relayed, or bubbled without this method. I make it a habit to always override clone() in all my custom events. After being burned with a couple hours of head scratching debugging, you will too.

What we want to do is update the MessageView when the user clicks the HelloButton. The HelloButtonMediator needs to listen for the MouseEvent.CLICK on the HelloButton and then dispatch the HelloWorldMessageEvent to the application. It doesn't know who will respond to this event. It doesn't care who responds to the event. The HelloButtonMediator has done its job.

HelloButtonMediator.as

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

public class HelloButtonMediator extends Mediator
{
    [Inject]
    public var view:HelloButton;
 
    override public function onRegister():void
    {
        addViewListener(MouseEvent.CLICK, handleMouseClick)
    }
 
    private function handleMouseClick(event:MouseEvent):void
    {
        dispatch(new HelloWorldMessageEvent(HelloWorldMessageEvent.MESSAGE_DISPATCHED, "Hello World"));
    }
}

With the view listener added to the HelloButtonMediator, we are now dispatching an event to the application. The next step is to do something with that event. The MessageViewMediator seems like the logical choice.

MessageViewMediator.as

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

public class MessageViewMediator extends Mediator
{
    [Inject]
    public var view:MessageView;
 
    override public function onRegister():void
    {
        addContextListener(HelloWorldMessageEvent.MESSAGE_DISPATCHED, handleMessage)
    }
 
    private function handleMessage(event:HelloWorldMessageEvent):void
    {
        view.text = event.message;
    }
}

...and with that, we have a Hello World! Seems like the long way to get there, but it will pay off in your non-trivial applications. In the next part in this series we will explore models and commands followed by an article on services. In addition to the core of Robotlegs, we will look in detail at some of the utilities that are currently available to make use of tools such as AS3-Signals and modular application development. It is an exciting time to be developing with Robotlegs and I look forward to sharing some of my enthusiasm here on InsideRIA over the coming weeks.

If you can't wait, there are articles on my blog (and lots of others across the internets) dealing with various Robotlegs topics. John Lindquist has a Hello World screencast on his blog (watching him use FDT is interesting in and of itself). Additionally there is a Best Practices document that has proven helpful for many. You can always hit the Robotlegs Knowledge Base for help and support. It has an active group of community volunteers, including myself, that diligently answer questions regarding all things Robotlegs. Additionally I participated in writing the forthcoming Flex 4 in Action book, which has 22 pages of Robotlegs material.

Part 2: Models can be found here.

I'm incredibly humbled and excited to be speaking at 360Flex this year in Denver, CO. Last year in San Jose was my first trip to the event and it was really a great experience. 3 days jam packed full of learning and connecting with fellow developers.

This year I am going to be delivering an introduction to the Parsley framework. I've been using Parsley extensively for the last 7 months and have really enjoyed the experience. So if you have a hand in building RIAs large enough to need a robust modular framework, this talk will likely give you an idea of how Parsley might fit that bill.

More than the knowledge transfer at these events, I really love the connections that it allows. In my day to day life I feel a bit isolated, and while I truly love working from my home office, gatherings like 360|Flex fill a much needed nerd-to-nerd void. So get your tickets and lets connect at 360|Flex!

I've been using IntelliJ Idea 9 quite a bit in both production and personal work lately. It is a great IDE, with lots of useful features. This is going to be a series of short screencasts that highlight the workflow in Idea for Flex/Actionscript development. The first is a quick introduction and how to set up a Flex project. If you have any questions or requests for future videos in the series please feel free to leave them in the comments.

direct link to the video (42mb QT)

Resources

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

Robotlegs and AS3-Signals play really well together. Both apply solid object-oriented principles to accomplish their respective goals. Signals is extremely well suited for automated Dependency Injection. By combining Signals and Robotlegs you are able to eliminate the use of Flash Events in the framework layer of your application. Eliminating Events means eliminating the ambiguity that can accompany Events and their String registry based approach to the Observer pattern. Signals provides a strongly-typed object-oriented approach to this same pattern.

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

Jason Crist posted a thought provoking request for his upcoming presentation comparing Robotlegs and Swiz. He's got a clever knack for stirring the framework ant pile and getting developers eyes off their IDEs long enough to discuss their passions. In this case the developers include Ben Clinkinbeard, Shaun Smith, Jesse Warden and myself.

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:

This post continues to be the most popular on this space after a year and a half. I've never been particularly fond of the implmenetation. Tightly coupled to very specific data sets and not really anything like a Flex component. It is setup more like an application (because it was pulled out of an application and generalized).

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?

Live demos are available on robotlegs.org here

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.

I've been reviewing the various IoC containers available for Flex/Actionscript. One of the benefits of IoC and DI is that it greatly facilitates unit testing. By injecting our dependencies into our applications actors, we are effectively isolating them from the other classes that make the application function. "So what?"

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.