Note: This is a tutorial that I wrote for a contest at SitePoint earlier this year.  I had titled it Creating a Reusable Custom Component in Flex. After watching this session from 360Flex, I now know about there being two “levels” of reusability: loosely-coupled components and polished, fit for cataloging/distribution components. This tutorial is for the former.

---

Creating a Reusable Custom Component in Flex

by Jamie McDaniel

In this tutorial, I will guide you through the process of creating a custom Flex component. You will also learn how to pass data between the main Flex application and the custom component using best practices.

If you do not have Flex Builder, you can download a 60-day trial.  If you are a student, faculty, or staff of an eligible education institution, you can get the education version of Flex Builder 3 free by going to http://flexregistration.com.

The component we will be creating is a slideshow navigation bar.  The navigation bar will include buttons for previous, next, play/pause, full screen on/off, and sound on/off.  We will start by using the default buttons in Flex, and then proceed to style them using more recognizable graphics.

Open Flex Builder and click File -> New -> Flex Project. I am giving this project the name of SitePointTutorial.

When you click Finish, Flex Builder will create folders for your project. In the src folder you will find the main application file called SitePointTutorial.mxml. Go ahead and create three additional folders inside the src folder and name them assets, components, and events.

Click File -> New -> MXML Component. Select the components folder as the parent folder and give this component a filename of SlideshowNavigationBar.  Base it on HBox and set the width to 400 and the height to 60.

In the SlideShowNavigationBar.mxml file, enter the following code:

This will create the five buttons and center them within an HBox with a rounded rectangle background. To include our new component in the main application, open up SitePointTutorial.mxml and update it so your code matches the following:

Note the xmlns:components="components.*" in the Application tag. This is because our custom component is in a folder that we named components.  Therefore we need to define a namespace that tells the compiler where to find our custom component.  All the standard components that ship with the Flex framework begin with a namespace of mx.  The mx namespace is also defined in the Application tag and it points to www.adobe.com/2006/mxml.

Our component is added to the application with the simple mxml tag:

The id property is needed to access the component with ActionScript.

To test the application, click the Debug button.

You should see the application running in your browser.

Styling the Slideshow Navigation Bar

In SlideshowNavigationBar.mxml add the following code inside the <mx:Script> tag just above the onInitialize function:

You will need to copy the graphic files from this tutorial into the assets folder of your project.

It is worth noting that we could do without the above code and set the upSkin, overSkin, and downSkin properties of each of our buttons like so:

However by associating each graphic with a class, we can swap out the icons at runtime using ActionScript. We will need to do that, for example, when the play button should show a pause graphic.

Also note that we have designated the scope of our variables as private and have prefixed their names with an underscore.  Setting variables inside a custom component as private is not required, but it is recommended as a best practice.  You can always make the variable more accessible later if needed. Prefixing private variables with an underscore is a coding practice used by many developers for readability.

We now need to update the onInitialize function so that it contains the following code:

Remove the label property on each of the five buttons so that they look like the following:

Run the application and you should see the styled navigation bar below:

Changing a Button’s Appearance on Mouseover

When the user hovers over the buttons, we would like to provide visual feedback.  One way to do that is by adjusting the alpha value.  In the onInitialize function, add the following code:

To make the buttons respond to a mouseover event, we will first need to register event handler functions for each of the five buttons.  To do so, add the following code to the onInitialize function:

Next, add these two event handler functions. The functions can appear anywhere, but I would suggest placing them after the onInitialize function.

When an event occurs, an event object gets passed to the event handler function. The event object has properties that contain information about the event. Here we have used the currentTarget property of the event object to point to the button that triggered the event.

Before we run the application, let’s set the background color in our SitePointTutorial.mxml file.

Now when you hover the mouse over the buttons, you should get a subtle visual clue.

With our slideshow navigation bar looking good, let’s move to the next step — programming our custom component to dispatch an event that contains information on which button was clicked.  Events are how components notify the application (or the larger component that they are part of) that an action has taken place.  Just as each of the five button components dispatched mouseover events that our SlideshowNavigationBar component listened for, the SlideshowNavigationBar component can be programmed to dispatch events that its parent (the application SitePointTutorial) listens for.

“Loosely Coupled” Versus “Tightly Coupled” Components

Before programming the SlideshowNavigationBar to dispatch its own custom events, let’s talk about how you could accomplish the same result without doing so. You could update the SitePointTutorial.mxml file as follows:

Here we have registered an event listener on the component btPrev inside our component mySlideshowNavigationBar.  This works, however it is not a best practice.   By doing so, you are creating what is referred to as a “tightly coupled” component.  If you were to use the slideshow navigation bar in several applications and then changed the id of the button to something else (perhaps btPrevSlide), it would break all the applications that relied on the component the next time they were compiled.

A “loosely coupled” component, on the other hand, has a well-defined interface. The internal workings of the component can change, but the interface does not. Information is passed down to the component through the setting of properties. The component passes information back up with event objects (or, in some cases, the parent reads a property of the component at a specific point in time.)

To develop a “loosely coupled” (and thus highly reusable component) you should avoid accessing the component’s own internal components.  So instead of “reaching inside” mySlideshowNavigationBar and registering an event listener on its button, we should register an event listener directly on mySlideshowNavigationBar.  But first we need to program our slideshow navigation bar component to dispatch events.

Creating a Custom Event

The base class for all event objects is the flash.events.Event class.  Subclasses such as the MouseEvent class extend the Event class to contain additional information.  You can see all the standard subclasses listed in the Flex documentation.  You can create your own subclasses of the Event class as well, which is what we will be doing now.

Click File -> New -> ActionScript Class.  Browse and select the events folder as the package. Give it a name of SlideshowNavigationBarEvent. Set the Superclass as flash.events.Event (if you click Browse, it is under Event – flash.events).

Update the code for SlideshowNavigationBarEvent.as to match the following:

In our custom event class we have defined five constants that will be used as the value for the event’s type property. We have defined the constructor to require the type property be set. The constructor also accepts two optional arguments.  All three properties are passed with the super method.  (The super method calls the constructor of the superclass, which is the Event class.)  We also overrode the clone method which is required when creating a subclass of the Event class.

To use our new custom event, add this line to SlideshowNavigationBar.mxml inside the <mx:Script> tag at the top:

Before the <mx:Script> tag, add the following:

Now in the onInitialize function in SlideshowNavigatonBar.mxml add the following:

Add this event handler function to SlideshowNavigationBar.mxml after the other functions:

Our slideshow navigation bar component will now dispatch events that its parent component can listen for.  Update the SitePointTutorial.mxml as so:

When you run the application, take a moment to mentally step through the sequence that occurs when you click the Previous button:

1. The btPrev component in the mySlideshowNavigationBar component dispatches a click event.
2. As a result of the click event, the onButtonClick event handler function gets called and creates a new event object that is an instance of SlideshowNavigationBarEvent — a custom class that we created which extends the Event class. This event object has its type property set to the string “previousClick” (defined by the constant PREVIOUS_CLICK). The event is then dispatched with the dispatchEvent method.
3. In the main application, the function onPrevClick gets called because we registered the appropriate event listener. The application then sends information to the myTextArea component by setting its htmlText property.

This pattern is one that you will use repeatedly in the development of larger Flex applications.  The main application will contain several child components that dispatch events up to the parent application, which then sets properties on other child components.

It is also important to know that custom events can contain much more information than we used in our SlideshowNavigationBarEvent. We only used the type property, which is a standard property of the Event class. We could have extended the Event class to include new variables, including complex objects.

Creating Properties for our Custom Component

There are a few things left to do to make our slideshow navigation bar complete.  A slideshow would probably be playing automatically and when the user clicks the pause button, the application would stop at the current slide and change the pause button to a play button.  To allow for that, let’s add a property to the slideshow navigation bar component called isPlaying.  Add the following code to SlideshowNavigationBar.mxml above the onInitialize function:

We are defining the public property isPlaying by using a setter method.  Using getter and setter methods are not required, but they are a best practice when creating custom components.  Here we have a private variable named _isPlaying.  When this variable changes, the icon for the btPlay button needs to change as well.  Using a setter method allows us to always run code that is associated with the property whenever the property changes.

To simulate a slideshow automatically playing, add the following line to the onInitialize function in SitePointTutorial.mxml:

Update the onPlayClick function in SitePointTutorial.mxml as so:

Now when you run the application, the dual function of the Play/Pause button will work.

I’ll leave it to you to implement the dual function of the Full Screen and Sound buttons.  You can run the finished application and view the full code.

You can learn more about creating custom components in Adobe Flex by consulting the official documentation.