Archive for February, 2007

Hello World Application for Flex using ColdFusion Remoting

Feedback from a variety of sources has convinced me that we need a simpler on-ramp to Flex for ColdFusion users. The Getting Started with Flex 2 book has a CF-related lesson, however, it talks about the event gateway, a useful, but relatively complex feature. What we should have provided (and will provide in future releases) is a lesson on using the mx:RemoteObject tag to invoke a method on a CFC, a much more commonly used feature.

There are three ways to get started using the mx:RemoteObject tag to retrieve data from a CFC:

  • Use the default remoting destination, ColdFusion
  • Create CFC-specific destinations in the cf_root/WEB-INF/flex/services-config.xml file
  • Use the ColdFusion Extension Wizards in Flex Builder. As of the Flex Builder 2.0.1 update, the installer for the ColdFusion Extensions is in a subdirectory directly beneath your Flex Builder install root.

This posting describes the first two and will help you understand the third. For information on the ColdFusion Extension Wizards, I recommend viewing Dean Harmon’s presentations on the ColdFusion Developer Center.

These instructions cover configuration and usage for a simple Hello World application. For detailed information on using the Flash Remoting Update (the official name of this feature), see Using ColdFusion MX with Flex 2. This document includes data type mappings, which are always important with features like this.

Background

  • If you are using Flex to access data through ColdFusion, you typically use mx:RemoteObject instead of mx:WebService because mx:RemoteObject offers better performance.
  • You manage Flex mx:RemoteObject access to ColdFusion through destination elements in the cf_root/WEB-INF/flex/services-config.xml file.
  • This file contains a destination named ColdFusion that allows you to access any remote CFC method.
  • You can create CFC-specific destinations in the services-config.xml file, which provides a more secure configuration.

Using the default remoting destination
To use the default remoting destination, you need a CFC with at least one remote method and a Flex application.

  1. Create a Hello World CFC:

    <cfcomponent name=”User”>
      <cffunction name=”sayHelloString” access=”remote” returnType=”string”>
        <cfreturn “Hello World!”>
      </cffunction>
    </cfcomponent>
  2. Save this file as cfweb_root/myApplication/components/User.cfc
  3. Create a Flex Builder project and choose ColdFusion Flash Remoting Service, which automatically adds the –services compiler argument, pointing to the services-config.xml file. You’ll also need to specify:
    • Root folder (for example C:/CFusionMX/wwwroot) – This is the directory that contains the WEB-INF/flex directory, and the WEB-INF/flex directory must contain a services-config.xml
    • Root URL (for example, http://localhost:8500)
    • Context root (CF J2EE only)
    • Save your project in a directory under the ColdFusion webroot. Do not use the default location.
  4. Create the MXML file. The following (simple) file invokes the sayHelloString method in User.cfc:

    <?xml version=”1.0″ encoding=”utf-8″?>
    <mx:Application xmlns:mx=”http://www.adobe.com/2006/mxml” layout=”absolute”>
      <mx:RemoteObject
        id=”myCfc”
        destination=”ColdFusion”
        source=”myApplication.components.User”
        result=”remotingCFCHandler(event)”/>
     
      <mx:Script>
      <![CDATA[
        import mx.rpc.events.ResultEvent;
        import mx.utils.ObjectUtil;
     
        private function remotingCFCHandler(e:ResultEvent):void
        {
          returnedText.text = ObjectUtil.toString(e.result);
        }
     
        private function callRemotingCFC():void
        {
        // invoke sayHelloString method on User.cfc
          myCfc.sayHelloString();
        }
        ]]>
      </mx:Script>
      <mx:VBox>
        <mx:TextArea id=”returnedText” />
        <mx:Button label=”Show” click=”callRemotingCFC()”/>
      </mx:VBox>
    </mx:Application>
  5. Compile and run the application.

Using a CFC-specific destination
To use a CFC-specific destination, you need to modify the services-config.xml file, create a CFC with at least one remote method, and create a Flex application.

  1. The first three steps are the same as the previous procedure.
  2. Open the cf_root/WEB-INF/flex/services-config.xml file and create a destination element for your CFC. The source element specifies the path to the CFC, relative to the webroot:

    <destination id=”helloworld”>
      <channels>
        <channel ref=”my-cfamf”/>
      </channels>
      <properties>
        <source>myApplication.components.User</source>
          <!– define the resolution rules and access level of the cfc being invoked –>
          <access>
          <!– Use the ColdFusion mappings to find CFCs, by default only CFC files under your webroot can be found. –>
          <use-mappings>false</use-mappings>
          <!– allow “public and remote” or just “remote” methods to be invoked –>
          <method-access-level>remote</method-access-level>
        </access>
     
        <property-case>
          <!– cfc property names –>
          <force-cfc-lowercase>false</force-cfc-lowercase>
          <!– Query column names –>
          <force-query-lowercase>false</force-query-lowercase>
          <!– struct keys –>
          <force-struct-lowercase>false</force-struct-lowercase>
        </property-case>
      </properties>
    </destination>

  3. Create a new Flex Builder project, as described above, or reuse the existing project.
  4. Code an mx:RemoteObject tag, but specify the new destination in the destination attribute and omit the source attribute.
  5. Compile and run the application.

Using the command-line compiler
If you’re using the command-line compiler, you must include the –services and -context-root compiler arguments The –services argument specifies the location of the services-config.xml file. The -context-root argument specifies the context root of the ColdFusion web application (for the standalone version, specify /). For example:


C:\CFusionMX7\wwwroot\hello>c:\flexsdk201\bin\mxmlc –services c:\CFusionMX7\ww
wroot\WEB-INF\flex\services-config.xml -context-root=/ hello.mxml

If you use the command-line compiler, you’ll need to create a wrapper file manually, as described in the Creating a Wrapper discussion in Building and Deploying Flex 2 Applications.

What’s next?

  • If you use Flex Builder, install and run the ColdFusion Extension Wizards in Flex Builder. This tool creates MXML, ActionScript, and ColdFusion code, allows you to view and select data from ColdFusion data sources, and provides more of a real-world architecture.
  • For reference, see Using ColdFusion MX with Flex 2.
  • For more usage and configuration information, see the RPC chapters of the Flex 2 Developer’s Guide.

Drag and Drop documentation update

We rewrote the Drag and Drop chapter of the Flex Developer’s Guide. The main changes were:

- Simplified the explanation of the drag/drop operation
- Added many new examples
- Added information and examples on performing a copy operation with the list-based controls (Tree, List, DataGrid) which is not handled by default
- Added information about overriding the default event handlers used by the list-based controls

Download the new chapter’s PDF: Using Drag and Drop

Here’s a ZIP file of all the code samples (full applications) used in the document: Code Samples.

Finding and Using Flex Documentation

Matt Chotin posted similar information to Flexcoders last week, and it reminded me that many people don’t know about the Flex Documentation page. The Flex Documentation page contains links to the latest and greatest Flex docs in PDF and LiveDocs format. It also contains a link to a ZIP file that contains the complete documentation for local use.

Now that we have that out of the way, let’s look at the complete range of formats and locations:

  • The Flex Builder Help system contains all Flex documentation in HTML format. Each page contains a link to the same page running on LiveDocs. We leverage the Eclipse Help engine for table of contents, search, and dynamic help functionality.
  • LiveDocs contains all Flex documentation in HTML, along with comments from community and Flex-team members. We occasionally update pages on LiveDocs and use the LiveDocs Related Topics functionality to provide links to related pages, such as Flex Quick Starts. We leverage adobe.com google search and provide a JavaScript-based table of contents.
  • Release Notes provide a high-level description of each product, along with a list of known issues and, for an update release like Flex 2.0.1, fixed bugs.
  • The Installation page provides install instructions for Flex Builder, Flex Data Services, Flex SDK, and Flex Charting.

The one you use depends on the way you work. If you use Flex Builder, the Flex Builder Help system is a handy and fast tool that links to LiveDocs for the latest and greatest information. Tip: Have you tried Flex Builder Dynamic Help? Dynamic Help, which is an option on the Help menu) provides links to the current tag and changes the links in near real time as you move through your file.

If you’re not using Flex Builder, try LiveDocs. You can either display the home page and navigate using the table of contents or use a search engine to hone in on the right page. Also, if you’re offline for a significant portion of your development time, we suggest downloading the complete doc set (50Mb ZIP file) and using it locally.