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.

Here is how I added Cairngorm to my skill-set (after first gaining enough Flex experience to understand why you would use an architectural framework).

David Tucker’s 5-Part Series

David’s excellent articles and accompanying videos are what I would highly recommend starting with.

• Getting Started with Cairngorm - Part 1
• Getting Started with Cairngorm - Part 2
• Getting Started with Cairngorm - Part 3
• Getting Started with Cairngorm - Part 4
• Getting Started with Cairngorm - Part 5

CairngormStore Example

Or rather Douglas McCarroll’s update of Chen Bekor’s ModifiedCairngormStore.  Douglas updated it for Cairngorm 2.2.1 and Flex 3.

10 Tips for Working with Cairngorm

Jesse Warden’s 10 Tips for Working with Cairngorm.  Tip #10 about not having nested views dispatch CairngormEvents (but rather dispatch regular events — or your own custom events that extend the event class — to the main view which would then dispatch a CairngormEvent) is a best practice to keep in mind when studying the CairngormStore example.

Adobe Consulting’s 6-Part Article

Steven Webster and Leon Tanner of Adobe Consulting wrote Developing Flex RIAs with Cairngorm microarchitecture. The article has a lot of really good information in it and uses the CairngormStore as an example (although you will want to get the updated CairngormStore from the link above).

Here are some nuggets I gleaned from the articles:

Nugget #1

…resist the opportunity to scatter state all over your application as strings, numbers, Booleans, and all manner of other primitive objects. …we strongly advocate that the client hold the data — as state, model, or whatever you want to call it — as objects that have semantic meaning.

Source: part 2, page 4

The use of value objects (or data transfer objects) was brought up in other places and is not specific to Cairngorm.  Still, it is good stuff that bears repeating.

Nugget #2

When you create components that rely upon client-side data, it is all too easy to create a direct reference to a Singleton model, such as ShopModelLocator. Indeed this is true throughout the application. We discourage this approach. Instead, consider passing the model and/or its properties down through a hierarchy of your view components, for a cleaner and more thoughtful solution.

Source: part 2, page 7

The goal is to make components more reusable. If you have components importing the modelLocator, using the getInstance method, and then binding directly to data in the Cairngorm modelLocator instance, then those components are coupled to your project and/or the Cairngorm framework.

The argument behind not using CairngormEvents other than in your main view (Jesse Warden’s tip #10 from above) is the same reasoning here — reusablity and loosely coupled components.  Ideally your components could be used outside of the Cairngorm framework.

The CairngormStore example follows this in some places, but not in others. In Main.mxml, for instance, a ProductVO is “injected” into the selectedItem attribute of the <details:ProductDetails> component. However other components, such as ProductsAndCheckoutViewStack.mxml, import the ModelLocator and use ShopModelLocator.getInstance().

Regarding the CairngormStore and best practices, Alistair McLeod states in a comment on his blog that “…you make a good point with CairngormStore - looking at the application now, it definitely does not advertise our best practices of building applications with Cairngorm, and that’s something else we want to rectify…”

I am still trying to fully understand best practices regarding reusability. There is a critique of Cairngorm (or rather a certain use of the Model Locator pattern) here where the author mentions some of this. Another blog post on Cairgorm with some discussion about the Model Locator and coupling components to it is here.

(And just when I thought I was beginning to understand reusability, I saw this session from 360Flex about there being two “levels” of reusability — loosely-coupled components and polished, fit for cataloging/distribution components. The gist being that a truly reusable component takes a lot more time to do and involves such things as allowing css styling and programming default behaviors.)

Nugget #3

Developers should always seek to extract these classes from the Cairngorm architecture. Pulling business logic out of commands and encapsulating into classes is a classic implementation of Extract class refactoring.

Source: part 4, page 5

This is in reference to the AddProductToShoppingCartCommand in CairngormStore. The execute function of this command class just calls a function on shoppingCart stored in the model locator.

Rather than have a lot of complex business logic associated with shopping cart behavior in the AddProductToShoppingCartCommand class, such business logic is encapsulated in a ShoppingCart class (which, in the CairngormStore example, was stored in the model folder.)

Nugget #4

…you and your team will approach the addition of each and every feature to a Cairngorm application in the same way. In short, you will add an event to the controller, register it with a Command class, and implement the Command class to do all the work. With this approach you can drive the development of your application with feature after feature, in a consistent, predictable manner that scales well.

Source: part 4, page 6

This is a good review of the flow in Cairngorm and the benefits of using an architectural framework.

One of my main Flex projects is a content management system.  It is continually being developed and is in production as my employer’s backend.  I hope to make it an even more usable CMS solution by making it where it can be deployed for other websites.

With that future goal in mind, I needed to revisit my services-config.xml file.  I use AMFPHP and had previously hardcoded the endpoint.  We use SSL because the backend is used for more than just editing web pages.  So for it to work on another site, I would needed to edit the services-config.xml file and recompile.

I did a google search on services-config secure and found this page which was very helpful. This page was also an interesting read. Before reading these, I did not know you could use the tokens {server.name} and {server.port} in your services-config.xml file.

Here is my new services-config.xml file that will use SSL if the page is using SSL and regular HTTP if it is not.  I verified it was indeed using SSL with Charles.

The only problem with this solution is that when on an http page, the swf will try to access crossdomain.xml via https. On Firefox and IE this silently fails. However on Safari (version 3.1.1 as of this writing) this causes the browser to stall indefinitely if you do not have a signed certificate.

Safari will not prompt you to accept the certificate, nor will it silently fail like the other browsers. Since my application is the backend for a CMS, I just went to the homepage via https and accepted the certificate permanently. However, that would not be a good solution for a public application.

Last month, Dice had a programming contest with a prize of $4,000.  My entry, using Flex, was selected as one of the ten finalists.  Go check out the 10 mashups and if you think mine is the best vote for Buried Treasure. Thank you!!  Here is the link to place your vote. Voting lasts until May 31.

Also, I had a previous blog post on the challenges I ran into while creating my entry. If you are trying to put a Google Map inside a Flex application AND need Flex content to appear over the map, you’ll find it helpful.

Update: I placed third.  The voting results are posted here.  I was quite surprised at the vote.  I thought I would finish first or second and the maps application I thought would probably win ended up placing next to last.  I think that is the last of the contests for me.  Only paying clients going forward. 

SitePoint puts outs free newsletters that I subscribe to.  I was glad to see AIR mentioned in a recent issue of their Tech Times. The email concluded with “You’ll certainly be seeing plenty more about Adobe AIR on SitePoint in the coming months.”  That is exciting news because generally I have gone to SitePoint for PHP, MySQL, and web hosting information but elsewhere for all things Flash.

When I went to SitePoint a few days ago, I saw that they also had two contests going - one for the best Flex article and the second for the best AIR article.  I spent last weekend creating my entry for the Flex contest.  Wish me luck!

Update: I was runner-up and got a PDF book.  See here.

I received an email on Friday, March 27 about the Dice Programming Challenge.  (My inbox shows that I received the same email on the 19th, but I must have missed it.)  Anyway, the email stated “Show off your web-based application skills! Build a Google Maps mashup and you could win $4,000.”  I had used the Yahoo! maps Flash component before, but I had never used Google Maps in an application.  The contest deadline was March 31.  On Saturday morning, I decided to put my whole weekend into creating an entry for the contest using Flex.

I first read about Google’s searchmash site in a blog post at RIApedia. I had used an iframe before inside of a Flex application, but what I was really impressed with was how Google got Flex content to appear on top of their maps (notice the More combobox at the top and the Recent Searches slideout on the left.)  Previously I had always had to hide the iframe when showing an alert or popup window.

I used Firebug to peak at what they were doing.  For starters, they were using wmode = transparent. But the real trick was they were changing the z-index of the iframe from 300 to 100 whenever the Flex content needed to appear on top of the map. The flash stays at a z-index of 200, and as you know, containers with the higher z-index appear on top of containers with a lower z-index.

With that knowledge, I put together this application.

The contest finalists won’t be announced until a few weeks and then dice members get to vote for the winner.

I had to overcome a few challenges in the three days I had to get my entry finished, so I thought I would document them here.

The first problem was my Flex application could not get the Geocoding data from Google using an HTTPService.  The problem was that Google did not have the necessary crossdomain.xml file in place. I found a solution on the web - use PHP to create a proxy on your server with curl. Then specify the url of the HTTPService as the proxy php file. The proxy just passes the XML from Google to the flash file.

Another obstacle was that Internet Explorer 7 (running under Parallels) would, about half the time, not show the Google map in the iframe.  Firefox 3 would display it fine every time. What was going on?  I had used this component for handling the iframe. You specify the url for the iframe in Flex and it passes it to the wrapper.  Apparently, that was a problem for how I had used Google maps.  When I hardcoded the url for the iframe in the wrapper, the problem in IE7 went away. With a deadline fast approaching, I didn’t dig too deep to find a more robust solution.

With just a few hours before midnight on March 31, I tested the application in Firefox 2 on Windows. And that is when a huge bug surfaced. The Flex application in Firefox on Windows would not respond to any mouse click that appeared over the iframe! A user could not get past the introductory popup message.

After doing several searches, I found a blog post that mentioned the issue. They had discovered that their flash movie does actually respond to the mouse click, but that the hit area is way off.  Sure enough, when I clicked about 50 pixels south of the button, it responded.

The solution that worked for me evolved from this comment. I created a secondary iframe with a width and height of 100%, a position of absolute, and a z-index of 101.

Update 5/15/2008: Good news! The need for all this iframe z-index trickery is obsolete now.  Google just released their Google Maps API for Flash.