== What Is the Flex AJAX Bridge? ==

The Flex AJAX Bridge (FABridge) is a small, unobtrusive code library that you can insert 
into an Apache® Flex application, a Flex component, or even an empty SWF file to expose 
it to scripting in the browser. It is being released to the community under the Apache
Software Foundation, v2 license.  See http://www.apache.org/licenses/LICENSE-2.0.

To humbly borrow a page from the Ruby on Rails community, FABridge is built with the 
"don't repeat yourself" principle in mind. Rather than having to define new, simplified 
APIs to expose a graph of ActionScript objects to JavaScript, with FABridge you can make 
your ActionScript classes available to JavaScript without any additional coding. After you
insert the library, essentially anything you can do with ActionScript, you can do with 
JavaScript.

Adobe® Flash® Player has the native ability, through the External API (the 
ExternalInterface class), to call JavaScript from ActionScript, and vice versa. But 
ExternalInterface has some limitations:
* The ExternalInterface class requires you, the developer, to write a library of extra 
code in both ActionScript and JavaScript, to expose the functionality of your Flex 
application to JavaScript, and vice versa.  
* The ExternalInterface class also limits what you can pass across the gap. Primitive 
types, arrays, and simple objects are legal, but user-defined classes, with associated 
properties and methods, are off-limits. 
* The ExternalInterface class enables you to define an interface so your JavaScript can 
call your ActionScript. FABridge essentially lets you write JavaScript instead of 
ActionScript.

== When Should I Use the Flex AJAX Bridge? ==

The FABridge library is useful in the following situations:
* You want to use a rich Flex component in an AJAX application but do not want to write a 
lot of Flex code. If you wrap the component in a FABridge-enabled stub application, you 
can script it entirely from JavaScript, including using eval()’d JavaScript generated 
remotely by the server.
* You have only one or two people on your team who know Flex.  Although I would strongly 
encourage everyone to grab a copy of Flex and try it out (you will love it, I promise!), 
the FABridge library lets everyone on your team use the work produced by one or two Flex 
specialists.
* You are building an integrated rich Internet application (RIA) with both Flex and AJAX 
portions.  While you could build the integration yourself using ExternalInterface, you 
might find it faster to start with the FABridge as a head start.

== What Do I Need to Use It? ==

To use the FABridge library and samples, you must have the following:
* AJAX Bridge, which is included in the following directory of the LiveCycle Data 
Services installation:

installation_dir\resources\FABridge

* Flex 2 SDK included in the LiveCycle Data Services installation
* Flash Player 9
* Microsoft Internet Explorer, Mozilla Firefox, or Opera with JavaScript enabled
* Any HTTP server to run the samples

== Download and Installation ==

To run the sample files, follow these steps:

1. Copy the src and samples directories from the install_dir\resources\FABridge directory 
of the LiveCycle Data Services installation side by side on any HTTP server.
2. Open a web browser to <your web server>/samples/FABridgeSample.html and 
samples/SimpleSample.html and follow the instructions there.

Make sure you access the samples through http:// URLs and not file:// URLs. The Flash 
Player security sandbox may prevent them from working correctly if accessed as local files.

== How Do I Use the Flex AJAX Bridge? ==

To use the FABridge library in your own Flex and AJAX applications, follow these steps:
* Add the src folder to the ActionScript <code>classpath</code> of your Flex application.
* If you are compiling from the command line, you can add the src folder to your 
application by specifying it using the --actionscript-classpath compiler option.
* Add the following tag to your application file:

  <mx:Application ...>
    <fab:FABridge xmlns:fab="bridge.*" />
    ...

Use the following code to access your application instance from JavaScript:

  function useBridge() 
  {
      var flexApp = FABridge.flash.root();
  }

To get the value of a property, call it like a function; use the same syntax to access 
objects by id, as the following example shows:

  function getMaxPrice() 
  {
      var flexApp = FABridge.flash.root();
      var appWidth = flexApp.getWidth();
      var maxPrice = flexApp.getMaxPriceSlider().getValue();
  }

To set the value of a property from JavaScript, call the function 
<code>setPropertyName()</code>, as the following example shows:

  function setMaxPrice(newMaxPrice) 
  {
      var flexApp = FABridge.flash.root();
      flexApp.getMaxPriceSlider().setValue(newMaxPrice);
  }

You can call object methods directly, just as you would from ActionScript, as the 
following example shows:

  function setMaxPrice(newMaxPrice) 
  {
      var flexApp = FABridge.flash.root();
      flexApp.getShoppingCart().addItem("Antique Figurine", 12.99);
  }

You can also pass functions, such as event handlers, from JavaScript to ActionScript, as 
the following example shows:

  function listenToMaxPrice() 
  {
      var flexApp = FABridge.flash.root();
      var maxPriceCallback = function(event)
      {
          document.maxPrice = event.getNewValue();
          document.loadFilteredProducts(document.minPrice, document.maxPrice);
      }
      flexApp.getMaxPriceSlider().addEventListener("change", maxPriceCallback);
  }

To run initialization code on a Flex file, you must wait for it to download and initialize 
first. Register a callback to be invoked when the movie is initialized, as the following 
example shows:

 function initMaxPrice(maxPrice)
  {
      var initCallback = function()
      {
          var flexApp = FABridge.flash.root();
          flexApp.getMaxPriceSlider().setValue(maxPrice);
      }
      FABridge.addInitializationCallback("flash",initCallback);
  } 

To script multiple Flash applications on the same page, give them unique bridge names 
through the flashvars mechanism.  Use the bridge name to access them from the bridge, and 
to register for initialization callbacks, as the following example shows:

  <object ...>
    <param name='flashvars' value='bridgeName=shoppingPanel'/>
    <param name='src' value='app.swf'/>
    <embed ... flashvars='bridgeName=shoppingPanel'/>
  </object>
  
  function initMaxPrice(maxPrice)
  {
      var initCallback = function()
      {
          var flexApp = FABridge.shoppingPanel.root();
          flexApp.getMaxPriceSlider().setValue(maxPrice);
      }
      FABridge.addInitializationCallback("shoppingPanel",initCallback);
  }

<b>Automatic memory management</b>

The FABridge provides automatic memory management that uses a reference counting mechanism
for all objects that are passed across the bridge. Objects created from the JavaScript 
side are kept in memory unless the memory is manually released. Events and other 
Actionscript-initiated objects are destroyed as soon as the corresponding JavaScript 
function that handles them directly completes its execution. You can manually call the 
<code>addRef()</code> for an object to have it remain available or call the 
<code>release()</code> method to decrease its reference counter.

If you must break the function call chain by using the <code>setTimeout()</code> function 
in JavaScript, for example to act on an event later on as the following example shows, you
must ensure that the event will still exist. Because the FABridge implements a reference 
counting mechanism to save memory, events thrown from ActionScript exist only for the 
duration of the dispatch function.

<pre>
var flexApp = FABridge.flash.root();
flexApp.getMaxPriceSlider().addEventListener("change", maxPriceCallback );
function maxPriceCallback(event) {
    //when the doSomethingLater function is hit, the event is no longer available;
    //to make it work you would have to call
    //FABridge.addRef(event);
    //then, when you're done with it call FABridge.release(event);
    setTimeout(function() {doSomethingLater(event);},10);
}
</pre>  

<b>Manually destroying objects</b>

You can manually destroy a specific object that has been passed across the bridge, 
regardless of its reference count by invoking the <code>releaseNamedASObject(myObject)</code> 
method from JavaScript. This invalidates the object over the bridge and any future calls 
to it or one of its methods will throw an error.

<b>Handling exceptions</b>

Exceptions that take place in the ActionScript of the bridge as a direct consequence of 
some JavaScript action are now thrown over the bridge into JavaScript. The mechanism 
works as follows:
* When an exception is raised in the ActionScript section, it is caught in a try-catch 
block, serialized, and passed to JavaScript. 
* When the JavaScript part receives an answer from ActionScript, it checks for the 
exception serialization and, if found, throws a JavaScript error with the message received
from ActionScript.

Note: To catch and use the exception information, you must surround the code that calls 
into ActionScript with a try-catch block. You can handle the error in the <code>catch(e)</code> 
block.

== What Are the Limitations? ==

The FABridge library is currently in a beta state. It has been tested on Mozilla Firefox 2
(Windows and Linux), Microsoft Internet Explorer 6, Opera 9, and Apple Safari 2.0.4.

Exceptions thrown across the bridge into JavaScript depend on the user having installed 
Flash Debug Player to display the entire error description. Otherwise, only the error ID
is thrown.

For performance reasons, when an anonymous object is sent from ActionScript to JavaScript,
the bridge assumes it contains only primitives, arrays, and other anonymous objects, and 
no strongly typed objects or methods. Instances or methods sent as part of an anonymous 
object are not bridged correctly.

== Summary ==

You can use the FABridge library to automatically expose your Flex application to 
AJAX-based HTML applications.  Using the bridge, you can easily embed rich Flex components
in your applications, integrating them tightly with the rest of the page content. After a
Flex application is enabled through the bridge, JavaScript developers have access to all
of the functionality it provides.