Compiling Flex Application

Introduction

Although Flex 4 SDK has been released, there are numerous applications running on Flex 2. This document focuses on the options available for compiling such applications.

A common practice is to embed the Flex applications in a JSP page. This document describes the two ways of compiling the Flex application in such a set up. An outline for how to use Flex Ant tasks to build Flex code is also provided.

Compiling using Flex JSP tag library

The easiest way to embed a Flex application in a JSP is to use the MXML tag of the JSP tag library provided with Flex 2.0.1. Flex 2 Tag Library for JSP is included as part of Adobe® LiveCycle® Data Services ES

Note: With the Flex JSP tag library, you can inline MXML (the Flex markup language) into a JSP, as opposed to pointing to an external MXML file.

What is the Flex 2 Tag Library for JSP?

The Flex™ 2 Tag Library for JSP is a set of JSP tags that you can use to embed Flex applications to a JSP page. This is prerelease software.

The <mxml> tag compiles the MXML code, if required, and then generates the HTML fragment to load Adobe® Flash® Player and the resulting SWF file in your JSP page. You can use this in two different ways. The source tag attribute lets you specify the source file to compile. This is useful because the JSP tag writes the HTML fragment for you. The other approach is to specify the source as the body content of the tag. Then, you use JSP scriptlets to generate the MXML source.

The <flashvar> tag lets you to pass variables to a Flex application. You access these variables by using the Application.application.parameters object.

The <param> tag that let you add Flash Player parameters to the HTML wrapper was eliminated in an effort to simplify tag usage. The <flash> tag, which generated an HTML wrapper for a pre-generated SWF file, was also eliminated.

Flex 2 Tag Library for JSP Reference

Tag	Description	Attributes
<mxml>	Compiles the MXML code and generates the HTML wrapper. Include MXML source as body content or specify an external source file with the source attribute.	source - Location of the MXML code to compile. id - Name used to expose the SWF file through the id or name attribute of the HTML object or embed tag. height - Height of the MXML wrapper. width - Width of the MXML wrapper. useHistoryManagement - Include history management for the Flex application. usePlayerDetection - Include Flash Player detection for the Flex application. useExpressInstall - Install Flash Player through Express Install; ignored if Flash Player detection is disabled. alternateContentPage - Present this alternate page when the Flash Player version is unavailable; ignored if Flash Player detection is disabled.
<flashvar>	Specifies a variable to pass to your Flex Application.	name - Specifies the name of the flashvar variable. value - Specifies the value of the flashvar variable.

What Do I Need to Use It?

The Flex 2 Tag Library for JSP requires the following:

• LiveCycle Data Services ES
• A supported Java application server or servlet container

Download and Installation

Flex 2 Tag Library for JSP is included as part of Adobe® LiveCycle® Data Services ES and is now shipping on Adobe.com.

• Download and install the data services available on the above link in the folder lcds
• Extract the flex.war present in lcds to the folder flexsdk
• Copy all the jars from flexsdk/WEB-INF/lib to your Java web project’s /WEB-INF/lib
• Copied all the jars from flexsdk/WEB-INF/flex/jars to the web project’s /WEB-INF/flex/jars
• Also, copied all the jars from flexsdk/WEB-INF/flex/jars to the web project’s /WEB-INF/lib
• Merge all the config files in flexsdk/WEB-INF/flex with those in web project’s /WEB-INF/flex
• Merge the web.xml in flexsdk/WEB-INF with that in web project’s /WEB-INF
• Set all warning variables as false in flex-config.xml
• Invoke the jsp. This will compile the Flex files.

Consider the following example:

HelloWorld.jsp

<%@ taglib uri="FlexTagLib" prefix="mm" %> <mm:mxml source="/jsp/HelloWorld.mxml">   <mm:flashvar name="name" value="<%=value%>"/> </mm:mxml>

HelloWorld.mxml

<?xml version="1.0" encoding="utf-8"?> <mx:Application xmlns:mx="http://www.macromedia.com/2003/mxml" width="200" height="100"> <mx:Label text="Hello World!"/> </mx:Application>

Here, the URI “FlexTagLib” stands for “/WEB-INF/lib/flex-bootstrap-jsp.jar” and is defined in flexsdk/WEB-INF/web.xml.

The HelloWorld.mxml can access the flashvar name using Application.application.parameters.name.

In the above example, since, source attribute is used, the HTML fragment for inserting the swf into the JSP is automatically generated. There is no need of including the object and embed tags explicitly. The swf file is created in the same location as HelloWorld.mxml.

An observation worth noting down is that server maintains a cache of the swf embedded in the jsp. So, even if the swf is deleted, the jsp can still show up the Flex content without needing to re-compile the Flex application. But if a change is made in the Flex files, the entire application is re-compiled on invoking the jsp.

Advantages

- The Flex application is compiled only if there is a change in any of the Flex files.

- The same environment (provided by /WEB-INF/lib & /WEB-INF/flex in web project) is used at compile-time and run-time. This makes the task of keeping the libraries of the environment up-to-date easy. This will be clearer after seeing how Flex SDK can be used for compiling Flex Application.

This method supports the use of Flex Data Services.

Compiling using Flex SDK

Another way of compiling the Flex Application is by using the Flex SDK. You use the mxmlc command-line compiler to create SWF files from MXML, AS, and other source files. You can open it as a shell script and executable file for use on Windows and UNIX systems. You use this compiler to pre-compile Flex applications that you deploy later.

What Do I Need to Use It?

• Download the Flex SDK from the link http://www.adobe.com/products/flex/. The SDK comes for free.
• It is in the flex_SDK_dir/bin directory in Flex 2 SDK.

For more information, see About the command-line compilers.

How Do I Use It?

Assume that the HelloWorld.mxml shown above is present in the location D:\FlexWorkSpace\FlexProject\WebContent\flexContent. This means that FlexProject is the web project containing the Flex Application.

1. Open DOS prompt and go to flex-sdk/bin
2. Type the following command to compile the Flex application:

mxmlc --warnings=false --services="D:\FlexWorkSpace\FlexProject\WebContent\WEB-INF\flex\services-config.xml" --locale=en_US --load-config="D:\FlexWorkSpace\FlexProject\WebContent\WEB-INF\flex\flex-config.xml" -file-specs D:\FlexWorkSpace\FlexProject\WebContent\flexContent\HelloWorld.mxml

1. By default, the swf file is created in the same location as HelloWorld.mxml and with the name HelloWorld.swf.

Note: The version of flex-config.xml and services-config.xml is determined by the version of the Flex libraries under /WEB-INF/lib & /WEB-INF/flex in web project and it should be same as the version of the Flex SDK used for compilation.

The mxmlc command-line compiler does not generate an HTML wrapper. You must create your own wrapper to deploy a SWF file that the mxmlc compiler produced. The wrapper is used to embed the SWF object in the HTML tag. It includes the <object> and <embed> tags, as well as scripts that support Flash Player version detection and history management. For information about creating an HTML wrapper, see Creating a Wrapper.

Disadvantages

- Compile time environment is provided by the Flex SDK but runtime environment is provided by the libraries under /WEB-INF/lib & /WEB-INF/flex in web project. This requires an overhead of making sure that same version of libraries is used in both.

This method supports the use of Flex Data Services.

Compiling using Flex ANT tasks

The Flex Ant tasks provide a convenient way to build your Flex projects using an industry-standard build management tool. If you are already using Ant projects to build Flex applications, then you can use the Flex Ant tasks to build the Flex application along with java code.

Installation

1. Download the Flex Ant tasks ZIP file and view the license agreement.
2. Extract the flexTasks.jar file from the ZIP file to a temporary directory.
3. Copy the flexTasks.jar file to Ant's lib directory ({ant_root}/lib). If you do not copy this file to the lib directory, you must specify it by using Ant's -lib option on the command line when you make a project.

Please note that the zip includes the source for Flex Ant tasks.

Using Flex Ant tasks

1. Add a new taskdef task to the build file of your project. In this task, specify the "flexTasks.tasks" file as the resource, and point to the flexTasks.jar file for the classpath. For example:

<taskdef resource="flexTasks.tasks" classpath="${basedir}/flexTasks/lib/flexTasks.jar" />

1. Define the FLEX_HOME and APP_ROOT properties. Use these properties to point to your Flex SDK's root directory and application's root directory. While not required, creating properties for these directories is a common practice because you will probably use them several times in your Ant tasks. For example:

<property name="FLEX_HOME" value="C:/flex/sdk"/>

<property name="APP_ROOT" value="myApps"/>

1. Write a target that uses the Flex Ant tasks. The following example defines the main target which uses the mxmlc task to compile the Main.mxml file:

<target name="main">

<mxmlc file="${APP_ROOT}/Main.mxml" keep-generated-actionscript="true">

<load-config filename="${FLEX_HOME}/frameworks/flex-config.xml"/>

<source-path path-element="${FLEX_HOME}/frameworks"/>

</mxmlc>

</target>

The following shows the complete example:

<?xml version="1.0" encoding="utf-8"?>

<!-- mySimpleBuild.xml -->

<project name="My App Builder" basedir=".">

<taskdef resource="flexTasks.tasks" classpath="${basedir}/flexTasks/lib/flexTasks.jar" />

<property name="FLEX_HOME" value="C:/flex/sdk"/>

<property name="APP_ROOT" value="myApp"/>

<target name="main">

<mxmlc file="${APP_ROOT}/Main.mxml">

<load-config filename="${FLEX_HOME}/frameworks/flex-config.xml"/>

<source-path path-element="${FLEX_HOME}/frameworks"/>

</mxmlc>

</target>

</project>

Please refer #Working with compiler options for details of different flex tasks.

1. Execute the Ant project; for example:

> ant -buildfile mySimpleBuild.xml main

If you did not copy the flexTasks.jar file to Ant's lib directory as described in step 3 of Installation, then you must include the JAR file by using Ant's -lib option. For example:

> ant -lib c:/ant/lib/flexTasks.jar -buildfile mySimpleBuild.xml main

Common errors encountered

1. lang.IllegalAccessError: cannot access superclass org/apache/xerces/util/XMLAttributesImpl$Attribute from class org/apache/xerces/util/XMLAttributesMMImpl$AttributeMMImpl

For this, just rename the xercesPatch.jar in the Flex SDK to xercesPatch.jar.bak

Resources

http://labs.adobe.com/wiki/index.php/Flex_Ant_Tasks#Using_Flex_Ant_tasks