Robotlegs 2 is easy to jump in to. From a basic standpoint, the MVCS concepts of how to build your applications remain the same. There are some significant differences in the semantic changes with Robotlegs 2 (beta), and that is what I am going to cover here. This post will go over the changes required to port the Robotlegs 1 Flickr Image Gallery demo. I'm not going to cover the basics of Robotlegs MVCS, so if you are looking for that, I'd recommend checking out the book! Also keep in mind that this is covering the beta release and some of the API is likely to change for the full release, but that shouldn't be radical either.

The full source for this example can be found on Github.

Building Your Context

Robotlegs 2 introduces the ContextBuilder. Instead of extending the concrete Context class, you utilize the builder that will configure your application's bundle(s).

Within the bundle (which is an implementation of the IContextBuilderBundle interface) you make use of the install method, which will add any additional bundles and supply any configs that go along with your bundle. Let's take a look at the ClassicRobotlegsBundle.

In essence, we are extending this bundle. It provides the tools we are used to seeing in Robotlegs 1 and allows us to make a composite bundle on top of it with out own configuration as you can see in GalleryAppConfig.

The config files are fairly similar to what you might be used to seeing within the startup() method of a Robotlegs 1 Context. There is a significant advantage to this approach that you will quickly recognize if you've ever had to create a ModularSignalCommandCrazyAssCompositeContext in your application before. With the Builder->Bundle->Config approach you are able to compose your applications with specific tools and extensions.

Changes to Mediators

Mediators, for the most part, function as expected. With the supplied MediatorMapExtension, you will no longer find the onRegister() method. Instead you will overrided the initialize() method of the Mediator class.

Mourning the Death of Actor

Actor was always an odd concrete class to include in the Framework by default. It is gone in Robotlegs 2. For this port, I create a BaseActor class of my own to supply the functionality that I needed for my services and models.

So there you have it...

Check out the source if you'd like to dig in a little deeper. It shouldn't be a radical departure from what you've come to like with Robotlegs. I'm really stoked about the framework architecture that allows for complete pluggable composition of features. This is huge, and should really open up some opportunities for creating a robust ala carte framework that suits you and your team's specific needs.

What a ride! Robotlegs has been an amazing project to work on for the last two years and we are excited to announce that the first book on Robotlegs is complete. This tome of knowledge was a collaboration between myself and Stray. She has written a great post that gives a lot of detail.

Print copies can be pre-ordered here. The e-version should be available soon and there will also be a bundle

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

This is the second 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. This article is going to expand on those concepts and introduce Models.

If you missed it, here is Part One: Context and Mediators

What is a Model?

Model classes encapsulate your application's data and provide an API to access and manipulate that data. The other classes in your application will make requests of models via this API. When data on the model is updated, the model dispatches events that the other classes within your application can react to. Models are appropriate for capturing the domain logic, such as performing calculations or other manipulations. An example of this might be a shopping cart. When an item is added to the shopping cart model, the new total for all of the items in the cart will be calculated. The new total will then be stored on the model for access by other classes within the application. By placing this logic within your models, you ensure that it isn't scattered across the entire application and know exactly where to look to see how and when your data is being manipulated.

In addition to controlling access to data, models maintain the state of your application. State, in the sense of the data model, is not the same concept as a Flex State, which relates to controlling the appearance of your application. They are certainly related, but with a model, consider a list of objects. You want to keep track of which of these objects is selected, so the data model has a selected property which is updated with the currently selected item. Other areas of your application can now access this property to discover which item is selected and react accordingly.

Models can be written to be portable. Along with Services this is something to keep in mind when you develop your models. There are many common sets of data that can easily transport between one application and the next. Think of, as an example, a UserLoginModel or a ShoppingCartModel. Portability takes a bit more thought and energy, but no more than writing the same code over again for each project does.

The model deserves a lot of attention. It is the core of your application. The visual components get all the ooos and aaahs, but as a developer you know that data is the man behind the curtain. It is our jobs, as developers, to curate the data and deliver it to those beautiful interface items accurately. This is why isolating domain logic in the model is so important. By isolating it you have made it easier to locate, update, and maintain. With the basic definition of the model in hand, let's look at a small example application.

On to the code!

This pure AS3 application is making use of Keith Peters's awesome Minimal Comps library. Don't worry, if you love Flex (and how could you not?) the next example will be a Flex app, but Minimal Comps makes it so easy to make quick examples with AS3, and Robotlegs is just as easy to use with a straight Actionscript application as it is with Flex. So let's take a look at the application and take it apart to examine its pieces.

Above is the application we will be examining. It is a simple list of authors with a quote displayed for the author that is selected in the list. Here is the archived Flash Builder project (zip 168k), which includes the Robotlegs 1.1 and MinimalComps SWC files as well.

SimpleListExample.as

1
2
3
4
5
6
7
8

public class SimpleListExample extends Sprite
{
  public function SimpleListExample()
  {
    stage.align = StageAlign.TOP_LEFT;
    stage.scaleMode = StageScaleMode.NO_SCALE;
  }
}

This is the main file of the application, the entry point. It is a simple Sprite. This is a Robotlegs application, so the first thing we need to do is create a Context:

SimpleListExampleContext.as

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

public class SimpleListExampleContext extends Context
{
    public function SimpleListExampleContext(contextView:DisplayObjectContainer)
    {
        super(contextView);
    }
 
    override public function startup():void
    {
        injector.mapSingleton(AuthorModel);
 
        mediatorMap.mapView(ListView, ListViewMediator);
        mediatorMap.mapView(QuoteTextArea, QuoteTextAreaMediator);
 
        mediatorMap.mapView(SimpleListExample, ApplicationMediator);
    }
}

It is common in Flex applications to leave out the constructor completely as the contextView is set inside the MXML declaration. In an Actionscript application you want to pass the contextView into the constructor so that it can be set immediately. Now lets create an instance of the SimpleListExampleContext in the main application view:

SimpleListExample.as

1
2
3
4
5
6
7
8
9
10
11

public class SimpleListExample extends Sprite
{
  public var context:SimpleListExampleContext;
 
  public function SimpleListExample()
  {
    stage.align = StageAlign.TOP_LEFT;
    stage.scaleMode = StageScaleMode.NO_SCALE;
    context = new SimpleListExampleContext(this);
  }
}

You should notice the context variable. It is important to have a reference to your context held in memory. If you were to simply create a new instance of SimpleListExampleContext in the constructor without placing it into a variable, it would be garbage collected at the Flash Players whim. This can cause some seriously confusing hours of trouble shooting! With Flex, you simply declare the context in MXML which holds onto the reference without needing the variable, unless you create the context in the Script tag. It will require a reference there just like the above Actionscript example.

This application will have two views. A list of names that can be selected and a text area that will display a quote from the selected item in the list. Those two views are called:

• ListView
• QuoteTextArea

No sense being too creative with the naming scheme. Both of these views are simple sub-classes of base Minimal Comps classes. Here they are:

ListView.as

1
2
3
4
5
6
7

public class ListView extends List
{
  public function ListView(parent:DisplayObjectContainer)
  {
    super(parent);
  }
}

QuoteTextArea.as

1
2
3
4
5
6
7

public class QuoteTextArea extends TextArea
{
  public function QuoteTextArea(parent:DisplayObjectContainer)
  {
    super(parent);
  }
}

This application only has one of each of these. It would be fully functional if we simply used the base List and TextArea classes. Why bother with the sub-classes at all? This is a habit, and a good one when dealing with dependency injection. If we know that we are going to mediate a view class, we sub-class it and give it a name that represents its purpose. When we do it this way it can be easily isolated for mediation.

Now we need to do is get these two views onto the stage as children of the main application. My preferred approach to this in Actionscript applications is to place a createChildren method on the main view and call it from a mediator. Here is the main view with the createChildren() method.

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

public class SimpleListExample extends Sprite
{
    private var hbox:HBox;
    private var list:ListView;
    private var quoteText:QuoteTextArea;
 
    public var context:SimpleListExampleContext;
 
    public function SimpleListExample()
    {
        stage.align = StageAlign.TOP_LEFT;
        stage.scaleMode = StageScaleMode.NO_SCALE;
        context = new SimpleListExampleContext(this);
    }
 
    /**
     * Called from ApplicationMediator's onRegister()
     */
    public function createChildren():void
    {
        hbox = new HBox(this,0,0);
        addChild(hbox);
 
        list = new ListView(hbox);
        list.alternateRows = true;
 
        quoteText = new QuoteTextArea(hbox);
        quoteText.editable = false;
        quoteText.selectable = false;
    }
}

You might be wondering why not just add the views in the constructor? I prefer to let Robotlegs get started before adding the children. By calling createChildren() from the ApplicationMediator, we are 100% certain all of the primary application bootstrapping is done and we are good to go. Here is the ApplicationMediator:

ApplicationMediator.as

1
2
3
4
5
6
7
8
9
10

public class ApplicationMediator extends Mediator
{
  [Inject]
  public var view:SimpleListExample;
 
  override public function onRegister():void
  {
    view.createChildren();
  }
}

The mediator doesn't have any more than the one responsibility in this simple example, but in your apps, mediating the view that is the contextView is a handy mechanism. After the mediator has been created, it needs to be mapped. This is an easy step to forget, but one to think back on when you hit debug and your mediator just doesn't respond. The odds are it isn't mapped, or its view component has never been ADDED_TO_STAGE. The startup method in your context will now look like this:

SimpleListExampleContext.as

override public function startup():void
{
    mediatorMap.mapView(SimpleListExample, ApplicationMediator);
}

When you run the application now, you should see an empty list and text area. Now we need to get the views some data. We are going to put some static data in a Model class that our view component's mediators will be able to access. Here is the basic model:

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

public class AuthorModel extends Actor
{
  private var _list:Array;
 
  public function get list():Array
  {
      if(!_list)
          initializeList();
      return _list;
  }
 
  protected function initializeList():void
  {
    var twain:Author = new Author("Twain");
    var poe:Author = new Author("Poe");
    var plato:Author = new Author("Plato");
    var fowler:Author = new Author("Fowler");
 
    twain.quote = "Why, I have known clergymen, good men, kind-hearted, liberal, sincere" +
            ", and all that, who did not know the meaning of a 'flush.' It is enough " +
            "to make one ashamed of one's species.";
    fowler.quote = "Any fool can write code that a computer can understand. " +
            "Good programmers write code that humans can understand.";
    poe.quote = "Deep into that darkness peering, long I stood there, wondering, " +
            "fearing, doubting, dreaming dreams no mortal ever dared to dream before.";
    plato.quote = "All things will be produced in superior quantity and quality, and with greater ease, " +
            "when each man works at a single occupation, in accordance with his natural gifts, " +
            "and at the right moment, without meddling with anything else. ";
 
    _list = [twain,fowler,poe,plato];
  }
}

Right away you notice that the AuthorModel extends Actor. Actor is a convenience class provided with MVCS. It provides the appropriate code for injecting the IEventDispatcher used to communicate in the context as well as a dispatch() method to send events through that dispatcher. It is not strictly necessary to extend Actor, but you will need to provide the IEventDispatcher injection point yourself if you do not. The Model in Robotlegs MVC+S is purely conceptual. There is no Model class to extend, and the naming convention is simply to express the intent of the class.

The model currently supplies a list of Authors that I admire, with a quote from each of them. The Author class is a simple value object to hold these properties as you can see below:

Author.as

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

public class Author
{
  public var name:String;
  public var quote:String;
 
  public function Author(name:String)
  {
    this.name = name;
  }
 
	/**
	 * Minimal comps took issue with toString(); 
	 * @return 
	 * 
	 */	
	public function get label():String
	{
		return name;
	}
}

With a model stuffed full of data, we need to deliver that data to our list for display. The first step is to map the model for injection. The second step is to mediate the ListView and transfer the data from our model to the list. Your context's startup() method will look like this after mapping the model:

SimpleListExampleContext.as

1
2
3
4
5
6

override public function startup():void
{
  injector.mapSingleton(AuthorModel);
 
  mediatorMap.mapView(SimpleListExample, ApplicationMediator);
}

To map the model, or any other class that you would like to inject, you will use the context's injector. The injector has several methods for mapping classes and values for injection. The mapSingleton() method is very common for mapping a simple class for injection. It should be noted that the term "singleton" in this context is not referring to a Singleton in the strict sense of the design pattern. In this case, mapSingleton() means that the injector will create and supply one single instance of the AuthorModel whenever it is asked to do so. You can have as many instances of AuthorModel as you want, but the injector will only create and inject the one you asked for with the above mapping. There are several other methods for mapping with the injector, and I highly recommend reading Till Schneideriet's documentation for the SwiftSuspenders Injector. By default this is what Robotlegs uses. The Robotlegs Best Practices documentation also discusses using the Injector. In addition to the documentation, we will be discussing the other injection mapping options in future articles.

With the model mapped for injection, we are one step closer to getting the Authors into their list. To do that, we will mediate the ListView and inject the AuthorModel into the mediator. here is the mediator for ListView:

ListViewMediator.as

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

public class ListViewMediator extends Mediator
{
  [Inject]
  public var view:ListView;
 
  [Inject]
  public var authorModel:AuthorModel;
 
  override public function onRegister():void
  {
    view.items = authorModel.list;
  }
}

Outside of the [Inject] tag for the mediated view components we haven't looked at the use of the [Inject] tag or discussed how Robotlegs provides access to dependency injection for your classes. In the ListViewMediator you will see the view being injected. In addition to the view there is a public property called authorModel of the type AuthorModel marked with the [Inject] tag as well. When you place the [Inject] tag over a public property, when the class is created by Robotlegs it will "inject" that property based on the rules you have mapped. Note, that if you haven't supplied a rule for the injection you will receive a runtime error directing you to the problem. If this occurs, be sure to check your mapping. In this case, we have already used mapSingleton() to prepare AuthorModel for injection.

In the onRegister() method of the mediator that is run when the mediator has been fully constructed and provided injection we are accessing the model and assigning the list property to the items property of the view. Nice! We should see the items in the list now.

...well...

...oh ya!...

First we need to map the mediator:

SimpleListExampleContext.as

1
2
3
4
5
6
7
8

override public function startup():void
{
  injector.mapSingleton(AuthorModel);
 
  mediatorMap.mapView(ListView, ListViewMediator);
 
  mediatorMap.mapView(SimpleListExample, ApplicationMediator);
}

There we go. The ListView is mediated. Take note of the order of the mappings. The ListView mediator mapping is ABOVE the SimpleListExample (main view) mapping. The SimpleListExample is the main view, as well as the contextView. The contextView is treated a bit differently when its class is mapped. Instead of listening for the ADDED_TO_STAGE event to occur, the contextView is immediately mediated. Since the contextView is generally already on the stage, we can't reliably listen for an event that might never occur. Since we want ListView to be mediated when it is added to stage we make sure that it is mapped before the ApplicationMediators onRegister() ever has a chance to be called. If you recall, the ApplicationMediator's onRegister() is where we tell the main view to add its children, including the ListView.

So with the ListView being populated with data, you can now select from the list of Authors in the list. Pretty exciting, no? Try to contain yourself for a bit. There is still a ways to go. Now we want to fill the QuoteTextArea with some text. Preferably a quote from the selected Author. To do that, we will be making additions to the AuthorModel so that it will keep track of the selected Author. When an Author is selected in the ListView the ListViewMediator will update the AuthorModel. The AuthorModel will then send an event to notify anybody that might be listening that an Author was selected. We will need to also create a mediator for the QuoteTextArea so that it can listen for that event and update with the quote from the selected Author. We know we will need the event, so lets make that first:

SelectedAuthorEvent.as

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

public class SelectedAuthorEvent extends Event
{
  public static const SELECTED:String = "authorSelected";
 
  private var _author:Author;
 
  public function get author():Author
  {
    return _author;
  }
 
  public function SelectedAuthorEvent(type:String, author:Author = null, bubbles:Boolean = false, cancelable:Boolean = false)
  {
    super(type, bubbles, cancelable);
    _author = author;
  }
 
  override public function clone():Event
  {
    return new SelectedAuthorEvent(type, author, bubbles, cancelable)
  }
}

The event is rather unremarkable. It is a typical custom event with a single constant, SELECTED, for a type and an optional author parameter. Now that we have the event, we need to updated the AuthorModel to keep track of the selected Author and notify the application when the it has changed:

AuthorModel.as

1
2
3
4
5
6
7
8
9
10
11

private var _selected:Author;
public function get selected():Author
{
  return _selected;
}
 
public function set selected(value:Author):void
{
  _selected = value;
  dispatch(new SelectedAuthorEvent(SelectedAuthorEvent.SELECTED, selected));
}

With the above code added to the AuthorModel we are effectively able to track the currently selected Author. To set this property on the model we will update the ListViewMediator to listen for a selection event from the ListView and update the model when it occurs:

ListViewMediator.as

1
2
3
4
5
6
7
8
9
10
11

override public function onRegister():void
{
  view.items = authorModel.list;
 
  addViewListener(Event.SELECT, handleSelected)
}
 
private function handleSelected(event:Event):void
{
  authorModel.selected = view.selectedItem as Author;
}

Inside of the ListViewMediator's onRegister() we will use the addViewListener() method to add an event listener on the view for Event.SELECT to be handled by the handleSelected method. Now, when an item in the list is selected, the event handler method will access the selected property of the authorModel and updated it with the item that was selected. That value will be set, and the AuthorModel will dispatch the event notifying the rest of the application that this has occurred.

"Why not just dispatch the selected event here and be done with it?"

You very well could, and if your application is this simple it is probably the appropriate way to go. There aren't many apps this simple in my life, and this is an example of how to use a Model, so that is the reason we are taking the seemingly long way here. And now that we have traveled down that path, we still need to get that text into the QuoteTextArea, so lets get it mediated:

QuoteTextAreaMediator.as

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

public class QuoteTextAreaMediator extends Mediator
{
  [Inject]
  public var view:QuoteTextArea;
 
  override public function onRegister():void
  {
    addContextListener(SelectedAuthorEvent.SELECTED, handleSelectedAuthorChanged)
  }
 
  private function handleSelectedAuthorChanged(event:SelectedAuthorEvent):void
  {
    var author:Author = event.author;
    view.text = author.quote;
  }
}

So there it is. The QuoteTextArea now has a connection to the rest of the application. In its onRegister we will use the addContextListener() to listen for the SelectedAuthorEvent.SELECTED and handle it with handleSelectedAuthorChanged.

The handleSelectedAuthorChanged method takes the information from that event and updates the view's text property with the quote from the selected Author. After we get that mediator mapped, we will have achieved the extent of this example's functionality:

SimpleListExampleContext.as

1
2
3
4
5
6
7
8
9

override public function startup():void
{
    injector.mapSingleton(AuthorModel);
 
    mediatorMap.mapView(ListView, ListViewMediator);
    mediatorMap.mapView(QuoteTextArea, QuoteTextAreaMediator);
 
    mediatorMap.mapView(SimpleListExample, ApplicationMediator);
}

With that you have an example that covers the basics of using Models in a Robotlegs application. The guardians of your data, Models play an extremely important part in your applications. By utilizing models as the access point for your data, you isolate where the data is stored an manipulated. When you sit down to solve a problem, you know where to look for issues regarding data and its subsequent representation of the state of your application. If your data is scattered in junks all across your application it becomes a murky stew making it difficult to quickly isolate trouble spots or add functionality to the application.

A few pages in a blog post is a very brief introduction to models. I highly recommend diving into some research on the M in MVC. In the next example will take a look at Services, and see how they are used within a Robotlegs application. After Services we will have a look at Commands to complete the Robotlegs MVC+S implementation before moving on to some more advanced topics.

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 the forthcoming Flex 4 in Action book, which has 22 pages of Robotlegs material.

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!

For the past year or so unit testing has been one of my favorite subjects. There are tons of books on the subject, but several really stand out. Here are my favorites so far:

Clean Code by Uncle Bob Martin

This book does cover unit testing a bit. It isn't the focus of the book, but regardless it sits here at the top of my unit testing list. Why? Because the hardest part of writing unit tests is writing code that can be tested in the first place. Get it. Read it. Learn it. Seriously. Uncle Bob rides in the vanguard in the battle against horrible dirty code.

The Art of Unit Testing by Roy Osherove

This is a small book, but it is stuffed to the gills with distilled information on the subject of unit testing. Don't be put off with the .NET examples. It doesn't make a difference at all. There are a couple of chapters that are .NET specific that you can just skip, but 90% of the book is killer information on testing your code.

Working Effectively With Legacy Code by Michael Feathers

Like Clean Code, this book isn't specifically focused on writing unit tests, but it totally is. Feathers defines "legacy code" as "code with no unit tests". You can quibble about the semantics of this definition, but you'd be missing the point of this kickass book. How do you take a pile of code with no tests and make it better in a safe incremental way? How do you stop producing legacy code at a furious pace? That's right, the code you wrote today is probably sitting in the "legacy" column already. Even if you are writing tight unit tested code you will likely stumble into code that isn't, and this book has tons of good advice on how to deal with it.

xUnit Test Patterns by Gerard Meszaros

This one is a monster. It is a duplex book with a strong narrative up front and a massive patterns catalog bringing up the rear. if you read a lot of unit testing books you will "feel" this one under the best ones as the giant upon whom they are standing. This is source material here, and might be my personal favorite. I think The Art of Unit Testing makes for an easier (quicker anyway) read and if you were to choose one or the other go for it. Don't choose one or the other though. Read both!

Growing Object Oriented Software Guided by Tests by Steve Freeman

While the above books touch on the concept of TDD it isn't their focus. This relatively small volume is a great introduction to the subject of test-driving your code. It steps out of simple unit tests and gets into the realm of integration and acceptance testing. It has a fabulous explanation of mocking and is a fantastic introduction to the "testing layer cake" that high quality maintainable applications are guarded with.

So what is the take away from all of these books? Unit testing is actually pretty easy. Writing clean testable code is harder. We (developers) tend to complicate unit tests a lot. We write them as integration, acceptance, or other more complex test types that are orders of magnitude harder to write and maintain. A unit should be tiny and easy to test. If it isn't, then something is probably wrong with the unit or the scope of the test. Unit tests are for developers by developers and shouldn't be considered an afterthought or some line item on a managers spreadsheet. A high percentage of test coverage should not be the goal. Quality over quantity. Confusing unmaintainable tests are a liability to a project. Concise readable unit tests can be a trusted asset.

As with all code, complexity is easy. It is the default. Elegant simplicity is much more difficult. At the end of the day, cramming all the information the above books offer into my head has me writing dead simple unit tests. It seems weird as I examine it, but that's how it has worked out. Study up and write some high quality tests. You will be well thanked by both your fellow developers and your future self.

There was a time in the push for a Robotlegs 1.0 that a nometa implementation existed. Robert Penner still uses it, if I'm not mistaken. It doesn't have as much convenience as the regular meta-loving MVCS implementation, meaning it doesn't inject a bunch of classes into the MVCS base classes. Is that bad? Not really. I find myself rarely using the injected classes anyway. At the time I pushed back on the nometa implementation and its inclusion in the core. I still think that is proper, because it would just tend to cloud the implementation and make it more difficult to document and support, both of these being key pillars in making Robotlegs a successful project that people will actually use. The concept of using as little metadata as possible in my applications is very appealing.

SwiftSuspenders beautifully supports constructor injection. This means that you don't need to annotate any methods or the class with metadata for it to honor injection into the constructor. With the [Inject] tag, you are marking required dependencies. They aren't optional. If there is no rule to supply the injection you will get a runtime error saying as such. So, given these non-optional dependencies, injecting them into the constructor makes a lot of sense. One drawback to this approach is that if you are injecting a lot of dependencies your constructor might get really big. In fact, the limit is 10 parameters. Guess what? If your class requires that many dependencies, it already smells bad. Clean it up and think single responsibility. For the love of Uncle Bob, keep it clean.

To illustrate this point I have refactored the Image Gallery example. It was my first example for Robotlegs almost a year ago. The original version resides in the Robotlegs Demo Bundle. In this refactoring I removed all occurrences of the [Inject] metadata tag. In addition, I removed all of the extensions of Robotlegs mvcs implementation sub-classes with the exception of Mediator. There are no Actor or Command subclasses. So what you end up with is a Command, Model, and Service tier that is completely meta and framework free. That rocks. It is just AS3 code doing its job. I love that.

Here's a link to the source for this project on Github.

Tooling is very lacking for metadata in all of the IDEs currently available. The SourceMate plugin from ElementRiver is a nice addition to Flash Builder if you make use of metadata. It actually gives you code completion, which in and of itself is a huge improvement over... nothing. I hope to see more IDE support for metadata soon. It would really make it a lot easier to manage.

In my professional life, I use all of the Actionscript DI frameworks (Robotlegs, Swiz, and Parsley). They are all great, when used appropriately within a defined set of patterns and practices. I worry about the trend for increased use of metadata. I think the complexity overhead is large. Sure, you get it, but there is a responsibility to build systems that can be understood by a wide range of developers without weeks of remedial training on a complex metadata based DSL. The less complex we make our complex systems the better. They are easier to train for, document, and build.

WTF is a Modular?

Modular programming is a versatile technique for separating an application into smaller parts. Each module is effectively an application and can be developed independently from one another. In a typical modular application you will have a Shell that is loaded initially. The Shell will manage the loading of modules and displaying their contents. Flex modules can be visual components that extend the Module class, but this is certainly not the extent of what can be considered a module.

Robotlegs is well suited for modular application development. Each Context is encapsulated and provides its own internal method for communication. A barrier to writing modular applications thus far with Robotlegs is that while these Context objects can exist in abundance in an application, they aren't very useful from a modular standpoint unless they can communicate with one another. As with many things within the Robotlegs eco-system, this is best accomplished through the development of a utility that can be used in conjunction with the core framework to provide the specific functionality that we are looking for. There has been some good work done in this area, but with Robotlegs 1.1 and more specifically the 1.5 release of the default Dependency Injection provider SwiftSuspenders, we have been equipped with better tools to accomplish modular contexts in a Robotlegs application in a clean effective manner.

A Little Backstory

Prior to Robotlegs I used PureMVC exclusively. There is a utility for PureMVC called Pipes, which I have written about previously. Pipes is pretty cool. It uses a plumbing metaphor to describe the connections between modules. It is... verbose... and requires a shit-ton of wiring code to be functional. This can be a challenge to get your head around, and can create code that you have to stare at for a good while to fully understand HTF everything is actually being wired.

My original path for a Robotlegs modular utility was to port Pipes. In fact, I didn't really have to port Pipes, but just wrote an adapter that allowed Pipes to fit into a Robotlegs application. The problem was that it didn't feel like Robotlegs. Verbose and confusing goes against the core moral fiber of what Robotlegs is all about. So I started whittling it down. At that point it looked like Stray's excellent work with the Robotlegs Modular utility. Heh. Full Circle! So instead of using Pipes, I've taken her work and expanded on it for Robotlegs 1.1 and at the same time clarifying some of the concepts within the utility and making it more useful across a broader range of use cases.

Where we are now

So with Pipes set aside for now, we have a dead simple modular implementation that can be used for Flex, AS3, and maybe even Flash applications. It doesn't provide all of the functionality that Pipes brings to the table. Specifically it is missing concepts like message filtering and queuing. While these are likely useful tools, I didn't feel that they needed to be implemented just yet. I have some ideas about how they might be implemented, but feel that the Robotlegs Modular Utility is clean and simple covering a big majority of typical use cases. Start simple and expand from there. This is where I am relying on you, gentle reader, to help guide the utility into something more useful while still keeping the clean and simple Robotlegs aesthetic.

With that behind us, lets look at an example of a modular application written with the Robotlegs Modular Utility. It is fairly useless, but covers the core concepts of what a modular application should be able to do.

Modular Doodads: A Lame but Functional Example

The full source for this example can be found HERE...

In this example you have three separate modules: the Shell, or the main application, a logging module that provides "console" output, and Doodads. Doodads are simple modules with not a whole lot of functionality. When you add a Doodad the shell creates a new Doodad and adds it to a container. The Doodads have a "request" button that will ask any other Doodads to change color. In addition to that, they have a close button to remove the Doodad. Above the Doodad container is a "trigger" button. This sends out an event that triggers a command on all of the Doodad modules (causing them to flash violently).

ModularDoodadsContext.as

1
2
3
4
5
6
7
8
9
10
11

public class ModularDoodadsContext extends ModuleContext
{
    override public function startup():void
    {
        //map the modules so that instances will be properly supplied (injected) with an injector.
        viewMap.mapType(LoggerModule);
        viewMap.mapType(DoodadModule);
 
        mediatorMap.mapView(ModularDoodads, ModuleDoodadsMediator);
    }
}

The main shell application context context is doing a couple of things. As with the other modules within the application, this Context extends ModuleContext. ModuleContext will create the ModuleEventDispatcher (IModuleEventDispatcher) as well as a ModuleCommandMap that can be used to map commands that respond to events on the ModuleEventDispatcher. ModuleContext is a convenience mechanism.

Since the modules in this application are view components we can use the ViewMap to map their types. This facilitates injection into the modules when they are added to the stage. The reason for this will become clear as we look at one of these modules.

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

<?xml version="1.0" encoding="utf-8"?>
<mx:Module xmlns:fx="http://ns.adobe.com/mxml/2009"
           xmlns:s="library://ns.adobe.com/flex/spark"
           xmlns:mx="library://ns.adobe.com/flex/mx"
           implements="org.robotlegs.utilities.modular.core.IModule"
           layout="absolute" width="100%" height="75">
    <fx:Script>
        <![CDATA[
            import org.robotlegs.core.IContext;
            import org.robotlegs.core.IInjector;
            import org.robotlegs.utilities.modular.core.IModule;
            import org.robotlegs.utilities.modular.core.IModuleContext;
 
            import robotlegs.examples.modulardoodads.modules.logger.skins.LoggingTextArea;
 
            protected var context:IModuleContext;
 
            [Embed(mimeType='application/x-font', source="assets/AnonPro.ttf", fontName="Anon")]
            private var anon:Class;
 
            [Bindable]
            public var messages:String = "";
 
            public function addLoggingMessage(message:String):void
            {
                message += "\r";
                messages += message;
                scrollToMax();
            }
 
            private function scrollToMax():void
            {
                messageDisplay.validateNow();
                messageDisplay.scroller.verticalScrollBar.value = messageDisplay.scroller.verticalScrollBar.maximum;
            }
 
            /**
             * We need to initialize our context by setting the parent
             * injector for the module. This is actually injected by the
             * shell, so no need to worry about it!
            */
            [Inject]
            public function set parentInjector(value:IInjector):void
            {
                context = new LoggerModuleContext(this, value);
            }
 
            public function dispose():void
            {
                context.dispose();
                context = null;
            }
 
        ]]>
    </fx:Script>
    <fx:Declarations>
        <!-- Place non-visual elements (e.g., services, value objects) here -->
    </fx:Declarations>
    <s:TextArea
        id="messageDisplay"
        fontFamily="Anon"
        fontSize="12"
        width="100%" height="100%"
        text="{messages}"
        skinClass="robotlegs.examples.modulardoodads.modules.logger.skins.LoggingTextArea"/>
</mx:Module>

Looking at the LoggerModule.mxml it is important to note that it implements the org.robotlegs.utilities.modular.core.IModule interface. This provides a contract to ensure that we supply the appropriate API to initialize the module. The IModule interface provides a setter for the parentInjector as well as a dispose() method that we can use to cleanup the module when it is removed. The key here is the setter for the parentInjector that supplies an injector to the module. This setter actually creates the context or the module and passes the injector into the context. As you will recall in the ModularDoodadContext above, the LoggerModule was mapped with the ViewMap. This means that when it is added to the stage its dependencies are injected. parentInjector is marked with the [Inject] metadata so the injector is automatically provided to the module. The context will then use that injector and create a child injector.

Child Injectors

A child injector is a new concept in Robotlegs 1.1. It is a powerful tool. When the parentInjector is set, the module context uses it to create a child injector. This child injector has a reference to its parent and the parent's injection mappings. This means that if you don't create a mapping in the child injector it will supply the injection a mapped within the parent (or grandparent). The parent has no reference at all to the child, and doesn't even know that it exists so if you create mappings in a child injector they are not reflected up the injector chain to ancestors. If you create a mapping that is identical to a mapping within an injector's family tree, the first mapping is honored and the injector will not check with its ancestors to see if the mapping exists.

Through this mechanism of child injectors we are able to map an event dispatcher within the top level application context that can then be shared amongst any number of other contexts providing that they are able to create and use a child injector. This is the core of how these modules are able to communicate with one another. We create the IModuleEventDispatcher in the shell and all sub-modules now have access to it through their injector. As long as you don't map a IModuleEventDispatcher with the child, any injections that call for it will be supplied with the original dispatcher from the parent injector.

Now what? For the most part, you develop modules as you would any other Robotlegs application. The Modular Utility does provide one other convenient mechanism to help save you on some typing. That is the ModuleMediator.

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

public class DoodadModuleMediator extends ModuleMediator
{
    [Inject]
    public var view:DoodadModule;
 
    private var madeRequest:Boolean;
 
    override public function onRegister():void
    {
        addViewListener(DoodadModuleEvent.DO_STUFF_REQUESTED, handleDoStuffRequested, DoodadModuleEvent);
        addViewListener(DoodadModuleEvent.REMOVE, handleRemove);
        addModuleListener(DoodadModuleEvent.DO_STUFF_REQUESTED, handleDoStuffRequest, DoodadModuleEvent);
        addContextListener(DoodadModuleEvent.FLASH_YOUR_DOODAD, handleDoodadFlashRequest);
    }
 
    private function handleRemove(event:DoodadModuleEvent):void
    {
        dispatchToModules(new LoggingEvent(LoggingEvent.MESSAGE, "Removing DoodadModule"));
        dispatchToModules(event);
        view.dispose();
    }
 
    private function handleDoStuffRequested(event:DoodadModuleEvent):void
    {
        madeRequest = true;
        dispatchToModules(new LoggingEvent(LoggingEvent.MESSAGE, "DoodadModule made request..."));
        moduleDispatcher.dispatchEvent(event);
    }
 
    private function handleDoStuffRequest(event:DoodadModuleEvent):void
    {
        if(!madeRequest)
        {
            view.color = Math.random()*0xFFFFFF;
            dispatchToModules(new LoggingEvent(LoggingEvent.MESSAGE, "DoodadModule changed color: " + view.color));
        }
        madeRequest = false;
    }
 
    private function handleDoodadFlashRequest(event:DoodadModuleEvent):void
    {
        view.flashIt();
    }
}

The DoodadModuleMediator extends ModuleMediator. The ModuleMediator provides basic injections for the ModuleCommandMap and the ModuleEventDispatcher. ModuleMediator also provides some convenience with a bit of syntactic sugar to make it easy to dispatch events to the ModuleEventDispatcher. The dispatchToModules() method sends events over the ModuleEventDispatcher in contrast to the dispatch() method which sends events over the EventDispatcher that is local to the context. Additionally you are provided with addModuleListener() that makes it easy to add a listener for an event type that is expected to be dispatched from another module (including the shell). These methods simply abstract the eventMap.mapListener() method, which in turn is abstracting eventDispatcher.addEventListener(). You have nothing if not options when it comes to adding a listener within a mediator!

Modular Application Development in Flex... Some Caveats

Possibly the biggest gotcha with modular application development is managing memory. With a typical application you are dealing with a single "module" - the application itself. You do not typically attempt to unload your entire application from memory. Simply refreshing the page or navigating away more effectively does this. We do try to prevent memory leaks diligently (right?) to provide our users with the smoothest possible experience, but this is different from trying to release all of the memory the application uses at runtime. Modules, on the other hand, can come into existence at runtime at any point during the lifecycle of your application. On the flip side of that is that the modules should be able to completely unload and release all of the memory that they have used.

There are a host of "tricks" to getting modules out of memory. This article is a good overview of the major ones. In addition to these sneaky memory peggers, you will also want to carefully ensure that your modules release references and dispose of objects properly.

The Modular Utility makes every effort to provide mechanisms for disposing of your modules, but when it gets down to it most of that responsibility will be left up to you. If you notice that Robotlegs or the Modular Utility is preventing a module from unloading please let me know so that I can address it as soon as possible. The end goal is to provide a robust tool for developing Robotlegs applications with modules. The Modular Utility is currently very modest, but what it isn't is a solution looking for a problem. As it grows it will be in response to real problems, and your feedback and use is critical to meeting that goal.

The bits you'll need...

Robotlegs Modular Utility (my fork)
The full source for this example
Robotlegs AS3

On a related note...

I recently had the pleasure of writing a full 22 pages on Robotlegs in the upcoming Flex 4 in Action from Manning. It is a great book overall and if you'd like to learn more about Robotlegs (or Flex 4 in general) then I highly recommend it.