My integration of ExtJS, ajaxCFC and ColdFusion continues.

Note: This is for version 3.3.1. I’ve also been happily playing around with version 4, but until it’s officially released, I must continue building with 3.3.1.

Anyway, here’s what I was trying to solve. When I want to allow users to serach for items from a ComboBox, I configure a store, and inside the store, I configure an Ext.data.HttpProxy to hit a separate ColdFusion page that performs a query and returns the results.

Standard HttpProxy Method

var WidgetStore = new Ext.data.Store({
    proxy: new Ext.data.HttpProxy({
        url: 'liveQueries/widgets.cfm'
    }),
    reader: new Ext.data.JsonReader({
        root: 'data',
        totalProperty:'totalRecords'
    }, Widget)
});

ColdFusion ‘Live’ Query

<cfsetting enablecfoutputonly="true">

<cfparam name="query" default="">

<cfquery name="chargeCodes" datasource="#getDatasource().getName()#">
SELECT UNIQUE widget_seq_no, identifier, descr
FROM 	widgets
WHERE 	(REGEXP_LIKE(identifier,<cfqueryparam cfsqltype="cf_sql_varchar" value="^#query#">,'i')
   OR REGEXP_LIKE(descr,<cfqueryparam cfsqltype="cf_sql_varchar" value="^#query#">,'i'))
   AND widget_type_cd='SNAPPYDS'
ORDER BY identifier asc
</cfquery>

<cfscript>
jsonBean = createobject("component","ajaxCFC.JSON");
jsonEncodedCriteria = jsonBean.encode(data=chargeCodes, queryFormat="array");
writeOutput(jsonEncodedCriteria);
</coldfusion>

<cfsetting enablecfoutputonly="false">

I hate this, because I already am using my Ext.AjaxCFC class to query my ColdSpring beans asynchronously, so why do I have to set up these standalone ColdFusion pages to performs queries that should be executed in the component?

I decided to take matters into my own hands, and I have to give the ExtJS team props again, because it was easy to accomplish by extending the Ext.data.MemoryProxy class. As you can see, all I need to do is override the doRequest() method to execute Ext.AjaxCFC.request() with the data passed in during initialization.

Ext.ux.data.AjaxCFCProxy.js

Ext.ns('Ext.ux.data');

Ext.ux.data.AjaxCFCProxy = Ext.extend(Ext.data.MemoryProxy, {
   constructor : function(data){
      Ext.ux.data.AjaxCFCProxy.superclass.constructor.call(this);
      this.data = data;
   },
   doRequest : function(action, rs, params, reader, callback, scope, arg){
      this.data.data.query = params.query;
      Ext.AjaxCFC.request({
         bean : this.data.bean,
         method : this.data.method,
         data : this.data.data,
         success: function(rs) {
            var result = reader.readRecords(rs);
            callback.call(scope, result, arg, true);
         },
         error: function(results) {
            Ext.MessageBox.alert('Load Failed', 'Unable to load requested data');
         }
      });
   }
});

New and Improved Combobox for Searching

WidgetSearch = new Ext.form.ComboBox({
    minChars:           2,
    loadingText:        '',
    itemSelector:       'div.search-item',
    triggerClass:       'x-form-search-trigger',
    emptyText:          '',
    width:              300,
    listWidth:          0,
    store: new Ext.data.Store({
        // I've extended the base Ext.data.MemoryProxy()
        // class to use the AjaxCFC object for searching
        // instead of having to use a liveQuery. Much cleaner.
        proxy: new Ext.ux.data.AjaxCFCProxy({
            bean    : 'Widget',
            method  : 'search',
            data    : { source_table : 'WIDGET' }
        }),

Now that I’m a heavy user of the Sencha ExtJS framework, I thought it would be useful to port the jQuery.ajaxCFC.js file over to an Ext.AjaxCFC.js file that extended the native Ext.data.Connection class and utilized the Ext.Ajax object.

Took me about half the day, but I finally got a working Ext.AjaxCFC.request() method that uses the same syntax as the $.AjaxCFC() method. For those familiar with the inner workings and code of the jQuery AjaxCFC class, this will look very familiar.

So now I can make AJAX calls using native ExtJS classes, access ColdSpring beans in my application’s bean factory, or connect directly to any CFC

Ext.AjaxCFC.js

Ext.AjaxCFCConnection = Ext.extend(Ext.data.Connection, {
   data        : null,
   queryFormat : 'array',
   factory     : (typeof(__ajaxConfig) == 'undefined') ? null : __ajaxConfig.beanFactory,
   timeout     : (typeof(__ajaxConfig) == 'undefined') ? 30000 : __ajaxConfig.defaultTimeout,
   url         : __ajaxConfig.url,
   bean        : null,

   request : function(arguments) {
      var params = (typeof(arguments.data) == 'undefined') ? {} : arguments.data;
      arguments.params = {};
      arguments.params['C0-ID']         = (Math.floor(Math.random() * 10001) + "_" + new Date().getTime()).toString(),
      arguments.params['method']        = 'init';
      arguments.params['component']     = arguments.component;
      arguments.params['bean']          = (typeof(arguments.bean) == 'undefined') ? this.bean : arguments.bean;
      arguments.params['factory']       = this.factory;
      arguments.params['C0-METHODNAME'] = arguments.method;
      arguments.params['queryFormat']   = (typeof(arguments.queryFormat) == 'undefined') ? this.queryFormat : arguments.queryFormat;
      arguments.params['C0-PARAM0']     = params;

      arguments.url = this.url + '?method=' + arguments.params['method'];
      arguments.method = 'POST';
      arguments.failure = arguments.error;
      arguments.timeout = this.timeout;

      var ____success = arguments.success;

      arguments.success = function(data) {
         data = data.responseText.replace(/^\s*|\s*$/g, '');

         if (data.substring(0,9) == '__json__:') {
            data = Ext.util.JSON.decode(data.slice(9));
         }
         ____success(data, this);
      };

      if ( params ) {
         if (typeof params != 'string') {
            arguments.params['C0-PARAM0'] = Ext.util.JSON.encode(params);
         }
      }

      Ext.Ajax.request(arguments);
   }
});

Ext.AjaxCFC = new Ext.AjaxCFCConnection();

Usage

// Include Ext.AjaxCFC code
<script type="text/javascript" src="js/Ext.AjaxCFC.js"></script>

// Default configuration properties for the ajaxCFC library
__ajaxConfig = {
   'url':'/myApp/ajaxCFC/ajax.cfc',
   'defaultTimeout':30000,
   'beanFactory':'application.beanFactory'
};

// AjaxCFC call using Ext.data.Connection class
Ext.AjaxCFC.request({
   bean: 'AColdSpringBean',
   method: 'aMethod',
   data: {
      'id': 416198,
      'first_name': 'Steve',
      'last_name': 'Brownlee'
   },
   success: function(details, s){
      DataStore.loadData(details);
   },
   error: function(results){
      Ext.MessageBox.alert('Search Failed', 'An unexpected error occurred. Please try again.');
   }
});

Alex Uhlmann officially announced the release of Cairngorm 3 beta on October 5th, and from my limited access to the documentation and code, I have a few opinions.

Cairngorm 3 != MVC

I think that it is a positive thing that Adobe Consulting decided to take their hat out of the ring of application architecture providers. The next release of Cairngorm is a complete paradigm shift for the project, in that it is – to simplify it a bit – a set of best practices and support libraries that developers can use within an application architecture such as Mate, Swiz or Parsley.

After I learned this fact, I was surprised that they kept the same project name, but it is a strong brand which will retain the current developer base and level of interest.

I also think that it lays the groundwork for a more free-market environment for other application architectures available today, or soon to be available. I know that a large consideration we made at my company was that since Cairngorm was produced by Adobe Consulting, that it would always be a strong contender, and most likely the proverbial 400-pound gorilla. Now that there is not an “official” application architecture supported by Adobe, then the weight of the brand is removed from the decision making. Now becomes about who has the architecture that is best implemented, best documented, easiest to integrate, etc.

It’s Smart Business

Looking at it strictly from a consulting business perspective, this approach to application development support is much more sustainable and has higher revenue-generating potential. If a shop chose to implement the Cairngorm 2 architecture, they may require assistance initially to get up to speed but eventually they become highly proficient and that well dries up.

In addition, it limits their business to people who implement Cairngorm 2.

Now that Cairngorm 3 can enhance and extend any architecture available – since it is about applying best practices – their consulting possibilities are now limitless. It doesn’t matter if you choose to use Mate, or PureMVC, because the Cairngorm 3 libraries can enhance them to support enterprise Flex development.

It’s a win-win situation. They get more business and more expertise, which in turn generates more ideas for Cairngorm, and makes their package more useful as time goes on.

Past Imperfect

However, I now wish I could turn back the clock 1 year and change the decision we made to implement Cairngorm 2 architecture. After doing internal testing of the major packages available, Cairngorm was not our main choice from a technical perspective, but was the top contender from the business perspective, and so we bit the bullet and adapted.

At the time, Mate was my choice for our application development efforts, and now we may have the discussion again internally about moving over. I know it won’t happen, for we’ve invested far too much time and effort into adopting Cairngorm, but I at least want to have the conversation.

Exciting Times

Lastly, I will say I am excited about this new direction that Adobe has taken, and we’ve already begun to play around with some of the code in-house. I’ll post reviews once I’ve had a chance to digest most of it.

The intended purpose for the AbstractEvent class in Cairngorm was three-fold:

1. Reduce the number of files needed to manage business events by organizing Events into domains
2. Implement a callback feature so that a view can specify another action to perform upon the successful completion of an event
3. Make each domain event class as lightweight as possible

Related Posts

Abstract Commands | Abstract Delegates

Concept

To accomplish these goals, each domain event (e.g. ProjectEvent, PaymentEvent, etc.) would be polymorphic (kinda) in that there is no longer just one identifier designated with the EVENT_ID constant. In addition, I wanted to abstract as much functionality and classification as possible into a common class that each domain event would extend.

Lightweight, Polymorphic Event Class

Here’s an example of a domain event. It has three public identifiers – CREATE_PROJECT, LOAD_PROJECTS, DEACTIVATE_PROJECT- and has no logic other than to pass its constructor’s arguments to AbstractEvent.

ProjectEvent.as

package business.events
{
   import com.adobe.cairngorm.control.CairngormEvent;

   public class ProjectEvent extends AbstractEvent
   {
      public static const CREATE_PROJECT:String = "createProject";
      public static const LOAD_PROJECTS:String = "getProjects";
      public static const DEACTIVATE_PROJECT:String = "deactivateProject";

      public function ProjectEvent(type:String, data:Object = null, callbacks:Array=null)
      {
         super(type, data, callback);
      }
   }
}

AbstractEvent Class

The AbstractEvent class itself isn’t much more complicated at all. It simply has three public variables to hold the type of the event, an object containing key/value pairs for the data, and the reference to the callback function in the view (if specified).

AbstractEvent.as

package business.events
{
   import com.adobe.cairngorm.control.CairngormEvent;

   public class AbstractEvent extends CairngormEvent
   {
      public var callbacks:Array = null;

      public function AbstractEvent(type:String, data:Object = null, callbacks:Array=[])
      {
         super(type);

         this.data = data;
         this.callbacks = callbacks;
      }
   }
}

Example View – Projects

Here’s some snippets of code from my project view. One piece of functionality is for a user to disable a selected project from a list in an AdvancedDataGrid. When the user clicks on the “Disable Project” button, the btnDeactivateProject_Click() function fires and creates a new Project event in which the loadProjects() function is specified as the callback function.

Projects.mxml

private function btnDeactivateProject_Click(e:Event):void
{
   var thisProject:Project = gridProjects.selectedItem as Project;
   new ProjectEvent(ProjectEvent.DEACTIVATE_PROJECT,
            {project:thisProject},
            [loadProjects]).dispatch();
}

public function loadProjects():void
{
   new ProjectEvent(ProjectEvent.LOAD_PROJECTS).dispatch();
}

<mx:Button id="btnDeactivateProject"
	click="btnDeactivateProject_Click(event)"
	x="10" y="393"
	label="Deactivate Project"/>

Mapping Events to Commands

Your controller logic doesn’t change. The only difference is that you’re using one domain event, with specified identities, mapped to different Commands.

Controller.as

package business
{
   import business.commands.*;
   import business.events.*;
   import com.adobe.cairngorm.control.FrontController;

   public class Controller extends FrontController
   {
      public function Controller()
      {
         super();
         addCommand(ProjectEvent.LOAD_PROJECTS, LoadProjectsCommand);
         addCommand(ProjectEvent.CREATE_PROJECT, CreateProjectCommand);
         addCommand(ProjectEvent.DEACTIVATE_PROJECT, DeactivateProjectCommand);
      }
   }
}

The intended purpose for the AbstractCommand class in Cairngorm is three-fold:

1. Further implementation of a callback feature – in conjunction with the AbstractEvent – so that a view can specify other actions to perform upon the successful completion of business event
2. Create a Responder object for the Delegate to use
3. Make each Command class as lightweight as possible

Related Posts

Batch Commands | Abstract Events | Abstract Delegates

Concept

Standard, Responseful Command

Below is an example Command in my system, it extends AbstractCommand which in turn implements the ICustomCommand interface. To make the Command responseful, an array of functions is passed from the Event to the Command, which will execute them upon success (see more below). Here’s an example call:

new EmployeeEvent(EmployeeEvent.GET_DETAILS,
         {employee_id:params.empID},
         [showEmployeeDetails, updateEmployeeGraph])

To implement a very basic command, it is only required to set the delegate property to a new instance of the appropriate Delegate class, and then invoke the needed method. The AbstractCommand will automatically create a new Responder object and assign it to the delegate.

LoadProjectCommand.as

public class LoadProjectCommand extends AbstractCommand
{
   private var _model:ModelLocator = ModelLocator.getInstance();

   override public function execute():void
   {
      delegate = new ProjectDelegate();
      (delegate as ProjectDelegate).loadProject(invoker.data);
   }

   override public function commandSuccess(event:Event):void
   {
      if (event.result.success)
      {
         _model.project = (event as ResultEvent).result.data;
         notifyInvoker();
      }
   }
}
}

The invoker object is a reference to the original Event that was called, and to get it assigned as a property of the Command, I extended the FrontController class so that it is assigned before the Command is executed.

protected function executeAbstractCommand(event:AbstractEvent):void
{
   var commandRef:Class = getCommand(event.type);
   var commandToExecute:ICustomCommand = new commandRef();

   commandToExecute.invoker = event;
   commandToExecute.execute();
}

AbstractCommand Class

This class is straightforward and handles the tedious aspects of creating a Command. The notifyInvoker() method simply loops through the array of callback functions – if they exist – and runs them.

AbstractCommand.as

public class AbstractCommand
{
   private var _callbacks:Array = null;
   private var _invoker:AbstractEvent = null;
   private var _delegate:AbstractDelegate = null;

   public function AbstractCommand() { }
   public function execute():void { }
   public function commandSuccess(event:Event):void { }
   public function commandFault(event:Event):void { }

   public function set delegate(d:*):void
   {
      _delegate = d;
      _delegate.setResponder(new Responder(commandSuccess, commandFault));
   }

   public function get delegate():*
   {
      return _delegate;
   }

   public function set invoker(e:AbstractEvent):void
   {
      _invoker = e;
      if (e.callbacks != null) _callbacks = e.callbacks;
   }

   public function get invoker():AbstractEvent
   {
      return _invoker;
   }

   public function notifyInvoker(info:Object = null):void
   {
      if (_callbacks != null)
      {
         for (var i:uint = 0; i < _callbacks.length; i++)
         {
            var callback:Function = _callbacks[i];
           (info != null) ? callback.call(this, info) : callback.call(this);
         }
      }
   }
}

ICustomCommand Interface

ICustomCommand.as

package business.commands
{
   import business.events.AbstractEvent;
   import flash.events.Event;

   public interface ICustomCommand
   {
      function commandSuccess(event:Event):void;
      function commandFault(event:Event):void;
      function execute():void;
      function set invoker(event:AbstractEvent):void;
      function set delegate(delegate:*):void;
   }
}

Granularity is a well-known topic in software development. Another common concept is encapsulation. There’s books, magazine articles, and blog posts about these topics going back decades (well, not the blog posts).

One challenge we’ve had recently is trying to apply these concepts to a Flex application that uses modules. We want a global data model that modules can access, but have no way to access its internal mechanisms (i.e. no public variables).

The Shell

The core idea is that we want a common data model loaded into a basic Flex app – the Shell – which has no functionality, in and of itself, other than to load and unload modules that contain the business functionality.

This common data would then need to be accessible to every module that got loaded into the Shell – regardless of whether the module needed it or not.

The Interface

First thing we need is establish an interface that each module can use to identify itself so that when the Shell loads it, the Shell recognizes that it should send its global data model to the module.

People and places have had their names changed to protect their identity…

package com.widget.common.interfaces
{
   public interface ICoolModule
   {
      function getModuleController():Class
      function setGlobalModel(model:Class):void
   }
}

The key method defined for this mechanism is the setGlobalModel() method. This is the method that it called by the Shell (shown below) when it loads a module to ensure that each module has a reference to the global data model.

The CoolModule

I then extended the basic Flex Module class, so that I could implement the ICoolModule interface and provide basic functionality for accessing the global data model

CoolModule.as

package com.widget.common.components
{
   import com.widget.common.interfaces.ICoolModule;

   import mx.core.Singleton;
   import mx.modules.Module;

   public class CoolModule extends Module implements ICoolModule
   {
      [Bindable] public var _globalModel:*;

      public function CoolModule()
      {
         super();
      }

      public function getModuleController():Class
      {
         return null;
      }

      public function setGlobalModel(globalModelLocator:Class):void
      {
          _globalModel = Singleton.getInstance("IModelLocator") as globalModelLocator;
      }
   }
}

Now when I create a new module, it’s a CoolModule instead of the base Module.

Module1.mxml

<component:CoolModule xmlns:mx="http://www.adobe.com/2006/mxml"
    xmlns:component="com.widget.common.components.*">

Loading the Module

So now that we’ve set up things on the Module end, let’s see how the Shell actually injects its model into each Module. I’ve got a command that handles loading modules with a commandSuccess() method that handles the coupling (significantly stripped down version here just to show the relevent code).

LoadModuleCommand.as

package com.widget.thisApp.business.commands
{
   import com.widget.thisApp.model.ModelLocator;

   public class ModuleLoaderCommand extends AbstractCommand implements ICustomCommand
   {
      ...
      public function commandSuccess(event:Event):void
      {
         if(_component is ICoolModule)
         {
            var coolModule:ICoolModule = _component as ICoolModule;
            ...
            coolModule.setGlobalModel(ModelLocator);
         }
      }
      ...
   }
}

Now, for those who were paying attention, you may have figured out the key to all of this is that the ModelLocator is a singleton. As long as the module gets loaded into the current application and security domain…

module.load(ApplicationDomain.currentDomain, SecurityDomain.currentDomain);

…then it can access the Model singleton.

Conclusion

We’ve found that while module-parent, and module-module, communication is certainly not elegantly built into the Flex framework, it is possible with a little bit of grunt work. I’m hoping that as the Flex SDK matures and becomes more feature-rich that this feature become more robust.

Abstract Commands

Basic Cairngorm Commands

In the base implementation of the Cairngorm micro-architecture, events and commands are mapped on a 1-1 basis. For every invoker (event) you have to specify one command in your controller.

public function Controller()
{
   super();
   addCommand(TeammateEvent.LOAD_TEAMMATES, LoadTeammatesCommand);
   addCommand(EffortEvent.LOAD_TYPES, LoadEffortTypesCommand);
   addCommand(ProjectEvent.LOAD_PROJECTS, LoadProjectsCommand);
   addCommand(TeammateEvent.LOAD_TEAMMATE_ROLES, LoadTeammateRolesCommand);
   ...
}

For most cases, this is perfectly fine, but in a data-heavy model, such as the one being built for my current application, I need to initialize the application and fire off many individual events in order to load my model with base data.

// Load all teammates in the database for display in the reports tab
new TeammateEvent(TeammateEvent.LOAD_TEAMMATES).dispatch();

// Load all effort types
new EffortEvent(EffortEvent.LOAD_TYPES).dispatch();

// Load all projects
new ProjectEvent(ProjectEvent.LOAD_PROJECTS).dispatch();

// Load all roles
new TeammateEvent(TeammateEvent.LOAD_TEAMMATE_ROLES).dispatch();

...

Batch Commands

In order to avoid having to dispatch n events for n commands to be executed, I would rather map 1 event to n commands and have them fired off in sequence. Then, if I need a batch of commands to fire, I only need to dispatch one event, instead of the 4 I used in the example above.

new ApplicationEvent(ApplicationEvent.LOAD_MODEL).dispatch();

Unfortunately, Cairngorm does not allow this, so I had to extend the basic architecture. I created a addCommands() function that maps a single event to multiple commands as an array.

public class Controller extends ExtendedFrontController
{
   public function Controller()
   {
      addCommands(ApplicationEvent.LOAD_MODEL, [LoadTeammatesCommand,
                                LoadEffortTypesCommand,
                                LoadProjectsCommand,
                                LoadTeammateRolesCommand,
                                ...]);
   }
}

Extended Controller Class

Here’s the code that I’ve come up with so far. This is working fine, but there still some things I plan on implementing in the future.

ExtendedFrontController.as

public class ExtendedFrontController extends FrontController
{
   public function ExtendedFrontController()
   {
      super();
   }

   public function addCommands(commandName:String, commandRefs:Array, useWeakReference:Boolean = true):void
   {
      if(commands[ commandName ] != null)
      {
         throw new CairngormError( CairngormMessageCodes.COMMAND_ALREADY_REGISTERED, commandName );
      }

      if (commandRefs == null)
      {
         throw new Error("The commandRefs argument to addCommands() is null");
      }

      commands[commandName] = commandRefs;

      for (var priority:uint = 0; priority < commandRefs.length; priority++)
      {
         CairngormEventDispatcher.getInstance().addEventListener(commandName, executeCommands, false, priority, useWeakReference);
      }
   }

   protected function executeCommands(event:AbstractEvent):void
   {
      var commandsToInitialise:Array = getCommands(event.type);
      var commandRef:Class;

      for (var i:uint = 0; i < commandsToInitialise.length; i++)
      {
         commandRef = commandsToInitialise[i];
         var commandToExecute:ICustomCommand = new commandRef();
         commandToExecute.execute(event);
      }
   }

   protected function getCommands(commandName:String):Array
   {
      var commands:Array = commands[commandName];

      if ( commands == null )
         throw new CairngormError( CairngormMessageCodes.COMMAND_NOT_FOUND, commandName );

      return commands;
   }
}

Call me a junkie, that’s fine, but this stuff works. I’ve said many times in the past that the whole purpose of using design patterns, code frameworks, and application architectures should be to reduce the code I write (as time progresses), make an application easier to extend, and reduce the cost of turnover.

After quickly learning what the Cairngorm architecture had to offer, I noticed several gaps that needed to be filled. One of which was the inordinate amount of files that are created using the base patterns (which I alleviated with my abstract classes for Event, Command, and Delegate). Another gap is that it doesn’t have a view mediator. That’s the one feature from the PureMVC framework that I actually was a huge fan of.

Mediators

You see, PureMVC uses a Mediator pattern in order to provide a mechanism by which views could interact with the business logic, as well as with each other, while remaining ignorant of the man behind the curtain. Keeping the views decoupled from the model is good – especially with my apps – because subtle changes to the data model happen often, and while a good part of that is handled in the business logic, it often bubbles up to the UI model as well.

I am a Command, I am an Island

Another value feature that other frameworks have is that ability for a View – via a Mediator – to actually know if a Command was successful or not. Gasp! With the base Cairngorm implementation, the only way to perform an action on success of a Command was in the Command itself. Very bad, otherwise you end up with situations that call for SaveProjectAndReloadModelCommand in which you do one action and then immediately call another Command, and SaveProjectWithNoModelReloadCommand for when you don’t need to do the second Command.

A Command should be as insular as possible. It should never directly call another Command.

Responseful Commands

My way around this was to implement a function callback feature in the Event and Command abstract classes.

When an Event is dispatched from a View, the name of a local function is passed as an argument. The Command consumes this function reference and then runs it if the execution was successful.

Tested in the Field

Sure, theory is fine, but how does all this work when actually writing a Flex app? Well, I put that to the test just the other day. An app I’m working needed a significant enhancement and change. After changing the database model, I was able to crank out the business logic, and three views in Flex in which users could create new items, deactivate/activate them, and a few other doo-dads in just under 40 minutes.

Conclusion

Don’t be afraid to enhance a framework or code architecture with your own ideas. Trust yourself and your ideas because you’re smart, too.

My intended purpose for the AbstractCommand class in Cairngorm was two-fold:

1. Implement a callback feature so that a view can specify another action to perform upon the successful completion of an event
2. Make each Command class as lightweight as possible

Related Posts

Batch Commands | Abstract Events | Abstract Delegates

Concept

Standard, Responseful Command

Here’s an example Command in my system, it extends AbstractCommand and implements the ICustomCommand interface – which simply enforces a commandSuccess() and commandFault() method be present.

When the execute() method is invoked, the callback function property of the domain event is assigned by calling the setCallbackFunction() of the AbstractCommand, then the standard process of instantiating the proper delegate happens.

Now that the Command has a reference to the callback function (if it exists), in the commandSuccess() method, we simply call the AbstractCommand’s notifyCaller() method which executes that function.

DeactivateProjectCommand.as

package business.commands
{
   public class DeactivateProjectCommand extends AbstractCommand implements ICustomCommand
   {
      private var _model:ModelLocator = ModelLocator.getInstance();

      public function execute(event:CairngormEvent):void
      {
         setCallbackFunction((event as ProjectEvent).callbackFunction);

         var delegate:ProjectDelegate = new ProjectDelegate();
         delegate.setResponder(new Responder(commandSuccess, commandFault));
         delegate.deactivate((event as ProjectEvent).eventData);
      }

      public function commandSuccess(event:ResultEvent):void
      {
         if (event.result.success)
         {
            notifyCaller(event.result.data.project as Project);
         }
      }

      public function commandFault(event:FaultEvent):void { }
   }
}

AbstractCommand Class

This class is straightforward and simple. It simply contains the setCallbackFunction() and notifyCaller() methods with a private class member _callback.

AbstractCommand.as

package business.commands
{
   public class AbstractCommand
   {
      private var _callback:Function = null;

      public function setCallbackFunction(value:Function):void
      {
         if (value != null) _callback = value;
      }

      public function notifyCaller(info:Object = null):void
      {
         if (_callback != null)
         {
            if (info != null)
            {
               _callback.call(this, info);
            } else {
               _callback.call(this);
            }
         }
      }
   }
}

ICustomCommand Interface

This interface simply enforces the implementation of the commandSuccess() and commandFault() methods.

ICustomCommand.as

package business.commands
{
   import com.adobe.cairngorm.commands.ICommand;
   import mx.rpc.events.FaultEvent;
   import mx.rpc.events.ResultEvent;

   public interface ICustomCommand extends ICommand
   {
      function commandSuccess(event:ResultEvent):void;
      function commandFault(event:FaultEvent):void;
   }
}

My intended purpose for the AbstractEvent class in Cairngorm was three-fold:

1. Reduce the number of files needed to manage business events by organizing Events into domains
2. Implement a callback feature so that a view can specify another action to perform upon the successful completion of an event
3. Make each domain event class as lightweight as possible

Related Posts

Abstract Commands | Abstract Delegates

Concept

To accomplish my goals, each domain event (e.g. ProjectEvent, PaymentEvent, etc.) would be polymorphic (kinda) in that there is no longer just one identifier designated with the EVENT_ID constant. In addition, I wanted to abstract as much functionality and classification as possible into a common class that each domain event would extend.

Lightweight, Polymorphic Event Class

Here’s an example of a domain event. It has three public identifiers – CREATE_PROJECT, LOAD_PROJECTS, DEACTIVATE_PROJECT- and has no logic other than to pass its constructor’s arguments to AbstractEvent.

ProjectEvent.as

package business.events
{
   import com.adobe.cairngorm.control.CairngormEvent;

   public class ProjectEvent extends AbstractEvent
   {
      public static const CREATE_PROJECT:String = "createProject";
      public static const LOAD_PROJECTS:String = "getProjects";
      public static const DEACTIVATE_PROJECT:String = "deactivateProject";

      public function ProjectEvent(type:String, data:Object = null, callback:Function = null)
      {
         super(type, data, callback);
      }
   }
}

AbstractEvent Class

The AbstractEvent class itself isn’t much more complicated at all. It simply has three public variables to hold the type of the event, an object containing key/value pairs for the data, and the reference to the callback function in the view (if specified).

AbstractEvent.as

package business.events
{
   import com.adobe.cairngorm.control.CairngormEvent;

   public class AbstractEvent extends CairngormEvent
   {
      public var eventType:String = "";
      public var eventData:Object = new Object();
      public var callbackFunction:Function = null;

      public function AbstractEvent(type:String, data:Object = null, callback:Function = null)
      {
         super(type);
         eventType = type;
         eventData = data;
         callbackFunction = callback;
      }
   }
}

Example View – Projects

Here’s some snippets of code from my project view. One piece of functionality is for a user to disable a selected project from a list in an AdvancedDataGrid. When the user clicks on the “Disable Project” button, the btnDeactivateProject_Click() function fires and creates a new Project event in which the loadProjects() function is specified as the callback function.

Projects.mxml

private function btnDeactivateProject_Click(e:Event):void
{
   var p:Project = gridProjects.selectedItem as Project;
   var event:ProjectEvent = new ProjectEvent(
                                  ProjectEvent.DEACTIVATE_PROJECT,
                                  {project:p},
                                  loadProjects);
   event.dispatch();
}

public function loadProjects():void
{
   var projectEvent:ProjectEvent = new ProjectEvent(ProjectEvent.LOAD_PROJECTS);
   projectEvent.dispatch();
}

<mx:Button id="btnDeactivateProject"
	click="btnDeactivateProject_Click(event)"
	x="10" y="393"
	label="Deactivate Project"/>

Mapping Events to Commands

Your controller logic doesn’t change. The only difference is that you’re using one domain event, with specified identities, mapped to difference Commands.

Controller.as

package business
{
   import business.commands.*;
   import business.events.*;
   import com.adobe.cairngorm.control.FrontController;

   public class Controller extends FrontController
   {
      public function Controller()
      {
         super();
         addCommand(ProjectEvent.LOAD_PROJECTS, LoadProjectsCommand);
         addCommand(ProjectEvent.CREATE_PROJECT, CreateProjectCommand);
         addCommand(ProjectEvent.DEACTIVATE_PROJECT, DeactivateProjectCommand);
      }
   }
}