ActionMap

The ActionMap is a key player in HandBones, it allows to map actions defined in you site.xml to the shell dispatcher or any other IEventDispatcher (e.g. a “go to home” button in your header). Primarily the ActionMap will be used in a Mediator, but the ActionMap needs “scope”, by this I mean “what actions it should be referencing”. Thus we have 3 implementations (not actual, but different uses) of the IActionMap.

Make sure that you’ve gone through the Action node section on the wiki before continuing.

Table of Contents

1. How Actions work
2. Injecting the IActionMap
3. Extending the RootActionMediator
4. Extending the PageActionMediator
5. Examples
   • Mapping a root Action
   • Mapping a page Action

How Actions work

Actions are defined in your site.xml file, they are little segments of information you don’t want to hard code into flash. Actions are mapped to an IEventDispatcher via the ActionMap, the only coupling point is a String reference id you give to the Action node. I would recommend creating a class that keeps your action references together as constants. So create a class called ActionRef and continuously add public constants to it as you need them. Naturally their string values must match the string you gave the action in your site.xml. They ARE case sensitive. When you don’t define a reference, the action is automatically mapped to the shell dispatcher. Just be warned that these will be coupled to Flash’s “magic string” event system, no concrete event type checking will occur.

Actions can listen to any event, the default is “click” (MouseEvent.CLICK). As this is most likely the event type you’ll be mapping to. Once this event fire from the IEventDispatcher the Action node is analysed and it’s corresponding “actions” are performed (e.g. open a url, navigate to a page, etc).

Action nodes can contain multiple tracking nodes, which are carried out once the Action is invoked. These tracking nodes are performed in order of appearance. Please note that “page views” are tracked automatically.

Injecting the IActionMap

This is the primary ActionMap that is referring to the actions you defined directly within the site node node of your site.xml file.

You can inject this any where at any time, but keep in mind if this is occurring in a view component that is continuously added and removed from stage, you need unmap the mappings made by this view component. Otherwise your mappings will stack.

Extending the RootActionMediator

This is a localised version of the ActionMap, it keeps track of what mappings have been made in order to automatically unmap them as soon as the view component is removed from stage.

The scope passed to this ActionMap is referring to the actions you defined directly within the site node node of your site.xml file.

Extending the PageActionMediator

Same as the RootActionMediator, but the scope passed to this ActionMap is referring to the actions you defined within the current page’s node of your site.xml.

Examples

Here are some uses for the ActionMap.

Let’s take the below as our site.xml. Please see the Getting Started wiki page.

<site>

	<!-- SETTINGS -->
	<title prefix="" body="Home" suffix=" | Donkey.com" />
	
	<!-- ACTIONS -->
	<action ref="GOTO_GALLERY_PAGE" gotoPageId="GALLERY_PAGE" />
	
	<!-- PAGES -->
	<page id="CONTACT_US_PAGE" title="Contact Us" address="ContactUs" src="pages/ContactUsPage.swf" >
	</page>
	
	<page id="GALLERY_PAGE" title="Gallery" address="Gallery" src="pages/GalleryPage.swf" >
		<action ref="FLICKR" invokeUrl="http://www.flickr.com/" />
	</page>
	
</site>

Mapping a root Action

Here is the top section of the site that has some buttons for navigation. The one button is called galleryBtn.

package com.donkey.view
{
	import org.robotlegs.mvcs.Mediator;
	
	import flash.events.MouseEvent;

	public class HeaderMediator extends Mediator 
	{

		[Inject]
		public var view : Header;
		
		[Inject]
		public var actionMap : IActionMap;		

		override public function onRegister() : void 
		{
			actionMap.mapAction(view.galleryBtn, "GOTO_GALLERY_PAGE", MouseEvent);
		}
		
		override public function onRemove() : void 
		{
			actionMap.unmapAction(view.galleryBtn, "GOTO_GALLERY_PAGE", MouseEvent);
		}
	}
}

Alternatively you could just extend RootActionMediator, this creates a localised version of the ActionMap which unmaps all mappings automatically when removed.

package com.donkey.view
{
	import org.handbones.mvcs.RootActionMediator;
	
	import flash.events.MouseEvent;

	public class HeaderMediator extends RootActionMediator 
	{

		[Inject]
		public var view : Header;

		override public function onRegister() : void 
		{
			actionMap.mapAction(view.galleryBtn, "GOTO_GALLERY_PAGE", MouseEvent);
		}
	}
}

Mapping a page Action

Here are are mapping the flickr button to an Action node defined in the gallery page’s scope.

package com.donkey.pages.galley.view
{
	import org.handbones.mvcs.PageActionMediator;
	
	import flash.events.MouseEvent;

	public class GalleryMediator extends PageActionMediator 
	{

		[Inject]
		public var view : Gallery;

		override public function onRegister() : void 
		{
			actionMap.mapAction(view.flickrBtn, "FLICKR", MouseEvent);
		}
	}
}