In Cairngorm you have a few central classes which are accessible as singletons. In Swiz you won’t have any singletons in your code at all if you don’t want to but instead you will use the Autowire annotation to let Swiz wire things together for you using dependency injection aka Inversion of Control. These kind of classes are mainly models, controllers, delegates and services.

You can mix Cairngorm and Swiz at the same time while migrating so you are not forced to refactor your application at once but in an iterative way.

Let’s get started: Download the latest Swiz library SWC and add it to your project libs. If you want to check out the latest sources from SVN to compile the SWC on your own be sure to add the compiler parameter -keep-as3-metadata+=Autowire,Mediate.

To initialize Swiz you need at least one BeanLoader which will be the place where you declare models, controllers, delegates and services. The terminology “Bean” will probably change in one of the next Swiz releases. Imagine the BeanLoader as the place where you set up non-view classes.

Create a new MXML class and call it e.g. MyLoader and let it extend BeanLoader. Then change the namespace to org.swizframework.util.* so it will look like this:

<?xml version="1.0" encoding="utf-8"?>
<BeanLoader xmlns="org.swizframework.util.*">
 
</BeanLoader>

So let’s refactor your first peace of code. Let’s assume your ModelLocator contains a class ContactModel which holds a list of contacts. The ContactModel instance is bound to one of your views like:

[Bindable]
var modelLocator:MyModelLocator = MyModelLocator.getIntance();
 
<mx:List dataProvider="{modelLocator.contactModel.list}" />

Now remove the contactModel from your ModelLocator and add it to the BeanLoader so it will looks like this:

<?xml version="1.0" encoding="utf-8"?>
<BeanLoader xmlns="org.swizframework.util.*">
	<model:ContactModel xmlns:model="com.domain.project.model.*" />
</BeanLoader>

and change the view to this:

[Bindable][Autowire]
public var contactModel:ContactModel;
 
<mx:List dataProvider="{contactModel.list}" />

With the Autowire annotation we tell Swiz that we need the the ContactModel. It has to be defined public because otherwise Swiz is not able to inject the instance defined in MyLoader.
Now we have to tell Swiz to use the MyLoader where we have just set up our ContactModel. Switch to your main application MXML and add an event listener for preinitialize and define the event handler like this:

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
	preinitialize="preInitHandler()" />
	<mx:Script>
		<![CDATA[
			import org.swizframework.Swiz;
			import com.domain.project.MyBeans;
			private function preInitHandler():void
			{
				Swiz.loadBeans([MyBeans]);
			}
		]]>
	</mx:Script>

You see that loadBeans expects an array so you can define multiple BeanLoaders if you like.
In this case we have used autowire-by-type. This means Swiz will find the ContactModel because only one instance is defined in the BeanLoader. If you have classes of the same type in the BeanLoader you can also autowire by id. Only give the instance an id like e.g. id=”contactModel” and autowire it with [Autowire(bean="contactModel")]

With this refactoring we might have broken a Cairngorm command because now the flow looks like this

• Command was invoked from a Cairngorm event mapped to in the FrontController
• Command instantiated a Business Delegate and added itself as a Responder implementing the Responder interface
• Business Delegate gets service from ServiceLocator and calls it
• Service returns result/fault and the Command in this case Responder gets notified

With Swiz you have no FrontController, no ServiceLocator and the delegates are also only created once because they live in a BeanLoader. The Command will be replaced by a controller so it is easier to have multiple actions in one controller so you don’t end up with a ContactReadCommand, ContactAddCommand, ContactUpdateCommand or a switch statement in the command itself to determine which event came in.

To refactor do the following:

• Move the contact service from ServiceLocator to MyLoader
• Add the delegate to MyLoader
• Create a new controller called ContactController extending AbstractController and add it to MyLoader

Your BeanLoader now looks smilar like this:

<?xml version="1.0" encoding="utf-8"?>
<BeanLoader xmlns="org.swizframework.util.*"
	xmlns:mx="http://www.adobe.com/2006/mxml"
	xmlns:model="example.model.*"
	xmlns:ctrl="example.ctrl.*"
	xmlns:business="example.business.*">
 
	<model:ContactsModel />
	<ctrl:ContactController />
	<business:ContactDelegate />
	<mx:HTTPService id="contactService" />
 
</BeanLoader>

It is best practice to let delegates implement an interface so other classes only have to deal with a clean interface so the ContactDelegate interface looks like this:

package example.business
{
	import mx.rpc.AsyncToken;
 
	public interface IContactDelegate
	{
		function getContacts():AsyncToken;
	}
}

and the implementation like this:

package example.business
{
	import mx.rpc.AsyncToken;
	import mx.rpc.http.HTTPService;
 
	public class ContactDelegate implements IContactDelegate
	{
 
		[Autowire(bean="contactService")]
		public var service:HTTPService;
 
		public function getContacts():AsyncToken
		{
			return service.send();
		}
 
	}
}

You see that we simply autowire the service instead of having any call to a ServiceLocator.

Now the controller. The ContactController has two dependecies. We will need access to the delegate to call the service and to the model to store the result and both will be autowired:

package example.ctrl
{
	import example.business.IContactDelegate;
	import example.model.ContactModel;
 
	import mx.collections.ArrayCollection;
	import mx.rpc.AsyncToken;
	import mx.rpc.events.ResultEvent;
 
	import org.swizframework.controller.AbstractController;
 
	public class ContactController extends AbstractController
	{
 
		[Autowire]
		public var model:ContactModel;
 
		[Autowire]
		public var delegate:IContactDelegate;
 
		public function ContactController()
		{
		}
 
		[Mediate(event="loadContacts")]
		public function loadContacts():void
		{
			var call:AsyncToken = delegate.getContacts();
			executeServiceCall(call, contactsResultHandler);
		}
 
		protected function contactsResultHandler(re:ResultEvent):void
		{
			var ac:ArrayCollection = re.result as ArrayCollection;
			model.list = ac;
		}
 
	}
}

You see something new which is the Mediate annotation [Mediate(event="loadContacts")]
Instead of a FrontController which maps events to commands Swiz uses a concept called dynamic mediators. In this case we are using a primitive event and there are more sophisticated ways to implement dynamic mediators and also pass parameters (event member variables) etc.

So let’s say you want to load the contacts when your application starts simply add this line of code to the main application creationComplete event handler:

Swiz.dispatch("loadContacts")

Swiz is aware of all mediate annotations and has created event listeners and with the line above our controller method loadContacts gets invoked. You could also use an event class which does not need a special base class like the CairngormEvent but only flash.events.Event. For more info and some shortcuts and runtime validation read on here about eventPackages.

So let’s some up how the different layers of your application work together:

• Declare models, controller, delegates and services in the BeanLoader and load them with Swiz.loadBeans
• Views get the model autowired and can add data bindings.
• Views dispatch events caused by user gestures with Swiz.dispatchEvent or Swiz.dispatch
• Controller mediate events with [Mediate(event="...", properties="...")]
• Controllers get models autowired which need to be changed by the controller.
• If the controller calls a service autowire the delegate
• Delegates autowire services and return the AsyncToken from the service call

I hope at this post you have learned some concepts of Swiz compared to Cairngorm and see that migrating from Cairngorm to Swiz means more decoupling and removing repetitive code. I had a large project with more than one year development spend on and refactoring was done in a short timeframe and reduced about 30% lines of code.

If you have more questions please drop a comment and/or join the mailing list.

• AS2 -> AS3
• Flash -> Flex
• Windows -> OS X
• SWF Studio -> Adobe AIR

Due to these huge changes I wanted to see how AMFPHP fits into this environment and write a new tutorial.

First the setup up the local server. Instead of WAMP (Windows, Apache, MySQL, PHP) I am now using MAMP (M for Mac) which is the pendent on OS X:

• Download and install MAMP an Mac+Apache+MySQL+PHP bundle
• Start the MAMP server: /Applications/MAMP/MAMP.app (Your browser should come up with a MAMP page saying your installation was successfully)
• Download the latest AMFPHP and put it into /Applications/MAMP/htdocs/amfphp (I used 1.9 beta 20080120)
• Download the MyService.php.txt, rename it to MyService.php and place it into /Applications/MAMP/htdocs/amfphp/services

As a client we could choose Flex in the browser but I wanted to demonstrate AIR:

• Open Flex Builder and create a new AIR project called AMFPHPonAIR
• The AMFPHPonAIR.mxml opens where you put this code (download):

<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical"
	creationComplete="init()">
 
	<mx:Script>
		<![CDATA[
			import mx.controls.Alert;
			import mx.messaging.channels.AMFChannel;
			import mx.messaging.ChannelSet;
			import mx.rpc.events.FaultEvent;
			import mx.rpc.events.ResultEvent;
 
			[Bindable]
			private var lastResult:String;
 
			private function init():void
			{
				var cs:ChannelSet = new ChannelSet();
				var channel:AMFChannel = new AMFChannel("my-amf", "http://localhost:8888/amfphp/gateway.php");
				cs.addChannel(channel);
				myService.channelSet = cs;
				myService.hello("You");
			}
 
			private function onResult(re:ResultEvent):void
			{
				var s:String = re.result as String;
				Alert.show(s, "Remote Result");
				lastResult = s;
			}
			private function onFault(fe:FaultEvent):void
			{
				Alert.show(fe.message.toString(), "Remote Error");
			}
		]]>
	</mx:Script>
 
	<mx:TraceTarget fieldSeparator="->" includeLevel="true" includeCategory="true" includeTime="true" />
 
	<mx:RemoteObject id="myService" result="onResult(event)" fault="onFault(event)"
        showBusyCursor="true" destination="AMFPHP" source="MyService">
        <mx:method name="hello" />
    </mx:RemoteObject>
 
    <mx:HBox>
		<mx:TextInput id="message" text="Yourself" />
		<mx:Button label="say hello" click="myService.hello(message.text)" />
	</mx:HBox>
 
	<mx:Label text="Last Result: {lastResult}" />
 
</mx:WindowedApplication>

The most important part is in the init function where the remoting endpoint is set via ActionScript.
Right-click the src/AMFPHPonAIR.mxml and choose Debug As-> Adobe AIR Application

If all works right you should see something like this:

You can change the text in the TextInput control and click the button to send it to your server and the result is shown below the TextInput. Now that was easy I think! About 50 lines of code for a full AIR application which uses AMFPHP on the server side.

This example works but has no seperation of model,view and controller so I changed it to use the Cairngorm micro-architecture. Download this example AIR application (sourceview) and overwrite it into the src folder

The Cairngorm.swc should be in placed in the libs directory of your AIR project. Now let’s dive a bit in the code to understand the Cairngorm structure and how the RemoteObject configuration with the AMFPHP remoting gateway.

The AMFPHPonAIR.mxml is the main application MXML and you can right-click it to Run or Debug your AIR application. If you are not familiar with Cairngorm at all I recommend checking the docs as this is not a Cairngorm tutorial. If you have questions feel free to post a comment.

The main MXML is pretty short and instantiates only a TraceTarget, the FrontController, the Services (ServiceLocator) and the main view.

The creationComplete event goes into the init-function which dispatches a StartupEvent. Open the airamfphp/ctrl/FrontController.as on you see two events mapped to their commands. When the StartupEvent is dispatched the CairngormEventDispatcher calls the StartupCommand’s execute method with the event as the parameter.

Open the airamfphp/StartupCommand.as. The execute method gets called when the StartupEvent is dispatched. The ServiceLocator singleton maps to our business/Services.mxml because we instantiated it in out main MXML. The Services.mxml defines the RemoteObject which maps to the MyTestservice.php in the AMFPHP services directory. I added the method setServer to the ServiceLocator to set the remoting endpoint. This is pretty straight forward and is a replacement for the services-config.xml which can be compiled into the application (compiler flag -services service-config.xml). In real life the server settings should come out of an external configuration so you can switch from local dev to staging, production etc.

Going on in the StartupCommand you see that MyDelegate get’s instantiated and we call hello “You”. The delegate expects an IResponder as parameter and the command implements the IResponder interface meaning the methods result and fault. The delegate is standard Cairngorm so let’s finalize the command. For result and fault an Alert comes up which shows the server result of the call of MyService.hello(“You”).

The view/MainView.mxml shows a TextInput, Button and Label and when the button is pressed a HelloEvent with the text of the TextInput as parameter. The HelloEvent is mapped to the HelloCommand in the FrontController so open the HelloCommand to see what happens. We use the same delegate and fault-method and the result-method is changed to set the result within a bindable variable in the model/MyModelLocator singleton. This variable is bound to the Label’s text property so it shows up there after you pressed the button and the result is received from the server. That’s it!

If you want to use Flex in the browser instead of AIR simply create a new Flex project and change the root node from WindowedApplication to Application. The rest of the source should stay the same as we did not use any AIR API specific features.
A big thanks to the guys who have taken over the AMFPHP project and to Patrick Mineault of course for this great peace of software!
I would appreciate feedback if the detail level is to low or if your miss explanations on any parts so I can extend these parts.