This article describes how you can access ColdFusion Services from a Flex application using the new MXML tags for ColdFusion Services available in ColdFusion 9. Also new to ColdFusion 9 are a set of services that expose the functionality of a few popular ColdFusion tags. The MXML tags interact with the services that ColdFusion exposes, which allows you to directly access the functionality available in ColdFusion without writing any CFML or web services. This tutorial walks you through the functionality by describing a step-by-step process of building an AIR (Adobe Integrated Runtime) application that uses the MXML tags to manipulate a PDF file.

If you would like to understand how to leverage the functionality of the services that ColdFusion exposes from a Flex client, this article is for you.

AIR application for PDF manipulation

With the introduction of ColdFusion Services in ColdFusion 9, you can take advantage of accessing the goodness of popular ColdFusion tags outside of ColdFusion through a web service call without writing any CFML. The following tags have been exposed as services in ColdFusion: cfpdf, cfdocument, cfmail, cfpop, cfimage and cfchart. These MXML tags are available in the cfservices.swc file under /CFIDE/scripts/AIR/ directory in a typical ColdFusion installation.

In the AIR application, a user can upload a PDF file. The AIR application performs operations on the uploaded PDF, and displays the manipulated PDF in the HTML container.

Figure 1. AIR Application that allows a user to upload a PDF file

Server-side configuration in the User Manager

To use the services that ColdFusion exposes, you must set permissions for the specific user for individual service; you can do so by using the User Manager in the ColdFusion Administrator. Once you set the permissions, you must pass the user id and password to the exposed services. The services that ColdFusion exposes are PDF Service, Document Service, Image Service, Chart Service, Pop Service, Mail Service and Upload Service. You can use the Upload Service to securely upload files to ColdFusion server so that other services can act on the uploaded file.

The exposed services are CFCs present in /CFIDE/services directory with a function under each CFC for every action of the tag. Each function takes in the serviceusername and servicepassword attributes which you will use for authentication.

Figure 2. The User Manager user interface in the ColdFusion Administrator allows you to manage permissions for your services

Server-side configuration for Allowed IP Addresses

The next step is to specify the allowed IP addresses. You can do so by accessing the Allowed IP Addresses page under Security in the ColdFusion Administrator. The IP addresses that you specify in this area are the only ones that can remotely access the exposed ColdFusion services. The values can be specific IP addresses, IP address range, or wild cards. In the allowed IP addresses list, you must also specify the client IP addresses that will serve the MXML tags that will access the exposed services.

Figure 3. Specifying allowed IP Addresses page in ColdFusion Administrator

Building the AIR Application

Once you have configured the server-side settings, the next step is to build the AIR application using Flash Builder. Create an AIR project in Flash Builder 4 and add /CFIDE/scripts/AIR/cfservices.swc in the library path of Flex Build path setting of the project.

You can find the ActionScript documentation for the MXML tags and the related classes under cfservices.swc in the coldfusion.service package of the The ActionScript 3.0 Reference for the Adobe Flash Platform documentation.

To use the MXML tags, you must specify the namespace within the WindowedApplication tag, as follows:

        <s:WindowedApplication xmlns:fx="http://ns.adobe.com/mxml/2009" 
				xmlns:s="library://ns.adobe.com/flex/spark" 
				xmlns:mx="library://ns.adobe.com/flex/mx"
				xmlns:cf="coldfusion.service.mxml.*"
				creationComplete="init();">

    

Using the Upload Service

One of the services exposed by ColdFusion lets you upload files to the server so that other services can act on the file on server. For instance, to manipulate a PDF file, you would first use the Upload Service to upload a PDF file on the server and then use the PDF Service to manipulate the PDF file on the server.

The AIR application uses FileReference and FileReferenceList classes from the Flex SDK to upload files to the server. The URL for the upload service using which files can be uploaded is available on the Util class in the coldfusion.service package coldfusion.service.Util.UPLOAD_URL.

Apart from using this upload URL you must pass the service username and password values in the data field of URLRequest.

        var urlReq:URLRequest = new URLRequest(fileUploadURL);
var variables:URLVariables = new URLVariables();
variables.serviceusername = conf.serviceUserName;
variables.servicepassword = conf.servicePassword;
urlReq.data = variables;
    

Once the application calls the upload on FileReference, the Upload Service responds with the data that contains the URL to uploaded file path on the server. The returned data can be accessed on the function registered as an event handler for the DataEvent.UPLOAD_COMPLETE_DATA event, as follows:

fileRef.addEventListener(DataEvent.UPLOAD_COMPLETE_DATA,dataHandler);

You can use the API Util.extractURLFromUploadResponse to directly extract the uploaded URL path that the server returned.

        private function dataHandler(event:DataEvent):void
{		        
				
var responseURL:String = Util.extractURLFromUploadResponse(event.data.toString());
…

Now you can use the retrieved URL in other MXML tags to access other services that ColdFusion exposes.

Using the config tag and the PDF tag

The config tag in the coldfusion.service.mxml package is an MXML tag that you can use to specify all the configuration information required to access the services exposed by ColdFusion. The config tag has properties for specifying the ColdFusion server IP or name, the port on which the ColdFusion server runs, the context root on the server if any, and the service user name and password.

        <cf:Config id="conf" 
cfServer="{cfip.text}"  
cfPort="{int(cfprt.text)}"
cfContextRoot="{cfcnxtrt.text}"  
servicePassword="{cfservicepassword.text}" serviceUserName="{cfserviceusername.text}"/>

    

The attributes set on the config tag apply across the entire application. You can override these values using the individual MXML tags, which also have these attributes.

Since the AIR application discussed manipulates PDF files, the application uses the PDF MXML tag. Every individual MXML tag has tag attributes, similar to its server tag counterparts. In addition to the tag attributes on the server tag, the MXML tag has result and fault attributes, where you can register result and fault event handlers. All the attributes of the config tag are also present on the individual service MXML tag. For instance, a PDF MXML tag can override the properties set on the config tag. The action attribute of the PDF MXML tag takes values such as getinfo, deletepages, extractpages, addwatermark, removewatermark, and so forth.

        <!-- Get Info-->
<cf:Pdf id="pdfgetinfo" action="GETINFO" source="{uploadedFileURL}" result="handleArrayResult(event)" fault="handleError(event)"/>
<!-- Delete Pages-->
<cf:Pdf id="pdfdeletepages" action="deletepages" pages="{pages.text}" password="{del_pwd.text}" source="{uploadedFileURL}" result="handlePDFResult(event)" fault="handleError(event)"/>
<!-- extract pages-->
<cf:Pdf id="pdfextractpages" action="extractpages" source="{uploadedFileURL}" password="{extrct_pwd.text}" pages="{extrct_pages.text}" keepBookmark="{bookmark.selectedItem.data}" result="handlePDFResult(event)" fault="handleError(event)"/>
<!-- addwatermark-->
<cf:Pdf id="pdfaddwatermark" action="addwatermark" source="{uploadedFileURL}" image="{watermarkImage}" result="handlePDFResult(event)" fault="handleError(event)"/>
<!-- removewatermark-->
<cf:Pdf id="pdfremovewatermark" action="removewatermark" source="{uploadedFileURL}" pages="{rmv_watermark_pages.text}" result="handlePDFResult(event)" fault="handleError(event)"/>
<!-- protect-->
<cf:Pdf id="pdfprotect" action="protect" source="{uploadedFileURL}" newUserPassword="{new_password.text}" permissions="All" result="handlePDFResult(event)" fault="handleError(event)"/>

    

Application User Interface (UI)

This application uses the Flex 4 SDK. The application user interface takes the ColdFusion server name/IP, the port on which the server is running, the context root if any specified on the server, and the service user name and password. Users can use the browse file button to select the PDF file to upload on the server and manipulate it based on the operation selected in the combo box.

Selecting a specific operation in the combo box opens up UI components corresponding to that operation in the ViewStack component.

By clicking the perform operation button, the application will upload the file to the server. The server returns the URL for the uploaded data. The application then passes the URL as the source to the PDF MXML tag for manipulation. The server returns the resulting URL for the manipulated PDF to the client. The client loads the resulting PDF in the HTML container UI Component.

Where to go from here

It is possible to build interesting Flex applications by making use of the MXML proxy tags. Also, you can use the Image MXML tag to build an image manipulation application similar to the PDF manipulation application. Similarly you can leverage the document service, pop service, mail service and chart service with less code using the MXML tags described in this article.

Check out the ColdFusion 9 documentation for Proxy ActionScript classes for ColdFusion services, which gives more detail on each of the MXML tag in Flex. As well, see The ActionScript 3 Reference for Adobe Flash Platform, which includes the ActionScript reference for the coldfusion.service package.

Acknowledgements

I would like to thank Jayesh Viradiya from the Adobe ColdFusion product team for helping to build the PDF Manipulation application discussed in this tutorial.

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License. Permissions beyond the scope of this license, pertaining to the examples of code included within this work are available at Adobe.

Accessing ColdFusion Services from Flex applications

by Rakshith Naresh

Content

Created

Page tools

Requirements

Prerequisite knowledge

User level

Required products

Sample files

AIR application for PDF manipulation

Server-side configuration in the User Manager

Server-side configuration for Allowed IP Addresses

Building the AIR Application

Using the Upload Service

Using the config tag and the PDF tag

Application User Interface (UI)

Where to go from here

Acknowledgements

More Like This

Tutorials & Samples

Tutorials

Samples

Products

Download

Support & Learning

Buy

Company