The <mx:Model> tag allows you to create an object that represents a data structure using MXML. To use the tag practically, you must always specify an id attribute:

<mx:Model id="example" />

Once you’ve created a model this way, you can do one of two things:

<mx:Model id="userData">
    <user>
        <email></email>
        <phone></phone>
        <address>
            <city></city>
            <state></state>
        </address>
    </user>
</mx:Model>

<mx:Model id="userData">
    <user>
        <email>[email protected]</email>
        <phone>123 555-1212</phone>
        <address>
            <city>Exampleville</city>
            <state>CA</state>
        </address>
    </user>
</mx:Model>

<states>
    <state>Alabama</state>
    <state>Alaska</state>
    <state>Arizona</state>
    <state>Arkansas</state>
    <state>California</state>
    <state>Colorado</state>
    <state>Connecticut</state>
    <state>Delaware</state>
    <state>Florida</state>
    <state>Georgia</state>
    <state>Hawaii</state>
    <state>Idaho</state>
    <state>Illinois</state>
    <!-- additional states... -->
</states>

<mx:Model id="statesModel" source="states.xml" />

<mx:Model id="userData">
    <user>
        <email>[email protected]</email>
        <phone>123 555-1212</phone>
        <address>
            <city>Exampleville</city>
            <state>CA</state>
        </address>
    </user>
</mx:Model>
<mx:Button click="trace(userData.email)" />

<mx:VBox>
    <mx:Button click="userData.address.city = 'Exampleville' +
                      Math.round(Math.random() * 10)" label="Update City" />
    <mx:Button click="trace(userData.address.city)" label="Trace" />
</mx:VBox>

<states>
    <state>Alabama</state>
    <state>Alaska</state>
    <state>Arizona</state>
    <state>Arkansas</state>
    <state>California</state>
    <state>Colorado</state>
    <state>Connecticut</state>
    <state>Delaware</state>
    <state>Florida</state>
    <state>Georgia</state>
    <state>Hawaii</state>
    <state>Idaho</state>
    <state>Illinois</state>
    <!-- additional states... -->
</states>

<mx:Model id="statesModel" source="states.xml" />

<mx:Button click="trace(statesModel.state is Array)" />

<mx:Script>
    <![CDATA[

        private function displayStates():void {
            for(var i:uint = 0; i < statesModel.state.length; i++) {
                statesTextArea.text += statesModel.state[i] + "
";
            }
        }

    ]]>
</mx:Script>
<mx:Model id="statesModel" source="states.xml" />
<mx:VBox>
    <mx:Button click="displayStates()" />
    <mx:TextArea id="statesTextArea" height="500" />
</mx:VBox>

The <mx:Model> tag is useful when you want to work with data stored in traditional types such as objects, strings, and arrays. If you want to work with XML-formatted data, you can use the <mx:XML> tag to create an XML-based data model (that you can access using E4X).

The <mx:Model> and <mx:XML> tags are structurally very similar. As with <mx:Model>, you should always specify an id attribute when creating an <mx:XML> tag:

<mx:XML id="example" />

Also, as with <mx:Model>, there are two basic ways to create the structure and/or initialize an <mx:XML> data model:

<mx:XML id="chaptersXml" xmlns="">
    <chapters label="Chapters">
        <chapter label="Chapter 1">
            <file label="File 1.1" />
        </chapter>
        <chapter label="Chapter 2">
            <file label="File 2.1" />
        </chapter>
    </chapters>
</mx:XML>

<mx:XML id=chaptersXml" source="chapters.xml" />

<mx:XML id="chaptersXml">
    <chapters label="Chapters">
        <chapter label="Chapter 1">
            <file label="File 1.1" />
        </chapter>
        <chapter label="Chapter 2">
            <file label="File 2.1" />
        </chapter>
    </chapters>
</mx:XML>
<mx:Button click="trace(chaptersXml.chapter[0].@label)" />

<mx:XML id="chaptersXml">
    <chapters label="Chapters">
        <chapter label="Chapter 1">
            <file label="File 1.1" />
        </chapter>
        <chapter label="Chapter 2">
            <file label="File 2.1" />
        </chapter>
    </chapters>
</mx:XML>
<mx:VBox>
    <mx:Button click="chapters.dataProvider = chaptersXml" />
    <mx:Tree id="chapters" width="200" labelField="@label" />
</mx:VBox>

Although the <mx:Model> and <mx:XML> data models provide a simple and convenient way to work with data, they are not the ideal solution in most cases. Even though they work well for simple, static data (such as a list of U.S. state names), they are not well suited for complex data, dynamic data, or data that has rules applied to it. In those cases, it is better to use a custom ActionScript class as the data model. Although there’s nothing wrong with using the <mx:Model> and <mx:XML> tags, it is best to be very sparse in your use of them. Remember that MXML is primarily intended for creating user interfaces and layout. ActionScript, on the other hand, is ideal for managing and working with data. Here are a few of the advantages of using a custom ActionScript class:

Writing an ActionScript class as a data model is quite simple. You merely need to define a new class with public accessor methods for all the properties. The class in Example 14-1 defines a data model for a user. Note that all the getters and setters are strongly typed and several of the setters use data testing.

package com.oreilly.programmingflex.data {

    public class User {

        private var _nameFirst:String;
        private var _nameLast:String;
        private var _email:String;
        private var _lastLogin:Date;
        private var _userType:uint;

        public function get nameFirst():String {
            return _nameFirst;
        }

        public function set nameFirst(value:String):void {
            _nameFirst = value;
        }

        public function get nameLast():String {
            return _nameLast;
        }

        public function set nameLast(value:String):void {
            _nameLast = value;
        }

        public function get email():String {
            return _email;
        }

        public function set email(value:String):void {
            var expression:RegExp = /[A-Z0-9._%-]+@[A-Z0-9.-]+.[A-Z]{2,4}/i;
            if(expression.test(value)) {
                _email = value;
            }
            else {
                _email = "invalid email";
            }
        }

        public function get lastLogin():Date {
            return _lastLogin;
        }

        public function set lastLogin(value:Date):void {
            _lastLogin = value;
        }

        public function get userType():uint {
            return _userType;
        }

        public function set userType(value:uint):void {
            if(userType <= 2) {
                _userType = value;
            }
        }

        public function User() {}


    }
}

You can then create an instance of the model class using MXML or ActionScript. With MXML you have to define the namespace, then use <namespace:Class> to create the instance:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
xmlns:data="com.oreilly.programmingflex.data.*" layout="absolute">

    <data:User id="user" email="[email protected]" lastLogin="{new Date()}"
               nameFirst="Abigail" nameLast="Smith" userType="1" />

</mx:Application>

With ActionScript you need to import the class, and then use the constructor as part of a new statement:

import com.oreilly.programmingflex.data.User;
private var user:User;

private function initializeHandler(event:Event):void {
    user = new User();
    user.email = "[email protected]';
    // etc.
}

In the next section, we’ll look at data binding. If you want to enable the data binding feature for a custom ActionScript-based data model, you must use the [Bindable] metadata tag when declaring the class:

[Bindable]
public class User {

If you create the instance using MXML, the instance is automatically enabled for data binding, assuming the class uses the [Bindable] metadata tag. However, if you create the instance using ActionScript, you must also use the [Bindable] tag when declaring the variable you use to store the reference:

[Bindable]
private var user:User;

We’ll talk more about data binding and the [Bindable] metadata tag in the Data Binding” section later in this chapter.

Another way that you can work with data is to use a collection. In this case, we’re using the word collection to refer to a class that implements the mx.collections.ICollectionView interface. Two of the primary such collection classes are mx.collections.ArrayCollection and mx.collections.XMLListCollection.

In some cases, collections can be substitutes for the other techniques we described earlier. For example, you can use a collection in place of a Model tag if you intend to use the data as a data provider for a list component. However, when you are using an ActionScript class to model data, a collection isn’t necessarily a substitute, but rather a complement. The primary value of a collection in such a case is that it provides a data-bindable way to store data.

You can use an ArrayCollection instead of an Array when you’d like to use data binding (see the next section for more information about data binding). This is because an Array does not allow for data binding. A change to an element in an array will not trigger changes in other components. However, ArrayCollection instances are data-bindable, and if you add or remove an element from the collection, it triggers binding changes. As with many things in Flex, you can create an ArrayCollection instance using ActionScript or MXML. First we’ll look at an example using MXML. In the following code, we create an ArrayCollection instance using an ArrayCollection tag. We are assigning the collection to the dataProvider property of a combo box component. You’ll notice that nested in the ArrayCollection tag is an Array tag. That’s because an ArrayCollection object is a data-bindable wrapper for an array.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical">
    <mx:ComboBox>
         <mx:dataProvider>
              <mx:ArrayCollection id="letters">
                   <mx:Array>
                        <mx:String>A</mx:String>
                        <mx:String>B</mx:String>
                        <mx:String>C</mx:String>
                        <mx:String>D</mx:String>
                   </mx:Array>
              </mx:ArrayCollection>
         </mx:dataProvider>
    </mx:ComboBox>
</mx:Application>

Once we’ve created an ArrayCollection instance we can update it using various methods. We can use the addItem() method to add elements to the collection. We can use the removeItemAt() method to remove elements at specific indexes. We can use the getItemAt() method to retrieve elements at specific indexes. Adding and removing elements using these methods triggers data binding changes, as you can see in the next example. In this code, we add a button that adds a random letter to the collection when the user clicks it. Because the update triggers data binding, the following code will result in the combo box redrawing itself, and it will display a new item in the drop-down list.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical">
    <mx:ComboBox>
         <mx:dataProvider>
              <mx:ArrayCollection id="letters">
                   <mx:Array>
                        <mx:String>A</mx:String>
                        <mx:String>B</mx:String>
                        <mx:String>C</mx:String>
                        <mx:String>D</mx:String>
                   </mx:Array>
              </mx:ArrayCollection>
         </mx:dataProvider>
    </mx:ComboBox>
    <mx:Button label="Change"
     click="letters.addItem(String.fromCharCode
(Math.round(Math.random() * 26) + 65))" />
</mx:Application>

As we said earlier, we can also create ArrayCollection instances using ActionScript. When we create ArrayCollection instances in this way, we can create the empty instance and add elements programmatically using the addItem() method, or we can initialize the collection by passing an array to the constructor, as in the following example.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical">
    <mx:Script>
          <![CDATA[
              import mx.collections.ArrayCollection;

              [Bindable]
              private var letters:ArrayCollection =
new ArrayCollection(["A", "B", "C", "D"]);

         ]]>
    </mx:Script>
    <mx:ComboBox dataProvider="{letters}" />
    <mx:Button label="Change"
     click="letters.addItem(String.fromCharCode
(Math.round(Math.random() * 26) + 65))" />
</mx:Application>

The XMLListCollection class is to XMLList objects what the ArrayCollection is to arrays. XMLListCollection instances wrap XMLList objects. XMLListCollection provides the same API for adding, retrieving, and removing elements as the ArrayCollection class does. However, when you call these methods, you use XML elements instead of nonhierarchical values, as you would with ArrayCollection. The following code illustrates how you can create an XMLListCollection using MXML:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical">
    <mx:Script>
         <![CDATA[

              private function addNewItem():void {
                   var item:XML = <element label="Numbers">
                                                <element label="1" />
                                                <element label="2" />
                                        </element>
                   collection.addItem(item);
              }

         ]]>
    </mx:Script>
    <mx:Tree labelField="@label" width="200">
         <mx:dataProvider>
              <mx:XMLListCollection id="collection">
                   <mx:XMLList xmlns="">
                        <element label="Letters">
                             <element label="A" />
                             <element label="B" />
                        </element>
                   </mx:XMLList>
              </mx:XMLListCollection>
         </mx:dataProvider>
    </mx:Tree>
    <mx:Button label="Change" click="addNewItem();" />
</mx:Application>

In this example, we create an XMLListCollection with an ID of collection, and we assign it as the dataProvider for a tree component. The XMLListCollection instance wraps an XMLList object with one element called Letters. When the user clicks the button we use the addItem() method to add a second element to the XMLListCollection. Because XMLListCollection updates data binding, the changes are reflected in the UI immediately.

You can also create an XMLListCollection object using ActionScript. The following example illustrates how to do this. This code results in the same behavior as the preceding example, but it uses ActionScript to create the XMLListCollection instance.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical">
    <mx:Script>
         <![CDATA[
              import mx.collections.XMLListCollection;

              private var xmlList:XMLList = new XMLList(<element label="Letters">
                                                              <element label="A" />
                                                              <element label="B" />
                                                       </element>);

              [Bindable]
              private var collection:XMLListCollection =
new XMLListCollection(xmlList);

              private function addNewItem():void {
                   var item:XML = <element label='Numbers'>
                                                <element label="1" />
                                                <element label="2" />
                                        </element>
                   collection.addItem(item);
              }

         ]]>
    </mx:Script>
    <mx:Tree labelField="@label" width="200" dataProvider="{collection}" />
    <mx:Button label="Change" click="addNewItem();" />
</mx:Application>