Component properties can aid in communicating to and from a component. You create properties by defining fields or getter/setter functions. You define properties in the same manner you would in ActionScript.

It is a good practice to not declare fields as public, but rather to declare getter/setter functions, as shown in the following code. This helps you to guarantee that if the implementation of the property changes in the future, the public interface will not change.

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

        private var _mode:String;

        [Bindable]
        public function set mode(value:String):void
        {
            _mode = value;
        }

        public function get mode():String
        {
            return _mode;
        }
        ]]>
    </mx:Script>
    <!-- contents omitted for brevity-->
</mx:Canvas>

In the preceding code, we declared a public property mode. You can use this property to set the mode property of the component from the parent. In the code, we declared the property as bindable using the [Bindable] metadata tag. It is a good idea to use [Bindable] whenever you declare a public property because it is likely that a developer will want to use the data-binding features of Flex with your new component. Finally, we declared a private _mode variable. It is a good practice to declare private properties with a preceding single underscore. This allows you to distinguish a public property from a private one, especially if you are exposing a private property via a public getter/setter function.

Once you’ve declared a property, you can access the property from the parent container as you would any other property. In the following code, we have set the property value from the parent container:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" initialize="init()"
xmlns:pf3="com.oreilly.programmingflex.contactmanager.views.*">
    <pf3:ContactDetails mode="view" />
    <!-- contents omitted for brevity -->
</mx:Application>

Most of the time, you will want a property to accept any value of a data type, and in such cases, this method works well. Sometimes, though, you will want to restrict the possible values. In the code we’ve been building on throughout this chapter, the mode value can accept only an enumeration of values. However, ActionScript does not support enumerations. It is a good practice, therefore, to provide the user with static variables. This reduces the possibility of user error and improves ease of use because static variables are a form of self-documentation for possible values. In addition to using static variables, we use the Inspectable metadata tag, which provides Flex Builder with hints on what data is accepted by the property. Adding both helps the developer and allows Flex Builder to provide code hinting for the possible values, but does not provide any sort of compile time or runtime type checking at this time. Example 9-4 is updated to make use of enumerations for the component, and Example 9-5 is the updated Main.mxml.

<?xml version="1.0" encoding="utf-8"?>
<mx:Canvas xmlns:mx="http://www.adobe.com/2006/mxml" width="100%"
backgroundColor="#f8f8f8" height="100%">
    <mx:Script>
        <![CDATA[

            public static const VIEW_MODE:String = "view";
            public static const EDIT_MODE:String = "edit";

            private var _mode:String;

            [Bindable]          [Inspectable(enumeration="{ContactDetails.VIEW_MODE},
{ContactDetails.EDIT_MODE}")]

            public function get mode():String
            {
                return _mode;
            }

            public function set mode(value:String):void
            {
                _mode = value;
            }
            ]]>
    </mx:Script>
    <!-- contents omitted for brevity -->
</mx:Canvas>

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" initialize="init()"
xmlns:pf3="com.oreilly.programmingflex.contactmanager.views.*">
    <pf3:ContactDetails mode="{ContactDetails.VIEW_MODE}"/>
</mx:Application>

So far in this section, we covered using properties to pass and retrieve values with a component. You also can use a property to pass an instance of an object with which you would like the component to communicate. For example, you could pass an instance of the root application to a component and have the component call methods directly on the root application. At first, this may seem like an appropriate method of communicating from child to parent, but it actually results in a tight coupling between the child and the passed object. This is not an absolute rule, but later in this chapter we will discuss how to use events to communicate with other objects. Although this requires more work, it will typically be the more appropriate method of communicating from a component as it helps promote loose coupling and reusability.

In the same way you declare a property, you can declare a component method within part of a component. Although you do not have to add any methods with the ContactDetails component, Example 9-6 shows how you would add a clear() method.

<?xml version="1.0" encoding="utf-8"?>
<mx:Canvas xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Script>
        <![CDATA[
           public function clear():void
           {
               address.text = null;
               phone.text = null;
               email.text = null;
           }
        ]]>
    </mx:Script>
</mx:Canvas>

This method clears the text within the input components. Once you’ve defined a method with a proper accessor keyword, you can call the new method from the parent, as shown in Example 9-7.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" initialize=
"initializeHandler()" xmlns:pf3="com.oreilly.programmingflex.contactmanager.
views.*">
    <mx:Script>
        <![CDATA[
           private function initializeHandler():void
           {
               //In this example, calling clear is redundant
               contactDetails.clear();
           }
        ]]>
    </mx:Script>
    <pf3:ContactDetails id="contactDetails"/>
</mx:Application>

In Example 9-7, the composing object creates an instance of the component and calls the clear() method. The parent has no knowledge of the internal workings of the component; it only knows of the publicly accessible interface, and it trusts that the component knows how to do what it needs to do. This further helps to decouple the parent and child relationship between components built in an application.

When creating an MXML component, you will typically be composing other objects within the component, as you did in the ContactDetails component. These child components dispatch their own events, and the application will be interested in some of the events or a custom event that is specific to ContactDetails. Because the children reside within the component, their events won’t be seen by the world outside the component. Actually, you wouldn’t even want them to be seen. Doing so would allow any internal component to dispatch any event, and you would have no control over what events your component dispatches.

For this reason, and to be able to define custom events that do not depend on existing events, you will need to define your own events for your component. In the ContactDetails component, one event that would be useful to define is when a user clicks on the edit button. Although a lot can happen within the component, you are only interested in knowing when a user has changed the data or maybe when the user is about to change the data (in edit mode). For this reason, it would be ideal for this component to have an EditChange event, with a description of “begin” and “end,” depending on whether the user has begun or finished editing the component.

All components in the Flex framework inherit from EventDispatcher, a class that implements the capability of an object to subscribe to and receive event notification. To add an event to a custom component, you need to define and dispatch the event.

To define an event, you first need to declare the event. You declare events using a metadata tag, and in MXML you do that using the <mx:Metadata/> tag, as shown in Example 9-8.

<?xml version="1.0" encoding="utf-8"?>
<mx:Canvas xmlns:mx="http://www.adobe.com/2006/mxml" width="100%" backgroundColor=
"#f8f8f8" height="100%">
    <mx:Metadata>
       [Event(name="editChange", type="com.oreilly.programmingflex.contactmanager.
events.EditChangeEvent")]
    </mx:Metadata>
    <!-- contents omitted for brevity -->
</mx:Canvas>

In Example 9-8, we added an event called editChange and the type EditChangeEvent. EditChangeEvent is the object type passed to the handler function when an event occurs. You could have used a generic event class here, but it is a good idea to create your own events for components. Doing so will allow you to provide added functionality that is specific to your component.

Let’s create the EditChangeEvent class in the com.oreilly.programmingflex.contactmanager.events package. It's a good practice as usual to specify a package for a class and for events, and to place all events in an events package. This is consistent with the Flex framework and allows users to import a single package that will contain all events. Here is the definition of the EditChangeEvent class:

package com.oreilly.programmingflex.contactmanager.events
{
    import flash.events.Event;

    public class EditChangeEvent extends Event
    {
        public static const EDIT_CHANGE:String = "editChange";
        public var edit:Boolean;

        public function EditChangeEvent(edit:Boolean=false)
        {
            super(EDIT_CHANGE);
            this.edit = edit;
        }

        override public function clone():Event
        {
            return new EditChangeEvent(this.edit);
        }
    }
}

With the custom event type created, now you can dispatch the new event (see Example 9-9). We will incorporate the new event into the ContactDetails component later in this chapter.

var eventEditing:EditChangeEvent = new EditChangeEvent(true);
dispatchEvent(eventEditing);