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.