In this Part 2 on Flex l10n solutions, I offer a video tutorial, a demo of a Registration application localized to support Spanish and English, and an architecture diagram of LocalizationMap usages.

Also included with the live Flex demo is source code for both the demo and the l10n LocaleMap library.

Below is a screencast video tutorial; in which I provide a narrated overview of the issue involved with enabling your Flex application to support multiple languages (and locales). I also present LocalizationMaps as a great solution to easily and rapidly provide l10n (localization) features within your custom Flex apps.

Figure 1: Video Tutorial (click to play)

Note that the video/podcast tutorial may take 5-10 seconds for streaming to start.

Shown below is a live demo of the localized Registration application. This application has l10n (localization) support for English and Spanish. In the live demo, select the Spanish or English flags to change the current locale. Watch what happens to all the strings and styles.

Be sure to complete the registration fields and click the Register button to see the view state changes to show a localized Thank you with fullname and email parameters (sounds confusing… just try it)!

Figure 2: RegistrationDemo w/ Locales (click to launch)

Simply right-click to access the source code for both the demo and the l10n LocaleMap library. Or click here to download the source code. Before you review the source code, however, I encourage you to review the architecture diagram shown Figure 3 and listen to the Screencast tutorial (Figure 1).

Here is a high-level diagram that illustrates how the LocalizationMap is used within your custom applications. I encourage you to conceptualize the LocalizationMap as a plug-in to your application… an extension that is completely transparent (hidden) from your presentation/GUI layer.

Figure 3: LocalizationMap Usage Diagram (click to zoom)

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

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