Insights

I had an issue. iTunes is a fine program, with loads of great features, and it&#8217;s essential for the iTunes store and syncing my iPhone. Trouble is, in my house, we&#8217;ve got a central media server which reports 1037 albums &#8211; pulled from the CD collections of four music lovers. The combination of network access and a huge number of songs means that iTunes does get a little sluggish. I&#8217;ve tried alternatives &#8211; Songbird, Picoplay, Cog &#8211; but to be honest I want something that&#8217;s fast as lightning and I&#8217;m not really interested in the library features of iTunes.
I&#8217;ve written a <a href="http://github.com/colinramsay/euphony">very rough and ready Objective-C media player</a>. It sits as an OSX menu icon, near the spotlight and airport icons, and allows you to pick a directory of audio files to play. That&#8217;s pretty much it. You can choose &#8220;pause&#8221;, &#8220;skip&#8221; and &#8220;quit&#8221; to control the player, but there&#8217;s no notifications, libraries, fancy features or airs and graces.
I want to thank Matteo Bertozzi for teaching me <a href="http://th30z.netsons.org/2008/10/cocoa-system-statusbar-item-aka-traybar/">how to create the system bar items</a>, and P.J. Onori for the <a href="http://somerandomdude.com/projects/iconic/">icon from the Iconic set</a> which I used. I&#8217;m using this player daily, so it works for me, but we&#8217;re putting it in our labs and it&#8217;s on github, so please <a href="http://github.com/colinramsay/euphony">fork the audioplayer repo</a> if you have any features you want to add.
Updated 19/3/2010: The audioplayer has been renamed Euphony, so I&#8217;ve updated the links accordingly.

The Most Lightweight Audio Player for OSX

Depending on time of year, current workload, phase of moon, and other factors, the Go Tripod team may not always work from the same location. And even if we do, we&#8217;re often in Do Not Disturb mode with headphones on. We&#8217;ve found that the best way to keep track is by using the Campfire chat system, which allows not only standard back-and-forth yapping, but sharing of source code and images. A killer feature for us is the ability to see what&#8217;s been talked about if we&#8217;ve not been in the chatroom for a few hours; Campfire offers transcripts of everything that&#8217;s been said in your absence.
So we&#8217;re always in Campfire, and it&#8217;s an integrated part of our working day. As Go Tripod is going from strength to strength, we&#8217;ve started to need a way of doing a similar thing with projects &#8211; a very simple way for anyone to see and overview of projects that are on the go right now. We&#8217;ve kind of tried this before, but the stuff that we&#8217;ve tried either hasn&#8217;t been simple enough or we&#8217;ve only used it rarely because it&#8217;s separated out from every other part of our work. In the latter case, it just gets left by the wayside and forgotten.
The idea sprang to mind to somehow involve Campfire in the proceedings. Maybe we change the room title to reflect the current open projects? The problem with the room title is that it&#8217;s a bit out of the way up the top of the screen and could be affected by the same issue as I described above &#8211; out of sight, out of mind. So the solution needed to be integrated. In fact we basically needed another team member in Campfire, our communication method of choice, talking to us and updating us. Some kind of automated team member&#8230; Some kind of robot?
<h2>The Technical Bit</h2>
I did a quick search &#8211; <a href="http://github.com/timriley/campfire-bot">Tim Riley&#8217;s Campfire Bot</a> looked absolutely perfect, with its plugin system, so I tried to use that. Unfortunately I couldn&#8217;t get the latest source code to work, and I had other <a href="http://github.com/collectiveidea/tinder/issues#issue/3">issues</a> when I tried to use the <a href="http://github.com/collectiveidea/tinder/">Tinder</a> library which underlies the Campfire Bot.
A quick scout around for some more libraries led me to <a href="http://github.com/qrush/broach">Broach</a>, a simple wrapper for the Campfire API, and the 37 Signals <a href="http://developer.37signals.com/campfire/streaming">example code for the Campfire Streaming</a> API, which uses the <a href="http://github.com/voloko/twitter-stream">twitter-stream</a> library. I quickly put together a proof of concept using these tools and some sneaky code which allowed us to issue commands to the bot from the Campfire window itself.
<h2>The Results</h2>
A picture tells a thousand words:
<img loading="lazy" class="alignnone size-full wp-image-139" src="https://content.gotripod.com/images/2010/02/projects.png" alt="" width="458" height="53" srcset="https://content.gotripod.com/wp-content/uploads/2010/02/projects.png 458w, https://content.gotripod.com/wp-content/uploads/2010/02/projects-300x35.png 300w" sizes="(max-width: 458px) 100vw, 458px" />
A list of current projects! And Simon decides to add another:
<img loading="lazy" class="alignnone size-full wp-image-140" src="https://content.gotripod.com/images/2010/02/open.png" alt="" width="548" height="79" srcset="https://content.gotripod.com/wp-content/uploads/2010/02/open.png 548w, https://content.gotripod.com/wp-content/uploads/2010/02/open-300x43.png 300w" sizes="(max-width: 548px) 100vw, 548px" />
GoTripodBot is a helpful fellow:
<img loading="lazy" class="alignnone size-full wp-image-141" src="https://content.gotripod.com/images/2010/02/help.png" alt="" width="486" height="50" srcset="https://content.gotripod.com/wp-content/uploads/2010/02/help.png 486w, https://content.gotripod.com/wp-content/uploads/2010/02/help-300x31.png 300w" sizes="(max-width: 486px) 100vw, 486px" />
And a brief insight into the world of development (I wrote some unit tests after this):
<img loading="lazy" class="alignnone size-full wp-image-143" src="https://content.gotripod.com/images/2010/02/dev-issues.png" alt="" width="308" height="205" srcset="https://content.gotripod.com/wp-content/uploads/2010/02/dev-issues.png 308w, https://content.gotripod.com/wp-content/uploads/2010/02/dev-issues-300x200.png 300w" sizes="(max-width: 308px) 100vw, 308px" />
<h2>Conclusion</h2>
Of course there&#8217;s a lot more to our project management process than this (and a lot more projects to manage than I&#8217;ve shown!) but having such easy transparency into this top layer of our work is really going to improve our awareness of what&#8217;s happening right now in the world of Go Tripod.

How We Track Projects

The <a href="http://www.packtpub.com/ext-js-3-0-cookbook/">Ext JS 3.0 Cookbook</a> by <a href="http://miamicoder.com/">Jorge Ramon</a> is now available. As Jorge says in his <a href="http://www.miamicoder.com/post/2009/08/Announcing-the-Ext-JS-30-Cookbook.aspx">introductory post</a>:
<blockquote>The Ext JS 3.0 Cookbook is for developers who want a book of useful techniques, with explanations, that they can refer to and adapt to their purposes.</blockquote>
I was a Technical Reviewer for this book, and it contains not just simple recipes to get you started, but complex ones to allow you to bend Ext JS to your will. If you buy Ext JS 3.0 Cookbook eBook along with the eBook edition of the book I co-authored, Learning Ext JS, you can get a 50% discount using the promo code jsco34ler on the <a href="http://www.packtpub.com/ext-js-3-0-cookbook/">Packt website</a>. Congratulations Jorge!

Ext JS 3.0 Cookbook – Available Now

Very occasionally, people will start asking me in detail what I do for a living. When &#8220;I write software&#8221; or &#8220;I make websites&#8221; doesn&#8217;t satisfy them, I go into a bit more detail about the different aspects of my job. One thing that happens quite regularly if I don&#8217;t go into enough detail, is that I&#8217;ll tell someone how long it took to write something, or how much it cost, and they&#8217;ll raise their eyebrows.
&#8220;How can it cost so much?! It&#8217;s just a website!&#8221;
I can see their point. Most websites contain common elements &#8211; login, lists, articles, shopping carts, and so on &#8211; so you&#8217;d think that once you&#8217;ve written one, you&#8217;ll have the bits and pieces you need to make more. And taken individually, each of these parts are fairly straightforward &#8211; a list of products contains some pretty basic HTML, surely? And HTML is just a text file?
And again, that&#8217;s a fair point. The real time isn&#8217;t taken in writing these bits and pieces, it&#8217;s taken in understanding how the customer wants them to be written and how they need to fit together in a certain situation. For example, a shopping cart quickly becomes more complex when the customer adds on a few more features:
<ul>
<li>Integrates with Google Checkout</li>
<li>Customers can save carts for later ordering</li>
<li>Customers can reload past orders into a few cart</li>
</ul>
But it&#8217;s not just the cart, it&#8217;s viewing products too &#8211; what if certain customers see custom trade prices? Or products can be assigned to multiple categories and the customer wants to see how many products are in each category next to the category name? All of these things are minor when taking in isolation, but together they are a thousand tiny cuts which bleed development time.
As well as a collection of features, a specification for a website will also discuss requirements in language which is specific to the company you&#8217;re quoting for. Rather than &#8220;cart&#8221; you might have &#8220;basket&#8221;. Or you could have &#8220;assessors&#8221;, &#8220;reviewers&#8221;, &#8220;investigators&#8221;, or any other number of terms which a company uses internally and when referencing all of the features they want on their site. <a href="http://domaindrivendesign.org/">Eric Evans talks</a> about the &#8220;domain&#8221; of a problem when discussing software &#8211; not only do you have to appreciate what kind of features are necessary but you have to understand the domain in which they&#8217;re going to be used, in order to create a solution which fits together correctly.
So software is a whole big bag of questions and clarifications and solutions. From a developer&#8217;s point of view, it&#8217;s not just a case of taking some standard components and piecing them together &#8211; though that does happen occasionally. Instead every step of the development process is about solving problems, by understanding what the customer wants and by understanding the problem domain. Every day of development sees a developer tackle a new bit of work that needs resolving in a novel way, and that&#8217;s why making software isn&#8217;t just a case of shoving some parts together and hoping that it works, but a process, an evolution of the initial ideas.
When clients come to us and ask for software, they&#8217;ll pitch it by saying &#8220;make us a website&#8221;. But we know that what they really mean is &#8220;look, understand, and solve our problem&#8221;. And that&#8217;s what we do.

Problem Solving in Software

Rails 2.3 delivered a new feature that allows you to easily write forms in rails that can process nested attributes for related objects using the accepts_nested_attributes_for method in your models. Now there is a plugin to make adding and removing nested forms a walk in the park!
I am not going to go into detail about this feature as <a href="http://ryandaigle.com/articles/2009/2/1/what-s-new-in-edge-rails-nested-attributes#comment-form">Ryan Daigle has an excellent write up on his blog</a>.
However I have been looking at ways to easily add and remove nested form blocks using Javascript/RJS and came across a good method of achieving this <a href="http://railsforum.com/viewtopic.php?pid=91229">by Marsvin on the RailsForum website</a>.
We have used this method a few times now, so thought we would roll it up into a plugin. Simply install the plugin to give you two new view helpers that allow you to create links to add and remove these nested form item partials using RJS.
<a href="http://github.com/miletbaker/add_nested_fields">Visit the plugin&#8217;s page on GitHub to install or view the documentation.</a>

Dynamic Nested Forms in Rails 2.3+ Using RJS

One of the hidden gems of System.Net is the ability to change from using an SMTP server for sending your email. Instead you can specify a pickup directory which will receive all emails sent from your application as a .EML text file. There are clearly uses for this in production &#8211; you may have a second application which monitors this pickup directory and sends the emails after performing some processing on them.
My favourite use of this feature is for development &#8211; when you&#8217;re sending loads of test emails you can avoid polluting your inbox and simply check the pickup directory. You also avoid having to set up an SMTP host and all of the associated configuration.
Simply add the following to your web.config&#8217;s system.net section:
<pre><code class="language-xml">&lt;mailSettings&gt;
 &lt;smtp deliveryMethod="SpecifiedPickupDirectory"&gt;
 &lt;specifiedPickupDirectory pickupDirectoryLocation="c:temp"/&gt;
 &lt;/smtp&gt;
&lt;/mailSettings&gt;</code></pre>
Make sure you&#8217;ve got the right permissions on the directory. Now, send an email from your application and watch it appear in c:temp, as if by magic!

ASP.NET SMTP – Setting a Pickup Directory for Development

Having used flash extensively for the last few years I have really come to rely on using Scale-9 scaling on UI elements in the rich internet apps I design and develop. It is a great technique for things like rounded rectangles, button graphics etc and ensuring the rounded corners do not distort when stretched.
I have recently been doing Cocoa Development on Mac OS X 10.5 and was looking for a way to do this in Cocoa and <a href="http://www.karlkraft.com/index.php/2007/11/14/nsdrawninepartimage/">came across</a> a great drawing method named <a href="http://developer.apple.com/documentation/Cocoa/Reference/ApplicationKit/Miscellaneous/AppKit_Functions/Reference/reference.html">NSDrawNinePartImage</a>. The method has the following signature:
<pre><code class="language-objectivec">void NSDrawNinePartImage(NSRect frame,
 NSImage *topLeftCorner,
 NSImage *topEdgeFill,
 NSImage *topRightCorner,
 NSImage *leftEdgeFill,
 NSImage *centerFill,
 NSImage *rightEdgeFill,
 NSImage *bottomLeftCorner,
 NSImage *bottomEdgeFill,
 NSImage *bottomRightCorner,
 NSCompositingOperation op,
 CGFloat alphaFraction,
 BOOL flipped
);</code></pre>
This method requires the developer to provide 9 separate images to create the 9 sections of the scale 9 image. Luckily the article I had stumbled across had a handy example for using a single class, so I thought that I would use their technique to create a simple generic class that can be used to draw a single NSImage as a Scale-9 scalable image. This could be used for example in an NSView or NSButtonCell.
<pre><code class="language-objectivec">//
// GTDrawImage.m
// StretchMyView
//
// Created by Jon Baker on 17/06/2009.
// Copyright 2009 Go Tripod Ltd. All rights reserved.
//

#import "GTDrawImage.h"

@implementation GTDrawImage

+(void) drawScalableImage:(NSImage *)sourceImage scaleTopLeft:(NSPoint)topLeftPoint scaleBottomRight:(NSPoint)bottomRightPoint inFrame:(NSRect)frame
{
	NSSize sourceSize = [sourceImage size];

	// Top left
	NSRect topLeftTileRect = NSMakeRect(0, 0, topLeftPoint.x, sourceSize.height - topLeftPoint.y);
	NSRect topLeftCutRect = NSMakeRect(0, topLeftPoint.y, topLeftTileRect.size.width, topLeftTileRect.size.height);

	// TopRight
	NSRect topRightTileRect = NSMakeRect(0,0, sourceSize.width - bottomRightPoint.x, topLeftTileRect.size.height);
	NSRect topRightCutRect = NSMakeRect(sourceSize.width - topRightTileRect.size.width, topLeftPoint.y, topRightTileRect.size.width, topRightTileRect.size.height);

	// Top
	NSRect topTileRect = NSMakeRect(0, 0, sourceSize.width - topLeftTileRect.size.width - topRightTileRect.size.width, topLeftTileRect.size.height);
	NSRect topCutRect = NSMakeRect(topLeftPoint.x, topLeftPoint.y, topTileRect.size.width, topTileRect.size.height);

	// Bottom Left
	NSRect bottomLeftTileRect = NSMakeRect(0, 0, topLeftCutRect.size.width, bottomRightPoint.y);
	NSRect bottomLeftCutRect = NSMakeRect(0, 0, bottomLeftTileRect.size.width, bottomLeftTileRect.size.height);

	// Bottom Right
	NSRect bottomRightTileRect = NSMakeRect(0,0, topRightCutRect.size.width, bottomLeftTileRect.size.height);
	NSRect bottomRightCutRect = NSMakeRect(topRightCutRect.origin.x, 0, bottomRightTileRect.size.width , bottomRightTileRect.size.height );

	// Bottom
	NSRect bottomTileRect = NSMakeRect(0,0, topTileRect.size.width, bottomLeftTileRect.size.height);
	NSRect bottomCutRect = NSMakeRect(topCutRect.origin.x, 0, bottomTileRect.size.width, bottomTileRect.size.height);

	// left

	NSRect leftTileRect = NSMakeRect(0, 0, bottomLeftTileRect.size.width, sourceSize.height - topTileRect.size.height - bottomTileRect.size.height);
	NSRect leftCutRect = NSMakeRect(0, bottomRightPoint.y, leftTileRect.size.width, leftTileRect.size.height);

	// right

	NSRect rightTileRect = NSMakeRect(0, 0, topRightCutRect.size.width, leftCutRect.size.height);
	NSRect rightCutRect = NSMakeRect(bottomRightPoint.x, bottomRightPoint.y, rightTileRect.size.width, rightTileRect.size.height);

	//center
	NSRect centerTileRect = NSMakeRect(0, 0, topTileRect.size.width, leftTileRect.size.height);
	NSRect centerCutRect = NSMakeRect(topCutRect.origin.x, bottomRightPoint.y, centerTileRect.size.width, centerTileRect.size.height);

	NSImage *topLeft = [[NSImage alloc] initWithSize:topLeftTileRect.size];
	[topLeft lockFocus];
	[sourceImage drawInRect:topLeftTileRect fromRect:topLeftCutRect operation:NSCompositeCopy fraction:1.0];
	[topLeft unlockFocus];

	NSImage *top = [[NSImage alloc] initWithSize:topTileRect.size];
	[top lockFocus];
	[sourceImage drawInRect:topTileRect fromRect:topCutRect operation:NSCompositeCopy fraction:1.0];
	[top unlockFocus];

	NSImage *topRight = [[NSImage alloc] initWithSize:topRightTileRect.size];
	[topRight lockFocus];
	[sourceImage drawInRect:topRightTileRect fromRect:topRightCutRect operation:NSCompositeCopy fraction:1.0];
	[topRight unlockFocus];

	//setup center section, left, right
	NSImage *left = [[NSImage alloc] initWithSize:leftTileRect.size];
	[left lockFocus];
	[sourceImage drawInRect:leftTileRect fromRect:leftCutRect operation:NSCompositeCopy fraction:1.0];
	[left unlockFocus];

	NSImage *center = [[NSImage alloc] initWithSize:centerTileRect.size];
	[center lockFocus];
	[sourceImage drawInRect:centerTileRect fromRect:centerCutRect operation:NSCompositeCopy fraction:1.0];
	[center unlockFocus];

	NSImage *right = [[NSImage alloc] initWithSize:rightTileRect.size];
	[right lockFocus];
	[sourceImage drawInRect:rightTileRect fromRect:rightCutRect operation:NSCompositeCopy fraction:1.0];
	[right unlockFocus];

	NSImage *bottomLeft = [[NSImage alloc] initWithSize:bottomLeftTileRect.size];
	[bottomLeft lockFocus];
	[sourceImage drawInRect:bottomLeftTileRect fromRect:bottomLeftCutRect operation:NSCompositeCopy fraction:1.0];
	[bottomLeft unlockFocus];

	NSImage *bottom = [[NSImage alloc] initWithSize:bottomTileRect.size];
	[bottom lockFocus];
	[sourceImage drawInRect:bottomTileRect fromRect:bottomCutRect operation:NSCompositeCopy fraction:1.0];
	[bottom unlockFocus];

	NSImage *bottomRight = [[NSImage alloc] initWithSize:bottomRightTileRect.size];
	[bottomRight lockFocus];
	[sourceImage drawInRect:bottomRightTileRect fromRect:bottomRightCutRect operation:NSCompositeCopy fraction:1.0];
	[bottomRight unlockFocus];

	NSDrawNinePartImage(
						frame,
						topLeft, top, topRight,
						left, center, right,
						bottomLeft, bottom, bottomRight,
						NSCompositeSourceOver, 1.0, NO);

	[topLeft release];
	[top release];
	[topRight release];
	[left release];
	[center release];
	[right release];
	[bottomLeft release];
	[bottom release];
	[bottomRight release];
}

@end</code></pre>
To use this generic classes, you simply need to import it where required:
<pre><code class="language-objectivec">#import "GTDrawImage.h"</code></pre>
&#8230;and then you can call from within, for example the drawRect:, selector using the following method:
<pre><code class="language-objectivec">- (void)drawRect:(NSRect)rect {
	[GTDrawImage drawScalableImage:baseImage scaleTopLeft:NSMakePoint(8, 16) scaleBottomRight:NSMakePoint(16,8) inFrame: [self bounds]];
}</code></pre>
<code>drawScalableImage</code> takes an NSImage, in this case baseImage, and two reference points (NSPoint) to split the image into nine slices, firstly the scaleTopLeft: and secondly the scaleBottomRight:, both located from the bottom left corner. So for example to split a 24px x 24px image into 9 equal 8px by 8px segments (see below), the topLeftPoint would be x=8px, y=16px and the bottom x=16 and y=8.
Just download the following classes into your projects and away you go:
<ul>
<li>Header: <a class="s3-link" href="http://clockobj.co.uk.s3.amazonaws.com/GTDrawImage.h">GTDrawImage.h</a></li>
<li>Implementation: <a class="s3-link" href="http://clockobj.co.uk.s3.amazonaws.com/GTDrawImage.m">GTDrawImage.m</a></li>
<li>Sample Project using GTDrawImage: <a class="s3-link" href="http://clockobj.co.uk.s3.amazonaws.com/StretchMyView.zip">StretchMyView.zip</a> (Adapted example I found. Unfortunately I can&#8217;t remember where and so don&#8217;t know who to credit)</li>
</ul>

Scale-9 in Objective-C Cocoa on the Mac

I have been meaning to blog about Phusion Passenger for a while as about 3-4 months ago we migrated Stubmatic from using Apache / Mongrel Cluster to <a href="http://www.modrails.com/">Phusion Passenger A.K.A. mod_rails</a>.
Mod rails is extreamly easy to install. Make sure you update gem first:
<pre><code class="language-bash">gem update --system</code></pre>
Then install the Phusion Passenger gem
<pre><code class="language-bash">gem install passenger</code></pre>
Once complete you can run the Phusion Passenger install that compiles mod_rails for you.
<pre><code class="language-bash">passenger-install-apache2-module</code></pre>
Once this completes it will give you some code to past into your httpd.conf file and you are ready to start configuring your sites.. Well actually if you have been using Mongrels then time to strip most of the configuration out of your https.conf file. You can have as simple a configuration as shown below. Note: The DocumentRoot should be set to the public folder within your app. Passenger automatically detects that this is a rails app.
<pre><code class="language-powershell">ServerName www.stubmatic.com
DocumentRoot /websites/stubmatic/public</code></pre>
One thing to note is that by default Passenger disables ModRewrite for that VirtualHost and in our case we use ModRewrite for a number of things such as providing a Maintenance page when maintenance.html is in our public folder allowing us to take the app offline. We also use ModRewrite to hide .svn folders, so we needed to use ModRewrite. Thankfully Passenger provides a solution. Note: You must first make sure you remove the .htaccess file in your rails public folder!
So our new Apache configuration looks like this:
<pre><code class="language-powershell">ServerName www.stubmatic.com
DocumentRoot /websites/stubmatic/public

RailsAllowModRewrite on

RewriteEngine On

RewriteRule ^(.*/)?.svn/ - [F,L]

RewriteCond %{DOCUMENT_ROOT}/maintenance.html -f
RewriteCond %{SCRIPT_FILENAME} !maintenance.html
RewriteRule ^.*$ /maintenance.html [L]</code></pre>
If you want to setup an Apache / Phusion Passenger testing server you will also need to add the following directive to your VirtualHost configuration:
<pre><code class="language-powershell">RailsEnv development</code></pre>
As you can see Phusion Passenger make deployment of Ruby on Rails as trivial as deploying a PHP. You can easily reload Phusion Passenger by running the following command from within your Rails project root.
<pre><code class="language-powershell">touch tmp/restart.txt</code></pre>
In terms of performance, Phusion Passenger holds it&#8217;s own against Mongrel and there are <a href="http://www.modrails.com/documentation.html">plenty of details on Phusion&#8217;s website</a>.
For more information:
<ol>
<li><a href="http://www.modrails.com/">Phusion Passenger</a></li>
<li><a href="http://www.modrails.com/documentation/Users%20guide.html">Phusion Passenger Documentation</a></li>
</ol>

Rails deployment is so easy these days

iPhone and Adobe Air developers (as well as any others that use SQLite 3) <a href="http://menial.co.uk">Menial</a> has just released an excellent little app for creating, managing and running queries against SQLite 3 databases called Bases.
<a data-size="764x648" href="https://content.gotripod.com/images/2008/11/schema1.png"><img loading="lazy" class="alignnone size-medium wp-image-145" src="https://content.gotripod.com/images/2008/11/schema1-300x254.png" alt="" width="300" height="254" srcset="https://content.gotripod.com/wp-content/uploads/2008/11/schema1-300x254.png 300w, https://content.gotripod.com/wp-content/uploads/2008/11/schema1.png 764w" sizes="(max-width: 300px) 100vw, 300px" /></a>
The application is simple to use, very user friendly and has worked well from the testing I have done. It costs just £10 and there is a free trial available so you can try before you buy.
<a href="http://menial.co.uk/software/base/">Find out more and download here</a>

Excellent OS X SQLite 3 Management & Query App

A quick sorry to all my Flex readership for the lack of Flex related posts these last few months. I though I would drop a quick tip / class I often use to create a two way binding between a form to a corresponding class model.
Flex provides a one way binding through its &lt;mx:Binding&gt; tags, if you are unfamiliar with this tag check out the <a href="http://www.adobe.com/devnet/flex/quickstart/using_data_binding/#section3">section on them in Adobe&#8217;s Flex quick start guide</a>. However if you want changes made to the model reflected in the form as well as changes made to the form reflected back in the model you need to set up two way bindings. To simplify this I have created a helper class (listed below) which then allows me to establish a two way binding.
<pre><code class="language-actionscript">package com.vibrant.components.Forms
{
	import flash.display.DisplayObject;

	import mx.binding.utils.BindingUtils;
	import mx.binding.utils.ChangeWatcher;

	public class ModelBinding
	{

		private var _modelWatcher		: ChangeWatcher;
		private var _componentWatcher		: ChangeWatcher;
		private var bindingsAreEstablished	: Boolean = false;

		public function ModelBinding()
		{
		}

		/**
		 * Property field
		 * @default null
		 */

		private var _model : Object;

		public function set model( value : Object ):void
		{
			_model = value;
			updateBinding();
		}

		public function get model() : Object
		{
			return _model;
		}

		/**
		 * Property field, field within model to bind
		 * @default ""
		 */

		private var _field:String;

		public function set field( value : String ):void
		{
			_field = value;
			updateBinding();
		}

		public function get field() : String
		{
			return _field;
		}

		/**
		 * Property: target, component to tartget binding from model to.
		 */

		private var _target : Object;

		public function set target( value : Object ):void
		{
			_target = value;
			updateBinding();
		}

		public function get target() : Object
		{
			return _target;
		}

		/**
		 * Property: property, to bind to on target component
		 */

		private var _property : String = "text";

		public function set property( value : String ):void
		{
			_property = value;
			updateBinding();
		}

		public function get property() : String
		{
			return _property;
		}

		/**
		 * @private
		 * Updates bindings between component and model
		 *
		 */
		private function updateBinding() : void
		{
			if ( bindingsAreEstablished ) clearBindings();

			if ( model != null &amp;&amp; model.hasOwnProperty( field )
				&amp;&amp; target != null &amp;&amp; target.hasOwnProperty( property ) )
			{
				_modelWatcher = BindingUtils.bindProperty( target, property, model, field );
				_componentWatcher = BindingUtils.bindProperty( model, field, target, property );
				bindingsAreEstablished = true;
			}
		}

		/**
		 * Clears bindings
		 *
		 */
		private function clearBindings() : void {

			if ( _modelWatcher != null )
			{
				_modelWatcher.unwatch();
				_modelWatcher = null;
			}

			if ( _componentWatcher != null )
			{
				_componentWatcher.unwatch();
				_componentWatcher = null;
			}
			bindingsAreEstablished = false;
		}

	}
}</code></pre>
This class basically takes a model class, that has the data you would like to setup the bindings with in. The field name, the name of the property within the model class to bind to. A target, the form component to establish the view side binding with and finally you can specify an optional property that the binding should be made to on the form element. If unspecified, the &#8216;property&#8217; defaults to &#8220;text&#8221; as this is the most often used property to bind to. So for example given the following User model:
<pre><code class="language-actionscript">public class UserModel
{
 public var firstName : String;
 public var lastName : String;

	public function UserModel()
	{
	}
}</code></pre>
We could set up a binding to a TextInput as follows:
<pre class="line-numbers"><code class="language-markup">...
&lt;mx:Script&gt;
	&lt;![CDATA[
		public var userModel : UserModel;
	]]&gt;
&lt;/mx:Script&gt;
&lt;mx:Form&gt;
	&lt;mx:FormItem label="First Name"&gt;
		&lt;mx:TextInput id="txtFirstName"/&gt;
	&lt;/mx:FormItem&gt;
&lt;/mx:Form&gt;
&lt;modelBinding model="{userModel}" field="firstName" target="{txtFirstName}"/&gt;
...</code></pre>
As you can see with this class you can quickly setup two-way bindings with your models.

Creating a two-way binding between Model and Form in Flex

I recently needed to setup recurring payments through PayPal&#8217;s express checkout for a subscription based site I have writen using Ruby on Rails. There is already an excellent framework for interacting with most payment gateways, including PayPal, for Ruby called <a href="http://www.activemerchant.org/">Active Merchant</a>. Unfortunately recurring payments support in Active Merchant for PayPal Express Checkout is limited to a <a href="http://jadedpixel.lighthouseapp.com/projects/11599-active-merchant/tickets/17-patch-creating-paypal-recurring-payments-profile-with-activemerchant#ticket-17-4">script pasted into their lighthous bug tracking system</a>. The trouble is that this script only covers creating subscription profiles and also later getting details of that profile, but I needed to be able to suspend and cancel subscriptions profiles as well as make changes to the subscription from my site.
**** UPDATE: ActiveMerchant recently removed the functionality to use PayPal&#8217;s NVP API and so this code will no longer work with the latest ActiveMerchant. Raymond Law has kindly ported the code to use the SOAP API and <a href="http://rayvinly.com/articles/2009/02/20/paypal-recurring-billing-with-activemerchant-in-ruby-on-rails/">you can find out more information and usage on his blog</a>. ****
Active Merchant is very easy to extend so I have written a Ruby class that can be dropped into /vendor/plugins/active_merchant/billing/gateways/ within your Rails project (assuming you have AM installed as a plugin)
<pre><code class="language-ruby"># simple extension to ActiveMerchant for basic support of recurring payments with Express Checkout API
#
# See http://http://www.gotripod.com/2008/09/07/ruby-on-rails-paypal-express-recurring-payments-using-active-merchant/
# for details on getting started with this gateway
#
#
module ActiveMerchant #:nodoc:
 module Billing #:nodoc:
 class PaypalExpressRecurringNvGateway &lt; Gateway
 include PaypalNvCommonAPI

 LIVE_REDIRECT_URL = 'https://www.paypal.com/cgibin/webscr?cmd=_customer-billing-agreement&amp;token='
 TEST_REDIRECT_URL = 'https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_customer-billing-agreement&amp;token='

 def redirect_url
 test? ? TEST_REDIRECT_URL : LIVE_REDIRECT_URL
 end

 def redirect_url_for(token)
 "#{redirect_url}#{token}"
 end

 def setup_agreement(description, options = {})
 requires!(options, :return_url, :cancel_return_url)
 commit 'SetCustomerBillingAgreement', build_setup_agreement(description, options)
 end

 def get_agreement(token)
 commit 'GetBillingAgreementCustomerDetails', build_get_agreement(token)
 end

 def create_profile(money, token, options = {})
 commit 'CreateRecurringPaymentsProfile', build_create_profile(money, token, options)
 end

 def get_profile_details(profile_id)
 commit 'GetRecurringPaymentsProfileDetails', build_get_profile_details(profile_id)
 end

 def manage_profile(profile_id, action, options = {})
 commit 'ManageRecurringPaymentsProfileStatus', build_manage_profile(profile_id, action, options)
 end

 def update_profile(profile_id, options = {})
 commit 'UpdateRecurringPaymentsProfile', build_update_profile(profile_id, options)
 end

 def bill_outstanding(profile_id, money, options = {})
 commit 'BillOutstandingAmount', build_bill_outstanding(profile_id, money, options)
 end

 private

 def build_setup_agreement(description, options)
 post = {}
 add_pair(post, :billingagreementdescription, description)
 add_pair(post, :returnurl, options[:return_url])
 add_pair(post, :cancelurl, options[:cancel_return_url])
 add_pair(post, :billingtype, "RecurringPayments")
 add_pair(post, :paymenttype, options[:payment_type]) if options[:payment_type]
 add_pair(post, :localecode, options[:locale]) if options[:locale]
 add_pair(post, :billingagreementcustom, options[:custom_code]) if options[:custom_code]
 post
 end

 def build_get_agreement(token)
 post = {}
 add_pair(post, :token, token)
 post
 end

 def build_create_profile(money, token, options)
 post = {}
 add_pair(post, :token, token)
 add_amount(post, money, options)
 add_pair(post, :subscribername, options[:subscriber_name]) if options[:subscriber_name]
 add_pair(post, :initamt, options[:initamt]) if options[:initamt]
 add_pair(post, :failedinitamtaction, options[:failedinitamtaction]) if options[:failedinitamtaction]
 add_pair(post, :profilestartdate, Time.now.utc.iso8601)
 add_pair(post, :billingperiod, options[:billing_period] ? options[:billing_period] : "Month")
 add_pair(post, :billingfrequency, options[:billing_frequency] ? options[:billing_frequency] : 1)
 add_pair(post, :totalbillingcycles, options[:billing_cycles]) if [:billing_cycles]
 add_pair(post, :profilereference, options[:reference]) if options[:reference]
 add_pair(post, :autobillamt, options[:auto_bill_amt]) if options[:auto_bill_amt]
 add_pair(post, :maxfailedpayments, options[:max_failed_payments]) if options[:max_failed_payments]
 add_pair(post, :shippingamt, amount(options[:shipping_amount]), :allow_blank =&gt; false) if options[:shipping_amount]
 add_pair(post, :taxamt, amount(options[:tax_amount]), :allow_blank =&gt; false) if options[:tax_amount]
 add_shipping_address(post, options[:shipping_address]) if options[:shipping_address]
 post
 end

 def build_get_profile_details(profile_id)
 post = {}
 add_pair(post, :profileid, profile_id)
 post
 end

 def build_manage_profile(profile_id, action, options)
 post = {}
 add_pair(post, :profileid, profile_id)
 add_pair(post, :action, action)
 add_pair(post, :note, options[:note]) if options[:note]
 post
 end

 def build_update_profile(profile_id, options)
 post = {}
 add_pair(post, :profileid, profile_id)
 add_pair(post, :note, options[:note]) if options[:note]
 add_pair(post, :desc, options[:description]) if options[:description]
 add_pair(post, :subscribername, options[:subscriber_name]) if options[:subscriber_name]
 add_pair(post, :profilereference, options[:reference]) if options[:reference]
 add_pair(post, :additionalbillingcycles, options[:additional_billing_cycles]) if options[:additional_billing_cycles]
 add_amount(post, options[:money], options)
 add_pair(post, :shippingamt, amount(options[:shipping_amount]), :allow_blank =&gt; false) if options[:shipping_amount]
 add_pair(post, :autobillamt, options[:auto_bill_amt]) if options[:auto_bill_amt]
 add_pair(post, :maxfailedpayments, options[:max_failed_payments]) if options[:max_failed_payments]
 add_pair(post, :taxamt, amount(options[:tax_amount]), :allow_blank =&gt; false) if options[:tax_amount]
 add_shipping_address(post, options[:shipping_address]) if options[:shipping_address]
 post
 end

 def build_bill_outstanding(profile_id, money, options = {})
 post = {}
 add_pair(post, :profileid, profile_id)
 add_amount(post, money, options)
 add_pair(post, :note, options[:note]) if options[:note]
 post
 end

 def build_response(success, message, response, options = {})
 PaypalExpressNvResponse.new(success, message, response, options)
 end

 end
 end
end</code></pre>
With this class installed using Active Merchant to set up a subscription / recurring payment through PayPal Express Checkout is easy. Firstly setup your gateway object:
<pre><code class="language-ruby">gw = ActiveMerchant::Billing::PaypalExpressRecurringNvGateway.new( :login =&gt; 'PAYPALEMAIL', :password =&gt; 'PASSWORD', :signature =&gt; 'PAYPALAPISIGNATURE' )</code></pre>
Then make a request to PayPal to setup the recurring payment. At this stage you pass through a description (which is what is shown to the user when they are asked to authorise the subscription so make it descriptive) and you also need to provide URLs on your site, that PayPal should redirect the subscriber back to when they either complete the payment, or alternatively if they choose to cancel.
<pre><code class="language-ruby">response = gw.setup_agreement("Subscription £25 per month", :cancel_return_url =&gt; "https://mysite.com/cancel", :return_url =&gt; "https://mysite.com/complete" )</code></pre>
The request above returns us a token in the response from paypal and at this point we need to redirect the user to PayPal to authorise this subscription. The user will see the description &#8220;Subscription £25 per month&#8221; as sent in the previous request. We need to redirect the subscriber to PayPal using the following line of ruby:
<pre><code class="language-ruby">redirect_to gw.redirect_url_for(response.token)</code></pre>
Once the user has authorised the subscription they are returned to the :return_url we specified earlier, at which point we can create the actual subscription using the following:
<pre><code class="language-ruby">response = gw.create_profile(2500, response.token, :currency =&gt; "GBP", :reference =&gt; "34")</code></pre>
Note: PayPal are really confusing having one API for the US and another for the UK but if you are using PayPal Express (which is free) independently of PayPal Website Payments Pro (Which you need to pay for) the US PayPal Express API works for all countries (apart from Germany I believe) and as you can see above I am passing in the UK currency. I am using the US API and I have a UK PayPal account. Also note that I have passed in a reference (I have an IPN URL setup in my PayPal account &#8211; Unfortunately you cannot pass an IPN URL with the request) to be sent in the IPN.
The previous step completes the set up of our Subscription. However if we need to later get information on the subscription or change it, we need to extract the Profile ID from the response as follows:
<pre><code class="language-ruby">profile_id = response.params["profileid"]</code></pre>
With this profile_id we can then later use these additional methods that I have included, such as getting details of the subscription profile using:
<pre><code class="language-ruby">gw.get_profile_details(profile_id)</code></pre>
Update the subscription using various options (i.e. changing subscription amount shown below):
<pre><code class="language-ruby">gw.update_profile(profile_id, :money =&gt; 3000, :currency =&gt; "GBP")</code></pre>
Manage the subscription, for example cancel it as follows:
<pre><code class="language-ruby">gw.manage_profile(profile_id, "Cancel", :note =&gt; "Your subscription has been cancelled by us")</code></pre>
And finally bill any outstanding subscription balance:
<pre><code class="language-ruby">gw.bill_outstanding(profile_id, 2500, :currency=&gt; "GBP", :note =&gt; "£20 Overdue Subscription")</code></pre>
Please note that as of yet this class is not part of Active Merchant, however it has been added to <a href="http://jadedpixel.lighthouseapp.com/projects/11599-active-merchant/tickets/17-patch-creating-paypal-recurring-payments-profile-with-activemerchant#ticket-17-4">Active Merchants case #17</a> If you want to use this you will have to add it manually as above.
I recommend reading <a href="https://www.paypal.com/en_US/pdf/PP_ExpressCheckout_IntegrationGuide.pdf">PayPals Express Checkout Integration Guide</a> and the <a href="https://www.paypal.com/en_US/pdf/PP_NVPAPI_DeveloperGuide.pdf">Name Value Pair API Developer Guide and Reference</a> for more information on what variables can be passed in each request to PayPal.

Ruby on Rails, PayPal Express Recurring Payments using Active Merchant

This may be an unusual first post in my Objective-C and Cocoa categories however it is quite relevant as the guys behind <a href="http://280slides.com/">280 Slides</a> have released a <a href="http://cappuccino.org/">new open source extension</a> to the Javascript language known as Objective-J and a new Javascript framework based on Cocoa named Cappuccino.
Other than having a very nice logo designed by the guys at <a href="http://madebysofa.com/">Sofa</a> my first impressions are they have implemented Objective-C in javascript. To me this seems an unusual choice as I can&#8217;t image there are that many developers (within the web development industry) who are that familiar with Objective-C. Maybe I am wrong, certainly with the current gold rush to develop for the iPhone this will increase. I must admit I have been toying with Objective-C recently and once I got the hang of the syntax am really starting to enjoy it. So maybe there is method to their madness?<a id="more"></a><a id="more-373"></a>
The <a href="http://cappuccino.org/">Cappuccino framework</a> has been likened to the recently released (and overhyped in my opinion &#8211; seems slow and clunky to me) <a href="http://www.sproutcore.com/">SproutCore</a> framework. However I am extreamly impressed with how quick <a href="http://280slides.com/">280 Slides</a> responds to user interactions and in addition to this the set of controls provided with Cappuccino have a nicer OS X quality to them.
My personal opinion is that the future of Rich Internet Applications does not lie with Javascript (though I am biased to Flex). It is not that I dislike Javascript, quite the oposite in fact. My reservations mainly lie in Javascript relying too heavily on the HTML DOM and is at the mercy of browsers and their stakeholders (for which there are too many). One of the nices things with technologies such as Flex and Silverlight is the cross browser consistency. Not only this but also the many rich media features such as image manipulation &amp; processing, the ability to do advanced animation including 3D animation, video features etc. which to me put the Rich in Rich Internet Applications.
I may well eat my words as two major players in the form of Apple and Google are backing Javascript as the future standard for RIA development. Google&#8217;s <a href="http://www.google.com/chrome">Chrome</a> browser addresses some of the performance and stability issues and Apple has recently based it&#8217;s online MobileMe business on Javascript (aparently using <a href="http://www.sproutcore.com/">SpoutCore</a>) as well as introducing new extensions to Javascript such as the Canvas tag that help overcome some of Javascripts shortfalls.
One thing is sure I take my hat off to these guys for pushing the boundaries of Javascript and in particular for implementing Objective-C in Javascript. If you are an Objective-C developer, it is well worth a look as you will be able to quickly develop javascript web applications using a near identical language. If not, check it out anyway. These guys can certainly claim that this is Cocoa for Web Development.
<h3>Update</h3>
I wanted to include a couple of code snippets (taken from Cappuccino.org) just to illustrate how similar to Objective-C, Objective J is.
In Objective-J classes are declared much like an Objective-C header file:
<pre><code class="language-objectivec">@implementation Person : CPObject
{
 CPString name;
}
@end</code></pre>
Methods are declared using the identical Objective-C syntax:
<pre><code class="language-objectivec">- (void)setName:(CPString)aName
{
	name = aName;
}
- (CPString)name
{
	return name;
}</code></pre>
And class methods can be called using a once again similar syntax:
<pre><code class="language-objectivec">[myPerson setJobTitle: "Founder" company: "280 North"];</code></pre>
<a href="http://theocacao.com/document.page/593">Cocoa Master Scott Stevenson has done a nice comparison between Cocoa and Cappuccino, well worth a read..</a>

Objective-J & Cappuccino

A quick tip if you have a dynamic scroll bar and want to bind it&#8217;s maxScrollPosition to a value at runtime unfortunately you can&#8217;t use the MXML binding, i.e. <code>maxScrollPosition={value}</code>.
Alternatively you need to set the value programatically in an event handler, AND importantly call <code>updateDisplayList()</code> on the scrollbar. i.e.
<pre><code class="language-actionscript">&lt;!--[CDATA[
	private function handleSlideChange():void {
		scroll.maxScrollPosition = slider.value;
		scroll.invalidateDisplayList();
	}
]]--&gt;</code></pre>

Changing Flex3 ScrollBar maxScrollPosition at runtime

In this final part on building a medium to large scale flex or Air app using Cairngorm, I will look at how I approach the service locator and use flex builders built in responder mechanism to handle service call responses.
<h2>Services</h2>
In <a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-1">part 1</a> we created a ServiceLocator singleton using the same method as we did for our ModelLocator. We will use this in a minute when we register our Service with the ServiceLocator.
I like to create a proxy class for my services.
<pre><code class="language-actionscript">package uk.co.clockobj.cairngormdemo.controller.services
{
	import mx.rpc.AsyncToken;
	import mx.rpc.IResponder;
	import mx.rpc.remoting.RemoteObject;

	public class UserService
	{
		private var ro : RemoteObject;

		public function UserService()
		{
			ro = new RemoteObject();
			ro.destination = "userService";
		}

		public function logInUser( username : String, password : String, responder : IResponder) : void
		{
			var at : AsyncToken = ro.logInUser( username, password );
			at.addResponder( responder );
		}

	}
}</code></pre>
In this example we want to call a destination method called logInUser() passing a username and password as parameters. Here I am using the RemoteObject class to work with a backend server such as <a href="http://www.adobe.com/products/livecycle/">LiveCycle</a>, <a href="http://opensource.adobe.com/wiki/display/blazeds/BlazeDS">BlazeDS</a>, <a href="http://www.exadel.com/web/portal/flamingo">Flamingo</a>, <a href="http://www.themidnightcoders.com/weborb/">WebOrb</a> etc, via AMF (Actionscript Message Format), but you can use this with HTTPService, WebService, etc.
Notice that along with the two parameters that our service call will need, I have added a responder of type IResponder. I am going to use the <a href="http://www.darronschall.com/weblog/archives/000234.cfm">method championed by Darron Schall</a> where we use Flex&#8217;s built in responder and AsyncToken mechanism.
We need to now register this service on our ServiceLocator.
<pre><code class="language-actionscript">package uk.co.clockobj.cairngormdemo.controller
{
	import uk.co.clockobj.cairngormdemo.controller.services.ProductService;
	import uk.co.clockobj.cairngormdemo.controller.services.UserService;

	public class ServiceLocator
	{
		private static var _instance:ServiceLocator;

		public static function getInstance():ServiceLocator {
			if (_instance == null) {
				_instance = new ServiceLocator();
			}
			return _instance;
		}

		public function ServiceLocator()
		{
			if ( _instance != null )
			{
				throw( new Error( "Singleton class has already been instantiated" ) );
			} else
			{
				// Instantiate services here
				userService = new UserService();
				productService = new ProductService();
			}
		}

		public var userService : UserService;
		public var productService : ProductService;

	}
}</code></pre>
<h2>IResponder</h2>
The IResponder interface that we used in our service enforces any class that implements it to provide a result( data : Object ) and fault( info : Object ) method. Due to the Asynchronous nature of Actionscript 3, the AsyncToken ensures the responder we provide handles that particular service call. Regular Event handlers to not offer this.
We are going to get all the commands we create (that make service calls) to implement this IResponder interface, in addition to the ICommand interface. We can then pass the command to the service as the responder for the service call:
So for a command that gets the ProductDTOs we used in <a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-2">Part 2</a>, using for example a getProducts() method call on a productService destination.
Service:
<pre><code class="language-actionscript">package uk.co.clockobj.cairngormdemo.controller.services
{
	import mx.rpc.AsyncToken;
	import mx.rpc.IResponder;
	import mx.rpc.remoting.RemoteObject;

	public class ProductService
	{
		private var ro : RemoteObject;





		public function ProductService()
		{
			ro = new RemoteObject();
			ro.destination = "productService";
		}

		public function getProducts( responder : IResponder ) : void
		{
			var at : AsyncToken = ro.getProducts();
			at.addResponder( responder );
		}

	}
}</code></pre>
(We register this with our ServiceLocator as we did for the UserService)
GetAllProductsCommand:
<pre><code class="language-actionscript">package uk.co.clockobj.cairngormdemo.controller.commands
{
	import com.adobe.cairngorm.commands.ICommand;
	import com.adobe.cairngorm.control.CairngormEvent;

	import mx.rpc.IResponder;
	import mx.rpc.events.ResultEvent;

	import uk.co.clockobj.cairngormdemo.controller.ServiceLocator;
	import uk.co.clockobj.cairngormdemo.model.ModelLocator;

	public class GetAllProductsCommand implements ICommand, IResponder
	{
		public function GetAllProductsCommand()
		{
		}

		public function execute(event:CairngormEvent):void
		{
			ServiceLocator.getInstance().productService.getProducts( this );
		}

		public function result(data:Object):void
		{
			ModelLocator.getInstance().product.dtos = ResultEvent( data ).result;
		}

		public function fault(info:Object):void
		{
			// Fault handler code
		}

	}
}</code></pre>
Once this command is registered with our controller we can dispatch the relevant event form anywhere in our application to load all the products into our model.
Notice above how the command implements the IResponder interface and passes itself to the service to act as the responder for the service call. We then get to handle the service response and fault from within the command.
<h2>Chaining Commands Together (Revisited)</h2>
With this knowledge, we can return to our SequenceCommand example where we want to log a user in and then call the ChangeApplicationStateCommand to change the view state of Main.mxml to the logged in user state or logged in Admin state
<pre><code class="language-actionscript">package uk.co.clockobj.cairngormdemo.controller.commands
{
	import com.adobe.cairngorm.commands.SequenceCommand;
	import com.adobe.cairngorm.control.CairngormEvent;

	import mx.rpc.IResponder;
	import mx.rpc.events.ResultEvent;

	import uk.co.clockobj.cairngormdemo.controller.AppController;
	import uk.co.clockobj.cairngormdemo.controller.ServiceLocator;
	import uk.co.clockobj.cairngormdemo.controller.events.LoginEvent;
	import uk.co.clockobj.cairngormdemo.model.ModelLocator;
	import uk.co.clockobj.cairngormdemo.model.dto.UserDTO;
	import uk.co.clockobj.cairngormdemo.model.session.SessionModel;

	public class LogUserInCommand extends SequenceCommand implements IResponder
	{
		public function LogUserInCommand()
		{
			this.nextEvent = new CairngormEvent(AppController.CHANGE_APP_STATE);
		}

		override public function execute(event:CairngormEvent):void
		{
			var le : LoginEvent = LoginEvent( event );
			ServiceLocator.getInstance().userService.logInUser( le.username, le.password, this );
		}

		public function result(data:Object):void
		{
			ModelLocator.getInstance().session.userDTO = UserDTO( ResultEvent( data ).result );

			if ( ModelLocator.getInstance().session.loggedInUser.isAdmin )
			{
				this.nextEvent.data = SessionModel.APP_STATE_ADMIN;
			}
			else
			{
				this.nextEvent.data = SessionModel.APP_STATE_LOGGED_IN;
			}
			executeNextCommand();
		}

		public function fault(info:Object):void
		{
			// Fault handler code goes here
		}

	}
}</code></pre>
To use Cairngorm&#8217;s SequenceCommand feature, our command has to extend SequenceCommand. SequenceCommand already implements ICommand but this means we need to override the execute() method and we still need to implement IResponder as we want this class to handle the response from the userService.
In the commands constructor we set the SequenceCommands nextEvent property which takes the CairngormEvent you want to dispatch from this command. When you are ready you can dispatch the event using the SequenceCommand&#8217;s executeNextCommand() method.
Our ChangeApplicationStateCommand looks for the state we want to change to in the data property of the CairngormEvent so we set the relevant one in the result handler and dispatch.
As I previously demonstrated for the Product model, I have implemented similar code to convert the UserDTO returned from the service to a User model item object. The User object has some business logic in it to identify whether the user is an Admin (which is not in the DTO).
As you can see although Cairngorm adds a fair bit of code, in the long run we have a more organised and consistently centralised configuration which makes it easier to maintain, test etc. <a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-1">As I stated in Part 1</a> my method is not the documented way of using Cairngorm but has been adapted over use on several large projects to the solution that works best for us. I hope this series is useful to anyone starting out with Cairngorm and I do recommend you look at EasyMVC and alternatives to Cairngorm such as <a href="http://puremvc.org/">PureMVC</a> (I have never used this but only because Cairngorm meets my needs).
I have also attached the source files I used to write this article which i hope will help you see how everything hangs together.: <a href="/wp-content/uploads/2018/01/cairngormdemo.zip" download="">Cairngorm Demo Source Files</a>
<h2>Contents:</h2>
<a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-1">Part 1 &#8211; Setting up a project for Cairngorm</a> 
<a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-2">Part 2 &#8211; The Model</a> 
<a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-3">Part 3 &#8211; Commands</a> 
Part 4 &#8211; Services 
<a href="/wp-content/uploads/2018/01/cairngormdemo.zip" download="">Cairngorm Demo Source Files</a>

Building a medium to large scale Flex App using Cairngorm (Part 4)

In <a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-1">Parts 1</a> &amp; <a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-2">2</a> we setup Cairngorm and our models. In Part 3 we will look at how we will make use of the controller, using commands to handle events, chaining together a series of commands using Cairngorm&#8217;s SequenceCommand and creating custom CairngormEvents.
<h2>Controller</h2>
In <a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-1">part 1</a> we created a class that extends Cairngorm&#8217;s FrontController. This controller allows us to register event handlers on Cairngorm&#8217;s custom event dispatcher. But rather than creating each event handler directly in Cairngorm&#8217;s front controller (as we would in EasyMVC) we use the command pattern to organise our event handlers into separate classes.
As our app grows, this separation into commands helps keep our application easily maintainable.
<h2>Commands</h2>
Cairngorm provides an interface named ICommand, that command classes must implement. This interface enforces an execute() function which passes in a a CairngormEvent.
As an example, we are now going to create a command for changing the application&#8217;s state between it&#8217;s default logged out state, logged in state and admin state. If you remember back to <a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-2">Part 2</a>, we created a Session model and stored Main.mxml&#8217;s view state here using binding. We will now create a command that will change this state.
Firstly we start with the actual command class that will handle this event by creating a new ActionScript class that implements ICommand in the controller/commands folder. This command will fire when we dispatch the appropriate CairngormEvent. By default the CairngormEvent class has a data property that allows us to pass information to the command, in this case we want to pass the state that we want the command to change our Main.mxml viewstate to.
<pre><code class="language-actionscript">package uk.co.clockobj.cairngormdemo.controller.commands
{
	import com.adobe.cairngorm.commands.ICommand;
	import com.adobe.cairngorm.control.CairngormEvent;

	import uk.co.clockobj.cairngormdemo.model.ModelLocator;

	public class ChangeApplicationStateCommand implements ICommand
	{
		public function ChangeApplicationStateCommand()
		{
		}

		public function execute(event:CairngormEvent):void
		{
			ModelLocator.getInstance().session.appState = String( event.data );
		}

	}
}</code></pre>
Once we have written our command, we need to register the class with our controller. The FrontController that we extended provides an addCommand method that registers our command as an event listener for a specific named event.
Like native flex events, Cairngorm uses a name property on the event (of type string) to track which command will handle which event. By convention we store our event names as static string constants in the Controller.
<pre><code class="language-actionscript">package uk.co.clockobj.cairngormdemo.controller
{
	import com.adobe.cairngorm.control.FrontController;

	import uk.co.clockobj.cairngormdemo.controller.commands.ChangeApplicationStateCommand;

	public class AppController extends FrontController
	{
		public function AppController()
		{
			super();
			initialiseCommands();
		}

		private function initialiseCommands() : void
		{
			addCommand(CHANGE_APP_STATE, ChangeApplicationStateCommand)
		}

		public static const CHANGE_APP_STATE : String = "changeAppState";
	}
}</code></pre>
With our command registered we can now call it globally within our application using the following code. Note: If you remember back to <a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-2">part 2</a> we stored the three view states for Main.mxml as static constants on our Session model.
<pre><code class="language-actionscript">var ce : CairngormEvent = new CairngormEvent()
ce.data = SessionModel.APP_STATE_LOGGED_IN;
CairngormEventDispatcher.getInstance().dispatchEvent( ce );</code></pre>
If we were not passing any data, we could obviously do this in one line. Cairngorm&#8217;s data property is useful for passing all kinds of data, however in some cases you may need to pass more that one bit of data. For example a username and password, to a login command.
There are many ways we could do this, one of the easiest is to create a dynamic object instance to send the data over in. i.e.
<pre><code class="language-actionscript">var ce : CairngormEvent = new CairngormEvent(AppController.LOGIN_COMMAND)
ce.data = { username : "jon" , password: "baker" };
CairngormEventDispatcher.getInstance().dispatchEvent( ce );</code></pre>
Then in our command we can extract these values:
<pre><code class="language-actionscript">public function execute( event : CairngormEvent ):void
{
	var username : String = event.data.username;
	var password : String = event.data.password;</code></pre>
<h2>Custom events</h2>
The above method is fine for ad hoc requirements but if you need to formalise this, we need to create a custom CairngormEvent.
We do this by extending the CairngormEvent and including (in this case) a username and password property to our extended class.
<pre><code class="language-actionscript">package uk.co.clockobj.cairngormdemo.controller.events
{
	import com.adobe.cairngorm.control.CairngormEvent;

	public class LoginEvent extends CairngormEvent
	{

		public var username : String;
		public var password : String;

		public function LoginEvent(type:String, username : String = "", password : String = "", bubbles:Boolean=false, cancelable:Boolean=false)
		{
			super(type, bubbles, cancelable);
			this.username = username;
			this.password = password;
		}

	}
}</code></pre>
Note: I have added code to allow the username and password to the constructor, this is useful for dispatching the event from one line of code.
<h2>Chaining Commands Together</h2>
There are times when developing an application that we will want to run a command from within another command. For this we need to use Cairngorm&#8217;s built in SequenceCommand class.
So for example on logging into our application, we will want to change the application state to either the logged in state or the admin state, based on the user&#8217;s role. We could do this directly from our login command but we have an event for this so we want to reuse that command.
For any command that wants to make a call to an additional command, the calling class must extend SequenceCommand;
Note: With the example above we are making use of a service call to log a user in. I will first cover Services and the Service Locator classes in the next part, so to avoid confusion, I will cover these in <a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-4">Part 4</a> and finish up by returning to the example sequence command discussed above.
In Part 4, I will discuss how we use our ServiceLocator class we created in Part 1 to locate our services and how we will call and respond to these service calls from our commands.
<h2>Contents:</h2>
<a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-1">Part 1 &#8211; Setting up a project for Cairngorm</a> 
<a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-2">Part 2 &#8211; The Model</a> 
Part 3 &#8211; Commands 
<a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-4">Part 4 &#8211; Services</a> 
<a download href="/wp-content/uploads/2018/01/cairngormdemo.zip">Cairngorm Demo Source Files</a>

Building a medium to large scale Flex App using Cairngorm (Part 3)

In <a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-1">Part 1</a> we created a new Flex project and setup the classes we that will be used to support our application architecture. In this part we will look at how we build our application around these classes.
Having set up our project in Step 1 we are ready to start building our app. Like many flex developers, I don&#8217;t generally start building the view in the default application mxml file (CairngormDemo.mxml in the example I have been using). Instead I create a new MXML Component called Main.mxml file in the View folder (often based on a VBox or Canvas, 100% wide x 100% high). From here, all my other views hang off this. The main reason for this is that the application file needs to sit in the source root, while the rest of our application sits in our namespace folders. This avoids having code here.
There are various ways to implement the different application states. One approach which is popular, is to have a view state (within Main.mxml) for each top level state of the application, so for example I may have a default logged out state, a logged in state and possibly and admin state for example.
We need to ensure that we have nested our Main.mxml view into the application. While we are editing our application file, I place the Caringorm controller (App Controller we created in Part 1 here too). For purpose of example, my CairngormDemo.mxml file looks like this:
I may also add an mx:style tag referencing an external style sheet here but other than that nothing else goes here.
<h2>A model for session and state</h2>
I like to create a session model to hold session state data such as view states and depending on our apps perhaps the currently logged in user etc.
I create this model, as I would any other model (so it will be a good example). I firstly create a folder for this session model under the model directory (in this case called session) and create my new simple ActionScript class called SessionModel in that folder that will hold my model data.
As we are going to bind to data in this model directly from our mxml files, so we need to use the [Bindable] Meta tag.
For now we will add a property to hold the current view state for Main.mxml and store the name of each state as static properties on the model. As our app grows we will add other view states that need we want to make globally accessible here.
<pre><code class="language-actionscript">package uk.co.clockobj.cairngormdemo.model.session
{
	[Bindable]
	public class SessionModel
	{
		public function SessionModel()
		{
		}

		public static const APP_STATE_LOGGED_OUT : String = "";
		public static const APP_STATE_LOGGED_IN : String = "appStateLoggedIn";
		public static const APP_STATE_ADMIN : String = "appStateAdmin";

		public var appState : String = APP_STATE_LOGGED_OUT;

	}
}</code></pre>
We now want to make this locatable via our Model Locator. We can make the following modifications to the ModelLocater we created in <a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-1">Part 1</a> as as follows:
<pre><code class="language-actionscript">public function ModelLocator()
		{
			if ( instance != null )
			{
				throw( new Error( "Singleton class has already been instantiated" ) );
			} else
			{
				// Instantiate the model when the Locator is Instantiated
				session = new SessionModel();
			}
		}

		public var session : SessionModel;</code></pre>
Once we have done this we can add our bindings to Main.mxml&#8217;s currentState property using Flex&#8217;s binding mechanism, as in the following example:
<pre><code class="language-xml">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml" width="100%" height="100%"
	currentState="{ ModelLocator.getInstance().session.appState }"&gt;
	&lt;mx:states&gt;
		&lt;mx:State name="appStateLoggedIn"&gt;
			&lt;!-- Changes to mxml when logged in --&gt;
		&lt;/mx:State&gt;
		&lt;mx:State name="appStateAdmin"&gt;
			&lt;!-- Changes to mxml when admin logged in --&gt;
		&lt;/mx:State&gt;
	&lt;/mx:states&gt;
	&lt;mx:Script&gt;
		&lt;![CDATA[
			import uk.co.clockobj.cairngormdemo.model.ModelLocator;
		]]&gt;
	&lt;/mx:Script&gt;

	&lt;!-- Default view --&gt;

&lt;/mx:VBox&gt;</code></pre>
Once setup, we can now change the application&#8217;s state by doing something like this:
<pre><code class="language-actionscript">ModelLocator.getInstance().session.appState = SessionModel.APP_STATE_LOGGED_IN;</code></pre>
However, RESIST the temptation to do this all over the place. We want to maintain a convention and as this is an MVC framework, the controller should manage these state changes. Instead to change application state we will dispatch a CairngormEvent. (<a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-3">We will look at dispatching and handling Cairngorm events in Part 3</a>)
<h2>More on Models and Data Transfer Objects</h2>
The <a href="http://www.adobe.com/devnet/flex/articles/cairngorm_pt1.html">Cairngorm guide by Steven Webster</a> suggests storing Value Objects, or Data Transfer Objects, directly in the ModelLocator and binding to these directly. There are two schools of though here and your approach will depend on your project.
One is to do this and store the DTOs directly in the model, the other is to have separate model classes. The advantage of the latter is obviously less code, however by creating separate model classes to the DTOs may seem like duplication of work, you have the added advantage of being able to add business logic into your models, for example validation, conversions, etc. Secondly if the DTOs signatures change, you don&#8217;t have to re-factor your entire app changing all your bindings. You need to only to this in the translation methods between your DTOs and model. You also overcome an issue I encountered recently when returning remote objects received from a backend Java AMF server where you have to ensure all the data in cast to the correct DTOs (<a href="http://www.adobe.com/cfusion/communityengine/index.cfm?event=showdetails&amp;productId=2&amp;postId=8323">See this article</a>) as the translation process overcomes this.
An example, if we had to work with product data, I would have a product model which held product items. I would build a method into my model to translate DTOs into the model and back.
Note: if you are using soap / xml you could pass in the untyped object or xml to build the class from.
With the following DTO:
<pre><code class="language-actionscript">package uk.co.clockobj.cairngormdemo.model.dto
{
	[Bindable]
	[RemoteClass(alias="namespace.to.some.server.dto")]
	public class ProductDTO
	{

		public var id				: int;
		public var price 			: Number;
		public var description		: String;

		public function ProductDTO()
		{
		}

	}
}</code></pre>
Our product items (stored in our product model) would take an optional ProductDTO class passed to the constructor to build itself from. As an example, I have also added simple business logic to ensure the price is never negative. In a future article i want to show how validation logic can be put here (Which to me seems a more appropriate place than the view):
<pre><code class="language-actionscript">package uk.co.clockobj.cairngormdemo.model.product
{
	import uk.co.clockobj.cairngormdemo.model.dto.ProductDTO;

	[Bindable]
	public class Product
	{
		public var id			: int;

		private var _price 		: Number;

		public var description	: String;

		public function get price() : Number
		{
			return _price;
		}

		public function set price( value : Number ) : void
		{
			if ( value &lt; 0 )
				value = 0;
			_price = value;
		}

		public function Product( productDTO : ProductDTO = null )
		{
			if ( productDTO != null )
			{
				this.price = productDTO.price;
				this.description = productDTO.description;
			}
		}

	}
}</code></pre>
Finally we create our product model, as we did for our session model, but with a dto translation function (here implemented via a property setter / getter):
<pre><code class="language-actionscript">package uk.co.clockobj.cairngormdemo.model.product
{
	import mx.collections.ArrayCollection;

	import uk.co.clockobj.cairngormdemo.model.dto.ProductDTO;

	[Bindable]
	public class ProductModel
	{
		public var products : ArrayCollection;

		public function ProductModel()
		{
			products = new ArrayCollection()
		}

		public function set dtos( value : ArrayCollection ) : void
		{
			for each ( var pdto : ProductDTO in value )
			{
				products.addItem( new Product( pdto ) );
			}
		}

		public function get dtos() : ArrayCollection
		{
			var dtos : ArrayCollection;
			for each ( var p : Product in products )
			{
				var pdto : ProductDTO = new ProductDTO()
				pdto.id = p.id;
				pdto.description = p.description;
				pdto.price = p.price;
				dtos.addItem( pdto );
			}
			return dtos;
		}
	}
}</code></pre>
We would also need to put this product model into our model locator, exactly as we did for the session model.
<h2>Binding</h2>
We can now bind to our product data from throughout our application. We would do this as we bound the currentState property of Main.mxml. You can obviously use this approach when binding to editable controls (such as form fields) but, depending on the project, one thing I do is setup a two way binding (I have a custom component that uses the BindingUtils.bindProperty() method to bind the model to the form and the form back to the model). Again I hope to add an article about this in the future.
In <a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-3">Part 3</a> I will look at how we will make use of the controller, use commands to handle events, chain together a series of commands using Cairngorm&#8217;s SequenceCommand and also create custom events that extend CairngormEvents.
<h2>Contents:</h2>
<a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-1">Part 1 &#8211; Setting up a project for Cairngorm</a> 
Part 2 &#8211; The Model 
<a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-3">Part 3 &#8211; Commands</a> 
<a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-4">Part 4 &#8211; Services</a> 
<a download href="/wp-content/uploads/2018/01/cairngormdemo.zip">Cairngorm Demo Source Files</a>

Building a medium to large scale Flex App using Cairngorm (Part 2)

This is the first part of a four part series on my own approach to using Cairngorm to build an enterprise Rich Internet App.
In the first part, I cover setting up your project and creating the foundation classes that will hand our Rich Internet Application together.
<h2>Getting Started</h2>
Before we start although I am using Flex 3 and building a Flex app, this method works for Flex 2 and also Adobe Air applications.
Cairngorm is a Model View Controller framework and the first thing I like to do after creating a new Flex project is to create the appropriate folders in my project namespace. so for example, under uk/co/clockobj/projectname, I would create three folders named model, view and controller. Note: you don&#8217;t have to namespace or use this folder structure I use, but this is what I like to do by convention.
The controller folder will store my controller (Cairngorm&#8217;s Front Controller), my commands, my service locator, services and custom events.
The model folder will store my model locator, models and my Value Objects / Data Transfer Objects, in the screenshot above I have created a product subfolder to hold product related model classes.
Finally the view folder will store all our mxml.
<img loading="lazy" class="alignnone wp-image-154 size-full" src="https://content.gotripod.com/images/2008/06/cairngorm_layout.png" alt="" width="402" height="492" srcset="https://content.gotripod.com/wp-content/uploads/2008/06/cairngorm_layout.png 402w, https://content.gotripod.com/wp-content/uploads/2008/06/cairngorm_layout-245x300.png 245w" sizes="(max-width: 402px) 100vw, 402px" />
Note: I have an additional folder shown above called presentation. This is entirely optional but if you use a Presentation methodology, you can mimicking the folder structure of the view folder and store your Presentation modifier classes here.
Note: For now the presentation layer is beyond the scope of this article but I hope to post an article on this soon.
Next, you will want to <a href="http://labs.adobe.com/wiki/index.php/Cairngorm">download the Cairngorm.swc file from here</a>. (If you are new to Cairngorm <a href="http://www.adobe.com/devnet/flex/articles/cairngorm_pt1.html">do read Steven Websters articles</a>, they are a little outdated but explain the rationale and thinking behind cairngorm). Once downloaded, put the cairngorm.swc file in your libs folder.
With the Cairngorm.swc in our libs folder we have access to the Cairngorm classes. I also really recommend looking at the source code for Cairngorm (separate download from the link above).
<h2>Setting up Cairngorm</h2>
First thing we can setup is our controller. This is done by extending Cairngorm&#8217;s front controller class. Cairngorm&#8217;s front controller is very similar to the controller class created in my <a href="/insights/scaling-easymvc-flex-application-grows-part-1">scaling up EasyMVC articles</a> except Cairngorm uses it&#8217;s own EventDispatcher. Rather than listening to native events, it listens to CairngormEvents dispatched by it&#8217;s custom event handler.
We create an initialiseCommands function which is called from the constructor and this function will be where we will register our command classes as event listeners for cairngorm events. (<a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-3">more on that in part 3</a>)
Your controller class should look a little like this, I have called mine AppController:
<pre><code class="language-actionscript">package uk.co.clockobj.cairngormdemo.controller
{
	import com.adobe.cairngorm.control.FrontController;

	public class AppController extends FrontController
	{
		public function AppController()
		{
			super();
			initialiseCommands();
		}

		private function initialiseCommands() : void
		{
			// We will register our commands as event handlers here.
		}
	}
}</code></pre>
Next, I will create a Model Locator and Service Locator using the known locator pattern which yes, uses Singletons but as Steven Webster so rightly puts it: 
<a href="http://www.adobe.com/devnet/flex/articles/cairngorm_pt2_06.html">&#8220;The singleton nature of the Model Locator pattern ensures that you don&#8217;t suffer from duplicate state on the client, gives a large development team a consistent place to expose and share application-level state as instances of value objects, while ensuring that developers leverage the powerful data-binding capabilities of Flex to ensure that the view is notified when the model has changed.&#8221;</a>
<h2>Model Locator</h2>
I create my model locator named ModelLocator, however you will get a class name clash as there is a deprecated class in Cairngorm called ModelLocator (This just means when ever you add it to a class in Flex Builder you will be asked which one to use, which may annoy you).
<pre><code class="language-actionscript">package uk.co.clockobj.cairngormdemo.model
{
	import com.adobe.cairngorm.model.IModelLocator;

	[Bindable]
	public class ModelLocator implements IModelLocator
	{
		private static var _instance:ModelLocator;

		public static function getInstance():ModelLocator {
			if (_instance == null) {
				_instance = new ModelLocator();
			}
			return _instance;
		}

		public function ModelLocator()
		{
			if ( _instance != null )
			{
				throw( new Error( "Singleton class has already been instantiated" ) );
			}	else
			{
				// Instantiate services here
			}
		}

	}
}</code></pre>
Note: Although I implement Cairngorm&#8217;s IModelLocator interface above, it does not actually enforce any methods or properties.
In Steven Webster&#8217;s guide to Cairngorm, he stores the DTOs/VO as static properties of the model locator. I take a slightly different approach and I like to have models which are accessible through, and instantiated when the ModelLocator is first created, I will discuss this later (<a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-2">in part 2</a>)
<h2>Service Locator</h2>
I am also going to deviate slightly from the Cairngorm documented approach for Service Locators and implement a slightly less enforced version. Cairngorm uses an IServiceLocator interface which enforces the use of simple factory methods to access your services. You may need this so have a <a href="http://www.cairngormdocs.org/">look at the documentation</a>, but I going to keep my Service Locator consistent with my Model Locator.
So in the controller folder create a new ActionScript Class called ServiceLocator.as as follows:
<pre><code class="language-actionscript">package uk.co.clockobj.cairngormdemo.controller
{
	public class ServiceLocator
	{
		private static var _instance:ServiceLocator;

		public static function getInstance():ServiceLocator {
			if (_instance == null) {
				_instance = new ServiceLocator();
			}
			return _instance;
		}

		public function ServiceLocator()
		{
			if ( instance != null )
			{
				throw( new Error( "Singleton class has already been instantiated" ) );
			} else
			{
				// Instantiate services here
			}
		}

	}
}</code></pre>
For now we are not going to create any web services, <a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-3">we will do this in part 3</a>.
<a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-2">In the next part of this series</a> I will go into detail about how I implement models, discuss the advantages and disadvantages of accessing your DTOs directly and propose a different solution and show how we can bind our currentState view state property directly to the model.
<h2>Contents:</h2>
Part 1 &#8211; Setting up a project for Cairngorm 
<a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-2">Part 2 &#8211; The Model</a> 
<a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-3">Part 3 &#8211; Commands</a> 
<a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-4">Part 4 &#8211; Services</a> 
<a download href="/wp-content/uploads/2018/01/cairngormdemo.zip">Cairngorm Demo Source Files</a>

Building a medium to large scale Flex App using Cairngorm (Part 1)

The Flex scene seems to be lacking in beginners&#8217; guides to Cairngorm (maybe they are just alluding my Google searches) so I have put together (larger than hoped) a four part series that guides you through how I use Cairngorm.
For those of you who have read my articles on <a href="http://tombray.com/" target="_blank" rel="noopener">Tom Bray&#8217;s</a> EasyMVC, this may sound surprising. I have previously posted articles on how to <a href="/insights/scaling-easymvc-flex-application-grows-part-1">scale up EasyMVC into a Micro-architecture similar to Cairngorm</a>. However, the rationale behind these articles was to help developers who implement EasyMVC and find their app out grows the implementation that Tom originally presented, and not as a blueprint for architecting apps. EasyMVC is a great framework for small Flex apps and Flex widgets where using Cairngorm would be the equivalent of taking a sledgehammer to a walnut. If you know in advance you application is going to be fairly sizable, use Cairngorm (or something like <a href="http://puremvc.org/">PureMVC</a> if you prefer).
Before I get started, there is a slight disclaimer: I am going to present my own approach to using Cairngorm which does deviate from the documented approach, namely around services. I feel it is simpler, but you may beg to differ. I do not present this as the best solution or a perfect solution, but it is a tried and tested solution which hopefully will get more developers understanding and using Cairngorm where appropriate.
In essence this series should give you all you need to know to get started with Cairngorm.
<h2>Contents:</h2>
<a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-1">Part 1 &#8211; Setting up a project for Cairngorm</a> 
<a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-2">Part 2 &#8211; The Model</a> 
<a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-3">Part 3 &#8211; Commands</a> 
<a href="/insights/building-medium-large-scale-flex-app-using-cairngorm-part-4">Part 4 &#8211; Services</a> 
<a download href="/wp-content/uploads/2018/01/cairngormdemo.zip">Cairngorm Demo Source Files</a>