Xu Cui

Return to table of contents

Let’s say you want to modify Employee Directory for your own company and you want to add another filed (fax) to the employee data. How to do this?

In EmployeePanelDetail.mxml, add the following block.

<!-- fax -->
<mx:HBox id="faxBox" width="100%" verticalAlign="top" horizontalGap="4">
<mx:Canvas width="100">
<mx:Label right="0" text="Fax:" styleName="dataPanelLabel" />
</mx:Canvas>
<mx:Text text="{ employee.fax }" styleName="dataPanelText" selectable="true" width="165" />
</mx:HBox>

In Employee.as, add

/** fax **/
public var fax : String;

In EmployeeCSVParser.as, add

employee.fax = (itemArr[15] != '' ? itemArr[15]:null);

In InsertEmployeeDataCommand.as, add fax column

stmt.text = "INSERT INTO employee ('id', 'firstName', 'lastName', 'displayName', 'title', 'department', 'managerId', 'email', " +
"'phone', 'phoneExtension', 'fax', 'cellPhone', 'deskLocation', 'location', 'city', 'state', 'postalCode', 'countryCode') " +
" VALUES (:id, :firstName, :lastName, :displayName, :title, :department, :managerId, :email," +
" :phone, :phoneExtension, :fax, :cellPhone, :deskLocation, :location, :city, :state, :postalCode, :countryCode);";

stmt.parameters[":fax"] = employee.fax ;

In InitDatabaseCommand.as, change

var stmtText : String = "CREATE TABLE employee( id TEXT, firstName TEXT, lastName TEXT, displayName TEXT, title TEXT, department TEXT" +
", managerId TEXT, email TEXT, phone TEXT, phoneExtension TEXT, fax TEXT, cellPhone TEXT, deskLocation TEXT, " +
" location TEXT, city TEXT, state TEXT, postalCode TEXT, countryCode TEXT )";

The sample data are in employee.csv. So append another column in this file. In this column, fill in the fax info for every employee.

Then compress employee.csv to employee.csv.zip; replacing the original employee.csv.zip in samplehtdocs under src.

Then clean your project (removing contents from folder bin-debug).

Clean the old data in C:\Documents and Settings\Xu Cui\Application Data\employeedirectory\Local Store (change Xu Cui to your own directory)

Build and run your application. It will be fine.

Employee Directory is an AIR sample application from which I learned a lot. (try it) Here I post some of what I learned here.

1. introduction
2. structure
2.1 singleton
2.2 command
2.3 Cairngorm
3. ui
3.1 style
3.2 size
3.3 component
4. flow
5 events
5.1 event bubble
5.2 event clone
6 modify ED for your own purpose: custom field

related links

Return to table of contents
ED’s custom events don’t override the clone() method: it doesn’t need because the events are never redispatched. When I test one of my applications I kept getting the following error:

Error #1034: Type Coercion failed: cannot convert flash.events::Event@141cb29 to org.mymvc.MyMVCEvent

It took me quite a while to debug and finally I have to google it. It seems I am not the only one who has the same problem. The trick here is you will have to override the clone() method in your custom events.

And here is a useful link:
http://www.asserttrue.com/articles/2006/10/14/custom-events-in-actionscript-3-0

Return to table of contents
ED defines 4 custom events,
CommandCompleteEvent
CommandProgressEvent
DataSynchronizationEvent
SelectedItemChangeEvent

The main job of these custom events seems to define constant (say public static const COMPLETE : String = “complete”;). Although CommandCompleteEvent and CommandProgressEvent also include a variable “command” which stores the command which dispatch the event, I don’t see ED uses this information (Except in CommandProgressEvent, this Event can retrieve the progress and progressMessage of the corresponding command).

The only class which dispatches SelectedItemChangeEvent is ApplicationModel. The only place where this event is listened is MainContentContainer. Although SelectedItemChangeEvent has variable “item”, again it seems not to be used. ApplicationModel holds a copy of “item” and it is this copy that is used.

Return to table of contents
All command classes are inherited from class Command. By name, commands perform something. Every command has execute() which does the job, and emits progress and complete event, and possibly error event.

The base class, Command, has the following three main functions:

public function execute() : void
protected function notifyComplete() : void
protected function notifyProgress( progress:uint, progressMessage:String = null ) : void
protected function notifyError( msg:String ) : void

The execute() function has to be overridden and implemented by subclasses. Other functions in a command class are usually private — this makes perfect sense as commands are supposed to execute only.

When using (or calling) a command, ED usually does this (using InitApplicationCommand as an example):

var cmd : InitApplicationCommand = new InitApplicationCommand( stage );
cmd.addEventListener( CommandCompleteEvent.COMPLETE, onAppInitComplete );
cmd.addEventListener( CommandProgressEvent.PROGRESS, onAppInitProgress );
cmd.addEventListener( ErrorEvent.ERROR, onAppInitError );
cmd.execute();

You will find this pattern again and again in ED.

Return to table of contents
1. CustomAutoComplete

This component can be very useful. It pops up a list of suggestions based on characters entered by the user. This is a very simple example on how to use it:

<controls:CustomAutoComplete id="searchInput"
typedTextChange="onTextChange();"
selectionChange="onSelectionChange();"
dataProvider="{ searchResults }"
lookAhead="true"
labelField="displayName"/>

And below is the the script part of the main mxml file I used to test this component.

   import mx.controls.Alert;

   import mx.collections.ArrayCollection;

   [Bindable]
   private var searchResults:ArrayCollection  = new ArrayCollection();
   private var all:ArrayCollection  = new ArrayCollection();
   private function init():void
   {
    all.addItem({displayName:"abc", name:"Jack Smith"});
    all.addItem({displayName:"abd", name:"John Win"});
    all.addItem({displayName:"abe", name:"Bob XC"});
    all.addItem({displayName:"acd", name:"LIN Bobby"});
    all.addItem({displayName:"efg", name:"xie iix"});
    all.addItem({displayName:"efv", name:"xfe abc"});
    all.addItem({displayName:"hik", name:"45 65"});
   }
   private function onTextChange():void
   {
    searchResults.removeAll();
    var ii:int;
    for(ii=0;ii<all.length;ii++)
    {
     if (all[ii].displayName.indexOf(searchInput.typedText) != -1)
      searchResults.addItem(all[ii]);
    }
   }
   private function onSelectionChange():void
   {
    mx.controls.Alert.show(searchInput.selectedItem.name);
   }

Return to table of contents
After the application is initialized, Event “applicationComplete” is dispatched and the following function is called:

// in employeedirectory.mxml
ui.init();

Go to ApplicationUI.mxml, we find ui.init() issues the InitApplicationCommand. The process can be shown in the following diagram:

Return to table of contents
In ApplicationUI.mxml (init()), you will find the following two lines:

// in ApplicationUI.mxml, in init()
titleControls.addEventListener( "showHelp", showHelpScreen );
addEventListener( "close", closePanel );

This is a little bit strange. One uses titleControls as event listener, the other uses ApplicationUI. It turns out this is due to the bubbling of event.

// in TitleControls.mxml
<mx:Button click="dispatchEvent( new Event('showHelp') )" />

// in EmployeeView.mxml
<mx:Button id="closeBtn" click="dispatchEvent( new Event( Event.CLOSE, true ) )"/>

Note that the “true” argument in the second case. It allows the Event to bubble to the parent components (ApplicationUI). That’s why ApplicationUI can hear the event. If you add “true” argument in the TitleControls.mxml, you can also use ApplicationUI to listen to the event.

Return to table of contents
Which line(s) in the code determines the size of the application?

This seemingly simple question did take me some time. The answer lines in the following two lines:

// in ApplicationUI.mxml
<mx:vbox id="contentBox" minwidth="310" minheight="70">

// in MainContentContainer.mxml
<mx:canvas width="290">

To really see the effect of changing these values, you need to change the width and height in employeedirectory.mxml. I changed them to 640×800.

// in employeedirectory.mxml
<mx:application height="800" width="640" x="100" y="50">

<transparent>false</transparent>

Here is the application of different size:

Return to table of contents
While reading ED code, I frequently encounter singleton pattern. A singleton class is a class you can only instantiate once and it is useful to store application-wide data (say window position). ApplicationModel and all managers are singleton classes.

Here is ED’s approach to singleton class to avoid multiple instantiation:

 public class ApplicationModel extends EventDispatcher
 {

  private static var instance : ApplicationModel;

  /**
   * Private constructor. Use getInstance() instead.
   */
  public function ApplicationModel()
  {
   if ( instance != null )
   {
    throw new Error("Private constructor. Use getIntance() instead.");
   }
  }

  /**
   * Get an instance of the DataManager.
   */
  public static function getInstance() : ApplicationModel
  {
   if ( instance == null )
   {
    instance = new ApplicationModel();
   }
   return instance;
  }
 }

One will have to use ApplicationModel.getInstance(), instead of new ApplicationModel() to create an ApplicationModel object. Please note the use of “static” in the declaration of variable instance and function getInstance().

In ED, all managers are singleton classes — there is no need to have two managers of the same kind.

There are 4 managers: ConfigManager, DatabaseConnectionManager, DataSynchronizationManager and WindowPositionManager.

ConfigManager: Read employeedirectory_config.xml and get the value of configuration such as data location.
DatabaseConnectionManager: keep the SQLConnection instance.
DataSynchronizationManager: sychronization data
WindowPositionManager: keep the entire window inside the computer screen.