Blog

It seems every Flex or Flash application I build eventually needs to have a ton of data garnered from the server upfront. In Cairngorm, an application framework for Flex, you typically use Commands to get your data. They have the option of utilizing a Business Delegate to make the actual call in case any data-massaging to and/or from the server needs to take place.

The issue becomes, however, a good written command is dumb; it does just what its name implies such as “get the user data” which is named GetUserDataCommand. While Cairngorm does provide an abstract base command class for you to extend to allow commands to be chained, you still have no clue when they’ve completed, nor the success or failure of such completion. You cannot make them too smart, however, because they suddenly aren’t portable.

For example, we have an application that has about 4 states that are applicable on start up. Does the user need to register? Does the user need to update their register information? Is the user registered, do they have existing form information? If so, what is that data?

This is accomplished by passing in the necessarey information via the URL. Those variables are then handled in a FrontController fashion to determine the application’s state at startup. While this works well, getting the specific data in order doesn’t. Asking the server-side guy(s) to give us the data in a different function, or even all of it in one complicates things not just for them, but for us. Granted there are plenty of reasonable changes, but this isn’t one of them. So, we end up needing to get data in a specific order.

Now, I could create a specific command specifically for this purpose. Since you can tell when a Business Delegate is done, you can have 1 command call 3 Delegates, in order, to get the data you need.

…however, this is a gregarious abuse of the reusability of Commands , and while isolated, you are effectively duplicating logic, and duplication of anything in code is bad. Quoting from The Pragmatic Programmer, be DRY – Don’t Repeat Yourself.

The simplest approach is to have all Commands to support callbacks. Callback handlers were how components back in Flash MX were created to allow events to be dispatched. Built in classes such as XML had supported such things since Flash 5; XML.onLoad = thisFunction; which translates to “XML, when your onLoad is fired, please call this function and pass in whether or not you failed”. This eventually graduated to the EventDispatcher style of dispatching events with context about those events in an object, and is now built-in into ActionScript 3 & Flash Player 8.5 with actual Event classes to allow strict typing, both at compile time and runtime.

Now, Commands don’t need to dispatch events. They themsevles are stateless, much like the XML object is. The XML class loads XML, and hands it to you when it’s done. Commands are the same way; they get data and stick it in a globally accessible place when they are done. The difference here is you have no clue when they are done.

It is reasonable to pass in the callback functionality to an event in the event.data. Commands that need context can pull data off of the event object that is passed into their execute method. This same entry mechinism can be utilized by also passing in a callback. “When you are done, please call this function”.

In Flex 2, this will have to be more strict, but in 1.5 you can be loose and not call the callback if there is no callback to call. Therefore, your Commands aren’t forced to abide by this way of doing things. Only 3 Commands out of the 27 I’m dealing with actually utilize a callback.

The way I approached it was to create a responder class which holds a callback function, and the scope to call it in. This responder class instance is passed into the Command. The Command keeps a copy of it, and when he has completed whatever it is he does, he calls the callback function.

That way, those who are dispatching events, and thus running commands know when they are done if they need to.

It’s important to note that since Cairngorm actually creates 1 instance of all Commands at startup, a Command will actually keep a reference to this callback for the life of the application. Thus, it’s imperative that you clear a callback object if none is passed in to ensure that no old callback data is retained and thus called. ARP doesn’t do this because ARP’s Controller creates and executes Commands when they are called, and doesn’t keep a reference to them.

The ideal thing to do is to utilize an interface so that only some Commands can utilize this feature, and it’s explicit which ones do and which ones don’t, but you know how deadlines go…

The steps:
– create a SimpleResponder class
– import into whatever class is dispatching the events to run commands (since you run Commands in Cairngorm by broadcasting an event)
– create an instance of the SimpleResponder class, passing in your callback function and scope
– stick this an object with the name “callback_obj”
– pass that object as the 2nd parameter to broadcastEvent
– if there is a callback in the event.data in your command, set it to the Commands’ internal reference, otherwise, delete the commands internal reference
– when the Command is done, call the runCallback function on the callback object, and pass any information about success or failure as a parameter(s)

Here is some pseudo code of the SimpleResponder class:

class SimpleResponder
{
        // scope the method is invoked in
        public var scope:Object;
        // a function that will be called when a Command is done
        public var method:Function;
        
        // when creating an instance, pass in the scope and function
        function SimpleResponder(p_scope:Object, p_method:Function)
        {
                scope = p_scope;
                method = p_method;
        }
        
        // this function is called when a Command is done
        // arguments are optional, but encouraged
        public function runCallback():Void
        {
                method.apply(scope, arguments);
        }
        
        public function toString():String
        {
                return "[class SimpleResponder]";
        }
}

Here is how you create a SimpleResonder class instance from whatever class is broadcasting the event via Cairngorm’s EventBroadcaster:

var sr:SimpleResponder = new SimpleResponder(this, onUserInfoReturned);

Broadcast your event like you usually do, and add your object as the 2nd parameter with the field name of “callback_obj”. This will be placed on the Event’s data property, and you can then access it by name in the Command’s execute method:

EventBroadcaster.getInstance().broadcastEvent( Controller.GET_USER,
                                              {callback_obj: sr} );

In your Command class, define a property up top to hold a reference to the callback_obj:

private var callback_obj:SimpleResponder;

In your Command’s execute method, inspect the Event’s data property to see if it has a callback_obj, and if so, store a reference to it internally, otherwise, set it to null explicitly to ensure the Command doesn’t retain state from past calls (don’t have to do this in ARP):

if(event.data.callback_obj != null)
{
        callback_obj = event.data.callback_obj;
}
else
{
        callback_obj = null
}

Finally, when your Command is completed, typically in your onResult or onFault functions defined in your Command, call the runCallback function, and pass in either a true or false… or whatever you want:

callback_obj.runCallback(true);

Your controller class, or whatever class is issuing commands, can then have a function defined looking like this to know when a Command is completed:

public function onUserInfoReturned(bool:Boolean):Void
{
        // show success or failure
}

This is a great way of handling server state because now you know exactly where things failed. This allows more control over what is shown when a server call is being made. You can now show a Loading window for example, and remove it when a call is completed instead of the default wait cursor. Even better, if you have multiple calls, you can utilize a ViewStack in your Loading Window to showcase many states of the linear operation (or non-linear if 5 unrelated calls for example) to know exactly which one is done, and actually visually represent that.

That’s a lot better than, “Um… the call failed, it must be the server guy’s fault, let’s go to lunch!” Now you, and the user, can see visually where it failed and why.

The downside is, the pontential for a race condition exists because if the same Command is called more than once, the later callback will overwrite the first, thus ensuring the first call never returns it’s result to those that care to know about it. I’m sure this can be easily fixed; either by changing how Cairngorm’s FrontController works (creating Commands on the fly vs. creating all initially on app startup), or by associating an ID… tons of ways, I’m sure.

When creating cell renderers in Flex (for use in Lists & DataGrids), using containers can be advantageous. Whether you use an ActionScript class, or an MXML one, centering things and controlling the layout of how your cell renderer works is a lot easier with say, an HBox.

Example, we have one DataGrid cell that represents a rating, and as a list of customers is shown in the grid, the rating goes from 0 to 5. I show a number of stars for the cell based on what the rating value is passed into the cell renderer’s setValue function.

Now, without a container, I’d have to create a position based on how many I created; usually just incrementing a number and adding the width of the previously created MovieClip.

HBox? Just call createChild in a for loop… done. 3 lines of code. Best thing is, you can later control horizontal & vertical centering and other properties since it’s all built into the box model (think DIV tags).

…one thing I forgot, however, was how all Containers extend ScrollRect. Meaning, if the content they hold is larger than they are, they will automatically show scrollbars so you can see the content. Just like a web browser works for example. You need to manually turn these off so the cell renderer doesn’t squeeze scrollbars in your List or DataGrid. Simply:

public function init():Void
{
        super.init();
        
        hScrollPolicy = "off";
        vScrollPolicy = "off";
}

Just a quick note, if you emailed/im’d me and I didn’t respond, sorry, been working 24/7 on-site finishing up the first round of a Flex project. Get up, drive an hour to work, work till 11’ish, drive an hour home, pass out, repeat. Email? Bills? Laundry? F-that stuff, yo. Code, code, and more code. Starbucks Dinner. Then code some more.

Preface

My last Flex 1.5 project completed at the end of December utilized ARP with my change to the Controller. I worked with 1 server-side ColdFusion developer, my boss. Therefore, utilizing a customized version of a mainly Flash orientated framework wasn’t that much of a business risk. ARP has a lot in common with Cairngorm architecturally, so re-factoring it to utilize Cairngorm instead wouldn’t be that much work nor time, even if not done by someone familiar with ARP, but familiar with Cairngorm.

Why would you do this? Most Flex developers utilize the Cairngorm framework, and thus are immediately familiar with how any given Flex application is put together if it uses Cairngorm.

This new project I’m working on utilizes Cairngorm. It’s about the same in scope in terms of size, but more work is required on the client than on the server. We are mainly utilizing 1 1/2 year-old services, so there are literally no bugs on the back-end because it’s been working for so long with other services and ColdFusion components. I’m working with 1 other client developer, and 1 back-end ColdFusion developer, my boss.

Production Art

I had already spent a tad over a week working feverishly to get the main Views done. Basically, taking what the designer (art director? don’t know his title…) did in a series of Fireworks PNG files, and working the design into Flex. Production art basically, and what I’ve been doing for 7 years. I sure hope Sparkle does away with that part of my job. While there is a good feeling of accomplishment that arises from porting a design into an actual application the likes of which make Java developers drool, there is no reason I should be doing it. It is a common task, and something that sets Flex & Flash RIA’s apart from any other current implementation. It is one of their strengths, and Adobe should be capitalizing on it. Adobe dropped the ball with it back in 1998 when Macromedia’s Fireworks 2 was owning with Director 7; they were too busy showing off ImageReady’s palette features when no multimedia developer gave a flip and wanted instead to have Photoshop support 32-bit PNG’s. So let us hope with the merger, people like me can… you know, actually code and get $*** done. That’d be neat. I don’t mind screwing with margins all day to get things right and getting paid for it; it’s what web developers and I have in common. I just know me and many others could be immensely more productive if this common and old bottleneck in the production process was removed.

This week was spent integrating my Views into the being-built project. Copy folder, paste folder into another folder, and point all image embeds to another folder. Not so bad to get into a framework, eh? Well, View’s are portable, so no brainer there.

ViewHelpers

…however, the guy I’m working with, a veteran of Cairngorm, started doing something weird that I wasn’t used to. He started implementing ViewHelper’s in all of my important Views. To give some context, my co-worker borders on an OOP Purist and has had extensive experience in large production workflows. Therefore, it is not difficult for him to justify why you do certain things a certain way. We make a pretty good team because I’m the opposite; I just want the ho to compile. If OOP helps me, cool, otherwise, I got things to do.

So, rather than doing what I should and read the documentation about ViewHelpers, I had a quick debate while discussing Cairngorm with another developer not on the project. I promised myself I wouldn’t form an opinion and blog about it till the project was over, but after 2 days, I changed my mind.

I’ll write this before I go read the documentation real quick to challenge my assumptions. Basically, to me and borrowing words from my co-worker, a ViewHelper helps separate the actual code business logic of a View and the presentation of the View. One could go so far as to say MXML for GUI and AS for logic, but that’s not true. Even if you utilized an external AS file for your script tag, there are still millions of justifiable cases for using ActionScript with MXML to get the desired View to work, even with no business logic whatsoever, merely GUI related stuff. Therefore, ViewHelpers are strictly for those who are “using” the View, “those” referring to other Views or other developers. Without opening the file, reading through the code and MXML to get an idea of how it works, instead, a ViewHelper provides a set of methods that deal specifically with populating the View with data, getting data from the View, and other common operations that have nothing to do on the surface with GUI logic.

Before I call bull$h1t on that last statement, let me copy what the docs say about ViewHelpers.

Used to isolate command classes from the implementation details of a view.

In order to carry out their function, Command classes will require to both interrogate and update the view. Prior to performing any business logic, the Command class may require to fetch values that have been set on the view; following completion of any business logic, the final task often to be performed of a Command class is to update the View (user interface) with any results returned, or perhaps to switch the View entirely (to a different screen).

By encapsulating all the logic necessary for interrogating and updating a particular View into a single helper class, we remove the need for the Command classes to have any knowledge about the implementation of the View. The ViewHelper class decouples our presentation from the control of the application.

A ViewHelper belongs to a particular View in the application; when a ViewHelper is created, its id is used to register against a particular View component (such as a particular tab in a TabNavigator, or a particular screen in a ViewStack). The developer then uses the ViewLocator to locate the particular ViewHelper for interrogation or update of a particular View.

Notice my explanation is selfish, “I’m a developer, utilizing a framework that helps me. Therefore, I want to know what is in it for me.” My explanation stands by the fact that I feel ViewHelpers are for removing complexity from other developers, removing their need to actually understand how the View’s actually work. This pretty much mirrors my co-workers explanation as well, who I trust.

Do I acknowledge this as valid? Sure. When your application gets above 30 Views, at least for me, you start to get really pressed to remember what each View does, what it is named, and where it is in location to other views. For example, “Dude, what form houses that little title and list thing? Like, that’s it’s own class, right? Where is it again? In the com.company.project.view.controls folder?”

This gets worse if you spent the better part of a week doing back-end code interfacing by writing Commands and Delegates, and you return to the View’s folder to start wiring things together, and you draw a blank. This is worse when you actually open the View and have to remember how it works.

Now, add, oh, 5 other developers to the mix. That is an unacceptable load of confusion for 5 people to have for the latter problem. I can see how using ViewHelpers would allow a developer to go, “Ok, I know this View needs this data that this Command will return; apparently I just call this method from the Command… cool.”

Brainless. Suddenly, rather than spending time moving from “business logic” to “implementation details of getting that data from the server” to “shoe-horning that data amongst display logic” is cut down to 2 steps which are more related anyway; “I got the data, and throw it here.” Nice.

For extremely big projects, makes sense. ViewLocator’s, basically used to get a ViewHelper by merely using a String, make this extremely easy and portable when used in Commands.

My issues with ViewHelpers

I have serious issues with this. First off, I’ve never seen big projects succeed, so doubt it works in practice. I’m not denying they do succeed, I’ve seen them do so, it’s just I personally have never been involved in such projects. Those that do that I can see reported on blogs are by extremely talented individuals, which makes me attribute their success more to towards their developer talents vs. a framework paving the way. However, take that with a grain of salt, because almost all I have read all admit and exclaim (as much as developers exclaim, me excluded) appreciation for Cairngorm/ARP. I still just cannot see how removing know-how on how Views work empowers success.

Can you read code?

While I admit it is challenging going from a “all data, no GUI” workflow to a “all GUI, no data” workflow in the course of 20 seconds, that’s still no excuse in my opinion for a developer not to have to read code. Sure, you are more than welcome to ignore my 300 line algorithm that creates & destroys controls to make the View dynamic, but for crying out loud, you CAN read “public” and “setData”, right? All script tags are up top in MXML to make the MXML component a class, and thus are in a predictable place. Granted, with ActionScript classes, things are not always so predictable location wise, but if a developer does what she/he is supposed to do, and repeats the same style throughout, then there should be no issue finding the public functions, right?

…am I suggesting to learn the style of 30 developers? Hell no, you should be following an at least mildly mentioned development standard such as “all public functions go at the bottom of a class” or “all of our View’s use this Interface for setting data” or something to that effect.

The Command who knew too much

Next, the fact Commands know anything at all about View’s, even if it’s through a ViewHelper, still feels wrong to me. Commands are touted as portable, and yet here they are taking data to a specific View; using a ViewHelper as a go-between does not illustrate encapsulation to me in the slightest. It’s a feint and I’m not taking the bait.

When I first learned about using Commands in ARP, suddenly my _root timeline in Flash (or my Application.mxml code in Flex) was reduced form thousands of lines of code to 500 or less. That’s a pretty bad ass concept! That exuberance, however, led to me treating Commands as a “sliced up and organized Controller code chunks”, which actually makes them too smart. My co-worker told me that Commands are really actions the user can take in using the application, and I agree; “SaveUser”, “DeleteSomeItem”, etc. Therefore, tying commands that have flexible usage to a specific View removes their inherent flexibility.

I’ll admit I still haven’t figured out the best way to spew out data that the Commands get. For simple ones, it’s easy to call the result function that the Controller specifies, and go true or false, “Yeah man, it saved.” or “No dude, it didn’t save.”. Even XML.onLoad does that pretty well, and no one has issues; it is very straightforward.

But at least I’m leaving that up to the Controller to handle since he is the one who is supposed to dictate which View gets what data if it isn’t already bound to it.

This is something both ARP and Cairngorm both do that I don’t like; giving too much power to Commands over Views. This is because I view Commands as chunks of executable code that are liaisons to the back-end, not field officers with delegated authority over parts of my visible application.

Project Scope – The Pragmatic Contention

Finally, and this is merely pragmatic: most projects I do are 2 to 5 developers, not 30 developers. I’d argue you give me a bad ass Java developer, 2 other client developers with a good attitude, and a competent manager who will stand her/his ground against scope creep, and we can produce some serious amount of work that actually works.

ViewLocators

ViewLocators? Ok, I’ll somewhat concede ground on this guy. I’ve had 2 projects in my entire career where I HAD to have the Controller know about a deeply nested View. While event bubbling discussed by Ralph and I, solves the need for a deeply nested View to inform high command about some action, having high command rely instructions to that deeply nested view was a bitch; complete pain in the ass consisting of using a bucket-bridge technique of defining proxy functions. Meaning, the main View defines a function for the clear and explicit purpose of passing the function call down the chain to it’s nested View, who in turn does the same function definition, until you finally arrive at the View who houses your target View, and relay’s the command.

Stupid, and only justified by deadlines. A ViewLocator on the other hand handles this eloquently by using a string to get access to a ViewHelper by name, and calling the method. Nice.

…too bad I still dislike ViewHelpers, but I still don’t deny the ViewLocator’s validity.

Command Creation Differences in ARP & Cairngorm

On a side-note, one thing I noticed differently about ARP & Cairngorm is that ARP creates Command classes on the fly; meaning, when the command is executed, the Command class has an instance created. In Cairngorm, Command class instances are created at the beginning of your application’s startup, and they thus remain in the FrontController’s hash array (a.k.a. associative array, a.k.a. Object). I’ve been going back and forth on this, and I still don’t know which has the better implementation. No one not-working for Adobe’s Flash Player team (cept for 1 dude, and his entry was wiped from the face of Google) knows how the Flash Player Garbage Collection works for Flash Player 7. Flash Player 8 is a little documented via Tinic Uro; he even wrote an example of where creating 1 member variable is better than creating many local variables that use optimized registers merely because it’s easier for the Flash 8 garbage collector to remove them (can’t find the link). Bottom line, you only ever actually run 1 Command anyway in Cairngorm, so creating them all at startup, and just keeping 1 instance around is great from a GC perspective. However, this removes the ability for Commands to retain knowledge via member variables on a case by case basis if there is only ever 1 instance. Hell, even Event objects in Flash Player 8.5 have member variables. So, while Cairngorm is apparently more GC friendly as best we can guess, ARP lends more flexibility in Command usage.

Both ARP and Cairngorm do the “event triggers command” thing that I hate. By dispatching an event, this magically triggers a Command that you map at authortime in the Controller class.

Conclusions

In conclusion, I couldn’t live without ARP or Cairngorm. Not having a framework to develop small to large applications is a fate worse than death and I’m glad they were created; they empower me to be successful. As much as I bitch about the concepts, you don’t see me creating my own framework; I instead still continue to use and promote theirs! I just want them to be better, is all, and some of my challenges are merely so I can learn more about them and their implementation in projects through discourse.