You write the client-side part of a LiveCycle Data Services ES application in Flex, and then use Flex Builder or the mxmlc command line compiler to compile it.

Before you begin

Before you begin to develop your client-side code, determine the files required to perform the compilation. Ensure that you configured your Flex installation to compile SWF files for LiveCycle Data Services ES applications.

Add the LiveCycle Data Services ES SWC files to the Flex SDK

To compile an application, Flex Builder and mxmlc reference the SWC library files that ships with the Flex SDK in the frameworks/libs directory. However, LiveCycle Data Services ES ships additional SWC library files and SWC localization files that you must reference in the compilation:

• datavisualization.swc and fds.swc

  The SWC library files that define LiveCycle Data Services ES. These SWC files must be included in the library path of the compiler. Typically you place them in the frameworks/libs directory of your Flex SDK, or specify the directory location of these SWC files by using the library-path option to the compiler. For more information on compiler options, see Building and Deploying Adobe Flex 3 Applications.

• airfds.swc and playerfds.swc

  The SWC files required to build LiveCycle Data Services ES applications for Flash Player (playerfds.swc) or AIR (airfds.swc). One of these SWC files must be included in the library path of the compiler.

  For the default Flex SDK installation, playerfds.swc must be in the libs/player directory, and airfds.swc must be in the libs/air directory. The airfds.swc and playerfds.swc files must not both be available at the time of compilation. When you compile your application in Flex Builder, it automatically references the correct SWC file based on your project settings.

  August 22, 2008: Added Flex 3.1 SDK note
  Note: If you are using the Flex 3.1 SDK you need to copy playerfds.swc to the libs/player/9 directory.

  When you compile an application using mxmlc, by default the compiler references the flex-config.xml configuration file, which specifies to include the libs/player directory in the library path for Flash Player. When you compile an application for AIR, use the load-config option to the mxmlc compiler to specify the air-config.xml file, which specifies to include the libs/air directory in the library path.

• datavisualization_rb.swc and fds_rb.swc

  The localized SWC files for LiveCycle Data Services ES. These SWC files must be in the library path of the compilation. Typically, you place them in the frameworks/locale/en_US directory of your Flex SDK, or specify the directory location of these SWC files by using the library-path option to the compiler. For more information on localization, see Adobe Flex 3 Developer Guide.

Add the necessary SWC files to the Flex 3 SDK

1. Unzip install_root/resources/flex_sdk/flex_sdk_3.zip to install_root/resources/flex_sdk, where install_root is the LiveCycle Data Services ES installation directory. For example, the default value of install_root is c:\lcds on Microsoft Windows.
2. August 22, 2008: Added note.
   Copy install_root/resources/frameworks/libs/datavisualization.swc and fds.swc to install_root/resources/flex_sdk/frameworks/libs.
   Note: If you are updating an SDK that shipped with FlexBuilder and already has the datavisualization.swc file, use that version of the SWC and don't overwrite it with the one that ships with LiveCycle DS. That is, skip this step.
3. Copy install_root/resources/frameworks/libs/air/airfds.swc to install_root/resources/flex_sdk/frameworks/libs/air.
4. Copy install_root/resources/frameworks/libs/player/playerfds.swc to install_root/resources/flex_sdk/frameworks/libs/player.
5. Copy install_root/resources/frameworks/locale/en_US/datavisualization_rb.swc and fds_rb.swc to install_root/resources/flex_sdk/frameworks/locale/en_US.

Specifying the services-config.xml file in a compilation

When you compile your Flex application, you typically specify the services-config.xml configuration file to the compiler. This file defines the channel URLs that the client-side Flex application uses to communicate with the LiveCycle Data Services ES server. Then the channel URLs are compiled into the resultant SWF file.

Both client-side and server-side code use the services-config.xml configuration file. If you change anything in services-config.xml, you usually have to recompile your client-side applications and restart your server-side application for the changes to take effect.

In Flex Builder, the appropriate services-config.xml file is included automatically based on the LiveCycle Data Services ES web application that you specified in the configuration of your Flex Builder project. When you use the mxmlc compiler, use the services option to specify the location of the file.

Specifying the context root in a compilation

The services-config.xml configuration file typically uses the context.root token to specify the context root of a web application. At compile time, you use the compiler context-root option to specify that information.

During a compilation, Flex Builder automatically sets the value of the context.root token based on the LiveCycle Data Services ES web application that you specified in the configuration of your project. When you use the mxmlc compiler, use the context-root option to set it.

Using Flex Builder to compile client-side code

Adobe Flex Builder is an integrated development environment (IDE) for developing applications that use the Adobe Flex framework, MXML, Adobe Flash Player 9, AIR 1.0, ActionScript 3.0, LiveCycle Data Services ES, and the Flex Charting components.

Flex Builder is built on top of Eclipse, an open-source IDE. It runs on Microsoft Windows, Apple Mac OS X, and Linux, and is available in several versions. Installation configuration options let you install Flex Builder as a plug-in to an existing Eclipse workbench installation, or to install it as a stand-alone application.

For more information, see Using Adobe Flex Builder 3.

Using stand-alone or plug-in configuration of Flex Builder

The Flex Builder installer provides the following two configuration options:

Plug-in configuration This configuration is for users who already use the Eclipse workbench, who already develop in Java, or who want to add the Flex Builder plug-ins to their toolkit of Eclipse plug-ins. Because Eclipse is an open, extensible platform, hundreds of plug-ins are available for many different development purposes.

Stand-alone configuration This configuration is a customized packaging of Eclipse and the Flex Builder plug-in created specifically for developing Flex and ActionScript applications. The stand-alone configuration is ideal for new users and users who intend to develop only Flex and ActionScript applications.

Both configurations provide the same functionality. You select the configuration when you install Flex Builder.

Most LiveCycle Data Services ES developers choose to use the Eclipse plug-in configuration. Then they develop the Java code that runs on the server in the same IDE that they use to develop the MXML and ActionScript code for the client Flex application.

If you aren't sure which configuration to use, follow these guidelines:

• If you already use and have Eclipse 3.11 (or later) installed, select the plug-in configuration. On Macintosh, Eclipse 3.2 is the earliest version.
• If you don't have Eclipse installed and your primary focus is on developing Flex and ActionScript applications, select the stand-alone configuration. This configuration also lets you install other Eclipse plug-ins, so you can expand the scope of your development work in the future.

Add the Flex SDK to Flex Builder

Before you can build your first LiveCycle Data Services ES application in Flex Builder, add the Flex SDK to Flex Builder that contains the LiveCycle Data Services SWC files. You perform this procedure only once.

For more information, see Add the LiveCycle Data Services ES SWC files to the Flex SDK.

1. Start Flex Builder.
2. Select Window > Preferences.
3. Select Flex > Installed Flex SDKs.
4. Click Add.
5. Specify install_root/resources/flex_sdk for the Flex SDK location in the Add Flex SDK dialog box, where install_root is the LiveCycle Data Services ES installation directory. For example, the default value of install_root is c:\lcds on Microsoft Windows.
6. Specify LCDS for the Flex SDK name, and click OK.
7. (Optional) Select the Flex LCDS SDK option to make it the default SDK for new Flex projects.
8. Click OK.

Create a Flex Builder project

Use this procedure to create a Flex Builder project to edit one of the samples shipped with the Test Drive application. The procedure for creating and configuring a new project is almost the same as the following procedure.

For more information on the Test Drive application, see Running the LiveCycle Data Services ES sample applications.

1. Start Flex Builder.
2. Select File > New > Flex Project.
3. Enter a project name. You are editing an existing application, so use the exact name of the sample folder: testdrive-chat.
   Note: If you are creating an empty project, you can name it anything that you want.

4. If you unzipped flex-src.zip in the lcds-samples directory, deselect the Use Default Location option, and specify the directory as C:\lcds\tomcat\webapps\lcds-samples\testdrive-chat, or wherever you unzipped the file on your computer.
   Note: By default, Flex Builder creates the project directory based on the project name and operating system. For example, if you are using the plug-in configuration of Flex Builder on Microsoft Windows, the default project directory is C:\Documents and Settings\USER_NAME\workspace\PROJECT_NAME.

5. Select the application type as Web application (runs in Flash Player) to configure the application to run in the browser as a Flash Player application.

   If you are creating an AIR application, select Desktop Application (Runs In Adobe AIR). However, make sure that you do not have any server tokens in URLs in the configuration files. In the web application that ships with LiveCycle Data Services ES, server tokens are used in the channel endpoint URLs in the WEB-INF/flex/services-config.xml file, as the following example shows:

   <endpoint url="https://{server.name}:{server.port}/{context.root}/messagebroker/streamingamf"
         class="flex.messaging.endpoints.StreamingAMFEndpoint"/>
   
   

   You would change that line to the following:

   <endpoint url="http://your_server_name:8400/lcds/messagebroker/streamingamf"
         class="flex.messaging.endpoints.StreamingAMFEndpoint"/>
   
   

6. Select J2EE as the Application server type.
7. Select Use Remote Object Access.
8. Select LiveCycle Data Services.
9. If the option is available, deselect Create Combined Java/Flex Project With WTP.
10. Click Next.
11. Deselect Use Default Location For Local LiveCycle Data Services Server.
12. Set the root folder, root URL, and context root of your web application.

    The root folder specifies the top-level directory of the web application (the directory that contains the WEB-INF directory). The root URL specifies the URL of the web application, and the context root specifies the root of the web application.

    If you are using the integrated Tomcat application server, set the properties as follows:

    Root folder: C:\lcds\tomcat\webapps\lcds-samples\

    Root URL: http://localhost:8400/lcds-samples/

    Context root: /lcds-samples/

    Modify these settings as appropriate if you are not using the Tomcat application server.

13. Make sure that your LiveCycle Data Services ES server is running, and click Validate Configuration to ensure that your project is valid.
14. Verify that the Compile The Application Locally In Flex Builder option is selected.
15. Clear the Output Folder field to set the directory of the compiled SWF file to the main project directory.

    By default, Flex Builder writes the compiled SWF file to the bin-debug directory under the main project directory. To use a different output directory, specify it in the Output Folder field.

16. Click Next.
17. Set the name of the main application file to Chat.mxml, and click Finish.

Configure your project to use the Flex SDK that ships with LiveCycle Data Services ES

1. Select the project, and select Project > Properties.
2. Select Flex Compiler.
3. Select the Use A Specific SDK option under Flex SDK version.
4. Select LCDS, or whatever you named the LCDS SDK, when you performed the procedure in Add the Flex SDK to Flex Builder.
5. Click OK.

You can now edit, compile, and deploy an application that uses LiveCycle Data Services ES.

Edit, compile, and deploy a LiveCycle Data Services ES application in Flex Builder

1. Open src\Chat.mxml in your Flex Builder project.
2. Edit Chat.mxml to change the definition of the TextArea control so that it displays an initial text string when the application starts:

   <mx:TextArea id="log" width="100%" height="100%" text="My edited file!"/>
   
   

3. Save the file.

   When you save the file, Flex Builder automatically compiles it. By default, the resultant SWF file is written to the C:\lcds\tomcat\webapps\lcds-samples\testdrive-chat\bin-debug directory, or the location you set for the Output directory for the project. You should have set the Output directory to the main project directory in the previous procedure.

   Note: If you write the Chat.SWF file to any directory other than lcds-samples\testdrive-chat, deploy the SWF file by copying it to the lcds-samples\testdrive-chat directory.

4. Make sure that you have started the samples database and LiveCycle Data Services ES, as described in Running the LiveCycle Data Services ES sample applications.
5. Select Run > Run to run the application.

   You can also request the application in a browser by using the URL http://localhost:8400/lcds-samples/testdrive-chat/index.html.

   Note: By default, Flex Builder creates a SWF file that contains debug information. When you are ready to deploy your final application, meaning one that does not contain debug information, select File > Export > Release Build. For more information, see Using Adobe Flex Builder 3.

6. Verify that your new text appears in the TextArea control.

Create a linked resource to the LiveCycle Data Services ES configuration files

While working on the client-side of your applications, you often look at or change the LiveCycle Data Services ES configuration files. You can create a linked resource inside a Flex Builder project to make the LiveCycle Data Services ES configuration files easily accessible.

1. Right-click the project name in the project navigation view.
2. Select New > Folder in the pop-up menu.
3. Specify the name of the folder as it will appear in the navigation view. This name can be different from the name of the folder in the file system. For example, type server-config.
4. Click the Advanced button.
5. Select the Link To Folder In The File System option.
6. Click the Browse button and select the flex folder under the WEB-INF directory of your web application. For example, on a typical Windows installation that uses the Tomcat integrated server, select: install_root/tomcat/webapps/lcds-samples/WEB-INF/flex.
7. Click Finish. The LiveCycle Data Services ES configuration files are now available in your Flex Builder project under the server-config folder.
   Note: If you change anything in services-config.xml, you usually have to recompile your client-side applications and restart your server-side application for the changes to take effect.

Using mxmlc to compile client-side code

You use the mxmlc command line compiler to create SWF files from MXML, ActionScript, and other source files. Typically, you pass the name of the MXML file that contains an <mx:Application> tag to the compiler. The output is a SWF file. The mxmlc compiler ships in the bin directory of the Flex SDK. You run the mxmlc compiler as a shell script and executable file on Windows and UNIX systems. For more information, see Building and Deploying Adobe Flex 3 Applications.

The basic syntax of the mxmlc utility is as follows:

mxmlc [options] target_file 

The target file of the compile is required. If you use a space-separated list as part of the options, you can terminate the list with a double hyphen before adding the target file.

mxmlc -option arg1 arg2 arg3 -- target_file.mxml

To see a list of options for mxmlc, use the help list option, as the following example shows:

mxmlc -help list

To see a list of all options available for mxmlc, including advanced options, use the following command:

mxmlc -help list advanced

The default output of mxmlc is filename.swf, where filename is the name of the target file. The default output location is in the same directory as the target, unless you specify an output file and location with the output option.

The mxmlc command line compiler does not generate an HTML wrapper. Create your own wrapper to deploy a SWF file that the mxmlc compiler produced. The wrapper embeds the SWF object in the HTML tag. The wrapper includes the <object> and <embed> tags, and scripts that support Flash Player version detection and history management. For information about creating an HTML wrapper, see Building and Deploying Adobe Flex 3 Applications.

Compiling LiveCycle Data Services ES applications

Along with the standard options that you use with the mxmlc compiler, use the following options to specify information about your LiveCycle Data Services ES application.

• services filename

  Specifies the location of the services-config.xml file.

• context-root context-path

  Sets the value of the context root of the application. This value corresponds to the {context.root} token in the services-config.xml file, which is often used in channel definitions. The default value is null.

Edit, compile, and deploy the Chat.mxml file

1. Unzip flex-src.zip in the lcds\tomcat\webapps\lcds-samples directory, as described in Running the LiveCycle Data Services ES sample applications.
2. Open the file C:\lcds\tomcat\webapps\lcds-samples\testdrive-chat\src\Chat.mxml in an editor. Modify this path as necessary based on where you unzipped flex-src.zip.
3. Change the definition of the TextArea control so that it displays an initial text string when the application starts:

   <mx:TextArea id="log" width="100%" height="100%" text="My edited file!"/>
   
   

4. Change the directory to C:\lcds\tomcat\webapps\lcds-samples.
5. Use the following command to compile Chat.mxml:
   Note: This command assumes that you added the mxmlc directory to your system path. The default location is install_root\resources\flex_sdk\bin.

   mxmlc -strict=true 
       -show-actionscript-warnings=true 
       -use-network=true 
       -services=WEB-INF/flex/services-config.xml 
       -context-root=lcds-samples 
       -output=testdrive-chat/Chat.swf 
       testdrive-chat/src/Chat.mxml
   
   

   The compiler writes the Chat.swf file to the lcds-samples\testdrive-chat directory.

6. Start the samples database and LiveCycle Data Services ES as described in Running the LiveCycle Data Services ES sample applications.
7. Request the application by using the URL http://localhost:8400/lcds-samples/testdrive-chat/index.html.
8. Verify that your new text appears in the TextArea control.

Rather than keeping your source code in your deployment directory, you can set up a separate directory, and then copy Chat.swf to lcds-samples\testdrive-chat to deploy it.