This presentation focuses on how your architectural design could look like to make agile testing feasible and efficient. It’s explaining principles we’ve been following at projects that can make Test Driven Development of RIAs a reality.

It also touches upon code coverage tooling available for Flex and its recommended usage. Checkout Flexcover, the open source code coverage tool. Flexcover was created by Joe Berkovitz and some months ago I joined his efforts after I developed an internal tool that followed another approach using only Flash Player APIs. Joe's approach is actually customizing the open source Flex compiler and can therefore achieve object code branch coverage. Join the Flexcover project to keep it going!

During the presentation I’ve mentioned further information about IoC frameworks that my collegue Ed Eustace already put online. Also, Michael Labriola’s presentation at MAX 08 “Testing Flex Applications” spend more time comparing different testing tools. This is not online at Adobe TV yet, but upcoming.

Also check out the presentations from my other colleagues at Adobe Professional Services:

• RIA Development with Cairngorm - Tips from the Experts from Peter Martin and Eric Garza
• Architectural Best Practices for Flex and LiveCycle ES Application from Steven Webster and Tunde Turner
• Television on AIR - Creating Custom Media Player Experiences from Xavi Beumala Segura, John Bennett Kyle Glossy and Mark Hirsch
• Delivering Collaborative Apps with AIR and LiveCycle Data Services from Alistair McLeod and Xavier Agnetti
• Lazy Innovation: Strategy for the Design of Innovative User Experiences from George Neill and Jerome Doran

Before I explain any further, take a look at a running example. I’ve taken the Cairngormstore and added the Flight effect to the point when the user wants to add a product to his shopping cart. Simply click on the “Add to Cart” button to see the effect playing.

The key here is that the product doesn’t immediately appear in the shopping cart DataGrid control as the user presses the “Add to Cart” button. Instead, the Flight effect animates the product into the shopping cart control. Download it here.

What is it?

The flight effect moves a display object either along a straight line or a quadratic bezier curve. While playing the display object is being scaled up and down to mimic a flight object taking off and landing (with using a good bit of imagination)

I’ll explain the usage of this effect with a simpler example. This flight effect is a standard Flex effect, so you can use it in ActionScript, Behaviours, Transitions etc. The following example shows a login panel moving and rotating to the bottom right corner of the screen. It plays in a Canvas container and all we need to set up the effect is to apply a simple Transition tag to the view state change.

   <mx:states>

      <mx:State name="stateA">

         <mx:SetProperty target="{ login1 }" name="x" value="519"/>

         <mx:SetProperty target="{ login1 }" name="y" value="323"/>

      </mx:State>

   </mx:states>


   <mx:transitions>

      <mx:Transition effect="{ mover }" />

   </mx:transitions>

   

   <mx:Sequence id="mover">

      <mxeffects:Flight 

         target="{ login1 }" 

         duration="2000" 

         maximumHeight="2" 

         rotate="true" />     

   </mx:Sequence>

   

   <sides:Login 

      id="login1" 

      change="currentState = ( currentState == 'stateA' ) ? '' : 'stateA';"/>

BTW: Behind the scences, Flight uses a MoveOnQuadCurve effect that I ported from AnimationPackage. You could also use this effect without Flight if you wish.

Flying across Flex container constraints

Since we use a Canvas container in the example above, the Panel component can be moved to arbitrary positions within that Canvas container. However, in some applications, like in the Cairngormstore sample application, we need to move across different containers. How I did this in Cairngormstore and how you can do the same in your applications will be the topic of the next section.

Flight Effect Applied

As pointed out in the end of the last section, the effect by itself isn’t enough if you want display objects to move across Flex containers. This section will show how I achieved this in the Cairngormstore sample application and how you can apply the same concept to your application. You can by the way also use a simple Move effect using the same concept.

But before I start with any implementation, let me please remind you on using this effect responsibly. As with many effects, applied in the wrong way, effects can dramatically reduce the user experience instead if increasing it. Consult a User Experience expert before you apply it to your application.

10000 feet overview

In order to let the flight object (our airplane) cross Flex container boundaries we need professional assistance. A FlightCaptain object can help us with

• starting up our airplane.
• finding our origin and destination coordinates.
• flying the airplane according to a specified route.

If this sounds all a bit strange to you, follow me with a little example.

Let’s fly one box from the black area to the red area.

With clicking the button, the user tells the FlightCaptain to get going:

            var captain : FlightCaptain = new FlightCaptain();            
            captain.airplaneType = Login;         
            captain.origin = login;
            captain.destination = destinationContainer;
            captain.play();

We tell him the type of plane we would like him to use (a custom Panel component of type Login), and the start and destination locations.

In the above example the FlightCaptain creates a new airplane of type Login, flies it to the destination location and once landed, he removes it (he would put it back into the hanger)

But in your specific application, you might want the FlightCaptain to move not just copy the display object that we tell him is the airplane.

We can do that with removing the display object specified with the origin property when FlightCaptain is taking off…

  captain.addEventListener( TweenEvent.TWEEN_START, acualTakeOffTime );

…and adding it to the display list once the captain lands.

  captain.addEventListener( TweenEvent.TWEEN_START, acualTakeOffTime );

Important to note here is that we use the TweenEvent.TWEEN_START event. This event is triggered when the first tween update is performed, meaning we are sure our airplane is in the air (popup is created) and we can safely remove our old display object.

We also have access to the route our FlightCaptain is taking. His route property is a Flight effect. We can i.e. tell him to take a long way round with modifying the xBetween and yBetween properties of route.

captain.flight.yBetween = 1000;

Here’s the full code:

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

<mx:Application 

	xmlns:mx="http://www.adobe.com/2006/mxml" 

	xmlns:sides="view.sides.*" 

	layout="horizontal">

	

   <mx:Script>

   	<![CDATA[

   		import mx.events.TweenEvent;

   		import mx.events.EffectEvent;

   		import mx.core.Container;

   		import view.sides.Login;

   		import com.adobe.ac.mxeffects.FlightCaptain;

         

         private var originContainer : Container;

         private var destinationContainer : Container;

         

         private function fly() : void

         {

         	destinationContainer = ( login.parent == blackBox ) ? redBox : blackBox;

            originContainer = ( destinationContainer == blackBox ) ? redBox : blackBox;

            

            var captain : FlightCaptain = new FlightCaptain();            

            captain.addEventListener( TweenEvent.TWEEN_START, acualTakeOffTime );

            captain.addEventListener( TweenEvent.TWEEN_END, acualLandingTime ); 

            captain.airplaneType = Login;         

            captain.origin = login;

            captain.destination = destinationContainer;

            captain.configureFlight();

            captain.play();

         }

         

         private function acualTakeOffTime( event : TweenEvent ) : void

         {

         	originContainer.removeChild( login );

         }

         

         private function acualLandingTime( event : TweenEvent ) : void

         {

         	destinationContainer.addChild( login );

         }

   	]]>

   </mx:Script>

   <mx:Canvas 

   	id="blackBox" 

   	backgroundColor="black" 

   	width="400" height="400"

   	>

   	<sides:Login 

   		id="login" left="8" top="8" 

   		change="fly()" />

   </mx:Canvas>

   

   <mx:Canvas 

   	id="redBox" 

      backgroundColor="red" 

      width="400" height="400"/>

      

</mx:Application>

How does the FlightCaptain do his job? This section explains how you he manages to fly across Flex containers.

Let’s first take a look into FlightCaptain’s play method.

At first we get the airplane of the specified type…

airplane = getPlaneFromHanger();

…which simply creates a popup using PopUpManager.

private function getPlaneFromHanger() : IFlexDisplayObject
{
return PopUpManager.createPopUp( DisplayObject( Application.application ), typeOfPlane );
}

Then he finds out about the actual coordinates where he is expected to start and land.

var originCoords : Point = findOriginCoords( origin );		
var destinationCoords : Point = findDestinationCoords( destination );         

This translates the local coordinates of our specified origin and destination display objects into a global coordinate system. We need to do this because our origin and destination display objects are potentially deeply nested somewhere between various Flex containers. Our FlightCaptain prefers to fly high up in the sky (in popup coordinate space, which understands global coordinates), therefore we need to translate.

private function findOriginCoords( origin : DisplayObject ) : Point
{
		var originTopLeft : Point = new Point( 0, 0 );
		originTopLeft = origin.localToGlobal( originTopLeft );
		return originTopLeft;
}
		
private function findDestinationCoords( destination : DisplayObject ) : Point
{
	var destinationTopLeft : Point = new Point( 0, 0 );
	destinationTopLeft = destination.localToGlobal( destinationTopLeft );
	return destinationTopLeft;
}

Have fun with it!

Lighting works on all effects supplied. Here’s how it looks like on CubeRotate:

But see all the effects in action from this example. Download it here directly.

Also, Tink has released a new Flex effects library (efflex.org) that also adds distortion effects. I’d definitely recommend checking out Tink’s work or even considering participating in this new exciting open source project. Great work Tink!

Here is How You Can Use it:

Generally you define a lighting source. When your lighting source is located on the top left then the effects will turn brighter once your display object turns towards the top or left.

To do that you just have to set two properties

• -horizontalLightingLocation takes either a LEFT and RIGHT value (use DistortionConstants for setting this or FlexBuilder’s code hints).
• -verticalLightingLocation takes either TOP or BOTTOM.
• -lightingStrength is an optional property, which defaults to 7.5 if not set.

Lighting is turned off by default. To activate it you just need to set either the horizontalLightingLocation, verticalLightingLocation or both properties.

Thanks for all your tremendous feedback on the previously released distortion effects. Some of that feedback is now included in this updated version. This version adds various features and updates. Here’s an excerpt:

Exceed Bounds

Much of the feedback I’ve received was about making the flip effect more realistic. The hint was to let its bounds overlap while the flip effect is coming towards the user. (flipping in). The new exceedBounds property on the Flip effect does exactly that and is now turned on by default!

Pop mode UP

The Pop effect now has an additional mode. The default mode is DOWN, which pops a display object off a stack/pile, away from the user. The new UP mode pops it towards the user.

Some of you have experienced issues with distortions done on display objects that are below other display objects, which are being scaled. You can scale display objects either using UIComponent’s or DisplayObject’s scaleX, scaleY properties or with modifying the DisplayObject’s transform matrix (a and d properties). This version of the distortion effects supports any scalings applied to any parent display objects in your display list.

Support of More Environments

My goal with these effects always was to support all possible environments where you can use these effects and distortions. With environments I meant i.e. using distortions or utilities in a non Flex framework environment, using only the Flash Player API. But also the use in different Flex framework containers and effect setups, i.e. States and Transitions, hideEffects, ActionScript effects, with ViewStacks, custom containers etc.

This version increases the number of environments to support to the point that I currently haven’t heard of an environment that isn’t supported. If you have one, let me know and feel free to send me an isolated example and I’ll try to help out.

This version added support for some States and Transition usages i.e. with supporting multiple siblings and improves error handling in case views cannot be initialized.

See them in action here.

Download here!

"How should I best create a popup in my Cairngorm application?"

I think of creating a popup control as something only views should be concerned about. It’s like creating other view components, managing states of view components or effects. Therefore this question isn't just about creating popups, instead it's about how to invoke methods that belong to the view. (BTW: I often hear from our User Experience team that they try to prevent popups where possible)

However, most of the use cases that came up when questions like the above have been asked are slightly more complex. Users for example want to create a popup in a completely different part of the application. Or they receive an asynchronous remote service response, only want to react to the user with a popup at that point in time and work in a context where no view references are available, such as a typical Cairngorm Command.

Some users have created the code needed for creating a popup directly in the result method of a command or in a model object that’s been called by the result method of a command.

Sticking to my above rule; that only views should be concerned about popups, I think both solutions are not the optimal approach. A command should just be an encapsulated request to your model and a model itself should also not be concerned about any UI behavior. I’d argue we need to tell the model about the state change that has just occurred in your application, but in a model context. For example you might set a loggedIn property on a Login model object to true in order to signal that the login process was successful after a positive remote service response.

So, how can our views react to that state change in our model?

In a typical Cairngorm application, we may bind UI controls to properties of our model objects. But for creating a Popup control, there’s no UI component where we can bind to. How do we best let a view invoke a view related method after a certain state change in our model occurred?

Let’s take a step by step approach using a very simple Cairngorm application, that retrieves a list of employees and displays them in a popup after successful retrieval.

Please do ask your UX team if something like this is really a good idea in a real world application. For the sake of this example we don’t care about the user experience here!

This step by step tutorial will walk you through the relevant parts. You can see and download (via right click > View Source) the complete application here. Let's go:

Dispatch a Cairngorm Event.

Let the view dispatch a user gesture via a Cairngorm Event in order to trigger the remote service:

On a mx:Button’s click event, the getEmployees method dispatches the Cairngorm event:

Excerpt from GetEmployeesCommand.as:

private function getEmployees() : void
{
  	var event : GetEmployeesEvent = new GetEmployeesEvent();
  	event.employees = model.employees;
  	CairngormEventDispatcher.getInstance().dispatchEvent( event );
}

Call and handle the remote service and modify your model.

The handling GetEmployeesCommand’s execute method calls a server side method. Its result method modifies the model. Here, it retrieves the model object Employeee via the ModelLocator.

Excerpt from GetEmployeesCommand.as:

private var employees : Employees;
		
public function execute( event : CairngormEvent ) : void
{
	employees = GetEmployeesEvent( event ).employees;
	employees.hasEmployees = false;
			
	var delegate : EmployeeDelegate = new EmployeeDelegate( this );
	delegate.getEmployees();
}
		
public function result( event : Object ) : void
{
	employees.employees = IList( event.result );
	employees.hasEmployees = true;
}

Employees.as:

package com.adobe.cairngorm.samples.popup.model
{
	import mx.collections.IList;
	
	public class Employees
	{
		[Bindable]
		public var employees : IList;
		[Bindable]
		public var hasEmployees : Boolean;		
	}
}

Note that we modify the hasEmployees property of the Empoyees model object.

Let the view react react for you!

And here comes the crux: You can use the mx:Binding tag or the Observe/ObserveValue tag to invoke a view method, once the hasEmployees Boolean value changes.

I’d recommend using the ObserveValue tag to listen to a specific value of a state change of your model. More precisely, you can bind the source property of it to the bindable hasEmployees property of your model object Employees.

<ac:ObserveValue 
	source="{ model.employees.hasEmployees }" 
	handler="{ createEmployeeList }" 
	value="{ true }"/>

You could have also used the Observe tag to listen all updates of the hasEmployees property. For more information, check this out.
The ObserveValue tag above will invoke the createEmployeeList method defined in a Script block of the same MXML file. This method will invoke the popup.

private function createEmployeeList() : void
{
	var application : DisplayObject = DisplayObject( Application.application );
	var popup : IFlexDisplayObject = PopUpManager.createPopUp( application, EmployeeList, true );			
	PopUpManager.centerPopUp( popup );
	var concretePopup : EmployeeList = EmployeeList( popup );
	concretePopup.employees = model.employees;
}

That's it! Through a state change in your model, you view has reacted. Furthermore, you can now let many other objects observing this particular state of your model and they can all act independently.

Cheers!

I think the question behind the question we're addressing here is not whether to use Code Behind, MXML Script blocks or View Helpers, but is actually where is it best to place functionality in a Flex application.

But first of all, let’s have a quick rundown on what Code Behind, View Helper and MXML Script blocks actually are:

The Script block is the part of an MXML file dedicated to ActionScript methods and properties.

For example:

<mx:Script>
	private function doSomething() : void
{
		blah…
}
</mx:Script>

For a View Helper, people might have different definitions. Personally, I’d define a View Helper as an ActionScript class that a MXML can call and listen to directly. Typically it contains the code related to the accompanying MXML and might even simply contain the functionality that developers otherwise would put in MXML Script blocks. It can have references to the view, such as the Cairngorm View Helper (which are not a recommended approach). I’d call ActionScript classes that help the view with more defined and fewer responsibilities utility classes. Utility classes usually don’t have references to views. They could i.e. be formatters.

Personally I find Code Behind is indeed a nice and quick way to organize functionality. However, I’d argue that if you would move code from a MXML Script block into a Code Behind class, you’re just changing the location and potentially rough syntax of that code. After this “refactoring”, your code still lives in the same context.

In a middle and larger scale application i.e. using Cairngorm, I’d advocate extracting functionality from views into unit-testable model and utility classes. IMHO such classes are best created when they don’t contain any references to views and few responsibilities. They should be simple ActionScript classes without dependencies on other contexts such as view components.

I’m not saying you couldn’t unit-test Code Behind classes. It is like unit-testing Cairngorm View Helpers, people have done this and are doing it successfully. However, I just find it easier to unit-test and also reuse classes that contain defined functionality adhering to OOP rules. If you keep your functionality in view code, this functionality often has much more responsibilities to keep track of.

Once you're focusing on extracting the right functionality from your views and commands into unit testable utility classes and an application model deciding if you'd rather have Code Behind, View Helper or an MXML script block becomes less of an important decision to take. Once you've extracted functionality out of views, the view code left, isn't usually that big. Just converting this view code into a different syntax (Code Behind, View Helper or MXML script block) doesn't necessarily make it much better.

And here is the Flex 2.0.1 version.

Behind the scenes, these effects are using the DistortImage utility from the open source 3D Engine Sandy. Make sure you check out Sandy if you haven’t yet! The effects included are called Flip, CubeRotate, Push, Pop, Door and Gate. But instead of talking about them, just see them in action for yourself:

Distortion Effects

This sample application lets you play with all effects available. You can also see different configurations, i.e. try enabling the blur checkbox.

<?xml version="1.0" encoding="utf-8"?>
<mx:VBox 
	xmlns:mx="http://www.adobe.com/2006/mxml" 
	xmlns:sides="view.sides.*"
	xmlns:mxeffects="com.adobe.ac.mxeffects.*">
        
	<mxeffects:CubeRotate 
		id="flipIn" 
		target="{ login }" siblings="{ [ registration ] }" 
		direction="RIGHT" duration="1000"/>
	<mxeffects:CubeRotate 
		id="flipBack" 
		target="{ registration }" siblings="{ [ login ] }" 
		direction="LEFT" duration="1000"/>
        
	<mx:ViewStack id="loginViewStack">
        
		<sides:Login 
			id="login" 
			title="Login" 
			hideEffect="{ flipIn }" 
			change="loginViewStack.selectedChild = registration;"/>
		<sides:Registration 
			id="registration" 
			title="Registration" 			
			hideEffect="{ flipBack }" 
			change="loginViewStack.selectedChild = login;"/>
	
	</mx:ViewStack>
	
</mx:VBox>

And here is how it looks like using States and Transitions:

<?xml version="1.0" encoding="utf-8"?>
<mx:Canvas 
	xmlns:mx="http://www.adobe.com/2006/mxml" 
	xmlns:sides="view.sides.*" 
	xmlns:mxeffects="com.adobe.ac.mxeffects.*">
	
	<mx:states>
		<mx:State name="registrationState">
			<mx:RemoveChild target="{ login }"/>
			<mx:AddChild>
				<sides:Registration 
					id="registration" title="Registration" 
					change="currentState = ''" />
			</mx:AddChild>
		</mx:State>
	</mx:states>
	
	<mx:transitions>
		<mx:Transition fromState="" toState="registrationState" 
			effect="{ flipFront }"/>
		<mx:Transition fromState="registrationState" toState="" 
			effect="{ flipBack }"/>
	</mx:transitions>
	
	<mx:Sequence id="flipFront">		
		
		<mxeffects:CubeRotate 
			target="{ login }" siblings="{ [ registration ] }" 
			direction="RIGHT"/>
		
		<mx:RemoveChildAction target="{ login }"/>
		<mx:AddChildAction target="{ registration }"/>				
	</mx:Sequence>
	
	<mx:Sequence id="flipBack">		
	
		<mxeffects:CubeRotate 
			target="{ registration }" siblings="{ [ login ] }" 
			direction="LEFT"/>
			
		<mx:RemoveChildAction target="{ registration }"/>
		<mx:AddChildAction target="{ login }"/>				
	</mx:Sequence>
	
	<sides:Login id="login" title="Login" 
		change="currentState = 'registrationState';"/>
	
</mx:Canvas>

You can also create your own customized Flex Framework Effects using base and utility classes of the distortion effects. Make sure you check out the chapter 15 of Creating and Extending Flex 2 Components (flex.org > Documentation) for more information on Flex Effects customizations.

Distortions

Independently of effects, you can also use the source code to create your own distortions using the com.adobe.ac.mxeffects.Distortion. The API can be very simple i.e. like:

var distortion : Distortion = new Distortion( login );
distortion.push( 50, DistortionConstants.TOP );

For more customized distortions you can use the distortion explorer, which is also included in the download.

The Flex 2 Framework is free but still, you might not able to use it because you create extremely lightweight (filesize) content or/and developing with the Flash IDE (Flash Professional 9 ActionScript 3.0 Preview). Anyway, you can still make use of distortions with using com.adobe.ac.mxeffects.SimpleDistortion.

Determining Filter Bounds at Runtime

And independently of effects and distortions, you might want to use the com.adobe.ac.util.DisplayObjectBoundsUtil if you’re looking for how to determine the bounds (width and height) of a display object at runtime that might have filters applied. Check on SimpleDisplayObjectBoundsUtil if you can’t use the Flex framework.

For usage, just add the included DistortionEffects.swc into your project, check out the included sample applications and let me know how you get on with it!

UPDATED: I've published a blog entry to an updated version here. The source code and example links on this blog entry contain the updated version.

I’ve been using the binding approach and that made it very easy and flexible to do. But as I said in my last post, this can have one slight drawback you have to consider. In this post I’ll showcase the drawback and provide a solution to it via an extended version of Paul’s Observe tag. Furthermore, this extended version of Observe makes it even easier to perform this kind of listening to the model.

There are multiple ways to use binding. All of them require a source that defines what property you want to listen to and a destination that defines what shall be triggered once your source changes.
You can either use the MXML curly braces syntax, function binding, the mx:Binding tag or define bindings in ActionScript.

Either way, you have to be careful in triggering application code in a destination of a binding, which we've done in previous examples of my Dashboard sample using either function binding to trigger a formatter or mx:Binding to invoke a view related method.
Since the Binding feature hides us from many exceptions that would have been thrown using EventDispatcher, it cannot differentiate in certain situations when certain; to us important, exceptions are thrown in our application code that is triggered in the destination. Let's showcase this and throw one of these "certain" exceptions on purpose in our latest Cairngorm Dashboard sample. Let's throw one that I'm sure you've have seen before: The one and famous:

ErrorID 1009: "Cannot access a property or method of a null object reference."

Change the createChargedMessage setter to:

private function set createChargedMessage( value : Boolean ) : void
{
        var o1 : Object = {};
	o1.o2 = {};
	trace( "show o2 " + o1.o2 );	
	o1.o2 = null;
	o1.o2.foo = "bar"; //oops, o2 doesn't exist, an exception should be thrown.
	trace( "show foo " + o1.o2.foo );
	if( value ) Alert.show( "Thanks! Your bank account has been charged" );
}

Since this code is triggered as a destination of the mx:Binding tag, the runtime exception that should appear on

o1.o2 = null;
o1.o2.foo = "bar";

is swallowed by the binding code in the Flex framework. You will not see the usually expected runtime exception displayed via the Flash Debug Player. Instead, the following code like the trace( "show foo " + o1.o2.foo ); will just not execute.

Note, that this will only happen with certain exceptions. It will only happen on the following exceptions:

• Error #1006: Call attempted on an object that is not a function.
• Error #1009: null has no properties.
• Error #1010: undefined has no properties.
• Error #1055: - has no properties.
• Error #1069: Property - not found on - and there is no default value

For more information on these errors take a look at Run-Time Errors of Adobe Livedocs.

Note also, that this will only happen when your application code in the destination executes in the same ActionScript block. This means if your exception throwing code executes in a different frame (as would usually be the case on a custom effect) you will see a runtime exception as expected.

However, if your application code does throw one of the swallowed exceptions in the same ActionScript block, there are ways so you can see this immediately.

You could use a special debug class in the Flex framework to help you see the error message. Use
mx.binding.BindingManager.debugBinding( <your destination as a String> );

But in a production environment I'd recommend you use another more bullet-prove way of solving this problem. You can use the extended version of Paul’s Observe tag.

<ac:Observe 
	source="{ stockTransaction.stockPurchase.isComplete }" 
	handler="{ createChargedMessage }"/>

Using Observe you can invoke a method instead of the setter.

private function createChargedMessage( value : Boolean ) : void
{
	if( value ) Alert.show( "Thanks! Your bank account has been charged" );
}

Try putting the code from above that will throw a runtime exception into the createChargedMessage method. Observe will make sure that a runtime exception is being thrown as expected.
Internally, Observe wraps another global Error handler around your destination, saves the exception thrown and throws it in the next frame.

Furthermore this approach offers an additional feature for your convenience. If you want to listen to only a specific value of the source, you can use ObserveValue for this. In our use case of the iteration 6 Cairngorm Dashboard we just want to know when the isComplete property of our StockPurchase object is true.

<ac:ObserveValue 
	id="observe" 
	source="{ stockTransaction.stockPurchase.isComplete }" 
	handler="{ createChargedMessage }" 
	value="{ true }"/>

private function createChargedMessage() : void
{
	Alert.show( "Thanks! Your bank account has been charged" );
}

I've mentioned above that this also applies to function bindings. In StockMarketPod.mxml of the iteration 6 Cairngorm Dashboard sample application, I've used the provided Observe.execute method in order to ensure a secure use of our function binding, which tirggers a custom formatter.

<mx:Label text="{ observe.execute( statusFormatter.format, stockTransaction.status ) }"/>

You can download the Observe and ObserveValue utility classes from here.

Hope this helps!

Furthermore, our customer wants us to show a pop-up as soon as a successful stock purchase is being made. I’ll cover how a state change in your model can transparently cause view related code (like creating a pop-up) to be executed.

In iteration 5 we had a statusMessage field in both model objects, StockQuote and StockPurchase. Two separate text input fields have listened to these properties. Now, let’s only have one status message for both model objects. This i.e. could bring us to the idea of creating another object that encapsulates StockQuote and StockPurchase. Let’s call it StockTransaction:

package com.adobe.cairngorm.samples.dashboard.model
{
	public class StockTransaction
	{
		[Bindable]
		public var stockQuote : StockQuote;		
		[Bindable]
		public var stockPurchase : StockPurchase;		
		[Bindable]
		public var status : int;
		
		public function StockTransaction()
		{
			stockQuote = new StockQuote();
			stockPurchase = new StockPurchase( stockQuote );
		}
	}
}

Note that in the above, I’ve changed the previous statusMessage property; which was typed as a String, to a status property; which is typed as an int. I’ve done that so our model objects can only be concerned with a status of our use case and not with the presentation of this status. I think the presentation of the status is something that our views should be responsible for.

Our model objects can contain the different status options they can be in. i.e. our new StockQuote object can have an ERROR and a SUCCESS status, showing that the StockQuote retrieval was either successful or not. So, we can define the states with two values.

public static const ERROR : int = 1;
public static const SUCCESS : int = 0;

In our new GetStockQuoteCommand we can decide in what state the StockQuote object is currently in. Here’s a snippet of it:

public function onResult( event : * = null ) : void
{
	//for demo purpose: event would normally be an event object of remote service result.
	stockTransaction.stockQuote.lastStockQuote = event as Number;			
	stockTransaction.stockQuote.isPending = false;
	stockTransaction.status = StockQuote.SUCCESS;
}
		
public function onFault( event : * = null ) : void
{
	stockTransaction.stockQuote.lastStockQuote = NaN;
	stockTransaction.status = StockQuote.ERROR;
	stockTransaction.stockQuote.isPending = false;	   	
}

There are various ways to achieve a similar separation of concerns. In this application however, I'll let the StockMarketPod.mxml view listen to the value of status and depending on the status value, StockMarketPod will display a String, which is defined on this view. StockMarketPod uses a helper class called StatusMessageFormatter that translates the status property into the correct String needed by the view. This helper class is initialized like this:

<view:StatusMessageFormatter 
	id="statusFormatter" 
	statusMessages="{ [ '', 'Quote retrieval error.', 'Purchase error.', 'Purchase succesfull.' ] }"/>	

I listen to the status via a function binding on the status property. For more information on this you can take a look into the full source code for this application at the end of this post.

Flex 2 make it easy to perform refactorings like this. This is very important since refactorings of your model objects can occur all the time and most often you rarely get it right the first time around. ;)

Iteration 6 - Invoking View Related Methods

As said in the beginning of this post, our customer wants us to alert the user via popup when a stock purchase request has successfully been made. Let’s think of creating a simple Alert window (mx.controls.Alert). When the onResult handler of the PurchaseStockCommand is invoked we know a stock purchase has been completed.

I think of creating an Alert control as something only views should be concerned about. It’s like creating other view components, managing states of view components or effects. I think only views should be responsible. Usually we bind UI controls to properties of our model objects. But for creating an Alert control, there’s no UI component where we can bind to. How do we best let a view invoke a view related method after a certain state change in our model occurred?

I basically see two ways to do this from a model. We could manipulate a model object so it dispatches an EventDispatcher event that the view can listen to. We could also just mark properties of our model as Bindable and let our views subscribe to either a custom event name that you have defined in our Bindable metadata (with [Bindable(event="customEventName")]), or to the default "propertyChange" event. Using the propertyChange event your view's event handler method would have to differentiate what property changed. You can do that with the passed in mx.events.PropertyChangeEvent object. Listening to a custom event name defined in the Bindable metadata, we have to dispatch the event manually using dispatchEvent.

I see two drawbacks using this approach. First of all, it’s more code to write and most importantly, to read. This is because your views need to subscribe manually to events and define event handlers. It might also affect your models since some of them might need extra EventDispatcher functionality. Secondly, we need to make sure that our model objects exist when the view is subscribing to the event.

The latter is something binding gives us for free. We can bind to a state change of a model even if the model isn’t initialized at the time of subscription. Furthermore, using the binding approach is just quicker to do in many cases.

Following the binding approach, we can bind to a property of our model objects and invoke a method in our views with using the mx:Binding tag.

This could look like the below:

private function set createChargedMessage( value : Boolean ) : void
{
	if( value ) Alert.show( "Thanks! Your bank account has been charged" );
}

<mx:Binding 
	source="stockTransaction.stockPurchase.isComplete" 
	destination="createChargedMessage"/>	

Now, instead of using mx:Binding I recommend that you use an extended version of the Observe tag that Paul Williams originally blogged.

This can make your code more secure, and furthermore it does also give you a slightly easier API to solve the problem here. We only need to listen to the "true" value of the isComplete Boolean. Therefore, we tell our new utility exactly this.

<ac:ObserveValue 
	id="observe" 
	source="{ stockTransaction.stockPurchase.isComplete }" 
	handler="{ createChargedMessage }" 
	value="{ true }"/>

The createChargedMessage will be reduced to this:

private function createChargedMessage() : void
{
	Alert.show( "Thanks! Your bank account has been charged" );
}

For more information on why I’ve introduced this utility class, please read the follow up post on this topic, "Using Binding Securely".

Summary

What have we done here?

We needed our view to invoke a view related method based on some state change in our model. First, we’ve changed the state in the model with invoking a Command. The Command located our model object via ModelLocator and changed the state of this model object via its API. Because our view subscribed to this specific state change (via binding in our case), it could react to it with invoking a method. Since it was using mx:Binding, we didn’t need any extra ActionScript to setup the binding, neither did we need a MXML component that would accept a return value (which we didn’t have since we were calling a popup).

As I’ve noted above, there’s also one little drawback on how we use the binding approach here.

For more information on the drawback and a solution to it with an additional feature please read the next post, "Using Binding Securely"

As after every post in this series, you can view the application and download the source code of it via right mouse click > View Source.

Leveraging Flex 2 and Flash Player 9 for Truly Cinematic Experiences

and I’d like to give you more information where this will be about, in hope you consider joining my session!

I’ll talk about how cinematic effects can dramatically improve the user experience of a Rich Internet Application and can contribute significantly to the success of how your RIA will translate the experience that your costumer wants to deliver.

You will see new types of effects and learn best practices toward their use and creation.

I’ll showcase a variety of different effects but most importantly I'll showcase a new type of cinematic effects, leveraging the performance improvements, the new bitmap manipulation features and the new Effects Framework in Flex 2. You'll be given ideas and complete source code for these new type of effects and will be able to create your own customized effects based on the principles demonstrated.

One of these effects is a flip effect. I’ve a little teaser for you here:

See the Flip effect

How this is done, how you can use it in your own work and how all the other effects look like…stay tuned for MAX 2006!

Future of AnimationPackage

Some of you might know that I’ve developed AnimationPackage, an ActionScript 2 library for Flash and Flex 1.x developers. I’ll outline how I see the future of this framework and how I see it fitting alongside the Flex 2 effects framework.

See you soon, on the
25. October, Wednesday, 1:45 p.m
and the
26. October, Thursday, 3:00 p.m.
in Las Vegas!

I'm excited!

The previous posts (part 1, part 2) were primarily about the infrastructure of a very simple single and multiple view dashboard application. This and the following posts will add further functionality to the application with the indent to demonstrate how your model objects become a focus point of your application.

In particular, we'll add validation logic, formatting logic and an additional use case.

Let's go back to our single view dashboard and let's first make this application a bit more realistic with simulating a delay for the dummy remote service that is invoked after the user presses the "Get Quote" button. I'll just add a flash.utils.setTimeout method in our iteration 2 delegate (StockMarketDelegate.as) to simulate a delay.

Usually, while a remote service is being processed, the UI is supposed to react to it with i.e. displaying a progress or disabling certain UI components to let the user know that further requests cannot be dispatched. In our use case we'd like to disable the "Get Quote" button while a remote service call is being processed. We can achieve this easily with adding a property to our representing model object from iteration 2 StockQuote. Let's call it isPending and make it a Boolean where our view can bind to.

[Bindable]
public var isPending : Boolean;

Adding Validation Logic

Let's add a validation of our stock quote with inspecting the actual stock quote value. We can easily use the mx.validators.StringValidator of the Flex Framework for this type of work.

In our application we need both parameters of validations (isPending and the result of StringValidator) to pass in order to let the UI allow a remote service request. Our model object could have an isValid property, which combines these two parameters of validation. I compute isValid with the following method.

private function validate() : void
{
	isValid = ( isSymbolValid && !isPending );
}

isSymbolValid is a property, which will be the result of our StringValidator.

We could add the mx:StringValidator tag into the StockMarketPod.mxml and have it calling the StockQuote model object on its "valid" and "invalid" events.

<mx:StringValidator 
	minLength="2" triggerEvent="change" 
	source="{ symbolTextInput }" property="text"
	valid="stockQuote.validateSymbol( true );" 
	invalid="stockQuote.validateSymbol( false );"/>

To call a model object directly from the view isn't the clearest form of MVC since views should only dispatch events, which are handled by your controller. But for this example I find it good enough to have a method be called directly from the view. In my humble opinion this use case doesn't justify a "round trip" to the model object just yet. Think: "The simplest thing that could possibly work".

Adding Formatting Logic

This is easy. We want to have our stock quote result being formatted with a currency formatter. You could define the formatter in StockMarketPod.mxml with

<mx:CurrencyFormatter 
	id="standardEuroFormatter"  
	currencySymbol="€" precision="2"/>

and have it formatting with a method binding

<mx:Label text="{ standardEuroFormatter.format( stockQuote.lastStockQuote ) }"/>

Now, let's have a complete look into our StockQuote model object.

package com.adobe.cairngorm.samples.dashboard.model
{
	public class StockQuote
	{
		[Bindable]
		public var lastStockQuote : Number;
		[Bindable]
		public var isValid : Boolean;
		[Bindable]
		public var statusMessage : String;
				
		private var _isPending : Boolean;
		private var isSymbolValid : Boolean;
                
		[Bindable]
		public function get isPending() : Boolean
		{
			return _isPending;
		}
		
		public function set isPending( value : Boolean ) : void
		{
			_isPending = value;
			validate();
		}
			
		public function validateSymbol( isValid : Boolean ) : void
		{
			isSymbolValid = isValid;
			validate();
		}
		
		private function validate() : void
		{
			isValid = ( isSymbolValid && !isPending );
		}		
	}
}

The new isPending state is being manipulated by the GetStockQuoteCommand.

private var model : ModelLocator = ModelLocator.getInstance();
private var stockQuote : StockQuote = model.stockQuote;
	 	
public function execute( event : CairngormEvent ) : void
{
	stockQuote.isPending = true;
	     	
	var stockQuoteEvent : GetStockQuoteEvent = GetStockQuoteEvent( event );	      
	var symbol : String = stockQuoteEvent.symbol;
	var delegate : StockMarketDelegate = new StockMarketDelegate( this );
	delegate.getQuoteForSymbol( symbol );    
}
		
public function onResult( event : * = null ) : void
{
	//for demo purpose: event would normally be an event object of remote service result.			
	stockQuote.lastStockQuote = event as Number;			
	stockQuote.isPending = false;
	stockQuote.statusMessage = "";
}
		
public function onFault( event : * = null ) : void
{
	stockQuote.lastStockQuote = NaN;
	stockQuote.statusMessage = "Quote retrieval error.";
	stockQuote.isPending = false;
}

And let's finally look into our view StockMarketPod.mxml

<?xml version="1.0" encoding="utf-8"?>
<mx:Panel 
	xmlns:mx="http://www.adobe.com/2006/mxml"
	xmlns:util="com.adobe.cairngorm.samples.dashboard.util.*">
        
	<mx:Script>
		<![CDATA[
			import com.adobe.cairngorm.control.CairngormEventDispatcher;
			import com.adobe.cairngorm.samples.dashboard.model.StockQuote;
			import com.adobe.cairngorm.samples.dashboard.events.GetStockQuoteEvent;	
			
			[Bindable]
			public var stockQuote : StockQuote;
			
			private function getQuoteForSymbol() : void
			{
				var event : GetStockQuoteEvent = new GetStockQuoteEvent( symbolTextInput.text );
				CairngormEventDispatcher.getInstance().dispatchEvent( event );
			}
		]]>
	</mx:Script>
	
	<mx:CurrencyFormatter 
                id="standardEuroFormatter"  
		currencySymbol="€" precision="2"/>
		
	<mx:StringValidator 
		minLength="2" triggerEvent="change" 
		source="{ symbolTextInput }" property="text"
		valid="stockQuote.validateSymbol( true );" 
		invalid="stockQuote.validateSymbol( false );"/>
	
	<mx:Form>
	
		<mx:FormItem label="Symbol">
			<mx:TextInput 
				id="symbolTextInput"/>
			<mx:Button 
				label="Get Quote" 
				enabled="{ stockQuote.isValid }" 
				click="getQuoteForSymbol();"/>
		</mx:FormItem>
				
		<mx:FormItem label="Price Quote">
			<mx:Label text="{ standardEuroFormatter.format( stockQuote.lastStockQuote ) }"/>
			<mx:Label text="{ stockQuote.statusMessage }"/>
		</mx:FormItem>
		
	</mx:Form>	
</mx:Panel>

Note, that this version of StockMarketPod.mxml doesn't have a reference to ModelLocator anymore. Instead, the model objects, which are needed, are passed into StockMarketPod.mxml.

<mx:Script>
	<![CDATA[
		import com.adobe.cairngorm.samples.dashboard.model.ModelLocator;
		import com.adobe.cairngorm.samples.dashboard.model.StockQuote;
									
		[Bindable]
		private var model : ModelLocator = ModelLocator.getInstance();
		[Bindable]
		private var stockQuote : StockQuote = model.stockQuote;	
	]]>
</mx:Script>
 
<view:StockMarketPod 
	stockQuote="{ stockQuote }" 
	title="Stockmarket Pod"/>

I find it beneficial to give view components only the information they need instead of global access to all your business logic through a reference of your ModelLocator. Furthermore, this makes view components more reusable across projects.

Optionally; to further increase view reusability, we could also replace CairngormEventDispatcher calls inside StockMarketPod.mxml with view events dispatched via EventDispatcher. We would handle these events outside the view component that we want to make reusable across applications and dispatch the Cairngorm event using CairngormEventDispatcher in order to reach application specific Cairngorm commands.

Download and "view source" the complete iteration 4 example.

Iteration 5 – Adding a Use Case

Let's pretend our customer now wants us to also purchase stocks after a stock quote has been retrieved. We are supposed to add another text input field with a quantity field that defines how many stocks the user would want to buy. Furthermore, we would need a purchase button. The purchase button must only be enabled when the user is allowed purchase a stock quote. This is the case when:

• the quantity field contains a valid value.
• another stock purchase request is not pending.
• a stock quote has been successfully retrieved.

We could use another model object responsible for managing all this. Let's call it StockPurchase. StockPurchase can have a very similar structure than StockQuote. But the third bullet point requires StockPurchase to know about StockQuote's state. Only if StockQuote has been completed, StockPurchase's validation can pass completely. There are various ways to let StockPurchase know about StockQuote's state. For this example I just pass a reference of StockQuote to the constructor of StockPurchase. I'll do that inside an initialize method (here in ModelLocator). This is being called at start up.

private function initialize() : void
{
	stockQuote = new StockQuote();
	stockPurchase = new StockPurchase( stockQuote );   		
}

Here is the full source code of StockPurchase.

And here are the additions to StockMarketPod.mxml including the additional validator and formatter.

A new PurchaseStockCommand finally sends the remote purchase request, handles the response and manipulates the client side model objects accordingly. Our views listen to model object events through bindings and translate the model data according to view related rules. This translation process could be done using view helpers like the mx:CurrencyFormatter used in this sample.

Download and "view source" the complete iteration 5 example.

I hope you've enjoyed my dashboard iterations so far. The most important point I wanted to bring across is how valuable I think it is to think about our model objects and try to extract much functionality out of our views. Going forward this way, I find it's much easier to build unit-testable, flexible and scalable Rich Internet Applications.

In the next iteration I'll cover some additional refactorings on the view and model objects and how state changes in the model can cause view related methods to be executed.

I'd like to give you early access to a new version of the CairngormLogin sample, which we'll ultimately make available on Adobe Labs. We’ve been releasing this very simple example application in earlier versions of Cairngorm alongside the framework code. Intention is to showcase how to get a simple Cairngorm application running. Furthermore, I’ve also upgraded my dashboard samples, which I’ve shown in previous posts.

I’ve also updated the Dashboard examples to work with the latest Cairngorm release. Expect some further updates that actually add some real functionality to this in future.

see and download (right click and view source) the samples here:

• CairngormLogin sample


• Dashboard sample iteration 1


• Dashboard sample iteration 2


• Dashboard sample iteration 3

As Steven Webster mentioned previously, expect more examples from us coming up soon and let us know when you’ve examples to show. I think the more the better!

The signature of Responder has changed to an optional typeless (wildcard type '*') from the mx.rpc.events.ResultEvent and mx.rpc.events.FaultEvent signatures. Here are three reasons for this:

• You can now handle RemoteService, WebService, RemoteObject and non Flex framework remoting responses.
• You can now more easily perform spikes (prototypes) to simulate a server side response. Just place stub data into the delegate and return that to the onResult handler of your Command. Since it’s optional, you don’t have to return any data to the Command.
• If you unit test your Commands, this signature might also be handy.

2. Minor improvements

There have been a number of minor improvements i.e. Cairngorm now prevents to add an already registered Command, the ViewHelper adds and removes itself from the ViewLocator once added or removed from the display list and other minor code refactorings have been performed as well.

3. New Cairngorm Event Dispatcher

This is the most significant change. For Cairngorm Flex 1 users this is familiar as it basically is EventBroadcaster with a more “Flex 2 EventDispatcher-like” syntax.

Here are the corresponding release notes:

In the beta releases of Cairngorm for Flex 2, we departed from the Cairngorm 0.99 approach of dispatching events, and used the new built-in dispatchEvent method with bubbling available on Flex components. However, since bubbling is only available on the display list we had to listen to a top level child on the display list for all events, which we decided to be mx.core.Application.application. In cases where a view reference on the display list below mx.core.Application.application is not available, users had to obtain mx.core.Application.application directly in order to dispatch a Cairngorm event. This was often the case in for example pop-ups and other ActionScript classes without the appropiate view reference. Our experience within Adobe Consulting in delivering Flex 2 projects, coupled with community feedback, has encouraged us to revert to an architecture more like the original Cairngorm 0.99 architecture using EventBroadcaster.

This is indented to encourage developers to have a clear separation of Cairngorm events and application events. The new CairngormEventDispatcher offers exactly this, since only event objects of type CairngormEvent can be dispatched and handled. Furthermore, CairngormEvent has the typeless data property for lazy people. ;) For more information about CairngormEventDispatcher, check out the ASDocs, temporarily available through Alistair McLeod’s blog.

Migrating your Cairngorm Application.

The Flex 2 compiler helps you most with migrating your application. For example it will tell you that the new Responder interface might not be compatible to your pre Cairngorm for Flex 2 application.

However, for larger applications a migration of the event dispatching system from legacy Cairngorm Flex beta Application.application event dispatching to the new event dispatching system using CairngormEventDispatcher could be a bit trickier to accomplish.

The reason is that there could be Cairngorm events that trigger and modify various things while they bubble up the display list till they arrive to the root of the display list and the FrontController. If you would just replace the dispatchEvent calls from the view with CairngormEventDispatcher calls, code that relies on bubbling of events will break. Therefore; in larger applications, this migration should probably not be done in one step.

I've created a little migration Front Controller, which can use both techniques simultaneously, so developers can replace this event dispatching code carefully step by step. Here is a potential migration path that you could perform:

• Delete all legacy Cairngorm framework code with the updated framework. Since it’s a package change, Flex Builder will make it easy for you to spot the places in the application that have to be changed due to Cairngorm 2.
• Now, here’s the ugly part: In order to make this migration work, you’ve got to temporarily change a Cairngorm source file. Open com.adobe.cairngorm.control.CairngormEvent and set the default value of the bubbles property to true. Make sure you reverse this change after your migration. Or better: Use the Cairngorm framework ActionScript source files while you are in a migration period and replace all Cairngorm framework source files with the Cairngorm SWC file that accompanies the latest release of Cairngorm.
• Let your application FrontController extend com.adobe.cairngorm.control.MigrationFrontController instead of com.adobe.cairngorm.control.FrontController.

When you now run the application, you’ll receive logging statements if the deprecated cairngorm event dispatching call is invoked. This logging statement can help you to locate the event and help you to make a decision if it can be replaced without side effects.

using trace

---------------------------------------------------------------------------
 MigrationFrontController.handleDeprecated: Deprecated event dispatching used with:
			event object: com.adobe.cairngorm.samples.dashboard.events::GetStockQuoteEvent
			event.type: EVENT_GET_STOCK_QUOTE
			event.target: Dashboard0.StockMarketDashboard5._StockMarketPod1
			event source: com.adobe.cairngorm.samples.dashboard.view::StockMarketPod
			event.currentTarget: Dashboard0

or using mx.logging:

10:27:59.760 [INFO] com.adobe.cairngorm.samples.dashboard.control.DashboardController 
---------------------------------------------------------------------------
			MigrationFrontController.handleDeprecated: Deprecated event dispatching used with:
			event object: com.adobe.cairngorm.samples.dashboard.events::GetStockQuoteEvent
			event.type: EVENT_GET_STOCK_QUOTE
			event.target: Dashboard0.StockMarketDashboard5._StockMarketPod1
			event source: com.adobe.cairngorm.samples.dashboard.view::StockMarketPod
			event.currentTarget: Dashboard0

Download MigrationFrontController here.

Often, I find use cases where many views of a same type share common functionality. Each view can be represented by a model object. The view can request the appropriate model object from a manager object at start up. For example the StockMarketDashboard.mxml would look like this with additional pods:

<view:StockMarketPod 
	quoteId="quote1" 
	title="Stockmarket first pod"/>
<view:StockMarketPod 
	quoteId="quote2" 
	title="Stockmarket second pod"/>
<view:StockMarketPod 
	quoteId="quote3" 
	title="Stockmarket third pod"/>
<view:StockMarketPod 
	quoteId="quote4" 
	title="Stockmarket fourth pod"/>

Notice that the view needs to send some form of unique identifier to the manager. We add this unique identifier to our StockQuote class.

package org.nevis.cairngorm.samples.dashboard.model
{
	public class StockQuote
	{
		[Bindable]
		public var lastStockQuote : Number;
		[Bindable]
		public var stockQuoteError : String;		
	}
}

The manager object StockQuoteManager, is declared at initialization on the ModelLocator instance. But how does this manager object look like?

Usually, I implement it with a hash map that is keyed by the view’s unique identifier. In the constructor we can initialize the hash map. In Flex 1.x we would have used a generic Object to create a hash map. In Flex 2, I like to use flash.utils.Dictionary, which more clearly shows the indent of the code.

public function StockQuoteManager() 
{
	stockQuotes = new Dictionary();
}

The getStockQuote method either creates or returns a specific StockQuote object based on the view’s unique identifier quoteId.

public function getStockQuote( quoteId : String ) : StockQuote
{
	var key : String = quoteId;
	if( stockQuotes[ key ] == null )
	{
		var stockQuote : StockQuote = new StockQuote();
		stockQuotes[ key ] = stockQuote;
	}
	return StockQuote( stockQuotes[ key ] );
}

The StockMarketPod.mxml almost looks identical to the old version of iteration 2, which refactored ModelLocator properties to the StockQuote model object. We just need to send the unique identifier to the Command, since the Command itself needs to retrieve a StockQuote object from the manager object. So the GetStockQuoteEvent class gets another quoteId property.

In GetStockQuoteCommand we need to store the unique identifier as an instance property since the command needs to retrieve and update the correct StockQuote object in an onResult or onFault handler.

private var model : ModelLocator = ModelLocator.getInstance();
private var quoteId : String;
	 	
public function execute( event : CairngormEvent ) : void
{
	var stockQuoteEvent : GetStockQuoteEvent = GetStockQuoteEvent( event );	     	
	var symbol : String = stockQuoteEvent.symbol;
	quoteId = stockQuoteEvent.quoteId;
	var delegate : StockMarketDelegate = new StockMarketDelegate( this );
	delegate.getQuoteForSymbol( symbol );
}
		
public function onResult( event : ResultEvent = null ) : void
{
	//simulate a result from service
	var lastStockQuote : Number = Math.random() * 50 + 5;
	var stockQuote : StockQuote = model.stockQuoteManager.getStockQuote( quoteId );
	stockQuote.lastStockQuote = lastStockQuote;
	stockQuote.stockQuoteError = "";
}
		
public function onFault( event : FaultEvent = null ) : void
{
	var stockQuote : StockQuote = model.stockQuoteManager.getStockQuote( quoteId );
	stockQuote.lastStockQuote = NaN;
	stockQuote.stockQuoteError = "An error occured.";
}

Also, notice that in the example above we make use of stateless commands. Since the introduction of stateless commands in Cairngorm, new command instances are being created each time a Cairngorm event is dispatched (see Alistair McLeod’s blog entry). You can now securely save instance properties in your commands without fearing that the instance property will be modified by another Cairngorm event. Would your command not be stateless, our quoteId could be overwritten by a quoteId from another stock pod. When the command's onResult is triggered by the incoming response from the first remote service request, the response would map to a wrong StockQuote object. But thankfully, we don't need to think about that anymore. ;)

Spinning it a wee bit further.

Notice, that your manager object could contain other functionality that applies to all pods. Think about a domain model that suits your use case best.

Furthermore, in a slightly more elaborate use case it might be significant that the onResult handler in GetStockQuoteCommand requests the currently up-to-date StockQuote object from the manager object as it does in the example shown. While the command is waiting for a response for a request to a remote service, the state of the RIA could change. When the response comes in, the manager object might want to return a different StockQuote object or not a StockQuote object at all.

For example, the end user might be able to close certain stock quote pods. In this case, its representing StockQuote model object may also have been deleted. On subsequent requests to the StockQuote object, the manager object might want to throw an exception. This exception might be handled differently by the command.

You might want to check out the complete source (right click on the sample app and choose “View Source” or download it as a ZIP file).

Basically, your views bind to properties that are retrieved from your ModelLocator. These properties can be changed from your Commands, other business logic or other views and once changed; all listening views are updated seamlessly.

Since many of the Cairngorm examples out there are meant to be easy to understand, they often just show these properties exposed as single properties on the ModelLocator. Once your RIA grows in size, this indeed can be quite limiting. I’ll showcase another Cairngorm sample application that focuses on how you can improve your architecture with investing in slightly more advanced business logic. The sample application is a stock market dashboard that allows users to retrieve price quotes on a company stock. From time to time I’ll add features to this application, to showcase some possible ways to architect a Cairngorm application. This version of it will use Cairngorm for Flex 2 Beta 3.

But let’s first look at the very simplest possible solution with still leveraging MVC principles advocated by Cairngorm. The stock market dashboard in its first iteration just contains a single pod with minimal UI controls. See example.

With pressing the “Get Quote” button the user dispatches a Cairngorm event that is handled by a Command instance to request a new quote.

StockMarketPod.mxml dispatches the Cairngorm event on behalf of a Button’s click event:

<mx:Button label="Get Quote" click="getQuoteForSymbol();"/>

And the corresponding mx:Script tag:

import org.nevis.cairngorm.samples.dashboard.events.GetStockQuoteEvent;									
private function getQuoteForSymbol() : void
{
	var event : GetStockQuoteEvent = new GetStockQuoteEvent( symbolTextInput.text );
	dispatchEvent( event );
}

GetStockQuoteCommand handles the Cairngorm event and asks a business delegate class (StockMarketDelegate) for a quote.

public function execute( event : CairngormEvent ) : void
{
	var symbol : String = GetStockQuoteEvent( event ).symbol;
	var delegate : StockMarketDelegate = new StockMarketDelegate( this );
	delegate.getQuoteForSymbol( symbol );
}

In a real world scenario this would be most likely a server side call, but for the sake of simplicity in this demo, I’ve commented the code that would be needed to call a remote service in the business delegate.

StockMarketDelegate.as just calls back to the Command immediately. Notice that if the user enters a symbol “fail”, the Command’s onFault handler will be invoked.

public function StockMarketDelegate( responder : Responder )
{
	//disabled for demo
	//this.service = ServiceLocator.getInstance().getService( "stockMarketDelegate" );
	this.responder = responder;
}
		
public function getQuoteForSymbol( symbol : String ) : void
{
	//disabled for demo
	//var call : AsyncToken = service.getQuoteForSymbol( symbol );
	//call.resultHandler = responder.onResult;
	//call.faultHandler = responder.onFault;
	if( symbol == "fail" )
	{
		responder.onFault();
	}
	else
	{
		responder.onResult();
	}
}

Our StockMarketPod view just needs two information from the application’s business logic.

• The answer to the quote (the stock price)
• An error message, that communicates to the user if a request fails.

Because this is so simple, I have just created two properties directly on the ModelLocator.

public var lastStockQuote : Number;
public var stockQuoteError : String;

GetStockQuoteCommand can then just change these values in the onResult or onFault handler. For this demo purpose, it performs some dummy calculations to simulate the remote service result.

public function onResult( event : ResultEvent = null ) : void
{
	//simulate a result from service
	var stockQuote : Number = Math.random() * 50 + 5;
	model.lastStockQuote = stockQuote;
	model.stockQuoteError = "";
 }
		
public function onFault( event : FaultEvent = null ) : void
{
	model.lastStockQuote = NaN;
	model.stockQuoteError = "An error occured.";
}

The StockMarketPod view can bind to those properties and further format the result based on its presentation needs:

<mx:FormItem label="Symbol">
	<mx:Label text="{ formatQuote( model.lastStockQuote ) }"/>
</mx:FormItem>
<mx:FormItem>
	<mx:Label text="{ model.stockQuoteError }"/>
</mx:FormItem>

And the formatting logic of a mx:Script block.

private function formatQuote( quote : Number ) : String
{
	return ( isNaN( quote ) ) ? "" : String( quote );
}

Note that this type of code could be refactored and extracted out from the view into a unit-testable utility class.

Iteration 2 - Creating business logic that fit your needs

Now, the above example is the simplest thing that could possibly work. As your RIA grows in size this can be limiting. You may find that your ModelLocator instance is “overcrowded” with properties that you might even forget what they are needed for. You might also run into naming conflicts with other properties designed for different use cases.

A common refactoring is to create business objects that encapsulate the properties of your use case. These business objects can represent the information that your views need in a business context. You can design them at a granularity that fits your use case best. For example in a larger RIA you might want to think about a number of classes to represent your use case. Your views may then bind to these business objects or to properties of it. Your views might bind to other application objects that translate your business objects to a form that’s more useful to your views.

This way, your ModelLocator might better communicate its intent as it’s much easier for developers to grasp what business logic your application contains.

In our stock market dashboard, we could e.g. encapsulate the lastStockQuote and stockQuoteError properties in a simple business object:

package org.nevis.cairngorm.samples.dashboard.model
{
	public class StockQuote
	{
		[Bindable]
		public var lastStockQuote : Number;
		[Bindable]
		public var stockQuoteError : String;
	}
}

Note, that in a true business object you would probably not even have a property that directly holds a String with an error message. Instead, the business object would just hold an error type and other application objects would translate that error type to e.g. a String representation, which could then be used by views.

Our ModelLocator would just define a single property representing a stock market pod view in a business context. E.g. with

public var stockQuote : StockQuote = new StockQuote ();

And our view would change to this:

<mx:FormItem label="Symbol">
	<mx:Label text="{ formatQuote( model.stockQuote.lastStockQuote ) }"/>
</mx:FormItem>
<mx:FormItem>
	<mx:Label text="{ model.stockQuote.stockQuoteError }"/>
</mx:FormItem>

You might want to check out the complete source (right click on the sample app and choose “View Source” or download it as a ZIP file).