Preface

When UltraShock asked me to write an introductory tutorial on Forms and Screens in FlashMX 2004 Professional (hereafter F04Pro), I thought "Sounds great! Slap a few components on a couple of forms, add some behaviours, and it's done!". But the more I worked with forms, and the more I thought through the tutorial I wanted to write, the less I liked that idea. It seemed to me that despite all of the drag'n'drop code for dummies that forms supported, the whole concept wasn't really made for beginners. I mean, why would they only put Forms in F04 Pro if it was aimed at newbies?

So, valiantly fighting against the various frustrations that cropped up (not least of which was the initial dearth of documentation), I set out to write a tutorial that showed this new feature as I saw it: A promising new model for building robust MVC applications that maybe isn't quite ready for prime time. (I'm sooo heroic!)

This incarnation of the tutorial was a whole lot trickier to write than what I originally signed up for, but hopefully the work pays off by providing the right people with the right information. My fingers are crossed (which will make typing the rest of this tutorial insanely difficult).

Introduction

This tutorial is going to focus on using forms and screens to develop a Rich Internet Application in F04Pro using the MVC design pattern. It will guide you through developing a simple address book application - without a single line of code in the FLA (tell me that's not 1337). In order to keep this tutorial succinct, the end product is pretty light on features (it doesn't even save).

To get the most out of this tutorial, you will need a basic understanding of Object Oriented Programming in ActionScript 2. Dave Yang has written an excellent tutorial on this topic for UltraShock if you need to get up to speed on this. I have also written a series of posts about it on my blog . You'll also want to read up on the MVC design pattern before proceeding, if you aren't already familiar with it.

About Forms

So what the heck are forms, and why do you care? Forms and screens represent a new state-based metaphor for application development in FlashMX 2004 Pro. They don't really do anything that you couldn't have done using movieclips and timelines in MX, but they do make developing state-based applications simpler, and more self-evident.

In form based development, each form lives in a hierarchy of forms, at the top of which is the root form. This hierarchy is navigated in code using dot syntax, such as "_root.application.form1". This should sound familiar, as it's very similar to how MovieClips work.

Each form represents a single state of the application, and its visibility can be toggled on and off as required. The visual elements of child forms are overlaid on its parent when it is visible, and in many ways this lets the interface act in a very similar manner to inheritance in programming, where the "sub form" (child) builds on (or even overwrites) the interface of its "super form" (parent). You can see this in action in the screenshot below.

Forms also have the benefit of letting us cleanly separate the three parts of an MVC application. The view is represented by interface components sitting on the stage of a form, the controller can be an AS2 class bound to the form, and the model can be created as a separate data class. Best of all, we can create a forms-based application without a single line of code in the FLA, using only external class definitions in .as files, and compiled UI components.

So where's the catch?

Unfortunately, as with so many things in Flash 2004, Forms don't quite seem "complete", and they're still poorly documented in some respects (though that is improving). They seem to be lacking some essential functionality, some of which we will be adding in order to make this tutorial work. They're also despairingly slow, both to work with and to compile, so get used to seeing the image below if you're working on larger projects.

The documentation is coming, the community will no doubt extend the Form class to add the functionality it requires (heck, I'm starting that with this tutorial), and hopefully the compile speed will improve with an update to Flash one of these days. I'm sure things will work out well, so let's get down to business!

Planning

I'm a huge proponent of carrying out thorough analysis and planning before starting to code. One tool that I really like (though I'm biased) is gModeler.com , which lets you create UML class diagrams for Flash. I've made it easy for you, and diagrammed the project so you can see what it would look like in the planning phase. Just click on the thumbnail to the right to see the full size diagram. Visit gModeler.com for more information on using UML to plan your application.

Setting Up The Project

This application is going to consist of a fair number of files, so we'll start by creating them all, and adding them to a project.

1. First, create a new Flash Project (File:New...), and save it as AddressBook.flp .
2. Next, create five ActionScript File s, and save them to the same directory as your project file with the following names: GForm.as , ObjectArray.as , AddressBookForm.as , ContactListForm.as , ContactEditForm.as . Notice that each ActionScript file corresponds to a class element in the UML diagram from above, these files will contain the definitions for those classes.
3. Finally, create a new Flash Form Application and save it as AddressBook.fla in the same directory.

Now, add all of these files to your project: Open the Project panel, and click the plus icon. Y ou can now select all of the files you just created (except the project file), and click Open to add them to the project. They will be shown in the Project panel as in the image to the right.

The Model: Creating the Data Class

We're going to create a very simple data class to act as our model for the application. Our needs are pretty basic:

1. We need to be able to be able to add, delete and modify contacts through the class's interface (public methods).
2. We want it to be usable as a dataProvider with UI components.

Double click on ObjectArray in the project panel to open it, then enter the following code. Read the comments for descriptions of what each method does.

class ObjectArray extends Array { 
    // adds the item to the array 
    function addItem(p_item:Object):Void 
    { 
        push(p_item); 
    } 
    
    // finds and replaces oldItem with item in the array 
    function updateItem(p_oldItem:Object,p_item:Object):Void 
    { 
        this[getIndexOf(p_oldItem)] = p_item; 
    } 

    // removes the specified object from the array 
    function deleteItem(p_item:Object):Void 
    { 
        splice(getIndexOf(p_item),1); 
    } 

    // finds and returns the index of a specific object: 
    // used internally by deleteItem and updateItem 
    private function getIndexOf(p_item:Object):Number 
    { 
        var i:Number=length; 
        while (i-- > 0) { 
            if (this[i] == p_item) { 
                return i; 
            } 
        } 
        return -1; 
    } 
}

      

Check the code for errors ( Tools -> Check Syntax ), save the file, and close it. We'll use an instance of the ObjectArray as our model when we create the controller.

The View: Creating the interface

Double click on AddressBook.fla in the project panel to open the Flash Form Application . The first thing you'll notice is screens panel on the left, showing the form hierarchy. The second thing you'll notice is that there is no timeline. Don't panic, it's still there if you need it, but we're not going to touch it.

Right now, you should have two forms showing in the screens panel: the root form called application , and a subform called form1 . Rename the root form addressBook , and the subform contactList . Click the plus sign at the top of the panel to create a new subform, and rename it contactEdit . Your screens panel should now look like the image to the right.

The root addressBook form handles the global aspects of our application. Its stage will contain any elements that are present throughout the application, and it will be bound to a class that handles the top level application tasks. Similarly, the two subforms each represent a state of the application (listing contacts, and editing a contact), and will contain the interface elements (on their stage) and the programming logic (in the class they are bound to) that is within the context of that state.

Click to select each form in turn to edit it, and add interface elements as described below. Right clicking on each of the subforms and selecting Hide Screen will reduce the clutter, and make this task easier.

With the addressBook form selected, place a background and title for the application. These elements will be omnipresent in your application.

With the contactList form selected, place a subtitle for the form, and the following components: A DataGrid (with instance name contactList_dg ), an "Add New" PushButton ( addNew_btn ), an "Edit" PushButton ( edit_btn ) and a "Delete" push button ( delete_btn ).

Place a subtitle for the form, and the following components: Three TextInput components (with instance names name_ti , phone_ti and email_ti ); a TextArea ( notes_ta ); and three PushButtons labelled "Reset" ( reset_btn ), "Save" ( save_btn ) and "Cancel" ( cancel_btn ). It also might be nice to put in some labels for your text inputs.

And that's it for the view. We don't have to write any code - all the code that we need is already present in the UI components. So now all we need to do is glue the model to the view with a bit of business logic -- on to the controller!

The Controller: Hell Breaks Loose!

Now we're all ready to write the logic that ties our model to our view. Our controller is going to comprise a class bound to each form that defines the business logic for that form. To avoid making this tutorial overlong, I've tried to minimize discussion of the actual code used by commenting it effectively in-line, so pay close attention to the code comments!

You're going to love this part (assuming you're a masochist)!

Seeing as how we already have AddressBook.fla open, we may as well create the associations between our forms, and the classes that will control them. Click on the addressBook form in the screens panel to select it. In the properties inspector, you will notice a property called Class name - set its value to AddressBookForm . This will bind the addressBook form to the AddressBookForm class we will be defining inside AddressBookForm.as . Select the contactList form and set its class name to ContactListForm , then select contactEdit and set its class name to ContactEditForm .

GForm: Pure Band-Aid Goodness

In an ideal world, we would jump into coding a set of classes that extend mx.screens.Form directly, and they would marry happily to everything we've done so far and we'd be finished. BUT... this is not an ideal world, and mx.screens.Form has a couple of major deficiencies we need to fix first.

Normally, when you define classes to bind to forms they inherit directly from mx.screens.Form (the built in Form class). However, in my brief time working with forms, I have identified two major issues with the built-in Form class that prevent me from using them as I would like to:

1. Firstly, the Form class does not include a collection of child forms. This means that you can only reference child forms by a largely arbitrary index number, not by name, unless you declare each child form manually in your class.
2. Secondly, because the class initializes before the UI components it contains and its child forms, it is very difficult to write logic that sets up and populates interface elements when the form loads.

Double click on GForm.as in the project panel to open it, then copy the code below, paste it into GForm.as , and save.

/*
   GForm class created by Grant Skinner, http://gskinner.com/
   This class extends the mx.screens.Form function, and adds two
   essential capabilities:

   1) Calls a initUI method immediately after the form loads
      for setting up UI elements, and other tasks that require
      initialization to be complete.

      Example usage:
      function initUI():Void { myDataGrid.dataProvider = myData; }

   2) Maintains a childForms collection referenced by name.

      Example usage:
      childForms.myChildForm.visible = false
*/

class GForm extends mx.screens.Form {

    function GForm() {
        $initUIIntervalID = setInterval($initUI,1,this);
    }

    // macromedia uses _ prefix, so I'll use $:
    private var $childForms:Object;
    private var $numChildForms:Number;
    private var $initUIIntervalID:Number;

    // logic for initUI:
    private function $initUI(p_form:GForm):Void {
        clearInterval(p_form.$initUIIntervalID);
        delete(p_form.$initUIIntervalID);
        p_form.initUI();
    }

    // declare an empty initUI function
    function initUI():Void {}

    // child forms getter function
    function get childForms():Object {
        // check to see if we need to update our index:
        if ($numChildForms != numChildForms) {
        // counts don't match, so we need to update our index:
        $childForms = new Object();
        $numChildForms = numChildForms;
            for (var i:Number=0;i<$numChildForms;i++) {
                var f:mx.screens.Form = getChildForm(i);
                $childForms[f._name] = f;
            }
        }
        return $childForms;
    }
}

ContactListForm: List in carefully

This class provides the grey matter for the contact list form (bet you hadn't guessed that). It really only needs to do two things:

1. Set up the interface components and handle events from them.
2. Communicate events back to the addressBook form.

Study the code below, paying attention to the comments, then copy and paste it into ContactListForm.as and save.

dynamic class ContactListForm extends GForm {
    // declare the dataProvider property, it's contents will be passed to
    // me by the addressBook form.
    private var dataProvider:Object;
   
    // declare our UI elements:
    private var contactList_dg:mx.controls.DataGrid;
    private var delete_btn:Button;
    private var addNew_btn:Button;
    private var edit_btn:Button;
   
    // function to set up our UI:
    function initUI():Void {
        // set up buttons - we'll use the lazy way, 
        // instead of messing about with listeners:
        delete_btn.onRelease = function() { this._parent.deleteContact(); }
        addNew_btn.onRelease = function() { this._parent.addNewContact(); }
        edit_btn.onRelease = function() { this._parent.editContact(); }
        // set up datagrid component:
        contactList_dg.columnNames = ["name","phone"];
        contactList_dg.dataProvider = dataProvider;
    }
    function deleteContact():Void {
        // broadcast the deleteContact event, 
        // and pass the selected item as a property:
        dispatchEvent({type:"deleteContact",
        target:this,item:contactList_dg.getSelectedItem()});
    }
    function addNewContact():Void {
        // broadcast the addContact event:
        dispatchEvent({type:"addContact",target:this});
    }
    function editContact():Void {
        // broadcast the editContact event, 
        // and pass the selected item as a property:
        dispatchEvent({type:"editContact",
        target:this,item:contactList_dg.getSelectedItem()});
    }
    function refresh():Void {
        // force contactList_dg to redraw 
        // (the .redraw method doesn't actually work)
       contactList_dg.dataProvider = dataProvider;
    }
}

ContactEditForm: Edit this

The ContactEditForm class has to perform 2 additional tasks:

1. Accept an item passed from the addressBook form to edit, and populate the interface with data from that item.
2. Compile data from the interface to send back to the addressBook form.

For the first task, we'll simply define a public method called edit that addressBook can pass item and isNew parameters to (calling methods of forms lower in the hierarchy is perfectly fine since they belong, in effect, to the parent form). The second is self-explanatory: Have a look at the code below, then copy it into ContactEditForm and save.

class ContactEditForm extends GForm {
    // declare our dataProvider object and isNew properties:
    private var dataProvider:Object;
    private var isNew:Boolean;
 
    // declare our UI objects:
    private var name_ti:mx.controls.TextInput;
    private var phone_ti:mx.controls.TextInput;
    private var email_ti:mx.controls.TextInput;
    private var notes_ta:mx.controls.TextArea;
    private var save_btn:Button;
    private var reset_btn:Button;
    private var cancel_btn:Button;
 
    // function to set up our UI:
    function initUI():Void {
       // set up buttons:
       save_btn.onRelease = function() { this._parent.save(); }
       reset_btn.onRelease = function() { this._parent.reset(); }
       cancel_btn.onRelease = function() { this._parent.cancel(); }
    }
 
    // edit method, called by the addressBook form:
    function edit(p_item,p_new):Void {
       dataProvider = p_item; // the item object to edit
       isNew = p_new; // indicates if the item is new
       reset(); // fill the interface fields
    }
    // reset method, populates the interface fields 
    // with data from the dataProvider
    function reset():Void {
       name_ti.text = dataProvider.name;
       phone_ti.text = dataProvider.phone;
       email_ti.text = dataProvider.email;
       notes_ta.text = dataProvider.notes;
    }
    // cancel method, tells the addressBook form that 
    // we want to return to the list
    function cancel():Void {
       // broadcast cancelEdit event:
       dispatchEvent({type:"cancelEdit",target:this});
    }
    // save method, compiles data from interface, and 
    // passes it back to addressBook form
    function save():Void {
       // assemble a new item with the data from the interface:
       var item:Object = {name:name_ti.text,phone:phone_ti.text,
       email:email_ti.text,notes:notes_ta.text};
       // broadcast saveEdit event, with oldItem, item and isNew properties:
       dispatchEvent({type:"saveEdit",target:this,oldItem:dataProvider,
       item:item,isNew:isNew});
    }
}

AddressBookForm: It all comes together

This class handles the core application logic. It instantiates our model, manages the showing and hiding of the two child forms (thereby managing the application state), and handles all of the communication between the forms and the model.

It's actually extremely simple in implementation, with most of its code consisting of event handlers. You'll notice that it subscribes to it's child forms' events in the initUI method - this is necessary because child forms instantiate after their parent. Again, read through the code, then copy it into AddressBookForm.as and save.

class AddressBookForm extends GForm {
    private var dataProvider:ObjectArray;
   
    function AddressBookForm() {
        // create an instance of our ObjectArray class, 
        // this will serve as our model:
        dataProvider = new ObjectArray();
   
        // let's populate our contactList with a little 
        // dummy data, for the sake of demonstration:
        dataProvider.addItem({name:"Grant Skinner",phone:"1900hotflash",
        email:"info@gskinner.com",
        notes:"Likes rainbow sprinkle doughnuts."});
        dataProvider.addItem({name:"John Doe",phone:"5552323",
        email:"johndoe@macromedia.com",notes:"Hates pool noodles."});
   }
   function initUI():Void {
       // now, let's pass a reference to the contactList 
       // data for our list form:
       childForms.contactList.dataProvider = dataProvider;
       // and subscribe to our subforms events, 
       // so we know when a button is pressed:
       // contactList events:
       childForms.contactList.addEventListener("editContact",this);
       childForms.contactList.addEventListener("addContact",this);
       childForms.contactList.addEventListener("deleteContact",this);
       // contactEdit events:
       childForms.contactEdit.addEventListener("saveEdit",this);
       childForms.contactEdit.addEventListener("cancelEdit",this);
       // hide the contactEditForm, so we start out with just the list:
       childForms.contactEdit.visible = false;
   }
   function editContact(p_eventObj:Object):Void {
       // hide the list form, and show the edit form:
       childForms.contactList.visible = false;
       childForms.contactEdit.visible = true;
       // tell the edit form to edit the item that was passed to me:
       // second parameter false indicates it is not a new item
       childForms.contactEdit.edit(p_eventObj.item,false);
   }
   function addContact(p_eventObj:Object):Void {
       // hide the list form, and show the edit form:
       childForms.contactList.visible = false;
       childForms.contactEdit.visible = true;
       // tell the edit form to edit a new blank item:
       // second parameter true indicates a new item
       childForms.contactEdit.edit({name:"",phone:"",
       email:"",notes:""},true);
   }
   function deleteContact(p_eventObj:Object):Void {
       // tell the dataProvider to remove the item 
       // that was passed to me:
       dataProvider.deleteItem(p_eventObj.item);
       // refresh the list:
       childForms.contactList.refresh();
   }
   function cancelEdit(p_eventObj:Object):Void {
       // hide the edit form, and show the list form
       childForms.contactList.visible = true;
       childForms.contactEdit.visible = false;
   }
   function saveEdit(p_eventObj:Object):Void {
       // check if it's a new item
       if (p_eventObj.isNew) {
           // it is, tell the dataProvider to add it:
           dataProvider.addItem(p_eventObj.item);
       } else {
           // it isn't, tell the dataProvider to update it:
           dataProvider.updateItem(p_eventObj.oldItem,
           p_eventObj.item);
       }
       // close editing screen:
       cancelEdit();
       // refresh the list:
       childForms.contactList.refresh();
   }
}

Wrapping it All Up

You're done! You can now hit the Test Project button in the Project panel, select AddressBook.fla as your main file, and hopefully you'll have a crazy-cool, not-completely-useful AddressBook application to show your Mum. Just make sure you tell her there isn't a single line of code in the FLA! She'll be impressed, I promise! [Ed: We checked, there really isn't a single line of code in the FLA - if you find one, let us know !]

If it doesn't work, don't fret; the whole, completed project is available in the source downloads for this tutorial. You can play with the finished version, below.

So what have we learned? Well... Right now, forms seem a bit unpolished, but they give us a really sleek metaphor for building MVC applications. With a little work by the community and Macromedia, we could have something really smashing!