Creating custom components

You create custom components as either MXML or ActionScript files.

Creating MXML components

Flex supplies the Spark ComboBox control that you can use as part of a form that collects address information from a customer. In the form, you can include a ComboBox control to let the user select the state portion of the address from a list of the 50 states in the U.S. In an application that has multiple forms where a user can enter an address, it would be tedious to create and initialize multiple ComboBox controls with the same information about all 50 states.

Instead, you create an MXML component that contains a ComboBox control with all the 50 states defined within in it. Then, wherever you need to add a state selector to your application, you use your custom MXML component. The following example shows a possible definition for a custom ComboBox control:

<?xml version="1.0"?>
<!-- createcomps_intro\StateComboBox.mxml -->
<!-- Specify the root tag and namespace. -->
<s:ComboBox xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx">
    <s:dataProvider>   
        <s:ArrayList>
            <fx:String>AK</fx:String>
            <fx:String>AL</fx:String>
            <!-- Add all other states. -->
        </s:ArrayList>
    </s:dataProvider>
</s:ComboBox>

This example shows the following:

  1. The first line of the custom MXML component definition specifies the declaration of the XML version.

  2. The first MXML tag of the component, called its root tag, specifies a Flex component or a custom component. MXML components correspond to ActionScript classes, therefore, the root tag specifies the superclass of the MXML component. In this example, the MXML component specifies the Flex ComboBox control as its superclass.

  3. The xmlns properties in the root tag specifies the Flex XML namespaces. In this example, the xmlns property indicates that tags in the MX namespace use the prefix mx:.

  4. The remaining lines of the component specify its definition.

The main application, or any other MXML component file, references the StateComboBox component, as the following example shows:

<?xml version="1.0"?>
<!-- createcomps_intro/IntroMyApplication.mxml -->
<!-- Include the namespace definition for your custom components. -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"
    xmlns:MyComp="*">

    <!-- Use the filename as the MXML tag name. -->
    <MyComp:StateComboBox/>
</s:Application>

The executing SWF file for the previous example is shown below:

The MXML tag name for a custom component is composed of two parts: the namespace prefix, in this case MyComp, and the tag name. The namespace prefix tells Flex where to look for the file that implements the custom component. The tag name corresponds to the filename of the component, in this case StateComboBox.mxml. Therefore, a file named StateComboBox.mxml defines a component with the tag name of <namespace:StateComboBox>.

As part of the <s:Application> tag, the main application file includes the following namespace definition: xmlns:MyComp="*". This definition specifies that the component is in the same directory as the main application file, or in a directory included in the ActionScript source path. For more information on deploying MXML components, see Simple MXML components.

The best practice is to put your custom components in a subdirectory of your application. That practice helps to ensure that you do not have duplicate component names because they have a different namespace. If you stored your component in the myComponents subdirectory of your application, you would specify the namespace definition as xmlns:MyComp="myComponents.*".

The StateComboBox.mxml file specifies the ComboBox control as its root tag, so you can reference all of the properties of the ComboBox control in the MXML tag of your custom component, or in the ActionScript specified in an <fx:Script> tag. For example, the following example specifies the ComboBox.maxChars property and a listener for the ComboBox.close event for your custom control:

<?xml version="1.0"?>
<!-- createcomps_intro/MyApplicationProperties.mxml -->
<s:Application  xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"
    xmlns:MyComp="myComponents.*">
 
    <fx:Script>
        <![CDATA[
            import flash.events.Event;

            private function handleCloseEvent(eventObj:Event):void {
                // ...
            }
        ]]>
    </fx:Script>

    <MyComp:StateComboBox maxChars="25" 
        close="handleCloseEvent(event);"/>
</s:Application>

The executing SWF file for the previous example is shown below:

For more information on MXML components, see Simple MXML components.

Creating ActionScript components

You create ActionScript components by defining ActionScript classes. You can create the following types of components in ActionScript:

User-interface, or visual, components
User-interface components contain both processing logic and visual elements. You create custom user-interface components to modify existing behavior or add new functionality to the component. These components usually extend the Flex component hierarchy. You can extend from the UIComponent class, or any of the Flex components, such as Button, ComboBox, or DataGrid. Your custom ActionScript component inherits all of the methods, properties, events, styles, and effects of its superclass.

Nonvisual components
Nonvisual components define nonvisual elements. Flex includes several types of nonvisual components that you can create, including formatters, validators, and effects. You create nonvisual components by creating a subclass from the Flex component hierarchy. For validators, you create subclasses of the Validator class; for formatters you create subclasses of the Formatter class; and for effects, you create subclasses of the Effect class.

For example, you can define a custom button component based on the Spark Button class, as the following example shows:

package myComponents
{
    // createcomps_intro/myComponents/MyButton.as
    import spark.components.Button;

    public class MyButton extends Button {
    
        // Define the constructor. 
        public function MyButton() {
            // Call the constructor in the superclass. 
            super();
            // Set the label property to "Submit".
            label="Submit";
        }
    }
}

In this example, you write your MyButton class to the MyButton.as file.

You must define your custom components within an ActionScript package. The package reflects the directory location of your component in the directory structure of your application. Typically, you put custom ActionScript components in directories that are in the ActionScript source path, subdirectories of your application, or for Adobe® LiveCycle™ Data Services ES, in the WEB-INF/flex/user_classes directory. In this example, the package statement specifies that the MyButton.as file is in the myComponents subdirectory of your Flex application.

In the MXML file that references the custom component, you define the namespace and reference it in an MXML file as the following example shows:

<?xml version="1.0"?>
<!-- createcomps_intro/MyApplicationASComponent.mxml -->
<!-- Include the namespace definition for your custom components. -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:MyComp="myComponents.*">

    <!-- Use the filename as the MXML tag name. -->
    <MyComp:MyButton/>

</s:Application>

The executing SWF file for the previous example is shown below:

In this example, you first define the MyComp namespace that specifies the location of your custom component in the application’s directory structure. You then reference the component as an MXML tag using the namespace prefix.

For more information, see Create simple visual components in ActionScript.

Deploying components

When you deploy your custom components as MXML or ActionScript files, you typically deploy them in the same directory structure as your application files, in a directory specified in the ActionScript source path, or for LiveCycle Data Services ES, in the WEB-INF/flex/user_classes directory.

For security reasons, you may decide not to deploy your custom components as source code files. Alternatively, you can deploy your components as SWC files or as part of a Runtime Shared Library (RSL).

A SWC file is an archive file for Flex components. SWC files make it easy to exchange components among Flex developers. You need only exchange a single file, rather than the MXML or ActionScript files and images and other resource files. In addition, the SWF file inside a SWC file is compiled, which means that the code is hidden from casual view.

SWC files can contain one or more components and are packaged and expanded with the PKZip archive format. You can open and examine a SWC file using WinZip, JAR, or another archiving tool. However, you should not manually change the contents of a SWC file, and you should not try to run the SWF file that is in a SWC file outside of a SWC file.

To create a SWC file, use the compc utility in the flex_install_dir/bin directory. The compc utility generates a SWC file from MXML component source files and/or ActionScript component source files. For more information on compc, see Flex compilers.

One way to reduce the size of your application’s SWF file is by externalizing shared assets into stand-alone files that can be separately downloaded and cached on the client. These shared assets are loaded by any number of applications at run time, but only need to be transferred to the client once. These shared files are known as Runtime Shared Libraries or RSLs.

For more information, including information on how to create an RSL file, see Runtime Shared Libraries.