One of issues that frequently confuses, blocks, or complicates Cairngorm implementations is the issue of “view notifications”. Every Cairngorm developer ask the following question at some point: How should the Cairngorm business layer best communicate with the Presentation layer?

Review Figure 1 which illustrates the recommended relationships between the view and control layers:

• Model is a repository for data
• Views support user interactions and announce user gestures as dispatched events to Controllers
• Controllers employ commands to process dispatched events
• Commands are responsible for using Delegates to talk to the server, and updating model data (client side)
• Views use data binding to “watch” Model data changes and self-update to dipslay formatted data.

Commands are supposed to use the Model layer as the mediator between business and presentation layers. In Flex, data bindings and change watchers allow views to watch data models. When data is modified, hidden propertyChange events are dispatched from Models to Views and the View uses event listeners to self-update. This is the basic premise of the Flex Cairngorm MVC framework.

In real-world applications, data binding solutions espoused by Cairngorm MVC are not always sufficient; since such solutions require views to watch for data changes. Some times, however, watching for data changes is complicated… perhaps the data is not globally available. Sometimes the view [that dispatches the business event] is requesting data that should be available only to that specific instance of the calling view; and should not be stored in global repositories. Sometimes, we do not care so much about the data… but instead we want to execute custom code when the event succeeds and finishes.

PureMVC and traditional Cairngorm solutions require complex code and design patterns to solve these situations.

• ViewLocators could be used to try to lookup an instance of a view. (Requires coupling to specific view classes from the business layer…. BAD!)
• Views could employ/register private view controllers with the front controller,
• Command could dispatch new “notify view” events thru the front Controller to the view controller

The above approaches create a proliferation of view controllers and is useful ONLY when multiple views want to listen to the same event and be notified simultaneously. Please note that in such rare situtations, a custom event-bridge or a traditional data binding approach would be more practical [but that is another article]. In fact, in most scenarios, the view simply wants the notification directly and exclusively (only to its instance). For these situations, there is a simpler – and better – solution to the ViewController complexity.

• What if we cannot easily use global data models and view data binding?
• What if we do not want to create an hierarchy of bindable properties simply to deliver data to deeply nested child views?
• How can we deliver data directly to a view instance without storing that data in the ModelLocator hierarchy?
• And… if the View invokes a Command [via event dispatching] and Command/Delegate pairs process server data, how can the Command deliver the processed results back to the View only?

The remarkably easy solution is to use Responders as notification mechanisms to allow Commands to notify Views… just like the way Delegates notify Commands [See Cairngorm Secret Tip #2: Data Transformations within Delegates]. To understand the proposed solution, consider the Cairngorm approach where a Command instance employs a Delegate class as “API facade” to remote data services.

The command instance submits itself [or a proxy to itself] as a responder to the delegate. The delegate, in turn, simply uses the specified responder to direct dataservice responses directly to back to the command. This allows the Command to receive callbacks from the Delegate or the Server. In fact, advance this same approach is used at the Delegate level to allow Delegate instances to intercept server responses, transform data, and then notify/pass the modified data back to the Command.

Using Responders, a Command can submit itself as a callback to specific Delegate calls. Views can effectively do the same with Commands. Figure 2 below illustrates this process or queueing of responses. The queue builds with (1) View waits for a response from the Command, (2) the Commands waits on the Delegate, and (3) the Delegate waits on the Server. The queue unwinds after (4) the server responds, (5) Delegate notifies the command, (6) the Command notifies the view. Using a Responder proxy, the view is notified after the actual dataservice request/response and after Command processing; see Step (6) in Figure 2.

Well, when we dispatch business events to commands, we create custom events. So we simply need to transport a Responder instance along with the normal event information that is dispatched to the Cairngorm control layer. If all custom events have constructors with optional responder arguments then we have a built-in mechanism to support callbacks from Commands.

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

package mx.rpc
{
/**
 *  This interface provides the contract for any service
 *  that needs to respond to remote or asynchronous calls.
 */
public interface IResponder
{
	/**
	 *  This method is called by a service when the return value
	 *  has been received. 
	 *  While <code>data</code> is typed as Object, it is often
	 *  (but not always) an mx.rpc.events.ResultEvent.
	 */
	function result(data:Object):void; 
	/**
	 *  This method is called by a service when an error has been received.
	 *  While <code>info</code> is typed as Object it is often
	 *  (but not always) an mx.rpc.events.FaultEvent.
	 */
	function fault(info:Object):void;
}
 
}

package com.grdlinked.samples.control.events {
 
    import flash.events.Event;
    import mx.rpc.IResponder;
    import com.universalmind.cairngorm.events.UMEvent;
 
    public class LoadUserDetails extends UMEvent {
 
        public static var EVENT_ID : String = "loadUserDetailsBySSN";
 
        public var ssn      : String = "";
        public var password : String = ""; 
 
        // Constructor 
        public function LoadUserDetails( ssn:String,                                    password:String,
                                    callbacks:IResponder=null) {
            super(EVENT_ID, callbacks, true, false);
 
            this.ssn      = ssn;
            this.password = password;
 
        }
    }
}

For the examples in the post, we use a custom event LoadUserDetailsEvent class that accepts an optional “responder” parameter. Using a SSN and password the view requests user details from the control layer. The control/business layer may elect to lookup the user in a client-side cache or call the server. The business layer is responsible for all these details and the presentation/UI layer need not worry. And the view does NOT know anything about who handles the event or how the event is processed. This “separation of concerns” is what MVC is all about.

When the event is processed by the command, the command can temporarily cache the view responder or callback. Sometime later – after the asynchronous data service call responds – the following can happen:

1. the command can use the dataservice response to update the ModelLocator directly, trigger databindings to update, and
2. the command can forward the dataservice response or any OTHER data to the cached responder. Command::notifyCaller() is the method used to provide view notifications.

If your views want to implement the IResponder interface, each one of your views would need to include public result() and fault() functions:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

<?xml version="1.0" encoding="utf-8"?>
<mx:Canvas 	width="400" height="300" 
		implements="mx.rpc.IResponder"
		xmlns:mx="http://www.adobe.com/2006/mxml" >
 
	<mx:Script>
	<![CDATA[
		import mx.rpc.IResponder;
		import mx.controls.Alert;
 
     // Methods required by the IResponder interface		
      public function result(data:Object):void {
            btnLoad.enabled = true;
      }
      public function fault(data:Object):void {
            Alert.show(event.message);
            btnLoad.enabled = true;
      }
 
 
	// Private methods invoked by child controls		
      private function loadUserDetails(ssn:String):void {
            btnLoad.enabled = false;	// disable button while waiting for a response.
 
            // Load the user details for the specified user
            //NOTE how this view will be the responder...
            var callbacks : IResponder = this as IResponder;            var event : LoadUserDetailsEvent = new LoadUserDetailsEvent("435-34-1283", "anonymous", callbacks);
		  event.dispatchEvent(  );   // Cairngorm events self-dispatch directly to the business layer; 
      }
 
	]]>
	</mx:Script>
 
	<mx:Button id="btnLoad" label="Load User" textAlign="center" x="145" y="149" click="loadUserDetails()" width="147"/>
 
</mx:Canvas>

In our example the view needs to know when the results are available; since the load button is disabled until the business layer [and server] responds .

The above code sample shows, unfortunately, how each of your custom views would need to be modified to work as view responders. When the command finishes, it would call something like caller.result(). Unfortunately, the signature of the result() function is ambiguous and does not document which event triggered the result. In contrast a method like onResult_loadUserDetails() explicit documents its purpose.

After a thorough slapping, ask that developer this question:
“What if I had two buttons that each dispatched separate business events and each needed separate response handlers? How could the result() function be the common event handler for both events? Would I have to somehow detect – inside the result() method – which event is responding?”

As you can see, this solution rapidly creates nasty code and rapidly produces nasty, convoluted, unmanageable code.

So instead of requiring an abomination of view interfaces or view inheritance (which is even worse), the view will instead create an instance of a Responder class that will serve as a proxy responder class. The Responder class will redirect result() and fault() calls to methods that we specify. Let us look at some code for clarity. Below we see an example of custom view component created to load and display user details.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

<?xml version="1.0" encoding="utf-8"?>
<mx:Canvas 	width="400" height="300" 
		xmlns:mx="http://www.adobe.com/2006/mxml" >
 
    <mx:Script>
    <![CDATA[
		import mx.rpc.IResponder;
		import mx.controls.Alert;
		import mx.rpc.events.FaultEvent;
		import mx.rpc.Responder;
 
 
     private function loadUserDetails(ssn:String):void {
          // Load the user details for the specified user
          var callbacks : IResponder           = new Responder(onResults_loadUserDetails, onFault_loadUserDetails);          var event     : LoadUserDetailsEvent = new LoadUserDetailsEvent(user.ssn, user.password, callbacks);
 
          btnLoad.enabled = false;	// disable button while waiting for a response.
          event.dispatchEvent(  );	// Cairngorm events can self-dispatch to the business layer.	  
     }
 
     // ***************************************************
     // Private EventHandlers for the loadUserDetails()
     // ***************************************************
 
     private function onResuls_loadUserDetails(user:UserVO):void {
          // The SSN and password were authenticated; here are user details
          _user = !user ? new UserVO() : user;
          btnLoad.enabled = true;
     }	
 
     private function onFault_loadUserDetails(event:FaultEvent):void {
          Alert.show(event.message);
          btnLoad.enabled = true;
     }
 
     private var _user : UserVO = new UserVO();			
 
    ]]>
    </mx:Script>
 
	<mx:Text text="Please enter your credentials to edit your account:" x="16" y="30"/>
 
	<mx:FormItem label="FullName:" x="23" y="208">  
		<mx:Label text="{_user.fullName}"/> 
	</mx:FormItem>
	<mx:FormItem label="SSN:" x="54" y="104">  
		<mx:TextInput id="txtSSN"  text="{_user.ssn}" width="129"/> 
	</mx:FormItem>
 
	<mx:FormItem label="Password:" x="23" y="70"> 
		<mx:TextInput id="txtPassword" /> 
	</mx:FormItem>
 
	<mx:Button id="btnLoad" label="Load User" textAlign="center" x="145" y="149" click="loadUserDetails()" width="147"/>
 
</mx:Canvas>

Commands – after the processing is finished – will trigger any cached IResponders::result() methods to notify the sender [View] of the event.

In the code example above, look at line 15 where we use a Responder instance to act as a proxy for the functions that we want to call. The Responder class does NOT know any details about the view itself. It simply has functions that may be called upon an event response. For a successful response, the view wants onResults_loadUserDetails() to be called. Likewise for failures, the view wants onFault_loadUserDetails() to be called. With responders, the view essentially provides event handlers for Command post-processing.

To summarize the above code snippet as psuedo-code, you (a) use a responder proxy wrapper class, (b) package the responder instance inside the event, and (c) extend the command base class to support the caching of the callback/view responder. And voila’ you are done!

This is VERY clean:

1. your views are still standard mxml or as classes with aggregates and composite controls,
2. event dispatching is the same [with an optional callback] and
3. you do NOT have to create crude view controllers to handle view notifications
4. each view instance can have its OWN, separate callback
5. views can then support modal operations, undos, reverts, commits, etc… completely independent of each other.
6. you can dispatch as many business events as desired; each with their own event/response handler methods.

Better yet, this functionality is built into the Cairngorm Extensions (CGX) using both the Callback and the mx.rpc.Responder classes. CGX is an open-source extension to cairngorm. If you are interested in this and other Cairngorm extensions provide comments to this blog or or visit Google Cairngorm Extensions.

© Thomas Burleson for GridLinked to RUX, 2009.             Subscribe by Email | Contact Author             Permalink | 41 comments

One aspect of those designs was to create a sense of depth [and engage the user] by judiciously highlighting key components with lighting and reflections. Many of the resulting storyboard pages contained 2 or more components with reflections.

Manually creating a reflection requires 20 or more steps and about 60 seconds to complete… for each component. I will not bother listing each step… it is non-trivial and tedious [and the code at the bottom of this blog shows you the details]. There had to be a way to automate the process. I realized that a Fireworks Command was the solution!

With a Fireworks command and associated hot-key, I could automate 20+ steps and many mouse movements to a single command. And I could easily invoke that command using a hotkey. Wow! But how would I create the command if I did not know the Fireworks API? Before we solve the automation issue, let’s first see what the Reflection command actually does. Then we will learn how to create such a command.

Click on any of the thumbnails below to see the examples of using a ‘Create Reflection’ command.

Below is an outline of the process you can use to create your own reflection command. Let Fireworks record all your steps and save those steps as javascript code. Then you can fine-tune that code as desired:

1. Open the History panel and make sure the history is clear,
2. Manually create a reflection with the 20 or more steps (painful details not included),
3. In the History palette, select the steps that match the process to create the reflection,
4. Using the History Menu, select the ‘Save as Command…’ menu option,
5. Specify the name ‘Create Reflection’ and click OK
6. Edit the javascript command code to perform as desired:
   1. Use a text or code editor to open the ‘Create Reflection.jsf’ file (directory location below),
   2. Modify the code to programmatically support clip height, opacity, offsets, etc.
   3. Save modified command file,
   4. Return to Fireworks, select a object, and invoke the ‘Create Reflection’ command
7. Did your changes work? If not go to Step (6) make more coding changes and iterate…

Fireworks Commands Directory (Mac OS X)

But where [which directory] should you open/edit/save the ‘Create Reflection.jsf’ command file? Click the thumbnail on the right to zoom for details.

After the challenging [and fun] time invested to create my own working command, my ‘Create Reflection’ works great. The Ustrive2 developers loved using it for their own design efforts.

With the code [shown below] and a copy of the ‘Create Reflection.jsf’ command file, it is my hope that you will also enjoy using this command.

Below is the javascript code contained in the link for your own Create Reflection.jsf command (click to download):

/*
 * CreateReflection is a Fireworks Command that creates a vertical reflection [of the currently selected items].
 *
 * This is an incredible timesaver and allows the designer to quickly create reflections for anything.
 * When 1 or more items are selected in the current canvas area, those items are:
 *   1) Duplicated, flipped vertically, and flatten (original items are unchanged and deselected)
 *   2) The flattened copy is cropped to the top 40 pixels
 *   3) A gradient alpha mask is applied to the cropped image
 *   4) Both the mask and image are flattened and opacity set to 20%
 *
 * TODOs:
 *    1) Add support to skew/distort the selected images and reflection (for 3D perspective effect)
 *    2) Create runtime UI dialog to request clip height, offset, opacity, and skew parameters
 *    3) Check for no items currently selected and posting feedback to designer
 *
 * Author:  Thomas Burleson, Flex/Groovy Consultant
 *
 *          Blog    @ http://www.gridlinked.info
 *          Profile @ http://www.LinkedIn.com/in/ThomasBurleson
 *          eMail   @ ThomasBurleson@gmail.com
 *
 *
 * Date:  Feb 24, 2009
 */ 
 
var OFFSET         = 4;
var REFLECT_HEIGHT = 40;
 
var dom            = fw.getDocumentDOM();
var reflections    = new Array();
 
// Copy and flip selection, move to OFFSET below the original, and flatten to bitmap 
dom.clipCopy();
dom.clipPaste();
 
dom.group();
dom.reflectSelection(false, true, "autoTrimImages transformAttributes");
dom.flattenSelection();
 
var bounds = dom.getSelectionBounds();
dom.moveSelectionBy({x:0, y:bounds.bottom-bounds.top+OFFSET}, false, false);
 
// Clip image to REFLECT_HEIGHT,
bounds = dom.getSelectionBounds();
bounds.bottom = bounds.top + REFLECT_HEIGHT;
dom.setSelectionMask( {  maskBounds:bounds, 
                                       maskKind:"rectangle", 
                                       maskEdgeMode:"hard edge", 
                                       featherAmount:0, 
                                       maskData:null }, 
                                    "replace");
dom.exitPaintMode();
dom.cropSelection(bounds);
 
// Cache the reflection...
reflections.push(fw.selection[0]);
 
// Build an alpha clip mask and set transparency to 20%
dom.addNewRectanglePrimitive(bounds, 0);
dom.setBrushNColor(null, "#ffffff00");
dom.setFillVectorStart({x:bounds.left, y:bounds.top});
dom.setFill( { category     :"fc_Linear", 
			   ditherColors :[ "#000000", "#000000" ],
			   edgeType     :"antialiased", 
			   feather      :0, 
			   gradient     :{ name:"cn_Custom", nodes:[ { color:"#ffffff",  isOpacityNode:false, position:0 }, { color:"#ffffff",  isOpacityNode:false, position:1 }], opacityNodes:[ { color:"#000000",  isOpacityNode:true,  position:0 }, { color:"#00000000",isOpacityNode:true,  position:1 }] }, 
			   name         :"fn_Linear", 
			   pattern      :null, 
			   shape        :"linear", 
			   stampingMode :"blend opaque", 
			   textureBlend :0, 
			   webDitherTransparent:false });
 
// Cache the alpha mask
reflections.push(fw.selection[0]);
 
// Select the reflection and alpha mask, then group and set opacity...
fw.selection = reflections; 
dom.group("mask to image");
dom.flattenSelection();
dom.setOpacity(20);
 
// DONE!

After this tutorial, you should explore more solutions and start creating your own cool Fireworks commands. I will let you figure out how to assign a hotkey sequence to a command. With commands and hotkeys, your design life becomes FUN!

If you extend or enhance ‘Create Reflection’, please send me a copy And don’t forget, please comment and rate this article (rate by select the star levels) below.

© Thomas Burleson for GridLinked to RUX, 2009.             Subscribe by Email | Contact Author             Permalink | 3 comments