Products

Technologies

A–C

D–H

I–Z

Developer services

Project centers

Developer resources

Community resources

Integration

Product documentation

Downloads

Samples

Training and books

Newsletters

Blogs

ADC program

Additional resources

Flex Quick Start: Building custom components

Table of contents

Packaging components

One way to distribute your components to other developers is as MXML or ActionScript files. You set them up in the directory structure that matches the package structure, and you compress them into an archive format such as PKZip. The consumers of your components expand that archive into their development environment and use those components in their applications. The downside to this is that they have the source code and source files for your components, and your components are uncompiled.

The alternative method of distributing components is to package your components as a SWC file or as part of a Runtime Shared Library (RSL). The benefits to doing this include ease-of-deployment, run-time efficiency and security.

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 several MXML and ActionScript files, images, and other resource files. Also, the SWF file inside a SWC file is compiled, which means that the code is obfuscated 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 by 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.

Creating SWC files

To create a SWC file with the Flex SDK, use the compc command-line 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.

When you use the compc compiler to create a SWC file, you can include any number of components. When you use components from that SWC file in your Flex applications, the mxmlc compiler includes only those components that are used by your application, and dependent classes, in the final SWF file.

To start, create a folder called QuickStartLibrary. In it, create a folder named components and place the following custom component classes in the components folder.

components/ApplicationClass.as

package components
{
    import mx.core.Application;
    import mx.events.FlexEvent;
    import mx.controls.Alert;
    
    import components.AddressFormEvent;
    import components.AddressVO;
    import flash.utils.describeType;
    
    public class ApplicationClass extends Application
    {

        // Components in MXML.
        public var addressForm:AddressForm;
        
        public function ApplicationClass()
        {
            addEventListener(FlexEvent.CREATION_COMPLETE, creationCompleteHandler);
        }
        
        //
        // Event handlers.
        //
        private function creationCompleteHandler(event:FlexEvent):void
        {
            // The custom AddressForm component dispatches a "submit" 
            // event the form is submitted. Listen for this. 
            addressForm.addEventListener(AddressFormEvent.SUBMIT, submitHandler);
        }
        
        private function submitHandler(event:AddressFormEvent):void
        {
            // Get the value object (data) from the event object
            var data:AddressVO = event.data as AddressVO;
                                    
            // Compose a string to display the contents of the value object to the user.

            var msg:String = "You submitted the following information: \r";
            
            // Use the new introspection API and E4X to get a list of the properties
            // in the data object and enumerate over them to compose the string.
            var dataProperties:XMLList = describeType(data)..variable;
            
            for each (var i:XML in dataProperties) 
            {
                var propertyName:String = i.@name;
                msg += i.@name + ": " + data[i.@name] + "\r";
            }

            // Display the contents of the address form to the user.
            Alert.show(msg, "Thank you for submitting the form!");
        }
    }
}

components/AddressFormClass.as

package components

{
    import mx.events.FlexEvent;
    import mx.controls.Button;
    import mx.controls.TextInput;
    import flash.events.MouseEvent;
    import mx.containers.Form;
    
    public class AddressFormClass extends Form
    {

        // Components in the MXML must be 
        // declared public. This is a limitation in 
        // the current version of Flex and may change
        // in the future. 
        public var submitButton:Button;
        public var nameInput:TextInput;
        public var street:TextInput;
        public var city:TextInput;
        public var state:TextInput;
        public var country:CountryComboBox;
        
        // Constructor

        public function AddressFormClass ():void
        {
            addEventListener(FlexEvent.CREATION_COMPLETE, creationCompleteHandler);
        }

        
        // Creation complete is a good time to add event listeners and 
        // interact with child components.
        private function creationCompleteHandler (event:FlexEvent):void

        {
            submitButton.addEventListener(MouseEvent.CLICK, submitHandler);
        }
        
        // Gets called when the Submit button is clicked
        private function submitHandler (event:MouseEvent):void

        {
            // Gather the data for this form
            var addressVO:AddressVO = new AddressVO();
            addressVO.name = nameInput.text;
            addressVO.street = street.text;
            addressVO.city = city.text;
            addressVO.state = state.text;
            addressVO.country = country.selectedItem as String;
                        
            var submitEvent:AddressFormEvent = new AddressFormEvent(AddressFormEvent.SUBMIT);
            submitEvent.data = addressVO;
                        
            // Dispatch an event to signal that the form has been submitted 

            dispatchEvent(submitEvent);
        }
    }
}

components/AddressForm.mxml

<?xml version="1.0" encoding="utf-8"?>
<custom:AddressFormClass 
    xmlns:mx="http://www.adobe.com/2006/mxml"
    xmlns:custom="components.*"

>
   <mx:FormItem label="Name">
        <mx:TextInput id="nameInput"/>
    </mx:FormItem>

    <mx:FormItem label="Street">
        <mx:TextInput id="street"/>
    </mx:FormItem>

    <mx:FormItem label="City"> 
        <mx:TextInput id="city"/>
    </mx:FormItem>

    <mx:FormItem label="State/County"> 
        <mx:TextInput id="state"/>
    </mx:FormItem>

    <mx:FormItem label="Country"> 
        <custom:CountryComboBox id="country"/>

    </mx:FormItem>
   
    <mx:Button 
        id="submitButton"
        label="submit"
    />
</custom:AddressFormClass>

components/AddressFormEvent.as

package components
{
    import flash.events.Event;
    import components.AddressVO;

    public class AddressFormEvent extends Event
    {

        public static const SUBMIT:String = "submit";

        private var _data:AddressVO;

        public function AddressFormEvent (eventName:String)

        {
            super (eventName);
        }
        
        public function set data (value:AddressVO):void

        {
            _data = value;
        }
        
        public function get data ():AddressVO
        {

            return _data;
        }
    }
}

components/AddressVO.as

package components
{
    public class AddressVO
    {
        // We are using public properties for the
        // value object to keep this example short. In a
        // real-world application, make these properties
        // private and use implicit accessors to expose them
        // so you can do validation, etc. if necessary. 
        public var name:String;
        public var street:String;
        public var city:String;
        public var state:String;
        public var country:String;
    }

}

components/PaddedPanel.as

package components
{
    import mx.containers.Panel;

    public class PaddedPanel extends Panel
    {

        public function PaddedPanel()
        {
            // Call the constructor of the superclass.
            super();
            
            // Give the panel a uniform 10 pixel 
            // padding on all four sides.
            setStyle ("paddingLeft", 10);
            setStyle ("paddingRight", 10);
            setStyle ("paddingTop", 10);
            setStyle ("paddingBottom", 10);
        }

    }
}

components/CountryComboBox.mxml

<?xml version="1.0" encoding="utf-8"?>
<mx:ComboBox xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:dataProvider>    
        <mx:String>United States</mx:String>
        <mx:String>United Kingdom</mx:String>
		
        <!-- Add all other countries... -->
    </mx:dataProvider>
</mx:ComboBox>

To create the SWC file, ensure that the compc compiler is in your system path (if not, add it to the PATH environment variable under your System settings). From the QuickStartLibrary folder, enter the following command:

compc -source-path+=. 
  -output=bin/QuickStartLibrary.swc 
  -include-classes components.AddressForm 
   components.AddressFormClass 
   components.AddressFormEvent 
   components.AddressVO
   components.ApplicationClass 
   components.CountryComboBox 
   components.PaddedPanel

Note: Type the preceding command on a single line. It appears here on multiple lines here for the sake of clarity.

Tip: When you use the compc compiler to create a SWC file, you can include any number of components by using namespaces or a manifest file. This can keep the command line command from becoming long and unwieldly. For more information about using namespaces and manifest files, see Creating and Extending Adobe Flex 3 Components.

The source-path option includes the current directory in the source path. This is how compc finds the various classes that are listed in the include-classes option.

The output option specifies the output location of the SWC file. In this case, compc writes the QuickStartLibrary.swc file to a folder named bin.

The include-classes option specifies the classes that you want to include in the SWC file. These are the classes you just defined.

Tip: You can also create SWC files by creating a Flex Library Project in Adobe® Flex™ Builder™ 3. For more information, see Using Flex Builder 3.

Deploying SWC files

You use SWC files when compiling MXML files. You typically specify in the library-path option which SWC files the application uses.

The following example uses the AddressForm component from the QuickStartLibrary.swc that you created in the "Creating SWC Files" section.

Example

<?xml version="1.0" encoding="utf-8"?>
<custom:ApplicationClass 
    xmlns:mx="http://www.adobe.com/2006/mxml"
    xmlns:custom="components.*"
    width="400" height="310"
>
    <custom:PaddedPanel title="Creating Libraries">
        <custom:AddressForm id="addressForm"/>
    </custom:PaddedPanel>
</custom:ApplicationClass>

To compile this example using the stand-alone Flex compiler, enter the following command, substituting the location of the QuickStartLibrary.swc file on your system. In this example, the library is in the ../QuickStartLibrary/bin directory.

mxmlc -library-path+=.;../QuickStartLibrary/bin Main.mxml

Because all SWC files in the flex_install_dir/libs directory are added to the compiler's library path by default, you could just put the QuickStartLibrary.swc file in that directory and compile an application that uses those classes.

Result

This content requires Flash

Download the free Flash Player now!

You can download the library SWC file here.

Tip: You can also add SWC files to your Flex Builder projects. To add your SWC file, select Project > Properties > Flex Build Path. On the Library tab, click the Add SWC button and add the QuickStartLibrary to your project. The following image shows the QuickStartLibrary.swc file in the project's library path.

For more information

Compiling components with Flex SDK in the Adobe Flex 3 Help
Using compc, the component compiler in the Adobe Flex 3 Help

About the author

Aral Balkan acts and sings, leads development teams, designs user experiences, architects rich Internet applications, and runs OSFlash.org, the London Macromedia User Group, and his company, Ariaware. He loves talking design patterns and writing for books and magazines. He also authored Arp, the open-source RIA framework for the Flash platform. Aral is generally quite opinionated, animated, and passionate. He loves to smile, and can even chew gum and walk at the same time.

A–C

D–H

I–Z