I’ve recently completed my first Flex application, and am using this blog to write about my learning experience, and also to describe some of the concepts behind the application that make it work. Actually, these are two applications that work together, vRadio and RadioLoginDB.

These applications illustrate how to use Flex to create a master-detail application that accesses data from a PHP server, and also incorporates PHP sessions.

At the end of this posting is a list of documentation sources I used to learn how to create the applications. I also have links to the source files.

vRadio and RadioLoginDB applications

vRadio is a Master-Detail application, and corresponds to many type of applications that present stored data in a variety of presentation formats, and also provide forms for updating the data.

What is interesting about the the vRadio application is the way Flex handles XML data using the E4X format. By providing an XML feed into the vRadio application, the application displays the XML data in a tree view. When the user clicks a node in the tree, details are displayed.

This question led to an interesting thread that revealed a couple of alternatives to fading text without embedding the font. The result is that the SWF file size is smaller because it doesn't contain any font symbols.

First, here's code that embeds a font and defines a fadeIn and fadeOut effect:

[Embed("assets/MyriadWebPro.ttf", fontName="MyMyriad")]

public var myriad_font:Class;

...

<mx:Fade id="fadeOut" duration="1000" alphaFrom="1.0" alphaTo="0.0"/>

<mx:Fade id="fadeIn" duration="1000" alphaFrom="0.0" alphaTo="1.0"/>


<mx:Label id="label1" text="Hello World"  

            fontFamily="MyMyriad" fontSize="24"

            hideEffect="{fadeOut}" showEffect="{fadeIn}"/>

This app is 190K. It works very well because the Fade effect is applied directly to the control that uses an embedded font to render the text.

If you didn't embed the font, then the Fade effect would appear to fail: instead of a slow fade, you'd get a single instant where the text disappears. Non-embedded fonts don't include bitmap information for the Player to apply a Fade effect to.

Here's a running example that shows the failing fade on non-embedded text:

Now for the alternatives.

The first alternative is really clever: Apply the BlurFilter to the text before attempting to fade it in and out. When you apply a BlurFilter to text, Flash Player converts the text to a bitmap. Once the text is a bitmap, it can be faded in and out with the Fade effect. So instead of actually blurring the text with the BlurFilter, you just apply the BlurFilter with some dummy settings (0,0,0), and then you can fade the text with the Fade effect.

Here's the code that applies a BlurFilter to the text when the app initializes:

  private function addBlurFilter():void {

  var bf:BlurFilter = new BlurFilter(0,0,0);

  var myFilters:Array = new Array();

  myFilters.push(bf);

  label3.filters = myFilters;

}

When you toggle the checkbox, the Fade effect now appears to work seamlessly. Here's the running example:

The SWF file size is 165K. Adding the BlurFilter does not increase the SWF file size because you don't have to embed the font symbols. It might increase runtime memory usage because Flash Player now has to keep bitmap data in memory for that text, but it's still a damn clever trick, I think.

The second alternative is to use the Dissolve effect rather than the Fade effect. The Dissolve effect actually creates a rectangle over the target area, and applies a dissolve to the rectangle so that the underlying content appears to fade in and out.

Dissolve effects are set up and applied just like Fade effects:

<mx:Dissolve id="dissolveOut" duration="1000" alphaFrom="1.0" alphaTo="0.0"/>

<mx:Dissolve id="dissolveIn" duration="1000" alphaFrom="0.0" alphaTo="1.0"/>


<mx:Label id="label4" text="Hello World" fontSize="24" 

     hideEffect="{dissolveOut}" showEffect="{dissolveIn}"/>

As with the Blur effect, using the Dissolve effect does not increase the SWF file size because you don't have to embed the font symbols.

This ZIP file (2KB) contains the complete source MXML files for the three working examples in this blog entry.

Currently, the "Ion" project consists of a customized search engine that is populated with the best of the Flex-related resources on the web. You can access this new search feature directly at http://community.adobe.com/ion/. You can also search it by using the "Community-Powered Search" input on the Flex DevNet site.

Also part of Ion is the back end for commenting on Livedocs and DevNet articles. Prior to this, there was no commenting on DevNet articles, and the Livedocs commenting engine was much more restrictive.

This is just the beginning of the Ion project.

To extract the data visualization source code, you use the DMV-source.jar file. This file is located in the SDK's lib directory. If you are using Flex Builder, the lib directory is located at {Flex Builder 3}\sdks\3.0.0\lib.

The syntax to extract the data visualization source code is as follows:

> java -jar DMV-source.jar {license-file-location} {output-location}

The first argument is the location of the license.properties file. This file must contain a valid Flex Builder 3 Professional license key. The second parameter is the location that you want the data visualization source code to be extracted to.

If you installed Flex Builder 3 Professional, then the license.properties file is located at the following locations, depending on your operating system:

• Windows: C:\Documents and Settings\All Users\Application Data\Adobe\Flex\
• Mac OS: /Library/Application Support/Adobe/Flex/
• Linux: ~/.adobe/Flex/

The following example extracts the data visualization source code to the c:\temp\dataviz_source directory on Windows:

java -jar c:\Flex Builder 3\sdks\3.0.0\lib\DMV-source.jar 
     "C:\Documents and Settings\All Users\Application Data\Adobe\Flex\" 
     c:\temp\dataviz_source

If you have a valid Flex Builder 3 Professional license key but did not install Flex Builder, then you can create a license.properties file anywhere, and point to it when you use the DMV-source.jar file. The syntax of the license.properties file is as follows:

flexbuilder3={license_key}

The benefit to this is that if you have a wiki or blog that you can edit via a browser, you can build and update a data page without having to hit a database. The code extracts specially-tagged data from the HTML page, so even if it's part of a larger block of HTML, you can still extract just the data.

One thing to note: The target domain in this example works because it has a crossdomain.xml file. If you want to load a page from your own target domain, you must be sure that your target domain has a crossdomain.xml file in place, and that that policy file lets the domain on which the Flex app is running request data from it.

Here's the running example:

Here's the data page that drives this chart:
http://examples.adobe.com/flex3/exchangingdata/html/dataPage.html

You can download the source MXML file here:
HTMLDataProvider.zip (1KB)

The exact location of the data page is passed into the application as a flashVars property. To change the data page, you only have to edit the HTML wrapper for the SWF file.

In the HTML wrapper, we pass the target HTML page as a param in the <object> tag:

<param name="flashVars" value="dataPage=http://examples.adobe.com/flex3/exchangingdata/html/dataPage.html" />

flashVars="dataPage=http://www.shallowpondestates.com/misc/dataPage.html"

In the Flex app, the data page is read from the Application's application.parameters property:

dataPage = Application.application.parameters.dataPage;

<mx:HTTPService id="serviceInput" 

        resultFormat="text" 

        url="{dataPage}"

    />

var htmlBlob:String = serviceInput.lastResult.toString();

htmlBlob = htmlBlob.slice( htmlBlob.indexOf("<!-- data starts here -->", 0) + 25, htmlBlob.length );

htmlBlob = htmlBlob.slice( 0, htmlBlob.indexOf("<!-- data ends here -->", 0) );

var tagPattern:RegExp = /<[^<>]*>/g;  

htmlBlob = htmlBlob.replace(tagPattern, "");

			

var ltPattern:RegExp = /&lt;/g;

htmlBlob = htmlBlob.replace(ltPattern, "<");

			

var gtPattern:RegExp = /&gt;/g;

htmlBlob = htmlBlob.replace(gtPattern, ">");

chartData = new XMLList(htmlBlob);

Download the PDF: Building and Deploying LiveCycle Data Services ES Applications

The good news is that our web team has identified the bug that causes this. The bad news is that they're still testing the fix and it won't get rolled out until April 17.

I've had fairly random results over the last few days. Sometimes changing browsers helps, sometimes it doesn't; sometimes clearing browser cache fixes it, sometimes it doesn't. One suggestion is to download the complete Flex doc zip file, which contains usage docs in PDF and the Language Reference in HTML and access the docs locally.
This is available at http://livedocs.adobe.com/flex/3/flex3_documentation.zip. Individual PDFs are available from the Flex Help Resource Center page: http://www.adobe.com/support/documentation/en/flex/

I sincerely apologize for the inconvenience this is causing.
Randy Nielsen
Flex Documentation Manager

To install the Java development tools in the standalone version of Flex Builder:

1. Use the Help > Software Updates > Find and Install menu command to open the Install/Update dialog box

2. Select Search for new features to install.

3. Click Next.

4. In the results, choose Europa Discovery Site.

5. Click Finish.

6. Select the Java Development package to install.

7. Click Next.

8. Accept the license.

9. Click Finish.

Note: You might be prompted to install additional plugins required by the Java Development package.

To change perspective:

1. Use the Window > Perspective > Other to access all perspectives.

You can also click the Open Perspective button in the upper-right corner of the workbench window, then select a perspective from the pop-up menu.

2. Select Java from the list of perspectives.

The version of the chapter that was released with ColdFusion 8 was not updated correctly at that time, so it is not appropriate to use when integrating either Flex 2 or Flex 3 with ColdFusion 8. The updated chapter is (we believe) correct, and covers Flex Builder 2 and Flex Builder 3.

Download UseFlashRemotingUpdate_Blog.pdf

For example, you create a custom component named MyAirComboBox that extends the AIR mx.controls.FileSystemComboBox component. The directory location of your custom component file is:

C:\myApplication\myComponents\MyAirComboBox.as

Use the following ASDoc command to generate API reference documentation for MyAirComboBox:

..\bin\asdoc -doc-sources C:\myApplication\myComponents\MyAirComboBox.as -library-path+=..\frameworks\libs\air -main-title "My AIR API Documentation" -window-title "My AIR API Documentation" -output air-asdoc

This command assumes the following:

• You run the command from the directory C:\Program Files\Adobe\Flex Builder 3\sdks\3.0.0\asdoc in your Flex Builder installation directory structure. If you are using the Flex SDK, or have installed Flex Builder on another operating system, modify the paths in this command as necessary.
• The AIR SWC files are installed in the directory C:\Program Files\Adobe\Flex Builder 3\sdks\3.0.0\frameworks\libs\air. This is the default directory location for a Flex Builder installation.

  This command uses the library-path option to the ASDoc tool to specify the directory location of the AIR SWC files. The"+=" operator to the -library-path option specifies to append the AIR SWC files to the Flex SWC files.

• The ASDoc tool writes the output to the directory C:\Program Files\Adobe\Flex Builder 3\sdks\3.0.0\asdoc\air-asdoc.
  

If you have created multiple AIR components, you can use the following ASDoc command to generate documentation for an entire package:

..\bin\asdoc -doc-sources C:\myApplication\myComponents -library-path+=..\frameworks\libs\air -main-title "My AIR API Documentation" -window-title "My AIR API Documentation" -output air-asdoc

See the Flex 3 documentation for more information on the ASDoc tool.

This time around, however, the APIs have already been through the scrubbing and many of the issues have been ironed out. Most of the migration duties you'll encounter will be related to updated features, like:

Localization -- The l10n system has changed alot (for the better!). It's now much simpler to implement, and it supports runtime locale-switching. You can use the same properties files, but you might have to rewrite the way they are accessed. Check out the localization doc.

Style properties -- A number of style properties have changed to support the new subcomponent style feature.

Deep linking -- This is a new feature, but if you were using the HistoryManager class, you really should switch to using the BrowserManager class to do all your browser/Flex app communication.

Compiler and configuration args -- A few compiler arguments have changed. If you use config file or ant tasks to do your compilation, you might have to modify your files.

Here are some resources that should help with migration issues:

• Deprecated elements in the Language Reference -- A list of all the class elements that are now deprecated. The compiler will also warn you about these when you try to compile, but you can get a sense of what has changed from this list.
• Backwards compatibility -- This includes a list of differences between the configuration files for SDK 2.0.1 and SDK 3, as well as a list of the changes to the framework.


• Understanding Flex 3 Migration Issues on Joan Lafferty's blog: Part 1 and Part 2

• The Flex 3 Getting Started Experience - With Flex 2 and 2.0.1, we had a lot of negative feedback from Flex newbies.My manager, in her infinite wisdom, gave us a lot of support in hiring Inquirium (an instructional design firm) to interview Flex developers, figure out their common patterns/problems, and create a new getting started roadmap. Some hurdles we knew about (understanding that Flex access data indirectly through a server), but others were a surprise (a lot of people got caught up with asynchronous events). We then hired Trilemetry (big thanks to Emily, Annette, and Bob) to "realize" the Getting Started Experience. This turned out to be bigger than we thought, but I think it works really well, and the Beta feedback has been extremely positive.
• Revised table of contents (TOC) architecture for Flex Builder online Help and LiveDocs - In our work with Inquirium, it became clear that viewers weren't thinking about "books" in the online doc experience. The revised TOC feels more navigable and I think it makes it easier to find stuff. Please check it out and let me know what you think. Note that we only did this for the core Flex books, so Flex Builder, Data Visualization, AIR, and ActionScript are still presented as books. Also note that material is still available as books through the Flex Help Resource Center.

OK. I lied. Two more things:

• Obviously, I'm focusing on Flex, but AIR went live today, too, and this is a significant milestone for Adobe. For Flex developers, it's pretty simple: Any app you write for the browser should just run in the AIR runtime (and the Flex 3 LiveDocs include Developing AIR Applications with Flex). You can also take advantage of the extended functionality inherent in a desktop application and I recommend scanning the discussions of windows, menus, taskbars, files, data, HTML content and Rich media content. In particular, I think the drag & drop and local SQL database discussions are cool.
• Please use the public bugbase to report problems with the Flex 3 documentation. You can also search the bugbase to see if anyone else has already reported an issue.

Thanks everybody for your feedback during the Flex 3 Beta cycle. You made a difference.

On to Flex 4!

When enabled, information regarding message size, server processing time, and network travel time is available to the client that pushed a message to the server, to a client that received a pushed message from the server, or to a client that received an acknowledge message from the server in response a pushed message. A subset of this information is also available for access on the server.

Download the new chapter's PDF: Measuring Message Processing Performance

Downloads

The API's JavaDocs are here: flex_compiler_api.zip (245K)

There is a PDF which describes usage here: Compiler API Guide (194K)