Robotlegs Website Example Tutorial, Part II

In the first part of this tutorial I discussed the process of wiring up views to mediators, injection of the model and the view and mapping an event to a command. In this part, I’m going to discuss the process of mapping view events to their mediators, the use of the Command object as a controller and outline the overall flow of events in this sample website app. See the first post to see the demo app running and to download the source code.

Mapping View Events to Their Mediators

The place to map a view’s events to its corresponding mediator is inside the mediator’s onRegister function which Robotlegs calls when the app is starting up. In this demo site, I have created a simple navigation menu inside a component called NavMenu.mxml. This component just contains a pair of buttons to allow the user to choose either the home page or the about page.

In this scenario, Robotlegs offers a couple of methods of mapping events. Here is one approach:

addViewListener(MouseEvent.CLICK, handleMouseClick);

With this statement (which could be added to the onRegister function), all mouse click events originating from the nav menu would be dispatched to the mediator. This would include clicks anywhere within the nav menu component, including clicks on the background as well as on the buttons. Furthermore, the dispatched events would not be conveniently traceable to their source. But the mediator needs to know which button was clicked so that it can communicate the desired web page to the Command object which will receive the event (or if no button was clicked to ignore the event). It would be possible to determine the button ID from the event target but this seemed like the wrong approach. The mediator shouldn’t need to know about the internals of the menu in order to do its job. This would also be error-prone since changing the ID of a button in the menu component would break code outside of the component that depends on it. 

For these reasons and because I didn’t want to worry about non-button mouse clicks I decided to take another approach. I decided to create a click listener for each button inside the nav menu and then to create a custom NavMenuEvent to send to the nav menu mediator. This NavMenuEvent contains a menuData property which can contain a constant corresponding to the desired web page (NavMenu.HOME_PAGE or NavMenu.ABOUT_US_PAGE).

So, instead of using addViewListener as mentioned above, I added conventional mouse click listeners for each of the two buttons inside the nav menu component:

protected  function homeBtn_clickHandler(event:MouseEvent):void
{
  var  menuEvent:NavMenuEvent = new NavMenuEvent(NavMenuEvent.MENU_EVENT);
  menuEvent.menuData  = HOME_PAGE;
  dispatchEvent(menuEvent);
}

Then, inside the click listeners I dispatched a NavMenuEvent containing the desired page constant. In order to receive this event in NavMenuMediator, I mapped a listener in the onRegister function:

eventMap.mapListener(_navMenu, NavMenuEvent.MENU_EVENT,  menuHandler);

So, whenever a menu button is clicked in NavMenu.mxml the menuHandler function in NavMenuMediator.as is called:

protected function menuHandler(event:NavMenuEvent):void
{
  var  pageChangeEvent:PageChangeEvent = new  PageChangeEvent(PageChangeEvent.PAGE_CHANGE_EVENT);
  pageChangeEvent.pageToChangeTo  = event.menuData;
  dispatch(pageChangeEvent);
}

menuHandler then dispatches a PageChangeEvent. Note the use of the Robotlegs Mediator dispatch function instead of the normal Flex dispatchEvent method. dispatch is a function provided by the Robotlegs  Mediator class which does not depend on the ActionScript display list.

As described in part I, the context registered the PageChangeCommand class as the handler for PageChangeEvents. So, whenever a PageChangeEvent occurs PageChangeCommand’s execute function is invoked. This controller then notifies the model that a new page has been requested and tells the view to change to that page:

override public function execute():void
{
  _websiteModel.changePage(event.pageToChangeTo);
  _websiteView.displayPage(event.pageToChangeTo);
}

Conclusion

To recap, the process starts in the WebsiteContext where most of the desired mappings occur. Additional mappings occur in the mediator onRegister functions at startup. Once the app is running a mouse click on one of the menu buttons triggers a mouse event that is handled inside NavMenu.mxml. Those button event listeners then create a NavMenuEvent which contains a string that specifies what the user’s desired page is. That event is received in NavMenuMediator which forwards a PageChangeEvent to PageChangeCommand. Finally, PageChangeCommand tells the model and the view how to handle the event.

In this two-part tutorial, I’ve covered many of the basic Robotlegs objects including events, mediators, commands, models, and views. Hopefully, by demonstrating the skeleton of a website you’ll be able to get similar projects up and running a bit quicker.
See part I of this post for the demo app and source code.

Tagged as: MVC, Robotlegs