Cairngorm Console Integration Guide

Principles

Cairngorm monkey patching

In order to observe what happens inside Cairngorm, we had to "monkey patch" some of the classes of the framework. This means that inside the console, we copied these classes into the source code, using the same names and packages than the original classes.
Then, when you add CairngormConsole.swc into your librairies built with your project, the linked will use the patched classes instead of the original ones.
This is why its so easy to integrate the console (compared to PureMVCConsole, that needs a light application source code modification to work), but the counterside is that the build scripts may need an adaptation to manage a release build without CairngormConsole.swc.

Library requirements

In order to use the Cairngorm Console, you must use the following libraries:

• Flex SDK 3.0.1 or higher
• Cairngorm.swc 2 or higher
• CairngormConsole.swc

Warning You must not have the source code of Cairngorm directly into your application (or even inside a library used by your application), as in this case, the patched Cairngorm will not be used, and the console will not display events. If for some reason, you had to patch Cairngorm, then we are in trouble ! If this is the case, please contact us so that we figure out how to help you (actually, the CafeTownsend demo application includes Cairngorm source files in the project, so we had to remove them for this demo application)

If your application uses any of the three available remoting features (ie HTTPService, WebService or RemoteObject), then you would like to inspect, log and debug them with the console.
To do this, you will have to link KapITFXPatches.swc into your project.
This means that you will add KapITFPatches.swc into your compiler libraries dependencies, either with FlexBuilder or with your favourite tool.
Once again, be careful not to link the library with your production code.
It works the same if your application is not monolitic and uses other libraries, from which service calls may be sent.
The way you will know that patches has been used instead of regular classes, is by checking whether there is a "services" tab in the console.
For more information about all this stuff, see this important note

Initialization of the console

In order to get all initialization events of Cairngorm, it is important to instanciate the console before the FrontController.
To do this, you should either :

• instanciate the console in a static variable of your application:

  private static var console:CairngormConsole = 
                     new CairngormConsole(AppModelLocator.getInstance());
  

• instanciate the console in preInitialize event handler of your application
• create a back end AS3 class that extends Application, and instanciate the console in its constructor (your main application mxml file will have to extend this backend class instead of application class), such as in the example below:

  package
  {
    import com.adobe.cafetownsend.model.AppModelLocator;
    import fr.kapit.CairngormConsole;	
    import mx.core.Application;
    
    public class CafeTownsendApplication extends Application
    {
  	public function CafeTownsendApplication()
  	{
            super();
  	  new CairngormConsole(AppModelLocator.getInstance(), this)
  	}
    }
  }
  ...
  <CafeTownsendApplication
    xmlns="*"
    ...
  >
   
  Next >> [Presentation|CairngormConsoleUserGuidePresentation]
  

Simple Integration Method (mxml)

If you do not need to manage a release build, and do not care about embedding CairngormConsole code into your application (which is the case for prototypes, demo applications, and so on), then you will prefer this simple integration method.
The steps to follow are:

1. add CairngormConsole.swc into the libraries of your project
2. open the MXML source file for your main application (for AS3 see the other method)
3. add the following mxml tag:

   <kapit:CairngormConsole modelLocator="{AppModelLocator.getInstance()}"/>
   

4. generate the namespace declaration (with the Ctrl+space flex builder code assist shortcut)

   xmlns:kapit="fr.kapit.*"
   

5. Replace the value of modelLocator attribute with your specific ModelLocator instance

You can now rebuild the application, and start it, then give it focus by clicking in, and hit Ctrl+Alt+F5 (or Ctrl+alt+click). You should see the console popping up.
Once again, with this method, the console will not be removable by compile and build options

Multi Build Integration (AS3)

We want to manage a relase build without the console and the patched Cairngorm, and a development build that includes the library.

AS3 Integration

You may instanciate CairngormConsole through AS3 code, the simplest way to do this is through a static variable, to be sure that it will be created early:

private static var console:CairngormConsole = new CairngormConsole(AppModelLocator.getInstance());

You will have to use your own ModelLocator class here. However, if for any reasons, you cannot instanciate your ModelLocator in this way, then you will create the console within an initialization method of your application (prefer the "preInitialize" event that is fired very early)

Managing conditional compilation

To create a release version, you will have to use conditional compilation directives, such as:

CONFIG::cairngormConsole{
  import fr.kapit.CairngormConsole;
  private static var console:CairngormConsole = new CairngormConsole(AppModelLocator.getInstance());
}

You have to include the import directive inside the conditional compilation block, otherwise the project will not compile without the console library, and it is preferable that it's removed in a release build.

And to one of the following option to the compiler command line, whether you want to create the console:

-define=CONFIG::cairngormConsole,true
-define=CONFIG::cairngormConsole,false

Managing conditional build

If you have builds, then you must use either ANT, MAVEN or custom scripts to drive the build process.
You will have to add a parameter to your build scripts, that will control both :

• whether CairngormConsole.swc is included into the library list for linking application
• the value of the above compiler option CONFIG::cairngormConsole
  This should be done easily with the tools mentionned above.

Next >> Presentation