Now we’ve got the data back we need somewhere to store it.  This is where the model comes in.  Let’s create a ModelLocator called MemoryModelLocator.  It implements IModelLocator.  The interface doesn’t actually require any functions, it is just there to type the class.  Here’s the class

package com.worthyashes.simpleCairngorm.model
{
	import com.adobe.cairngorm.model.IModelLocator;
	[Bindable]
	public class MemoryModelLocator implements IModelLocator
	{
		//Singleton code
		private static var _instance:MemoryModelLocator;

		public function MemoryModelLocator(enforcer:SingletonEnforcer)
		{
			if (enforcer == null)
			{
				throw new Error("Like at the end of Highlander, before the crap sequal, there can be only one");
			}
		}

		public static function getInstance():MemoryModelLocator
		{
			if (_instance == null)
			{
				_instance = new MemoryModelLocator(new SingletonEnforcer());
			}
			return _instance;
		}
		//End of singleton code

		//Pop your vars into the model from here on
		public var loadedData:XMLList = new XMLList();
	}
}
class SingletonEnforcer{}

This is pretty much what we did in part two, the only addition being the variable loadedData which is of type XMLList.  Remember the most important thing is that this whole class is bindable.  This allows us to access the variables in this class using dynamic data binding.

Lets get the data in.  Back to our LoadXMLResponder class, remember Models in Cairngorm should ONLY be modified by a Command or a Responder.

package com.worthyashes.simpleCairngorm.responder
{
	import com.worthyashes.simpleCairngorm.model.MemoryModelLocator;

	import mx.rpc.IResponder;
	import mx.rpc.events.FaultEvent;
	import mx.rpc.events.ResultEvent;

	public class LoadXMLResponder implements IResponder
	{
		public function LoadXMLResponder()
		{
		}

		public function result(data:Object):void
		{
			var resultEvent:ResultEvent = data as ResultEvent;
			trace("XML loaded");

			var memoryModel:MemoryModelLocator = MemoryModelLocator.getInstance();
			memoryModel.loadedData = resultEvent.result.block as XMLList;
		}

		public function fault(info:Object):void
		{
			var faultEvent:FaultEvent = info as FaultEvent;

			trace("Fault at [LoadXMLResponder] " + faultEvent.message);
		}

	}
}

Obviously we populate the data in the result function.  We create a local variable of the memoryModel, don’t forget that as a Singleton we can’t access it directly, we need to call the static getInstance() function on the class.  This ensures that we always get the same singleton back regardless of where we are in the application.  As we are using the e4x result format we can use dot notation to drill down the XML to return the XML <block> nodes as an XMLList.

So – great we’ve populated the Model.  Whoopy do.  Well whoopy do indeed, because we’ve got the data in a class that is the same at every point in the application and it’s bindable.

Look back at the main application file, currently we have a Tree component and a TextArea component.  Lets ignore the TextArea component for a mo and we’ll focus on the Tree.  I’m going to take the Tree and it’s holding Box out of this file and create it as a custom component in the view folder.

<?xml version="1.0" encoding="utf-8"?>
<mx:Box  xmlns:mx="http://www.adobe.com/2006/mxml">
	<mx:Script>
		<![CDATA[
			import com.worthyashes.simpleCairngorm.model.MemoryModelLocator;
			[Bindable]
			private var memoryModel:MemoryModelLocator = MemoryModelLocator.getInstance();

			private function renderLabel(item:Object):String
			{
				var node:XML = item as XML;

				if (node.localName() == "block")
				{
					return node.@title;
				}
				else if (node.localName() == "item")
				{
					return node.@name;
				}
				return "Something went wrong!!";
			}
		]]>
	</mx:Script>

	<mx:Tree dataProvider="{memoryModel.loadedData}"
			 width="100%"
			 height="100%"
			 labelFunction="renderLabel"/>
</mx:Box>

So what’s happening here?  What we are doing is creating an instance of the MemoryModelLocator class, and binding it to the tree as it’s data provider.  This means that when the LoadXMLResponder loads the XML and changes the property loadedData it updates the Tree component.  This is what we mean when we say the model updates the view.  The model doesn’t ‘know’ it has a view watching it, but when it changes regardless it updates the data being used by the views bound to it.  Pretty cool.  All we need to do now is render the label for the Tree and we are done!

Pop this into the main application file

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
				xmlns:view="com.worthyashes.simpleCairngorm.view.*"
				xmlns:control="com.worthyashes.simpleCairngorm.control.*"
				xmlns:business="com.worthyashes.simpleCairngorm.business.*"
				creationComplete="creationCompleteHandler();"
				layout="vertical">

	<mx:Script>
		<![CDATA[

			private function creationCompleteHandler():void
			{
				var loadXMLEvent:LoadXMLEvent = new LoadXMLEvent();
				loadXMLEvent.dispatch();
			}

		]]>
	</mx:Script>

	<control:SimpleFrontController id="frontController"/>

	<business:Services id="services"/>

	<mx:Panel title="XML Display" width="600" height="500">
		<mx:ViewStack width="100%" height="100%">
			<view:XMLTree id="xmlTree"/>
			<mx:Box>
            	<mx:TextArea/>
            </mx:Box>
		</mx:ViewStack>
		<mx:ControlBar>
			<mx:Button id="btn_tree" label="Display as Tree"/>
			<mx:Button id="btn_datagrid" label="Display as Datagrid"/>
		</mx:ControlBar>
	</mx:Panel>

</mx:Application>

We’ve again created an xmlns with the name of view to allow us to access the com.worthyashes.simpleCairngorm.view package.  So now when we run this we will display the XML in the tree.

Next let’s have a look at using a ModelLocator to manage state.

We’ve created our LoadXMLEvent, created our FrontController and that has linked the event with the command to get the XML. Now we need to create our next set of classes. The Delegate class deals with retriving the data, it does this by using another Cairngorm class called the ServiceLocator. As the Delegate is getting some data we need to create a Responder to recieve and deal with the data. As this is a simple application we could make the Command the Responder too, but as I want this to be a pucker representation of how Cairngorm works I’m going to go ahead and create the Responder.

So – lets create the ServiceLocator. The ServiceLocator is a ModelLocator really, and is where you keep all of the data calls for the application. This is a great thing to do as the service locator is where you call the server side code, or as in this case load the XML. This means that if you’d developed an application with a ColdFusion backend and needed to port it over to AMFPHP then you should only need to swap out this class and it should all function as expected. (Note the use of the word ’should’)

Anyway lets have a look at it.

<?xml version="1.0" encoding="utf-8"?>
<cairngorm:ServiceLocator xmlns:mx="http://www.adobe.com/2006/mxml"
		          xmlns:cairngorm="com.adobe.cairngorm.business.*">

	<mx:HTTPService id="xmlService"
			resultFormat="e4x"
			showBusyCursor="true"/>

</cairngorm:ServiceLocator>

So to create this right click on the business folder and select new -> MXML component. It doesn’t matter what you choose as the component as you can see from above we are going to use our own tag to identify it. Add the xmlns declaration so we can reference the com.adobe.cairngorm.business package. Once you’ve done that pop the HTTPService tag in. This is what will load the XML and we’ve set the result format to e4x so we can use the e4x syntax to work with the XML returned.

Right one down. Now we’ll create the responder. Right click on the responder folder…..actually, by now I think you’ve got the hang of creating classes. I’ll just describe them. The responder classes live in the responder folder need to implement the IResponder interface.

package com.worthyashes.simpleCairngorm.responder
{
	import com.worthyashes.simpleCairngorm.model.MemoryModelLocator;

	import mx.rpc.IResponder;
	import mx.rpc.events.FaultEvent;
	import mx.rpc.events.ResultEvent;

	public class LoadXMLResponder implements IResponder
	{
		public function LoadXMLResponder()
		{
		}

		public function result(data:Object):void
		{
			var resultEvent:ResultEvent = data as ResultEvent;
			trace("XML loaded");
		}

		public function fault(info:Object):void
		{
			var faultEvent:FaultEvent = info as FaultEvent;

			trace("Fault at [LoadXMLResponder] " + faultEvent.message);
		}

	}
}

The result and fault events are called by either a -er- result or fault. To implement the interface correctly they have Objects passed in as parameters, but they are actually ResultEvents and FaultEvents respectively. This is why I’ve immediately created a local variable of type either ResultEvent or FaultEvent and cast the objects into it. If you’ve been hunting for tutorials on Cairngorm you’ll probably have seen something similar to “Fault at [LoadXMLResponder] “. I can’t remember which tutorial uses this, I’ll pop a link in when I find it, but this has been a lifesaver a number of times for debugging.

OK now we create the Delegate class that sticks this all together. The delegate also lives in the business folder, but doesn’t extend or implement anything.

package com.worthyashes.simpleCairngorm.business
{
	import com.adobe.cairngorm.business.ServiceLocator;

	import mx.rpc.AsyncToken;
	import mx.rpc.IResponder;
	import mx.rpc.http.mxml.HTTPService;

	public class LoadXMLDelegate
	{
		private var responder:IResponder;
		private var service:HTTPService;

		public function LoadXMLDelegate(responder:IResponder)
		{
			this.responder = responder;
			this.service = ServiceLocator.getInstance().getHTTPService("xmlService") as HTTPService;
			this.service.url = "xml/example.xml";
		}

		public function loadXML():void
		{
			var token:AsyncToken = service.send();
			token.addResponder(responder);
		}

	}
}

There we go. The delegate holds a referenced to the responder and the service to call. Then when called to load the XML it triggers the load on the service and adds the responder to the service. This is why the Responder needs to implement IResponder and have the result and fault events. Now we get the Command to create the Delegate and trigger it.

package com.worthyashes.simpleCairngorm.commands
{
	import com.adobe.cairngorm.commands.ICommand;
	import com.adobe.cairngorm.control.CairngormEvent;
	import com.worthyashes.simpleCairngorm.business.LoadXMLDelegate;
	import com.worthyashes.simpleCairngorm.events.LoadXMLEvent;
	import com.worthyashes.simpleCairngorm.responder.LoadXMLResponder;

	public class LoadXMLCommand implements ICommand
	{
		public function LoadXMLCommand()
		{
		}

		public function execute(event:CairngormEvent):void
		{
			var e:LoadXMLEvent = event as LoadXMLEvent;

			var delegate:LoadXMLDelegate = new LoadXMLDelegate(new LoadXMLResponder());
			delegate.loadXML();
			trace("Getting the XML");
		}

	}
}

All we’ve added is

var delegate:LoadXMLDelegate = new LoadXMLDelegate(new LoadXMLResponder());
delegate.loadXML();

Finally we need to instantiate the ServiceLocator, otherwise we won’t be able to use it.  Back in the main application file add the xml name space in the opening tag of

xmlns:business=”com.worthyashes.simpleCairngorm.business.*”

and add this MXML tag

<business:Services id=”services”/>

That’s it.  If you run the code now all being well you’ll get a trace to tell you the XML is loaded.

So now we’ve got the data loaded we need somewhere to put it, which takes us all the way back to the discussion of singletons. Next we are going to create a ModelLocator to hold the data.

So we’ve had a chat about the MVC design pattern and how that relates to Cairngorm, set up the environment and we’ve discussed how Singletons work.  Now we are ready to start using the framework to create a basic application.

Frameworks like Cairngorm really come into their own when you are creating a large or relatively complicated application.  For the purposes of this little demonstration we will load an XML file and display it in either a Tree component or in a TextArea component.  No great shakes and I know that if this was all you really needed to to then using Cairngorm is a little bit of an overkill, but keeping it simple means we’ll clearly be able to look at what the framework does without having to go over lots of code.

To just go back a step for a moment we are going to quickly recap how the Cairngorm framework operates.

The view dispatches events to the controller.  The controller then either modifies the model directly or in the case of getting some data, creates a delegate and a responder.  The delegate gets the data and returns it to the responder that modifies the model.  Then the model tells the view what to display.

Ideally each set of classes should only operate in an expected way on the other classes.  IE the models should only ever be modified by Controllers or Responders, the Delegates should be the only classes that get data, the views should only do view stuff.  This is the delegation of responsibility.

Lots of books and tutorials almost talk about classes as if they are sentient beings, the view shouldn’t know about the model, the model shouldn’t know about the controller.  This sort of worked for me, but I can’t really anthropomorphise what I know is just a set of classes.

Another way of looking at this, and one which makes sense to me, is that it’s all about organisation.  You wouldn’t file your car tax in the fridge, otherwise you’ll spend ages looking for it when you need to renew it.  Likewise with a Cairngorm app if something is wrong with the data call you know to start at the Delegate and see what is happening there.  (If you wanted a new car you wouldn’t want to have to change the fride too.  This analogy doesn’t quite hold up, but you know what I mean).

So if we’re happy with that lets get on with the code.

We’ll start first with the base mxml application file.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application layout="vertical">

<mx:Script>
<![CDATA[
]]>
</mx:Script>

<mx:Panel title="XML Display" width="600" height="500">
<mx:ViewStack width="100%" height="100%">
<mx:Box>
<mx:Tree/>
</mx:Box>
<mx:Box>
<mx:TextArea/>
</mx:Box>
</mx:ViewStack>
<mx:ControlBar>
<mx:Button id="btn_tree" label="Display as Tree"/>
<mx:Button id="btn_datagrid" label="Display as TextArea"/>
</mx:ControlBar>
</mx:Panel>

</mx:Application>

Nice and simple.  So first things first we need to get the XML.  I’ve created a very very simple XML file.

<?xml version="1.0" encoding="utf-8"?>
<exampleXML>
<block title="Block One">
<item name="Item One"/>
<item name="Item Two"/>
<item name="Item Three"/>
<item name="Item Four"/>
</block>
<block title="Block Two">
<item name="Item One"/>
<item name="Item Two"/>
<item name="Item Three"/>
<item name="Item Four"/>
<item name="Item Five"/>
<item name="Item Six"/>
<item name="Item Seven"/>
</block>
<block title="Block Three">
<item name="Item One"/>
<item name="Item Two"/>
<item name="Item Three"/>
<item name="Item Four"/>
<item name="Item Five"/>
<item name="Item Six"/>
</block>
<block title="Block Four">
<item name="Item One"/>
<item name="Item Two"/>
<item name="Item Three"/>
<item name="Item Four"/>
<item name="Item Five"/>
<item name="Item Six"/>
<item name="Item Seven"/>
<item name="Item Eight"/>
<item name="Item Nine"/>
<item name="Item Ten"/>
<item name="Item Eleven"/>
<item name="Item Twelve"/>
</block>
<block title="Block Five">
<item name="Item One"/>
<item name="Item Two"/>
<item name="Item Three"/>
<item name="Item Four"/>
</block>
<block title="Block Six">
<item name="Item One"/>
<item name="Item Two"/>
<item name="Item Three"/>
<item name="Item Four"/>
<item name="Item Five"/>
<item name="Item Six"/>
</block>
</exampleXML>

To trigger the load we’ll need to dispatch an event.  This is a very simple event so it’ll be a very simple class.  I’ve called it LoadXMLEvent and it’s saved in the event folder we created in part Two.  Right click on the folder, select new class.  When the class wizard launches we need to extend the CairngormEvent class.  Select the browse button next to the Superclass text input and then start to type ‘CairngormEvent’ into the panel that pops up.  It’ll quickly find CairngormEvent, click OK and then OK again into the wizard panel.  This will generate the class with the correct imports and will also create the constructor for you.

Like I said this is a very simple class, it doesn’t need to even parse any data, all we want to do is announce we need the XML.

package com.worthyashes.simpleCairngorm.events
{
import com.adobe.cairngorm.control.CairngormEvent;

import flash.events.Event;

public class LoadXMLEvent extends CairngormEvent
{
public static const LOAD_XML_EVENT:String = "loadXMLEvent";

public function LoadXMLEvent(bubbles:Boolean=false, cancelable:Boolean=false)
{
super(LOAD_XML_EVENT, bubbles, cancelable);
}

override public function clone():Event
{
return new LoadXMLEvent(this.bubbles,this.cancelable);
}

}
}

Lets go through the code.  The first variable is a public static constant variable (it’s in capitals as a visual indication that it is a constant, this is not necessary though it is a convention worth following.)

All this really does is hold the string to indicate what event this class is.  CairngormEvents exetend the standard Event class so it requires a string indicator.  Rather than parseing the name of the event in when the event is created by the class using it we are it in the class so we have more control, and access to it through the static variable.  This means that we don’t have to try and remember what we called this event, if we need to access this name all we need to do is use LoadXMLEvent.LOAD_XML_EVENT, and we make sure that we are talking about the correct event.

Now for the constructor.  As we are not parseing any data we don’t really have to put anything in the constructor, but as it’s best practice (and the code was written for us) we’ll leave the variables for bubbling and canceleable in.

Note that in the super() function, that calls the Superclasses constructor we are parsing the LOAD_XML_EVENT variable in to type the class.

Finally we override the clone function.  This function is used for bubbling and by overriding this function we make sure the correct event type is returned.

That’s it – our first CairngormEvent, woo hoo!

Next we’ll create the Controller that’ll actually do something.

On the commands folder right click, select new , class and then in the wizard rather than selecting a superclass we are going to select an interface.  The ICommand interface types this class as an ICommand and also defines the functions required by it.

Select the add button next to the Interface text area, start typing in ICommand and when it finds the correct interface select it and hit OK.  Select OK on the wizard panel and your controller will be created with all of the required imports and also the required functions to satisfy the interface.

Now onto the class

package com.worthyashes.simpleCairngorm.commands
{
import com.adobe.cairngorm.commands.ICommand;
import com.adobe.cairngorm.control.CairngormEvent;
import com.worthyashes.simpleCairngorm.events.LoadXMLEvent;

public class LoadXMLCommand implements ICommand
{
public function LoadXMLCommand()
{
}

public function execute(event:CairngormEvent):void
{
var e:LoadXMLEvent = event as LoadXMLEvent;

trace("Load XML Event triggered the command!!");
}

}
}

All we’ve done here is populate the execute function with a trace so we know it’s working.  I also set a variable, in this case e as the Type of event that has triggered this command and cast the event passed into the function to the correct type.  In other classes this can be useful as this then gives you native access to the Event classes properties.  In this case the LoadXMLEvent has no properties, it only exists to tell the application it is time to get some XML, but I still have it there.  It’s not necessary, but after you’ve been putting together a large application you have a pile of classes, having a reference to the event class in the command class makes it easier to find.

So we’ve created an Event and we’ve created a Command – but aren’t we doing an MVC implementation?  Where’s the controller?  That comes now and the controller exists to tie the Events and Commands together.

Right click on the control folder and select new class.  This class extends FrontController and I’ve called mine SimpleFrontController.
The FrontController class listens to the CairngormEventDispatcher class and executes Commands based on the events called.

Lets add our code to start it working.

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

public class SimpleFrontController extends FrontController
{
public function SimpleFrontController()
{
super();
initialise();
}

private function initialise():void
{
addCommand(LoadXMLEvent.LOAD_XML_EVENT,LoadXMLCommand);
}

}
}

We’ve created our own initialise function and in this function we tie the commands and the events together.  Remeber the static string we created in the LoadXMLEvent class that was then passed to the super function as the type?  This is an example of why we do this – we don’t need to remember the type, all we need to do is reference the Event class itself.  This is really handy if we need to change the type – rather than picking through the app changing strings we change it in the Event class itself and that’s it.

Now we’ve created the controller we need to instantiate it.  This can be done with MXML in the application.  We’ll also trigger the event.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application layout="vertical"
xmlns:control="com.worthyashes.simpleCairngorm.control.*"
creationComplete="creationCompleteHandler();">

<mx:Script>
<![CDATA[
private function creationCompleteHandler():void
{
var loadXMLEvent:LoadXMLEvent = new LoadXMLEvent();
loadXMLEvent.dispatch();
}
]]>
</mx:Script>

<control:SimpleFrontController id="frontController"/>

<mx:Panel title="XML Display" width="600" height="500">
<mx:ViewStack width="100%" height="100%">
<mx:Box>
<mx:Tree/>
</mx:Box>
<mx:Box>
<mx:TextArea/>
</mx:Box>
</mx:ViewStack>
<mx:ControlBar>
<mx:Button id="btn_tree" label="Display as Tree"/>
<mx:Button id="btn_datagrid" label="Display as TextArea"/>
</mx:ControlBar>
</mx:Panel>

</mx:Application>

What have we added?  First of all we’ve added an xmlns attibute to the main application tag.  This allows us to shortcut accessing the controller by using our own name ‘control’ that will reference the com.worthyashes.simpleCairngorm.control package.  We’ve also added a creation complete handler function for the creationComplete event.  This function creates and dispatches an loadXMLEvent.  Finally we’ve added the FrontController using MXML.  Run it and you will get the trace from the Command class as it executes – don’t forget to debug the application rather than running it.  Next we are going to look at the Delegate that retrieves the data and introduce a new class, the ServiceLocator class.

We’ve covered an overview of the MVC pattern and how it relates to Cairngorm and we’ve set up the environment and we’ve set up the environment so we can finally start to play with some code.  Nearly.

There is one last concept to go over before we move on, Singletons,  I’m sure that most of you are happy with this concept, but for those who don’t here we go.

A singleton is a class that there can only be one of.  Ever.  To borrow a joke from someone else – like Highlander there can be only one (though this analogy doesn’t quite add up as initially there were loads of them, then they had to fight each other to whittle the numbers down to one.  However the sequals made a mockerly of this idea as ‘aliens’ got involved in a typical WTF can we do now idea to make more money out of this clearly dead horse – and ruined a fantastic film.  So to relate this to a design pattern is actually quite misleading.) (Don’t get me started on the Matrix sequals – he had clearly won at the end of the first one, why didn’t you stop there?)

Right, sorry I do tend to digress a bit (Star Wars prequals!  WTF were they all about?  On a side note when I was an actor in the London Dungeon, long story but safe to say the acting career when fantastically well , I actually made the little boy who played Anakin Skywalker cry.  So I made Darth Vader cry – sort of.  Beat that!)

I did it again, concentrate – back to singletons.  Like I said a singleton is a class that there can be only one of.  Why is this helpful?  Well if there is only one then everytime you access the class you have exactly the same data stored within t.  They can be thought of as silos of data, or memory.  They can also be bound to view components and this is where the concept of changing the model to change the view works.  This is why they are used as a major part of the Cairngorm framework.  (Lots of people don’t like singletons, and I’m still not entirely sure why)

Here is an example of a Cairngorm singleton : -

package com.worthyashes.simpleCairngorm.model
{
        import com.adobe.cairngorm.model.IModelLocator;
        [Bindable]
        public class MemoryModelLocator implements IModelLocator
        {
         //Singleton code
         private static var _instance:MemoryModelLocator;

         public function MemoryModelLocator(enforcer:SingletonEnforcer)
         {
         if (enforcer == null)
             {
              throw new Error("Like at the end of Highlander, before the crap sequal, there can be only one");
             }
         }

          public static function getInstance():MemoryModelLocator
          {
           if (_instance == null)
            {
                _instance = new MemoryModelLocator(new SingletonEnforcer());
              }
            return _instance;
            }
            //End of singleton code

           //Pop your vars into the model from here on
      }
}
class SingletonEnforcer{}

Lets go through the code

[Bindable]

public class MemoryModelLocator implements IModelLocator

The [Bindable] keyword makes this class available for flex bindings so it is possible to directly bind the ModelLoactor and it’s subsequent variables to the view components as discussed above.

A Cairngorm Singleton is also known as a ModelLoactor and implements the IModelLocator interface. (For a discussion of interfaces you’re going to have to do a bit of a google.  I understand them, understand how and why to use them, but for the life of me I can’t actually put into words why – I’ll have a go at a later post)

Now for the slightly mind bending bit, once you’ve got the hang of this it will all become clear.

private static var _instance:MemoryModelLocator;

This variable _instance, the underscore is there to indicate it is a private variable (the private keyword does that really, the underscore is more a visual reminder in the code), holds a reference to the MemoryModelLocator class.  Which is the class that it is in.  So it holds a reference to itself, in itself.  Which you’d imagine would have another _instance variable, but the keyword static indicates that this variable is always the same in every single instance of this class.  So every time you access the Singleton after it has initially been instantiated you are getting the same class back.  I’ve just re-read that, I think it makes sense – if not then send me a mail and I’ll re-work that paragraph.

Now onto the constructor.  In order for a singleton to work we need to only ever create one at any time.  This means we DON’T want to be able to call the constructor directly, as this would instantiate a new class.  By convention we call a static function called getInstance() (It doesn’t have to be called this, but as it’s a convention I recommend you stick to it) that returns an instance of the class.

Singletons in AS2 were easier to do.  This was because it was allowed to create a class and set the constructor to be private.  So you’d write something like : -

private function MemoryModelLocator()
{
}

However you can’t do this in AS3.  So we have a hack.  The Cairngorm team have acknowledged it as a hack, so I’ll say it too, hack, hack, hack.  To understand how this hack works we need to look at the new package structure of AS3.  In this case : -

package com.worthyashes.simpleCairngorm.model
{
//The class goes in here
}

Now if I put another class in this package (folder) I would be able to instantiate the MemoryModelLocator class without importing it and use the functions within it.  I could create an instance of the class without any bother at all, and we want to stop this.  So we create a class outside the package declaration.

//End of class
}
class SingletonEnforcer{}

This class is outside the curly brackets that close off the package, and is not available to ANY class except for the MemoryModelLocator class.

So if we pop an instance of this Singleton enforcer class into the constructor of the MemoryModelLocator class then we can force the MemoryModelLocator class to only ever be instantiated by itself through the getInstance() function.

So the constructior is : -

public function MemoryModelLocator(enforcer:SingletonEnforcer)
{
if (enforcer == null)
{
throw new Error("Like at the end of Highlander, before the crap sequal, there can be only one");
}
}

and the getInstance() function looks like this.

public static function getInstance():MemoryModelLocator
{
if (_instance == null)
{
_instance = new MemoryModelLocator(new SingletonEnforcer());
}
return _instance;
}

To go through this and explain it, remember that the _instance variable is static and therefore will be the same every time this class is accessed.  What we do with the getInstance() call is to first of all check if the _instance variable exists.  If not then we create it by calling the constructor with an instance of the SingletonEnforcer class.  This can be accessed by the getInstance() function as it is in the MemoryModelLocator class.  Then we return the _instance variable.  So if we make the call to the getInstance() function in the MemoryModelLocator we will ALWAYS get the same Singleton.  As it is a static function (which it has to be so we can call it and return a static variable) we use it slightly differently, like this : -

var model:MemoryModelLocator = MemoryModelLocator.getInstance();

Right – hopefully that all made sense.  It’s a bit confusing, but hopefully once you see the ModelLocator in action it’ll all be made clear!

For an overview of Cairngorm check out part one.

OK – before we can start we need to set up the environment.  First things first go and get Cairngorm from here.  For now just download the binary, but further down the line you may want to download the source to have a look at the guts of the code.  Unzip the folder to somewhere that you can easily find.  I have a central folder called codeLibrary for all central code, but to be honest you can keep it on the desktop if you want.

Now fire up Flex Builder and create a new project.

Don’t click on finish click on next, the next screen asks where you want to compile the application to (default is fine, normally bin-debug), click next again.  Now we need to map in the Cairngorm library in, this is the .swc file you got in the download.

Click on the library tab, then the Add SWC button.

Browse to the folder where you unzipped the file and select the Cairngorm.swc.

Click OK

then finish.

Now we have access to the Cairngorm library.

NOTE : If tyou do get overexcited and click on finish and create the project before adding the Cairngorm.swf simply right click on the project, select preferences then Flex Build Pah.  This will then show you a similar dialog to the one I described above and you can map in the SWC there.

Final thing to do is to set up the folders for the Cairngorm structure.  This is not compulsory, but you’ll find it a lot easier if you have a folder structure like this.

Right click and select new – > folder.  I won’t go through it step by step, but here’s the recommended structue.

EDIT : I realised that’s not too clear.  The folder structure is : -

com

____>worthyashes

————->simpleCairngorm

—————————>business

—————————>commands

—————————>control

—————————>events

—————————>model

—————————>responder

—————————>view

—————————>vo

The com/worthyashes bit is just a standard namespace so if someone uses my classes they shouldn’t conflict with other classes (worthyashes is my normal username).

simpleCairngorm – this folder is really to hold all the code that specifically relates to this Cairngorm app.  This means that if you have a number of different bits of your app all using Cairngorm in theory you can pull an individual bit out and use it on other project, for example a user management system.

The sub folders of the simpleCairngorm folder are the actual suggested folder structure for Cairngorm.

Sorry it wasn’t clear from the piccy.

END OF EDIT.

OK – thats done.  Next – finally time to get our hands dirty with some code! (Well nearly.…..)

First things first I need to acknowledge David Tucker for this fantastic post that got me started.

As David Tucker says in his post, though I think he’s lying, I’m no Cairngorm Expert either.  But I have used it recently and I like it.  What I’m doing with this post is to explain it as I get it, so if I’ve made any glaring errors please let me know.  This is also an aide memoir to myself too so I apologise for the slightly jovial tone, I like to keep myself amused while I’m writing.  What I can say with authority though is that I really like Cairngorm even though I’m currently using the PureMVC framework (I hope to post a similar getting started for that framework).

The Cairngorm framework appears to be the main framework suggested by Adobe for use when creating RIAs with Flex.  There are lots of other frameworks, Pure MVC being one of them, but this one is really being pushed as they bought the company that created it (Iteration II – acutally they were bought by Macromedia, who were then bought by Adobe, but the essential theory stands).

Cairngorm is an MVC (Model, View, Controller) framework that aims to seperate these different parts of an application so it is easy to maintain and also easier for large development teams to work on.  As each part of the application is seperate a different developer can work on each bit, after planning the application of course.

In essence with an MVC design pattern the Model should deal with the data, the Controller with telling the Model what to do and the View should site there happily being told by the model what it’s supposed to be display.

I’ll have a go at some pretty diagrams of the MVC pattern (you’ll see I’m no designer) but I’ll mainly explain the way I understand it.

At the most simple level : -

A user interacts with the view.  The view dispatches an event which is mapped to the controller (known as a command), the command makes a change in the model and the model then tells the view what to display.

Now this is all well and good, but really the whole point of framework is to make it easy to manage the application and that includes data connections.  So the next step is : -

A user interacts with the view.  The view dispatches an event which is mapped to the controller (command).  The command creates a delegate to make a call to a data source and a responder that the result from the data call is mapped to.  The responder makes a change to model (which it is allowed to do as it is a controller) and the model tells the view what to display.

So for a simple app that loads some XML the flow would be : -

• Application Inititialises
• Dispatches an “I’m alive” event to a controller class
• The controller class creates a “GetXMLDelegate” class that calls to load the XML
• The XML is delivered back to responder (at the control level)
• The responder changes the model
• The view displays the data the model holds

OK, OK, I’m laboring the point – but that sort of is the point. It seems very obvious but this is really important.  View talks to Control, Control changes the model, model gets the view to display what it tells it to.

The most important and cardinal rule is ONLY CONTROLLERS (ie. Commands or Responders) CAN CHANGE THE MODEL!  If you stick to this cardinal rule your life with Cairngorm will be much more fruitful.

One other bit of advice is to try and keep things simple. One command does one function. This means you’ll end up with loads of classes, but if something does go tits up then you’ll probably have a good idea as to exactly where the application is failing, and probably the filename of the class that is the problem.

OK – part 2 – lets set up the environment for developing with Cairngorm.