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 came across a great drawing method named NSDrawNinePartImage. The method has the following signature:

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
);

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.

//
//  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

To use this generic classes, you simply need to import it where required:

#import "GTDrawImage.h"

…and then you can call from within, for example the drawRect:, selector using the following method:

- (void)drawRect:(NSRect)rect {
	[GTDrawImage drawScalableImage:baseImage scaleTopLeft:NSMakePoint(8, 16) scaleBottomRight:NSMakePoint(16,8) inFrame: [self bounds]];
}

drawScalableImage 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:

• Header: GTDrawImage.h
• Implementation: GTDrawImage.m
• Sample Project using GTDrawImage: StretchMyView.zip (Adapted example I found. Unfortunately I can’t remember where and so don’t know who to credit)

This is a great way to capture the interest of would be browsers that would normally see this page and immediately hit the back key, instead not only do they capture my attention, but they also tap into my curiosity which gets me to immediately click the products link.

In this case I didn’t need any of their products but this is a great tip.

Also note the search bar being visible. This is essential on a 404 page for keeping customers that know what they are looking for on your site.

The book is concise and more theoretical than many of the others I have read on the subject and covers everything you need to know to get started. One of the best things about this book is the depth it goes into many of the topics. For example, the book goes into great detail about consuming RESTful web services and parsing XML and makes use of real-world Web APIs such as Google Maps API for these examples. The book also provides a good insight into using the local file system and creating and working with local sqlite3 databases as well as several concise chapters on creating views and working with pretty much every control. Unfortunately the book lacks any coverage of Interface Builder (this may partly be down to when the book was written and what features were available at the time of writing) which provides in many cases quicker and easier solutions to creating views and handling events. I feel the example views shown in the various screen shots have suffered because of this.

Overall this book serves as an excellent reference, going into more depth in the programatic theory than many of the other books, and is certainly good value and just over £20.

This book is available via Amazon.co.uk

I just wanted to share with you a great framework I have been using recently called Mate (pronounced ma-tay).

Developed by the guys at ASFusion Mate is a great framework that features MXML declared event handling, dependency injection and best of all it is really easy to use and implement (It even has a way of reusing your existing Cairngorm commands. Additionally in the next version there will be an infrastructure for mocking out your services and really provides a clean architecture for Flex apps.

The framework is provided as a .swc file you can drop straight into your /libs folder and supports both Flex 2 and Flex 3. The only downside to the framework is the documentation does not reflect the latest .swc and is a little light in places, however the forums are excellent and very active and there is a good selection of examples.

I will be blogging about this in more details soon, but wanted to share my initial thoughts and urge you to look at this framework as it is really worth it.

gem update --system

Then install the Phusion Passenger gem

gem install passenger

Once complete you can run the Phusion Passenger install that compiles mod_rails for you.

passenger-install-apache2-module

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.

    ServerName www.stubmatic.com
    DocumentRoot /websites/stubmatic/public

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:

    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]

If you want to setup an Apache / Phusion Passenger testing server you will also need to add the following directive to your VirtualHost configuration:

RailsEnv development

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.

touch tmp/restart.txt

In terms of performance, Phusion Passenger holds it’s own against Mongrel and there are plenty of details on Phusion’s website.

For more information:

1. Phusion Passenger
2. Phusion Passenger Documentation

iPhone and Adobe Air developers (as well as any others that use SQLite 3) Menial has just released an excellent little app for creating, managing and running queries against SQLite 3 databases called Bases.

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.

Find out more and download here

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 &&  model.hasOwnProperty( field )
				&& target != null && 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;
		}
 
	}
}

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 ‘property’ defaults to “text” as this is the most often used property to bind to. So for example given the following User model:

1
2
3
4
5
6
7
8
9

public class UserModel
{
    public var firstName : String;
    public var lastName : String;
 
	public function UserModel()
	{
	}
}

We could set up a binding to a TextInput as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13

...
<mx:Script>
	<![CDATA[
		public var userModel : UserModel;
	]]>
</mx:Script>
<mx:Form>
	<mx:FormItem label="First Name">
		<mx:TextInput id="txtFirstName"/>
	</mx:FormItem>
</mx:Form>
<ModelBinding model="{userModel}" field="firstName" target="{txtFirstName}"/>
...

As you can see with this class you can quickly setup two-way bindings with your models.

Download ModelBinding.as
For more information on Binding, check out Adobe Devnet.

Also, if you are a blogger yourself and entering this competition, please comment so below and I will return the favour and add a comment to your blog post entry.

Thanks in advance to all those that comment..!

Regards,

Jon

But this is not the killer feature! – The guys over at Cashbackguide have created plugins for both Firefox and IE called Cashback Guardian and basically if you visit an online store that has a cash back scheme, it will notify you before making a purchase and notifying you how much cash back you could get.

I think this is a great use of technology that helps save a few pennies and well worth a look.

**** UPDATE: ActiveMerchant recently removed the functionality to use PayPal’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 you can find out more information and usage on his blog. ****

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)

Below is the code: (I have also attached the .rb file: paypal_express_recurring_nv.rb)

# simple extension to ActiveMerchant for basic support of recurring payments with Express Checkout API
#
# See http://http://clockobj.co.uk/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 < Gateway
      include PaypalNvCommonAPI
 
      LIVE_REDIRECT_URL = 'https://www.paypal.com/cgibin/webscr?cmd=_customer-billing-agreement&token='
      TEST_REDIRECT_URL = 'https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_customer-billing-agreement&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 => false) if options[:shipping_amount]
        add_pair(post, :taxamt, amount(options[:tax_amount]), :allow_blank => 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 => 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 => 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

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:

gw = ActiveMerchant::Billing::PaypalExpressRecurringNvGateway.new( :login => 'PAYPALEMAIL', :password => 'PASSWORD', :signature => 'PAYPALAPISIGNATURE' )

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.

response = gw.setup_agreement("Subscription £25 per month", :cancel_return_url => "https://mysite.com/cancel", :return_url => "https://mysite.com/complete" )

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 “Subscription £25 per month” as sent in the previous request. We need to redirect the subscriber to PayPal using the following line of ruby:

redirect_to gw.redirect_url_for(response.token)

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:

response = gw.create_profile(2500, response.token, :currency => "GBP", :reference => "34")

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 – 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:

profile_id = response.params["profileid"]

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:

gw.get_profile_details(profile_id)

Update the subscription using various options (i.e. changing subscription amount shown below):

gw.update_profile(profile_id, :money => 3000, :currency => "GBP")

Manage the subscription, for example cancel it as follows:

gw.manage_profile(profile_id, "Cancel", :note => "Your subscription has been cancelled by us")

And finally bill any outstanding subscription balance:

gw.bill_outstanding(profile_id, 2500, :currency=> "GBP", :note => "£20 Overdue Subscription")

Please note that as of yet this class is not part of Active Merchant, however it has been added to Active Merchants case #17 If you want to use this you will have to add it manually as above.

I recommend reading PayPals Express Checkout Integration Guide and the Name Value Pair API Developer Guide and Reference for more information on what variables can be passed in each request to PayPal.

Other than having a very nice logo designed by the guys at Sofa my first impressions are they have implemented Objective-C in javascript. To me this seems an unusual choice as I can’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?

The Cappuccino framework has been likened to the recently released (and overhyped in my opinion – seems slow and clunky to me) SproutCore framework. However I am extreamly impressed with how quick 280 Slides 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 & 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’s Chrome browser addresses some of the performance and stability issues and Apple has recently based it’s online MobileMe business on Javascript (aparently using SpoutCore) 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.

Update

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:

@implementation Person : CPObject
{
   CPString name;
}
@end

Methods are declared using the identical Objective-C syntax:

- (void)setName:(CPString)aName
{
	name = aName;
}
- (CPString)name
{
	return name;
}

And class methods can be called using a once again similar syntax:

[myPerson setJobTitle: "Founder" company: "280 North"];

Cocoa Master Scott Stevenson has done a nice comparison between Cocoa and Cappuccino, well worth a read..

Also I have migrated my blog over from a shared Windows host to a Linux VPS machine which should allow me to use some of Wordpress’ better plugins such as WP-SuperCache

Regards,

Jon

Services

In part 1 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

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 );
		}
 
	}
}

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 LiveCycle, BlazeDS, Flamingo, WebOrb 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 method championed by Darron Schall where we use Flex’s built in responder and AsyncToken mechanism.

We need to now register this service on our ServiceLocator.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

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;
 
	}
}

IResponder

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 Part 2, using for example a getProducts() method call on a productService destination.

Service:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

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 );
		}
 
	}
}

(We register this with our ServiceLocator as we did for the UserService)

GetAllProductsCommand:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

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
		}
 
	}
}

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.

Chaining Commands Together (Revisited)

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

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
		}
 
	}
}

To use Cairngorm’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’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. As I stated in Part 1 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 PureMVC ( 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.: Cairngorm Demo Srource Files

Contents:

Part 1 – Setting up a project for Cairngorm
Part 2 – The Model
Part 3 – Commands
Part 4 – Services
Cairngorm Demo Source Files

Controller

In part 1 we created a class that extends Cairngorm’s FrontController. This controller allows us to register event handlers on Cairngorm’s custom event dispatcher. But rather than creating each event handler directly in Cairngorm’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.

Commands

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’s state between it’s default logged out state, logged in state and admin state. If you remember back to Part 2, we created a Session model and stored Main.mxml’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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

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 );
		}
 
	}
}

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

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";
	}
}

With our command registered we can now call it globally within our application using the following code. Note: If you remember back to part 2 we stored the three view states for Main.mxml as static constants on our Session model.

1
2
3

var ce : CairngormEvent = new CairngormEvent()
ce.data = SessionModel.APP_STATE_LOGGED_IN;
CairngormEventDispatcher.getInstance().dispatchEvent( ce );

If we were not passing any data, we could obviously do this in one line. Cairngorm’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.

1
2
3

var ce : CairngormEvent = new CairngormEvent(AppController.LOGIN_COMMAND)
ce.data = { username : "jon" , password: "baker" };
CairngormEventDispatcher.getInstance().dispatchEvent( ce );

Then in our command we can extract these values:

14
15
16
17

public function execute( event : CairngormEvent ):void
{
	var username : String = event.data.username;
	var password : String = event.data.password;

Custom events

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

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;
		}
 
	}
}

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.

Chaining Commands Together

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’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’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 Part 4 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.

Contents:

Part 1 – Setting up a project for Cairngorm
Part 2 – The Model
Part 3 – Commands
Part 4 – Services
Cairngorm Demo Source Files

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.

A model for session and state

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.

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;
 
	}
}

We now want to make this locatable via our Model Locator. We can make the following modifications to the ModelLocater we created in Part 1 as as follows:

		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;

Once we have done this we can add our bindings to Main.mxml’s currentState property using Flex’s binding mechanism, as in the following example:

<?xml version="1.0" encoding="utf-8"?>
<mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml" width="100%" height="100%"
	currentState="{ ModelLocator.getInstance().session.appState }">
	<mx:states>
		<mx:State name="appStateLoggedIn">
			<!-- Changes to mxml when logged in -->
		</mx:State>
		<mx:State name="appStateAdmin">
			<!-- Changes to mxml when admin logged in -->
		</mx:State>
	</mx:states>
	<mx:Script>
		<![CDATA[
			import uk.co.clockobj.cairngormdemo.model.ModelLocator;
		]]>
	</mx:Script>
 
	<!-- Default view -->
 
</mx:VBox>

Once setup, we can now change the application’s state by doing something like this:

ModelLocator.getInstance().session.appState = SessionModel.APP_STATE_LOGGED_IN;

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. (We will look at dispatching and handling Cairngorm events in Part 3)

More on Models and Data Transfer Objects

The Cairngorm guide by Steven Webster 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’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 (See this article) 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:

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()
		{
		}
 
	}
}

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):

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 < 0 )
				value = 0;
			_price = value;
		}
 
		public function Product( productDTO : ProductDTO = null )
		{
			if ( productDTO != null )
			{
				this.price = productDTO.price;
				this.description = productDTO.description;
			}
		}
 
	}
}

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):

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;
		}
	}
}

We would also need to put this product model into our model locator, exactly as we did for the session model.

Binding

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 Part 3 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’s SequenceCommand and also create custom events that extend CairngormEvents.

Contents:

Part 1 – Setting up a project for Cairngorm
Part 2 – The Model
Part 3 – Commands
Part 4 – Services
Cairngorm Demo Source Files

In the first part, I cover setting up your project and creating the foundation classes that will hand our Rich Internet Application together.

Getting Started

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’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’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.

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 download the Cairngorm.swc file from here. (If you are new to Cairngorm do read Steven Websters articles, 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).

Setting up Cairngorm

First thing we can setup is our controller. This is done by extending Cairngorm’s front controller class. Cairngorm’s front controller is very similar to the controller class created in my scaling up EasyMVC articles except Cairngorm uses it’s own EventDispatcher. Rather than listening to native events, it listens to CairngormEvents dispatched by it’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. (more on that in part 3)

Your controller class should look a little like this, I have called mine AppController:

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.
		}
	}
}

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:
“The singleton nature of the Model Locator pattern ensures that you don’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.”

Model Locator

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).

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
			}
		}
 
	}
}

Note: Although I implement Cairngorm’s IModelLocator interface above, it does not actually enforce any methods or properties.

In Steven Webster’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 (in part 2)

Service Locator

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 look at the documentation, 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:

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
			}
		}
 
	}
}

For now we are not going to create any web services, we will do this in part 3.

In the next part of this series 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.

Contents:

Part 1 – Setting up a project for Cairngorm
Part 2 – The Model
Part 3 – Commands
Part 4 – Services
Cairngorm Demo Source Files

For those of you who have read my articles on Tom Bray’s EasyMVC, this may sound surprising. I have previously posted articles on how to scale up EasyMVC into a Micro-architecture similar to Cairngorm. 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 PureMVC 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.

Contents:

Part 1 – Setting up a project for Cairngorm
Part 2 – The Model
Part 3 – Commands
Part 4 – Services
Cairngorm Demo Source Files

Alternatively you need to set the value programatically in an event handler, AND importantly call updateDisplayList() on the scrollbar. i.e.

 
		<!--[CDATA[
			private function handleSlideChange():void {
				scroll.maxScrollPosition = slider.value;
				scroll.invalidateDisplayList();
			}
		]]-->

As part of the update, I have fixed the following:

• Compatibility with WordPress 2.5
• Issue where users without curl installed would get an error authenticating
• Updated the style to match WordPress 2.5
• AJAX enabled the plugin to stop the page refresh (which ws incompatible with WordPress 2.5) when switching Photo Sets on the write/edit post page

If you are using WordPress 2.5, you can automatically upgrade to the latest version from the plugins page. If you are not already using WP-Flickr, you can download it here http://wordpress.org/extend/plugins/wp-flickr/