Cairngorm is based on the MVC model. It is specifically designed to facilitate complex state and data synchronization between the client and the server, while keeping the programming of the View layer detached from the data implementation.
The role of the View layer in a Cairngorm application is to throw events and bind to data stored in the Model. Components on the View can bind to Value Objects or other properties in the Model (data) layer.
In a Cairngorm Model, related data are stored in Value Objects (VOs), while simple variables can be stored as direct properties of the ModelLocator class. A static reference to the ModelLocator singleton instance is used by the View layers to locate the required data.
The Controller is the most sophisticated part of the Cairngorm architecture. The Controller layer is implemented as a singleton FrontController. The FrontController instance, which receives every View-generated event, dispatches the events to the assigned Command class based on the event's declared type.
The Command class then processes the event by running the Command class' execute() method, which is an ICommand interface method. The event object may include additional data if required by the developer. The execute() method can update the central Model, as well as invoke a Service class which typically involves communication with a remote server. The IResponder interface, which is also implemented by the Command class, includes onResult and onFault methods to handle responses returned from the invoked remote service.
Organizing a Cairngorm Project
One of the tasks involved with any project is organization. When working with other developers, this becomes extremely important. Normally a Cairngorm project is organized in the following manner:
- There is a Main.mxml file that is the main application file for the Cairngorm application.
- The project files are contained in a folder that uses "reverse-dns" format. For example, if the project was named CairngormSample, I would use the following folders net/CairngormSample .
- Within the CairngormSample directory, there will be the following folders:
- events/ - This directory holds all of the custom events for the application
- control/ - This directory houses the FrontController for the application
- commands/ - This directory contains the Commands that are called by the FrontController
- model/ - The ModelLocator is contained in this folder (and other classes related to the model)
- view/ - The components of the view are contained in this directory
By following this standard, you can know where to find any class that you may need in your Cairngorm application. Figure 1 illustrates this project structure. It also is a good development process to have a standard organizational structure for your projects - even if you are not using Cairngorm.
 |
| Figure 1 - Cairngorm Project Structure |
The Service to Worker Pattern
The Service to Worker pattern is the hardest for most people to grasp. It encompasses most of the logic for a Cairngorm application. To understand this pattern, you will need to understand some of the classes that are included with Cairngorm and their respective purposes.
- CairngormEvent [Reference] - CairngormEvent is central in this pattern. It extends from Event. For your event to be handled properly in Cairngorm, it will need to be of type CairngormEvent.
- CairngormEventDispatcher [Reference] - CairngormEventDispatcher actually dispatches the CairngormEvents. It is a singleton (just like the ModelLocator). In previous Cairngorm versions, you would call this class regularly, but now CairngormEvents can dispatch themselves (via the method dispatch). This method is simply a wrapper for the CairngormEventDispatcher, so even if you don't actually import and call the class, it is still central to the Service to Worker pattern in Cairngorm.
- FrontController [Reference] - The FrontController maps a CairngormEvent to a Command.
- ICommand [Reference] - For a Command to function properly in Cairngorm, it needs to implement the ICommand interface. This interface requires that a command have a method named execute and that it accept the CairngormEvent that is mapped to it as an argument.
The Cairngorm Event Flow
The way that these classes interact is the Cairngorm Event Flow. Figure 2 illustrates this entire process. While this process seems lengthy, it follows a logical order.
 |
| Figure 2 - Cairngorm Basic Event Flow |
For example, assume that Figure 2 shows what happens when a user clicks a login button. It would follow the following steps:
1. The user is viewing a component that has a login button.
2. When the button is clicked, that component would dispatch an event named LoginEvent that extends CairngormEvent.
3. The FrontController would receive the LoginEvent and execute the command that is mapped to that event. For this example, it will be named LoginCommand and will implement ICommand.
4. The Command is executed and received the LoginEvent as an argument. The LoginCommand will change the workflowState value in the ModelLocator.
5. The ModelLocator will have a predefined constant for the "Logged in View". The command will change workflowState to this value.
6. Since the view is bound to workflowState, it will automatically update itself to the new view.
Once these items are understood, the next most important thing to understand about Cairngorm is: Everything Should Be Mapped to an Event. This is a drastic over-simplification, but it holds true in most situations. When a user clicks a login button - it should dispatch a CairngormEvent. When the user selects an option to change the view - it should dispatch a CairngormEvent. When a user submits a form to be stored on in a database - the form should dispatch a CairngormEvent. The dispatching of a CairngormEvent sets everything in motion.Organizing Your Cairngorm Project (With Server Interaction)
In the last section you saw the standard Cairngorm structure for a project. To complete this structure, you will need to add an additional two folders:
- /business - This folder typically contains two types of files: the ServiceLocator (named Services.mxml) and Business Delegates.
- /vo - This folder contains the value objects that are passed to and from the server.
Understanding the Process
Before you begin crafting the server interaction for your project, you need to understand the full Service to Worker pattern. Figure 3 illustrates the entire process.
 |
| Figure 3 - Cairngorm Event Flow with Server Interaction |
Phase I - Execution Phase
1. The user is viewing a component that has a login button. When the button is clicked, that component would dispatch an event named LoginEvent that extends CairngormEvent.
2. The FrontController would receive the LoginEvent and execute the command that is mapped to that event. For this example, it will be named LoginCommand and will implement ICommand.
3. The Command is executed and received the LoginEvent as an argument. The LoginCommand creates an instance of the Delegate while passing a reference to the Responder. The Command then calls the specified method on the Delegate.
4. The Delegate gets the service from the ServiceLocator and calls the method on the specific service.
5. The service defined in the ServiceLocator receives the information that is passed to it from the call in the Delegate.
Phase II - Application Tier Processing
Phase III - Response Phase
1. The service that is defined in the ServiceLocator returns the result of the server-side processing.
2. The Delegate receives the result and passes it to the specified responder.
3. The Responder receives the result indicating a successful login.
4. The ModelLocator will have a predefined constant for the "Logged in View". The Responder will change workflowState to this value.
5. Since the view is bound to workflowState, it will automatically update itself to the new view.
Note: Traditionally the Command and Responder were the same class in a Cairngorm application. If you are working with other developers, the applications will probably be coded in this manner. However, most developers (including Adobe Consulting) are now separating these classes into two different classes. For a less complex project, it might not make sense to separate these items, but in a large application it could prove advantageous in organization and practice to have two different classes.
Coming soon: Cairngorm Videos below made by David Tucker, an expert on the subject!
