/**
 * Allows this class to dispatch global events. Only methods using an
 * EventHandler metatadata tag with the property of scope="global" can
 * handle this event. This means other modules and even the shell application
 * can handle this event if we want.
 *
 * <p>
 * The event dispatcher is injected by Swiz due to the [Dispatcher] metadata
 * and the class member's type of IEventDispatcher.
 * </p>
 */
[Dispatcher(scope="global")]
public var globalDispatcher:IEventDispatcher;
...
public function sayHello():void
{
	logger.debug("sayHello");

	var appEvt:AppEvent;

	appEvt = new AppEvent(AppEvent.SAY_HELLO);
	appEvt.hello = "Hello World!";
    appEvt.topic = "wasiTopic";
	this.globalDispatcher.dispatchEvent(appEvt);
}

But the event handling is setup with a new, additional attribute called topicProperty.

public var myTopic:String = "wasiTopic";
...
[EventHandler(event="AppEvent.SAY_HELLO", properties="hello", scope="global", topicProperty="myTopic")]
public function helloWithTopic(hello:String):void
{
	logger.debug("hello = " + hello); // WORKS
}

This now allows the developer to set the member variable for the object doing the event handling at runtime. Internally in Swiz’s org.swizframework.utils.event.EventHandler’s method public function handleEvent( event:Event ):void we now look for the attribute “topic” and “topicProperty” in the EventHandler metadata. If the user has set the topicProperty, the method looks at the Bean that’s using EventHandler and inspects it for this String property and then compares it to the topic passed in the event. This requires some more changes to the Swiz class org.swizframework.utils.event.EventHandler.

Grab the changes I made to Swiz here.

Tweet This Post

UPDATE: Part 2 has Swiz framework code changes and a more robust solution.

If you don’t know about Swiz Event Scoping, then read on; otherwise, skip to the section labeled Filtering With Topics below.

Background

You can read the actual documentation from Swiz in the last link, but the gist is that you can tell Swiz to either broadcast events on a “global” level (using the highest level Application object) or on a “local” level (using the Module itself) and then listen to those events in the same fashion. This allows you to tell modules to listen to events only from themselves and not other modules (that might have the same events) or to listen to all events from your main, shell application and/or all other modules. Let’s look at a quick example by assuming the dispatching code is in LoginViewMediator and the handling code is in LoginController in a Module.

Local Event Dispatching

Local Event Dispatching From LoginViewMediator

/**
 * Allows this class to dispatch local events. Only methods using an
 * EventHandler metatadata tag with the property of scope="local" can
 * handle this event.
 *
 * <p>
 * The event dispatcher is injected by Swiz due to the [Dispatcher] metadata
 * and the class member's type of IEventDispatcher.
 * </p>
 */
[Dispatcher(scope="local")]
public var localDispatcher:IEventDispatcher;
...
public function login(userName:String, password:String):void
{
	logger.debug("login");

	var appEvt:AppEvent;

	appEvt = new AppEvent(AppEvent.SERVICE_LOGIN);
	appEvt.username = userName;
	appEvt.password = password;
	this.localDispatcher.dispatchEvent(appEvt);
}

Local Event Handling in LoginController

[EventHandler(event="AppEvent.SERVICE_LOGIN", properties="username, password", scope="local")]
public function login(username:String, password:String):void
{
	logger.debug("login: username = " + username + ", password = " + password);
}

If we had other Modules with this same EventHandler statement in their LoginController they would not fire because we specified the scope as local. If we change the scope property to global and the AppEvent is in a common library that all Modules can use, then they would each hear this event and all fire, which in many cases is not what you want. Just so we have a full understanding of what’s going on, let’s show an example of broadcasting global events in a similar fashion:

Global Event Dispatching

Global Event Dispatching From ModuleA

/**
 * Allows this class to dispatch global events. Only methods using an
 * EventHandler metatadata tag with the property of scope="global" can
 * handle this event. This means other modules and even the shell application
 * can handle this event if we want.
 *
 * <p>
 * The event dispatcher is injected by Swiz due to the [Dispatcher] metadata
 * and the class member's type of IEventDispatcher.
 * </p>
 */
[Dispatcher(scope="global")]
public var globalDispatcher:IEventDispatcher;
...
public function sayHello():void
{
	logger.debug("sayHello");

	var appEvt:AppEvent;

	appEvt = new AppEvent(AppEvent.SAY_HELLO);
	appEvt.hello = "Hello World!";
	this.globalDispatcher.dispatchEvent(appEvt);
}

Global Event Handling in Module B

[EventHandler(event="AppEvent.SAY_HELLO", properties="hello", scope="global")]
public function hello(hello:String):void
{
	logger.debug("hello = " + hello);
}

Filtering With Topics

Again, this is awesome…but what if you want to broadcast a message that you only want some of the modules to hear? You could obviously put in some simple logic in the event handler that determines if your Module was supposed to listen to the event based on a parameter passed in the EventHandler MetaData, but this could potentially become a large and unwieldy task that you’ll need to apply to all new modules…so what if we introduce filtering of Swiz events via a topic attribute in the EventHandler metadata and a corresponding topic property in our dispatched event?

To do this, we’ll need to do some quick monkey patching to Swiz (by creating the same package structure and adding the same classes we want to change that exist in the Swiz SWC). First, let’s add the topic property to the org.swizframework.metadata.EventHandlerMetadataTag. Add the topic property:

protected var _topic:String;
public function get topic():String
{
	return _topic;
}

Then add the following to the method override public function copyFrom( metadataTag:IMetadataTag ):void

if( hasArg( "topic" ) )
    _topic = getArg( "topic" ).value;

Next we’ll edit the method public function handleEvent( event:Event ):void in org.swizframework.utils.event.EventHandler. Add the following right after the first if() statement:

// look for a topic -- if the one exists in the EventHandler MeataData and
// the event does not have one or the value does not equal the EventHandler's
// then we'll filter out this event and not allow it
if(metadataTag.topic != null)
{
	if(event["topic"] == null)
	{
		return;
	}
	else if(event["topic"] != metadataTag.topic)
	{
		return;
	}
}

That’s it. Let’s give it a whirl by using a global dispatcher again, but adding a topic property to the event and a topic attribute to the EventHandler metadata.

Global Event Dispatching From ModuleA

/**
 * Allows this class to dispatch global events. Only methods using an
 * EventHandler metatadata tag with the property of scope="global" can
 * handle this event. This means other modules and even the shell application
 * can handle this event if we want.
 *
 * <p>
 * The event dispatcher is injected by Swiz due to the [Dispatcher] metadata
 * and the class member's type of IEventDispatcher.
 * </p>
 */
[Dispatcher(scope="global")]
public var globalDispatcher:IEventDispatcher;
...
public function sayHello():void
{
	logger.debug("sayHello");

	var appEvt:AppEvent;

	appEvt = new AppEvent(AppEvent.SAY_HELLO);
	appEvt.hello = "Hello World!";
        appEvt.topic = "wasiTopic";
	this.globalDispatcher.dispatchEvent(appEvt);
}

Global Event Handling in Module B

[EventHandler(event="AppEvent.SAY_HELLO", properties="hello", scope="global", topic="wasiTopic")]
public function helloWithTopic(hello:String):void
{
	logger.debug("hello = " + hello); // WORKS
}

[EventHandler(event="AppEvent.SAY_HELLO", properties="hello", scope="global")]
public function helloWithOutTopic(hello:String):void
{
	logger.debug("hello = " + hello); // NOPE
}

[EventHandler(event="AppEvent.SAY_HELLO", properties="hello", scope="global", topic="fooTopic")]
public function helloWithOutTopic(hello:String):void
{
	logger.debug("hello = " + hello); // NOPE
}

UPDATE: Part 2 has Swiz framework code changes and a more robust solution.

Tweet This Post

Download the new and improved AbstractViewMediator.

Normally, views are added to the display list, but popups are actually added to the SystemManager so they don’t fire off the flash.events.Event.ADDED_TO_STAGE event that’s mediated in the setView() method in my AbstractViewMediator and that’s the core piece of logic behind the entire AbtractViewMediator. See the last post for details.

So how would I connect my views to my VMs? The key was to make the AbstractViewMediator actually create the popup via the following method:

public function createPopupView(
								view:IFlexDisplayObject,
								parent:DisplayObject,
								modal:Boolean = false,
								childList:String = null,
								moduleFactory:IFlexModuleFactory = null
								):IFlexDisplayObject
{
	this.setView(view);

	PopUpManager.addPopUp(view, parent, true); // window:IFlexDisplayObject,parent:DisplayObject,modal:Boolean = false,childList:String = null,moduleFactory:IFlexModuleFactory = null
	PopUpManager.centerPopUp(view);

	return view;
}

If you look at the method signature you’ll see that I pass in a reference to the view we’re creating and then call the all important public function setView(value:*):void method that’s usually called by the mediated event flash.events.Event.ADDED_TO_STAGE. This is what creates the connection between a VM and a View. This also brings up a new question — who calls this method?

In order for the VM to be hooked up to the correct view, we’ll need to make sure we call the createPopupView(...) method on our concrete VM implementation…hmm…so how do we get a hold of that…ahh yes, the nice guys at Swiz gave us access to it via the list of beans that this instance of Swiz has. Let’s learn by example.

We’ll imagine we need to open a popup from MainView after clicking the “Get Users Button”. Naturally, our MainViewMediator mediates the button’s click event and calls this functional method:

/**
 * Open the create user view.
 */
public function openCreateUserView():void
{
	var view:CreateUserView;
	var vm:CreateUserViewMediator;

	view = new CreateUserView();
	vm = this.getViewMediatorBeanById("createUserViewMediator") as CreateUserViewMediator;

	vm.createPopupView(view, this.view, true);
}

The key line is where we get a handle to the CreateUserViewMediator via the method getViewMediatorBeanById(...) in the AbstractViewMediator:

/**
 * Helper method that returns a view mediator managed by Swiz by it's ID.
 *
 * @param	id	The unique ID for the view mediator as defined in the BeanLoader.
 */
public function getViewMediatorBeanById(id:String):AbstractViewMediator
{
	var vm:AbstractViewMediator = this.swiz.beanFactory.getBeanByName(id).source as AbstractViewMediator;

	return vm;
}

/**
 * Helper method that returns a view mediator managed by Swiz by it's ID.
 *
 * @param	clazz	The class type for our view mediator.
 */
public function getViewMediatorBeanByType(clazz:Class):AbstractViewMediator
{
	var vm:AbstractViewMediator = this.swiz.beanFactory.getBeanByType(clazz).source as AbstractViewMediator;

	return vm;
}

This method in the AVM also assumes it has a handle to the instance of Swiz that contains the beans. This is done by implementing the ISwizAware interface in the AVM.

/**
 * Creates a reference to the instance of Swiz this bean is in. This
 * allows us to get a hold of manager beans by using:
 * <code>var vm:MyViewMediator = swiz.beanFactory.getBeanByName("myViewMediator").source as MyViewMediator;</code>
 */
public function set swiz(swiz:ISwiz):void
{
	this._swiz = swiz;
}
public function get swiz():ISwiz
{
	return this._swiz;
}
protected var _swiz:ISwiz;

There you have it. All the pieces. If you create popups this way you’ll get the expected VM to View connection.

Download the new and improved AbstractViewMediator.

Tweet This Post

Well my favorite set of enhancements is without a doubt the MetataData Features:

• Metadata Content Assist
• Metadata Tag Validation
• Import/Export Tag Configuration

No more trying to remember the exact syntax for custom metadata for frameworks like Swiz…and even better is the fact that the Swiz doods at UM created a metadata config/preferences XML file for you to import to just start your Swiz project with SourceMate. Grab the file here from the Swiz Github repo and simply add it to your projects’s SourceMate preferences: Project Properties -> SourceMate -> Metadata -> Import… browse for the file and boom, you’r
e good to go!

SourceMate Metadata -> Import Swiz Configs

Nice work Swiz doods.

Tweet This Post

With the release of Swiz 1.0 RC1 right around the corner I figured I’d pull down the latest code from github, do a build, and then migrate my previous examples of Swiz and the Passive View to the latest SWC. I obviously ran into a couple of small changes between Swiz 0.6.4 and 1.0, but the one that caught me off-gaurd was the removal of metadata that injected views:

[Autowire( view="true" )]

Of course the first thing I tried was changing the metadata to use the new, preferred metadata tag [Inject]:

[Inject( view="true" )]

No dice. So I reached out to Ben Clinkinbeard and confirmed what I suspected — the injection of views (or any objects for that matter) that aren’t defined in the BeanLoader is no longer supported in Swiz 1.0; however, a simple change to my existing, base AbstractViewMediator and any concrete impls (subclasses thereof) fixed that right away — thanks to Ben for pointing me in the right direction on this one.

Assets:

• AbstractViewMediator.as
• LoginViewMediator.as

Let’s just take a quick look at what the new AbstractViewMediator looks like:

AbstractViewMediator

AbstractViewMediator.as

/**
* Web App Solution Confidential Information
* Copyright 2010, Web App Solution, Inc.
*
* @date April, 15, 2010
*/
package com.webappsolution.mediator
{
	import com.webappsolution.logging.LocalConnectionLog;
	import com.webappsolution.model.IAppModel;

	import flash.events.Event;
	import flash.events.IEventDispatcher;

	import mx.core.UIComponent;
	import mx.events.FlexEvent;
	import mx.logging.ILogger;

	/**
	 * The base class for all view mediators. It's most useful function is to
	 * provide the metadata and setter method to inject the corresponding view into
	 * the mediator.
	 *
	 * <p>
	 * In addition, it allows concrete View Mediators to add view event handlers
	 * and data bindings to children of the corresponding View with confidence by
	 * by determining if the view is "alive" (aka has been instantiated and added to
	 * the stage -- creationComplete event fired) or if it needs to listen for it's
	 * creation complete event before performing actions on it. See the
	 * <code>public function setView( value:* ):void</code> method for more
	 * details on this.
	 * </p>
	 */
	public class AbstractViewMediator
	{
		/**
		 * Logger.
		 */
		private static const logger:ILogger = LocalConnectionLog.getLogger(AbstractViewMediator);

		/**
		 * A flag indicating if the correpsonding view's creation complete has fired.
		 */
		public var isViewCreationComplete:Boolean = false;

		/**
		 * The view class we're injecting into the view mediator.
		 */
		protected var viewType:Class;

		/**
		 * The view that corresponds to this view mediator.
		 */
		protected var _view:UIComponent;

		/**
		 * Constructor.
		 */
		public function AbstractViewMediator(viewType:Class)
		{
			super();
			logger.debug("Constructor");

			this.viewType = viewType;
		}

		/**
		 * Allows this class to dispatch events. The event dispatcher is
		 * injected by Swiz due to the [Dispatcher] metadata and the class
		 * memeber's type of IEventDispatcher.
		 */
		[Dispatcher]
		public var dispatcher:IEventDispatcher;

		/**
		 * Instruct Swiz to Inject the ApplicationModel by type.
		 */
		[Inject]
		public function set appModel(value:IAppModel):void
		{
			logger.debug("AUTOWIRE :: appModel = " + value);

			this._appModel = value;
		}
		public function get appModel():IAppModel
		{
			return this._appModel;
		}
		private var _appModel:IAppModel;

		/**
		 * Listen for views added to the stage and determine if it's the corresponding
		 * View for this View Mediator. This check is done by looking at the view added
		 * to the stage and do a simple compare on the <code>viewType:Class</code> class
		 * member that we set in concrete View Medators via their constructors.
		 *
		 * <p>
		 * Also determine if the View has fired its creation complete event so developers
		 * can perform actions on the view from the View Mediator without hitting null pointers
		 * for uninstantiated objects in the View. If the creation complete has not fired, then
		 * listen for it.
		 * </p>
		 */
		[Mediate( "flash.events.Event.ADDED_TO_STAGE", properties="target", useCapture="true" )]
		public function setView(value:*):void
		{
			if(value is viewType)
			{
				logger.debug("AUTOWIRE :: view = " + value);
				this._view = value;

				// determine if the view has been initialized...
				// NO...listen for it;s creation complete event
				if(this._view.initialized == false)
				{
					this._view.addEventListener(FlexEvent.CREATION_COMPLETE, onCreationComplete);
				}
					// YES...call the init() method to kick off the instation of the view mediator
				else
				{
					this.isViewCreationComplete = true;
					this.init();
				}

				// don't get in GC's way if the view is removed
				this._view.addEventListener(Event.REMOVED_FROM_STAGE, cleanup);
			}
			else
			{
//				logger.warn("Don't inject the view " + value);
			}
		}

		/**
		 * The <code>init()</code> method is only called when the ViewMediator's corresponding
		 * View's creationComplete has been fired; this allows developers to add event listens,
		 * data bindings, and any other view functions in confidence (without worry about accessing
		 * children of the view that are null and cause runtime errors.)
		 *
		 * <p>
		 * Developers can override this to perform additional initializaitons in their ViewMediator,
		 * but must call <code>super.init()</code> in order for the aforementioned to function
		 * correctly.
		 * </p>
		 *
		 * <p>
		 * Does not have to be overriden. Simple here for convenience and as a marker method
		 * </p>
		 */
		protected function init():void
		{
			logger.debug("init");
			this.setViewListeners();
			this.setViewDataBindings();
		}

		/**
		 * Set the listeners for the UI components on the stage for the ViewMediator's corresponding View.
		 *
		 * <p>
		 * Does not have to be overriden. Simple here for convenience and as a marker method
		 * </p>
		 */
		protected function setViewListeners():void
		{
			logger.debug("setViewListeners");
			// OVERRIDDEN
		}

		/**
		 * Set the data bindings for the UI components on the stage for the ViewMediator's corresponding View.
		 *
		 * <p>
		 * Does not have to be overriden. Simple here for convenience and as a marker method
		 * </p>
		 */
		protected function setViewDataBindings():void
		{
			logger.debug("setViewDataBindings");
			// OVERRIDDEN
		}		

		/**
		 * Listen for the creation complete of the View for this ViewMediator.
		 */
		protected function onCreationComplete( event:FlexEvent ):void
		{
			logger.debug("onCreationComplete");

			this.isViewCreationComplete = true;
			this._view.removeEventListener(FlexEvent.CREATION_COMPLETE, onCreationComplete);
			this.init();
		}

		/**
		 * Remove any listeners we've created.
		 *
		 * <p>
		 * Developers should override this method to remove any custom listners
		 * created in the concrete ViewMediator. Developers must call
		 * <code>super.cleanup()</code> in order for this to function correctly.
		 * </p>
		 */
		protected function cleanup( event:Event ):void
		{
			logger.debug("cleanup");
			this._view.removeEventListener(Event.REMOVED_FROM_STAGE, cleanup);
		}
	}
}

The key change here is the changes to the public function setView(value:*):void method. Notice how it’s mediating the added to stage event — this event mediation checks to see if the View that was added to the stage is in fact the corresponding View for this View Mediator. Now you have to ask, but where is the viewType set for this check? And the answer is in each concrete impl’s constructor of the View Mediator. Here’s a quick example in a LoginViewMediator:

LoginViewMediator

LoginViewMediator.as

/**
 * Web App Solution Confidential Information
 * Copyright 2010, Web App Solution, Inc.
 *
 * @date April, 15, 2010
 */
package com.webappsolution.mediator
{
	import com.webappsolution.event.ApplicationEvent;
	import com.webappsolution.logging.LocalConnectionLog;
	import com.webappsolution.view.LoginView;

	import flash.events.Event;
	import flash.events.MouseEvent;

	import mx.controls.TextInput;
	import mx.events.ValidationResultEvent;
	import mx.logging.ILogger;
	import mx.validators.EmailValidator;
	import mx.validators.StringValidator;
	import mx.validators.Validator;

	/**
	 * Handles all events, data manipulation, data bindings, and whatever else it's
	 * corresponding View can dish out.
	 */
	public class LoginViewMediator extends AbstractViewMediator
	{
		/**
		 * Logger.
		 */
		private static const logger:ILogger = LocalConnectionLog.getLogger(LoginViewMediator);

		/**
		 * Field validator for the user name form field.
		 */
		protected var userNameValidator:EmailValidator;

		/**
		 * Field validator for the password form field.
		 */
		protected var passwordValidator:StringValidator;

		/**
		 * Constructor.
		 */
		public function LoginViewMediator(viewType:Class=null)
		{
			super(LoginView);
			logger.debug("Constructor");
		}

		/**
		 * Since the AbstractViewMediator sets the view via Autowiring in Swiz,
		 * we need to create a local getter to access the underlying, expected view
		 * class type.
		 */
		public function get view():LoginView
		{
			return this._view as LoginView;
		}

		/**
		 * The <code>init()</code> method is fired off automatically by the
		 * AbstractViewMediator when the creation complete event fires for the
		 * corresponding ViewMediator's view. This allows us to listen for events
		 * and set data bindings on the view with the confidence that our view
		 * and all of it's child views have been created and live on the stage.
		 */
		override protected function init():void
		{
			super.init();
			logger.debug("init");

			// create the form validators for the login panel
			this.createFormValidators();

			// disable the submit btn to start
			this.view.submitBtn.enabled = false;

			// make the submit btn the default btn so hitting enters submits the form
			this.view.loginForm.defaultButton = this.view.submitBtn;

			// set the focus to the username field
			this.view.userNameTextInput.setFocus();
		}

		/**
		 * Create listeners for all of the view's children that dispatch events
		 * that we want to handle in this mediator.
		 */
		override protected function setViewListeners():void
		{
			super.setViewListeners();
			logger.debug("setViewListeners");

			// handle user input on the form fields for instant form validation feedback
			this.view.userNameTextInput.addEventListener(Event.CHANGE, inputChgHandler);
			this.view.passwordTextInput.addEventListener(Event.CHANGE, inputChgHandler);

			// handle the click of the submit button
			this.view.submitBtn.addEventListener(MouseEvent.CLICK, submitBtnClickHandler);
		}

		/**
		 * Handles the click event from the submit button.
		 * Grabs the username and password from the respeective text
		 * input fields and populates a LoginDTO, then dispatches the
		 * LoginEvent to the Cairngorm framework.
		 */
		protected function submitBtnClickHandler(evt:MouseEvent):void
		{
			logger.debug("submitBtnClickHandler");

			var userName:String;
			var password:String;

			userName = this.view.userNameTextInput.text;
			password = this.view.passwordTextInput.text;

			this.login(userName, password);
		}

		/**
		 * The functional login method that dispatches the login event with the
		 * username and password.
		 *
		 * @param userName
		 * @param password
		 */
		protected function login(userName:String, password:String):void
		{
			var appEvt:ApplicationEvent;

			appEvt = new ApplicationEvent(ApplicationEvent.SERVICE_LOGIN);
			appEvt.username = userName;
			appEvt.password = password;
			this.dispatcher.dispatchEvent(appEvt);
		}

		/**
		 * Create the form field validators for the login fields.
		 */
		protected function createFormValidators():void
		{
			logger.debug("createFormValidators");

			// create the user name validator
			this.userNameValidator = new EmailValidator();
			this.userNameValidator.requiredFieldError = "Please enter a valid email address.";
			this.userNameValidator.property = "text";

			// create the password validator
			this.passwordValidator = new StringValidator();
			this.passwordValidator.required = true;
			this.passwordValidator.requiredFieldError = "Please enter a password.";
			this.passwordValidator.minLength = 4;
			this.passwordValidator.property = "text";
		}

		/**
		 * Handles text input changes to the username and password and validate them.
		 * Only enable the submit button if both the username and password fields
		 * are valid.
		 *
		 * @param evt    Change event from the targeted input field.
		 */
		protected function inputChgHandler(evt:Event):void
		{
			this.view.submitBtn.enabled =
				this.isTextInputFieldValid(this.view.userNameTextInput, this.userNameValidator) &&
				this.isTextInputFieldValid(this.view.passwordTextInput, this.passwordValidator);
		}

		/**
		 * Determines if the username text input is valid.
		 * @return Boolean
		 */
		protected function isTextInputFieldValid(textInput:TextInput, validator:Validator):Boolean
		{
			textInput.errorString = "";

			var resultEvent:ValidationResultEvent = validator.validate(textInput.text);
			if (resultEvent.type != ValidationResultEvent.VALID)
			{
				textInput.errorString = resultEvent.message;
			}
			return (resultEvent.type == ValidationResultEvent.VALID);
		}

		/**
		 * Remove any listeners we've created.
		 */
		override protected function cleanup( event:Event ):void
		{
			super.cleanup(event);
			logger.debug("cleanup");

			this.view.userNameTextInput.removeEventListener(Event.CHANGE, inputChgHandler);
			this.view.passwordTextInput.removeEventListener(Event.CHANGE, inputChgHandler);
			this.view.submitBtn.removeEventListener(MouseEvent.CLICK, submitBtnClickHandler);
		}
	}
}

There are two things to note here:

1) The setting of the view type via the Constructor

public function LoginViewMediator(viewType:Class=null)
{
super(LoginView);
logger.debug("Constructor");
}

2) The use of a getter method for strong typing of the View in the View Mediator

public function get view():LoginView
{
return this._view as LoginView;
}

Now armed with a new version of the AbstractViewMediator you can go back to using Swiz with your View Mediators without any issues.

NOTE: In order for this to work you must pull down the latest code from github and compile the SWC with the ant build.xml file provided with the project. Do not attempt to use this with the currently released Swiz Beta 1 SWC.

Tweet This Post

After implementing Part 1 of the Swiz + Passive View (PV) Example, I immediately decided that one thing I missed from the original Spring ActionScript (SAS) version was the ability to create services in an XML file that’s loaded at runtime, thus allowing you to take your app from one environment to another and simply change the XML as opposed to recompiling. Some devs don’t seem to care about this, but I find it quite useful and so do many of my clients so I created a simple DynamicServiceLocator (SL) class and “injected” it into my Example.

Tutorial Goal: Create a Dynamic Service Locator that Instantiates Services from an External XML File at Runtime

Assets

• Demo Application
• View Source

Acronyms

• PV = PassiveView
• SAS = Spring ActionScript
• SL = Service Locator
• VM = View Mediator
• CG = Cairngorm
• IoC = Inversion of Control
• DTO = Data Transfer Object

Caveats

Please read the previous posts in this series to get up to speed:

1. Part 1 of the Swiz + Passive View (PV) Example

I won’t go into the details of what Swiz is and how it works as I’d like to let the code speak for itself and you can just hit up the Swiz homepage and view their simple examples; that said, I’ll point out several things I really like about Swiz.

I am using Swiz 0.6.4, as I found issues with the 1.0.0 alpha release (that I’m going to bring up with Ben Clinkenbeard).

Getting Started

The idea is simple:

1. Create an XML file that defines all of the services leveraged in the app.
2. Add the DynamicServiceLocator to the BeanLoader (Beans.mxml) and give it the URL to load the services XML file.
3. Listen to the DynamicServiceLocator’s complete event, indicating that the services are loaded and parsed, and start the app up.
4. Inject the SL into the Delegates as opposed to injecting the services directly (that were previously defined and hardcoded in the BeanLoader from Part 1).
5. In the Delegate, request a service from the DynamicServiceLocator via an ID that was set in the service’s definition in the XML file.
6. Use the service.

Let’s take it piece by piece…

Step 1: Create Services XML File

Let’s start by creating an XML file called services.xml and putting it in src/assets/service-locator/. Next, let’s add some services — truth be told, I took the format for the XML that defines a service directly from the idea behind the application context files used in SAS and then created my own Object Factory…it’s very simple mind you b/c I didn’t need a huge object factory taking up a ton of memory when the only objects it would ever create were 8 different services.

<?xml version="1.0" encoding="utf-8"?>
<objects>

<!-- =================================================================== -->
<!-- SERVICE LOCATOR -->
<!-- =================================================================== -->

<!-- =================================================================== -->
<!-- This application context defines multiple test configurations, it
can be expanded to include a deployment configuration as well,
please see comments below.

1. Local Testing: XML Services
2. Dev Server Testing: XML Services
3. Deployment: XML Services
-->
<!-- =================================================================== -->

<!-- =================================================================== -->
<!-- 1. LOCAL TESTING: XML Services -->
<!-- =================================================================== -->

	<object id="loginService" class="mx.rpc.http.mxml.HTTPService">
		<property name="url" value="assets/xml/login.xml" />
		<property name="resultFormat" value="e4x" />
		<property name="method" value="GET" />
	</object>

	<object id="employeeService" class="mx.rpc.http.mxml.HTTPService">
		<property name="url" value="assets/xml/employee_list.xml" />
		<property name="resultFormat" value="e4x" />
		<property name="method" value="GET" />
	</object>

</objects>

The idea is to create a list of services as object nodes. Start by giving each <object> node a unique id attribute, as this is the key we’ll use to request the service later. The following line defines the loginService:

<object id="loginService" class="mx.rpc.http.mxml.HTTPService">

Next, define the concrete Flex service type in the class attr  — right now the service class must be one of the following types:

• mx.rpc.http.mxml.HTTPService
• mx.rpc.http.HTTPService
• mx.rpc.remoting.mxml.RemoteObject
• mx.rpc.remoting.RemoteObject
• mx.rpc.soap.mxml.WebService
• mx.rpc.soap.WebService

Finally, add any additional properties you want to define for the service as <property> nodes with the name and value attrs matching properties that are available for the service type. The following line adds the url property for the HTTPService:

<property name="url" value="assets/xml/login.xml" />

Step 2: Add DynamicServiceLocator to the BeanLoader

We’ll add the SL to the BeanLoader just like we did for all the other objects we want managed by the IoC Container, except we’ll also provide her with the URL to our services.xml file that we just created. When the url property is set on the SL, it will automatically load the services, parse the XML, instantiate a service for each <object> node it finds that matches one of the aforementioned service classes, and then adds that service to it’s hash or Dictionary object’s list of services via the id as it’s key.

<service:DynamicServiceLocator id="serviceLocator" eventDispatcher="{this.dispatcher}" url="assets/service-locator/services.xml" />

The other thing to make note of is that we’re again passing a reference to the BeanLoader’s dispatcher so the SL can broadcast events to other objects in the Swiz IoC Container.

Step 3: Listen to the SL’s Services Load Complete Event

Since this is more of an application level event, we’ll make the ApplicationController object handle this event:

[Mediate( event="serviceLocatorServicesLoadComplete" )]
public function onServiceLocatorLoadComplete():void
{
	logger.debug("onServiceLocatorLoadComplete");

	this.eventDispatcher.dispatchEvent(new DynamicEvent("showMainView"));
}

Which then in turn broadcasts a “showMainView” event that’s handled by the ApplicationViewMediator and ultimately removes a simple preloader (which is there in case the SL should take any significant amount of time to load and parse — unlikely here, but useful in the future) and adds the MainView to the stage.

[Mediate( event="showMainView" )]
public function showMainView():void
{
	logger.debug("showMainView");

	this.view.removeChild(this.view.progressBar);
	this.view.addChild(new MainView());
}

Now this may seem like overkill for this extremely simple example, as I could have just listened to the “serviceLocatorServicesLoadComplete” in the ApplicationViewMediator, but I wanted to proxy the event through the ApplicationController in case more needed to be done…What if we wanted to update a model level var to indicate that the SL was complete? What if we wanted to tell other objects that the SL was complete?…we wouldn’t want to do that from the ApplicationViewMediator as it’s sole purpose is to lend a hand to the MainView UI component and not to orchestrate application level processing, work, etc. Again, overkill in this example, but I wanted to put it in here as an example of what you might want to do in a much larger application.

Step 4: Inject the SL into the Delegates

Next we’ll want to inject the SL into the Delegates as opposed to injecting the hardcoded services defined in the BeanLoader. First, let’s declare the new serviceLocator property for the Delegate:

[Autowire(bean="serviceLocator")]
public var serviceLocator:DynamicServiceLocator;

Next, let’s remove the service var’s declaration and create a simple getter method for it instead:

public function get service():HTTPService
{
	return this.serviceLocator.getMXMLHTTPService("loginService");
}

Step 5: Request Service From SL

This allows us to leave the actual use of the service property untouched in our service method calls - this code hasn’t changed from Part 1, but I’m showing it for clarity. We’ll look at the Login Delegate for example:

public function login(dto:LoginDTO):AsyncToken
{
	logger.debug("login");

	return this.service.send();
}

Wrapping Up

The only other thing that I failed to mention that’s different from Part 1 is the use of a simple ProgressBar component in the Application root to provide the user with some additional feedback while the SL is loading and parsing. If you look at the main application file EmpMgmtConsoleSwizPassiveView you’ll notice that the MainView is now replaced by the ProgressBar component — once the SL is complete the ProgressBar is removed from the stage and the MainView is added (as mentioned in Step 3).

Finally, to test out the dynamic SL, open up the services.xml file in the example source code and comment out the first set of services that point to local, project-level XML files and ucomment the services that point to the WASI server. See, no recompiling.

And that about does it. Any questions?

Tweet This Post

If you followed my previous posts on the Employment Management Console application leveraging Spring ActionScript + Cairngorm, then you’ll be familiar with this small example as I simply ported it over from SAS + CG to Swiz using the Passive View (PV) design pattern.

Tutorial Goal: Create an Employee Management Console using Swiz and the Passive View Design Pattern

Assets

• Demo Application
• View Source

Acronyms

• PV = PassiveView
• VM = ViewMediator
• CG = Cairngorm
• IoC = Inversion of Control
• DTO = Data Transfer Object

Caveats

I won’t go into the details of what Swiz is and how it works as I’d like to let the code speak for itself and you can just hit up the Swiz homepage and view their simple examples; that said, I’ll point out several things I really like about Swiz.

I am using Swiz 0.6.4, as I found issues with the 1.0.0 alpha release (that I’m going to bring up with Ben Clinkenbeard).

As an additional side note, I chose the PV because I was always a fan of code-behind — I like separation of concerns so much that I actually detest looking at MXML with ActionScript in it — what a mess!..that and the fact that MXML is declarative and should just perform basic UI layout and not presentation logic. What I love about the PV is that it relies on composition as opposed to inheritance (ie the biggest issue I have with code-behind).

Finally, there are other examples of the PV + Swiz out there, like Ben Clinkenbeard’s example, but I went ahead and created an AbstractViewMediator that takes care of some race conditions when working with Views in a ViewMediator, like setting event handlers and data bindings. And I did some other things that I didn’t see in others that I’ll point out.

Swiz is Noninvasive

Swiz is a noninvasive framework that allows you to provide well organized structure and architecture to your app without writing a ton of boilerplate code that can be overly verbose and time consuming. Remember CG and how you were forced to do the following for service calls:

1. Create an Event that extends the CairngormEvent.
2. Create a Command to act as a responder for your service call.
3. Create a corresponding Delegate that actually makes the service call and transforms your data to client-side types before returning it to the Command.
4. Don’t forget to map your Custom CG Event to your Command in the FrontController.
5. Wash, rinse, repeat…and repeat…and repeat…and…mehhh

With Swiz, you can (and I emphasize can b/c you can still do it the old school way too) just broadcast a DynamicEvent from any object in the IoC Container (those objects that are defined in the Swiz BeanLoader — in my example, it’s in the class Beans.mxml) and then add some metadata to another object in the Container to “Mediate” that event.

Here’s an example — so in my LoginViewMediator I want to broadcast a “login” type event and pass the username and password along with it and I want my LoginController to handle this event:

private function submitBtnClickHandler(evt:MouseEvent):void
{
logger.debug("submitBtnClickHandler");

var dto:LoginDTO;

// create a login dto to contain the required fields for login
dto = new LoginDTO();
dto.userName = this.view.userNameTextInput.text;
dto.password = this.view.passwordTextInput.text;

var dynEvt:DynamicEvent = new DynamicEvent("login");
dynEvt.dto = dto;
this.eventDispatcher.dispatchEvent(dynEvt);
}

And now we handle this event in the LoginController like so:

[Mediate( event="login", properties="dto" )]
public function login( dto:LoginDTO ):void
{
logger.debug("login");

// TODO - make service call -- see in example src code
}

So let’s dig a bit deeper here and note all the cool stuff that’s going on and why I’m psyched about Swiz + PV:

No Custom Events (If You Don’t Want To)

Notice that I didn’t have to create a custom Event — less code — YES! Now, you can by all means create a custom event and Swiz will type check the event object and the event type to make sure they exist — check it out in the Swiz Docs for Event Handling — or you can save yourself some extra code and do what I did. While I’m usually a stickler for strongly typed objects, sometimes you have to ask yourself it it’s not just overkill for something as simple as this…personally preference I suppose, but less code without sacrificing organization and good practices wins that battle in my head.

Event Mediation

Swiz automatically handles the event and passes the meat of the event (the LoginDTO that I packages in my DynamicEvent) for me…uhm, yeah…that’s frigging cool! And you can pass multiple args as well. Again, see Swiz Docs. NOTE: One thing to remember about event mediation is that the handler method must be marked public — I’m used to making event handlers protected (and sometimes even private), but this won’t allow the Swiz event mediation to work it’s magic so make sure event handler methods are marked as public.

No Logic in MXML

My LoginViewMediator grabs the username and password from it’s corresponding LoginView and creates the event and DTO. The actual LoginView is just MXML…nuff said.

Event Dispatching and Handling Thereof in IoC Container Objects

Notice that the LoginViewMediator broadcasts the event from a class member variable called “eventDispatcher”. This next part is important: in order for Swiz to Mediate events, the events need to go through the central event bus using Swiz.dispatch(<eventType>) or by using the event dispatcher in the BeanLoader — I have chosen the latter. Why?…I have 2 reasons:

1. I don’t like having a reference of Swiz in my classes — it’s just unnecessary and makes my application that much more coupled to the framework, something Swiz tries to get developers away from to begin with.
2. The Swiz.as class is a singleton and singletons are bad…this is too long a topic to get into, but my main reason has to do with the use of Modules in large Flex apps and while this example doesn’t require modules, I’d still rather just stay the hell away from singletons.

I shove a reference of the BeanLoader’s eventDispatched into my IoC Container managed objects like this:

<controller:LoginController id="loginController" eventDispatcher="{this.dispatcher}" />
<mediator:LoginViewMediator id="loginViewMediator" eventDispatcher="{this.dispatcher}" />

Note that they both don’t need it in order for the controller to hear events from the view mediator — just the object broadcasting the event needs to have a reference to it, but I pushed it into the controller as well as since I’m broadcasting other events from it that I’d like other managed objects to listen to via mediation.

AbstractViewMediator

Since all of my views need a reference to their corresponding view, I decided to create a super class for all the mediators called AbstractViewMediator. This bad boy does several things starting with the injection of the view:

[Autowire( view="true" )]
public function set view( value:* ):void
{
logger.debug("AUTOWIRE :: view = " + value);
this._view = value;

// determine if the view has been initialized...
// NO...listen for it;s creation complete event
if(this._view.initialized == false)
{
this._view.addEventListener(FlexEvent.CREATION_COMPLETE, onCreationComplete);
}
// YES...call the init() method to kick off the instation of the view mediator
else
{
this.init();
}

// don't get in GC's way if the view is removed
this._view.addEventListener(Event.REMOVED_FROM_STAGE, cleanup);
}

Again, there’s a couple things to note about this method:

1. The argument for the method is untyped, so how does the concrete ViewMediator (VM) know how to inject the correct view? And then what about code-hinting for the view in the VM? Well, if you look at an actual implementation of a VM, like the LoginViewMediator you’ll see the following method:

   public function get view():LoginView
   {
   return this._view as LoginView;
   }
   

   Put this into method into each concrete VM with it’s corresponding view type and you’re good to go! Problem solved.

2. We check to see if the view has been initialized, ie, has the creationComplete event fired and can I start to work with children components of this view without getting runtime errors. If it has, then we call the init() method (which can and should be overridden by concrete VMs to initialize themselves); if not, then we listen for the creationComplete event and call the init() method then and only then. This ensures that when we want to set event handlers and data bindings on the view’s children we know they exist and we don’t hit nulls leading to runtime errors.
3. Finally, if you look at the init() method in the AbstractViewMediator, you’ll see that it also calls the setViewListeners() and setViewDataBindings() methods — these are placeholder methods where developers can again add concrete event handlers and data bindings in VM subclasses by overriding them.

The last thing the AbstractViewMediator does is provide the event dispatcher class member variable that we discussed earlier: public var eventDispatcher:IEventDispatcher;

Controllers & Delegates

In Swiz, we eliminate the idea of a Command class (from Cairgorm) and kind of replace it with the controller — I say kind of b/c it’s not exact mapping as the Cairngorm Command follows the actual J2EE Command design pattern whereas Swiz uses a controller to handle events from the UI to make service calls, act as a responder for the service calls, and finally to orchestrate what happens in the app after the service call (usually by dispatching an event). Since we already looked at the event mediation of the in the LoginController we won’t discuss that, but we will dig into how the controller leverages a corresponding LoginDelegate to call the service and perform data transformations on the service’s response object. So let’s look at the internals of the actual login event mediation in the LoginController:

[Mediate( event="login", properties="dto" )]
public function login( dto:LoginDTO ):void
{
logger.debug("login");

var call:AsyncToken = this.delegate.login(dto);

// I created 2 ways to handle the login service delegate
// you can either have the result come back to the controller
// or you can catch the result in the delegate and have it perform
// the necessary data transformations (traditional approach) before
// kicking it back to this controller via an event

// APPROACH 1) have the results come back directly to this controller
//this.executeServiceCall(call, onLoginResult, onLoginFault);

// APPROACH 2) have the results come back the delegate for data transformations
// before coming back to this controller
this.executeServiceCall(call, this.delegate.result, onLoginFault);
}

Out of the box, Swiz recommends that the controller handle the actual service response and data transformations before deciding what the app should do next…that’s too much responsibility for one object in my opinion, so as you can see I decided to allow the LoginDelegate to handle the actual service response: this.executeServiceCall(call, this.delegate.result, onLoginFault);. After the delegate finishes with the response, it dispatches an event:

LoginDelegate

public function result(resultEvent:ResultEvent):void
{
logger.debug("result");

var userModel:UserModel;
var xml:XML;
var dynEvt:DynamicEvent;

// get the response typed as desired
userModel = this.getTypedResponse(resultEvent);

// let something know that the login delegate is done
dynEvt = new DynamicEvent("loginDelegateComplete");
dynEvt.userModel = userModel;
this.eventDispatcher.dispatchEvent(dynEvt);
}

And then the event is mediated by the LoginController where it updates the necessary model properties and dispatches an event to signify the end of the login process.

[Mediate( event="loginDelegateComplete", properties="userModel" )]
public function completeLogin(userModel:UserModel):void
{
logger.debug("completeLogin");

var role:String;

// populate the model with data from the response DTO
this.appModel.user = userModel;

// determine of user is an admin
for each ( role in userModel.rolesList )
{
if(role == RolesConstants.ROLE_ADMIN)
{
this.appModel.user.isAdmin = true;
break;
}
}

// set this last as this is what binds the view change
this.appModel.isUserAuthenticated = true;

var evt:DynamicEvent = new DynamicEvent(EVENT_LOGIN_COMPLETE);
this.eventDispatcher.dispatchEvent(evt);
}

I think that about covers it for this edition. Any questions?

More to come on Swiz in the future.

Tweet This Post