Integrating Flex into Ajax applications ...

    Traditional Asynchronous JavaScript + XML (Ajax) development continues to be the leading method for producing rich Internet applications (RIAs). However, the popularity of Adobe® Flex cannot be ignored. This article introduces the Adobe Flex Ajax Bridge (FABridge), a code library that enables an easy and consistent method for integrating Ajax and Flex content. By the end of this article, you will be able to take advantage of the rich features available through Adobe Flash assets.

Building Ajax applications has proven to be a consistent method for providing engaging applications. However, the explosion in popularity of Adobe Flex cannot be ignored. As we are continually pushed to create the best user experience, we are often faced with the difficult task of integrating Flash-based assets embedded in our Ajax applications. This article discusses the integration of Flash content with existing Ajax content using the FABridge, a code library developed by Adobe to handle this very task.

To be an Ajax developer today is pretty special. We are always at the front lines, ready to greet users and offer the best first impression to the applications we build for them. As Web standards advance and more vendors decide to implement them, our jobs have become easier, allowing us to focus on the user experience. The further advancements in JavaScript frameworks such as Ext JS, jQuery, and Prototype have also allowed us to spend less time worrying about whether our code will work across the platforms we are asked to support, leaving more time to innovate.

Although there are certainly more tools, techniques, and resources available to us today, there is also a shift in development methodology that serves as a push toward the rich world of Flash development. For many shops, the development workflow would involve the user interface (UI) group to produce designs that support a server-side-generated application. With just the JavaScript frameworks we have now, we are pushed in the direction of application development for the client side. However, the emergence of the Flex platform — a free, open source framework for producing Flash applications — brings us further into the application development arena. This type of innovation is good for us on the client side, but we must ensure that we handle the process of integrating it with current architectures in a thoughtful and careful manner.

Before I introduce code samples showing how to work with Ajax and Flex assets, you need to understand the tools and skills required:

    * I produced the Ajax samples in this article using the Ext JS JavaScript library, so you need to download the .zip file that contains the library and supporting documentation.
    * Next, grab a copy of the free Adobe Flex 3 SDK and Adobe Flash Player 9 with debugging capability, if you don already have it.
    * Although not required to follow along in this article, you may also want to check out at least a trial version of Adobe Flex Builder 3, an Eclipse-based IDE that enables rapid Flex application development in addition to superior debugging and profiling capabilities (see Resources).
    * Finally, a working knowledge of PHP is helpful.

The integration issue

If you were looking forward to replacing all your Ajax content with Flex assets, your task would be much simpler. However, this is an unlikely and often unreasonable approach, because there are many reasons to preserve traditional Ajax functionality. Fortunately, there is no reason you can keep the best of both environments to produce a rich, cohesive application.

There are quite a few simplistic methods for passing data to ActionScript code from the Flash container (HTML/JavaScript code), including the use of query strings and <param> tags. However, this method is limited to passing data into the container. A more powerful technique is to use the ExternalInterface class, an application program interface (API) used to broker communication between the ActionScript and JavaScript languages. The use of ExternalInterface is best demonstrated by the example in Listing 1:

Listing 1. ExternalInterface example

               
// ActionScript code
function exposed():String
{
   return "Hello, JavaScript!";
}

ExternalInterface.addCallback( "getActionScript", exposed );

// HTML/JavaScript code
<script language="JavaScript">

var result = flashObject.getActionScript();

</script>

<object id="flashObject" ...>
   <embed name="flashObject" ... />
</object>


Listing 1 demonstrates a stripped-down example of how to use the ExternalInterface class to register an ActionScript function so that JavaScript code can call it. You do this by first defining an ActionScript function, then using the addCallback() method to expose the function to JavaScript for execution. On the HTML side, simply obtain a handle to the Flash container and call the function, which was named using the first parameter to the addCallback() method. Although this demonstration concentrated on exposing functions to the JavaScript code, you can just as easily go the other way by using the call() method of the ExternalInterface class.

The ExternalInterface class can be quite powerful, but there are significant drawbacks to implementing it. To use ExternalInterface, you must be able to write code to implement both the ActionScript and JavaScript environments. This not only requires added skill but double the effort. In this situation, maintaining code as well as two very robust skill sets can become a challenge.

To address the limitations of development against the Flash external API, Adobe has released the FABridge. The FABridge, which ships with the Flex SDK, is a small library used to expose Flash content to scripting in the browser and works in most major browser platforms. With the FABridge, plumbing code that was required to directly implement the Flash external API is now virtually eliminated. Further, the skills required to implement the bridge aren as robust. As a JavaScript developer, you simply need to be able to understand what is available to you in the way of ActionScript properties and methods. Let is get started with a few examples that demonstrate the capabilities of the FABridge.

An FABridge tutorial

Before you get started using the FABridge, here are the materials and development environment you will be working with. After downloading the latest Flex SDK, configure the directory structure shown in Listing 2:

Listing 2. Directory structure for the FABridge tutorial

               
/
+--- bridge
|      +--- fabridge.js
|      +--- fabridge.as
|     
+--- index.html


The directory structure is straightforward: You just have an index page and the FABridge scripts hooked into their own directory named bridge. The location of the FABridge library files depends on your environment. Because I am using Flex Builder 3 Professional on Mac OS X, my library files reside in install_root/sdks/frameworks/3.0.0/javascript/fabridge/.

Now that you have the appropriate architecture in place, you can begin creating the skeletons on both the HTML/JavaScript and ActionScript sides. Use the code from Listing 3 to develop the HTML/JavaScript skeleton:

Listing 3. HTML/JavaScript skeleton

               
<html>
<head>
<title>FABridge Tutorial</title>

<script type="text/javascript" src="bridge/FABridge.js"></script>
<script type="text/javascript">
   // ...
</script>

</head>
<body>
</body>
</html>


As you can see, you simply hook the FABridge JavaScript library to your code, and all the functionality of the bridge is immediately available. Next, use the code from Listing 4 to implement the bridge on the ActionScript side:

Listing 4. Application skeleton

               
<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
       xmlns:bridge="bridge.*"
       layout="absolute"
       width="300"
       height="142">
      
   <bridge:FABridge bridgeName="flex" />
   <mx:TextInput x="70" y="54" id="txt_test" text="FABridge rocks!"/>
  
</mx:Application>


This code might be a bit more unfamiliar to you. The UI is kept clean and simple by defining a single text input control with the ID txt_test and a default value of FABridge rocks! The bridge namespace is defined, and all classes in the bridge directory are imported. Finally, the Flex application is given a name for the bridge to use to access it: flex. To compile this Flex code into a working SWF document, use the mxmlc utility from the Flex 3 SDK. The most basic compile command is shown in Listing 5:

Listing 5. Compiling MXML

               
                path_to_flex_bin_folder/mxmlc path_to_mxml file
           


The command in Listing 5 compiles the source file and outputs an SWF file with the same file name as the MXML in the same directory. Assuming a successful compilation, you can now hook the resulting SWF into your HTML file, as shown in Listing 6:

Listing 6. Linking the resulting SWF file

               
<embed src=”main.swf” />


Note: The code in Listing 6 is deliberately light to keep focus on the task of demonstrating the FABridge. Unless you are targeting a specific environment (Listing 6 is targeting Mozilla), you will want to add more intelligence in the way of object tags and other load scripts.

Assuming that all went well, your application should now look similar to Figure 1:

Figure 1. The sample application



Now that you have successfully compiled and linked the Flex application into the HTML container, invoke your first FABridge functions to obtain a reference to the Flex application. Use the code in Listing 7 to fill in the empty <script> tag in your HTML skeleton file:

Listing 7. Obtaining a reference to the Flex application

               
// global variable, holds reference to the Flex application
var flexApp; 
 
var initCallback = function() { 
   flexApp = FABridge.flex.root(); 
   return; 
} 
// register the callback to load reference to the Flex app
FABridge.addInitializationCallback( "flex", initCallback );


The code in Listing 7 starts by defining a global JavaScript variable that will hold a reference to the Flex application when the FABridge obtains it. A callback function is defined that sets the global variable and is invoked through the addInitializationCallback() FABridge method. Using this code is simply a matter of matching the name of the bridge that you configured in the Flex application. From here, you are able to access all sorts of ActionScript functionality from the JavaScript code.

Working with ActionScript objects

Now that you have obtained a global reference to the Flex application, you can access ActionScript objects through the consistent interface that the FABridge provides. In the ActionScript world, you would typically access objects through dot notation object.id. Rather than expose ActionScript objects in dot notation, however, the FABridge makes these objects available through function calls. It is a little different at first, but all you need to know is the template to follow. An object traditionally identified in ActionScript as object.id would now be accessed as object.getId(). This is best demonstrated through example: Type the code from Listing 8 into your HTML skeleton to try it out:

Listing 8. Getting ActionScript objects by ID

               
// get the text input control
var txt = flexApp.getTxt_test();


The variable txt is an object that represents the text input control with the ID txt_test from the Flex application. You can see the template you would need to follow for gaining access to other ActionScript objects by ID. The declaration begins with the global reference to the Flex application, then a method call that always begins with the string get followed by the ID of the target object. Notice that the name of the ID must begin with a capital letter in this declaration.

Getting and setting the properties of ActionScript objects is similar to the process just used. Keeping up with our example of manipulating the text input control, use the code from Listing 9 to get and set the text property:

Listing 9. Get and set ActionScript properties

               
alert( "old: " + txt.getText() );
   
txt.setText( "Reset!" );
   
alert( "new: " + txt.getText() );


The code in Listing 9 first alerts the original value of the text input control from the Flex application. By following the template described earlier, you can see that the text property is obtained through a function call, with the get string prepended and the property name camel cased. The set() method uses the same process but accepts a parameter used to configure the new value of the object. After the code in Listing 9 executes, you should see a screen similar to Figure 2:

Figure 2. Setting ActionScript object properties



Now, let is move on to the easiest manipulation of all: calling ActionScript object methods. This process requires no special considerations on your part. ActionScript object methods are used in JavaScript code just as they would be used in ActionScript code. The code in Listing 10 demonstrates the invocation of a method on your text input control:

Listing 10. Invoking ActionScript methods

               
txt.setVisible( false );


The code in Listing 10 sets the text input control in the Flex application to be invisible. The object can still be referenced and manipulated, it is just not physically visible. Between the ActionScript and JavaScript worlds, this is no change in the way the methods are invoked.

One of the more powerful features of the FABridge is the ability to pass functions between JavaScript and ActionScript code. Check out the code in Listing 11, which dynamically copies the value of the text input in Flex to a <div> on the HTML/JavaScript side:

Listing 11. Passing functions

               
// define a function used as a callback to JavaScript
var txtCallback = function( event ) { 
   // get the object which fired the event
   var swf_source = event.getTarget(); 
  
   document.getElementById( "copy" ).innerHTML = swf_source.getText();
     
   return; 
} 
txt.addEventListener( "change", txtCallback );


The code in Listing 11 is a JavaScript callback function that is fired each time the text input control value from the Flex application changes. When the value changes, it is copied to a <div> tag with the ID copy. This type of functionality can be very powerful, especially when attempting any sort of integration work between Ajax and Flex content. With both environments relying heavily on events, it is key to be able to have them work together.

The last feature this article explores is exception handling. By default, when you use try . . . catch blocks throughout your JavaScript code, you will be able to at least access an error code that you can then look up in the online reference for ActionScript errors. This methodology certainly works, but during development, you want access to as much information up front as possible. While using the FABridge, you can get this information simply by installing Flash Player 9 with debugging. With this feature installed, you have access to line numbers, file names, error types, and stack traces. Use the code in Listing 12 to see an example:

Listing 12. Exception handling

               
try {
   alert( flexApp.throwsAnError() );
}
catch( e ) {
   var msg = "";
   for( var i in e ) {
      msg += i + " = " + e[i];
   }
   alert( msg );
}


An error is thrown from the code in Listing 12 because the method throwsAnError() does not exist. The code from the catch block outputs an alert that looks similar to Figure 3:

Figure 3. Exception data



As you can see, this data is far more useful than a single error code and less work to troubleshoot. When you are working with complex integration issues between differing technologies such as JavaScript and ActionScript, you will appreciate this extra help.

source: ibm

 View Full Story.