Accessing ColdFusion Services from Flex applications
Created
27 September 2010
Requirements
Prerequisite knowledge
You should have a basic understanding of ActionScript and Flex programming.
User level
Intermediate
Required products
- ColdFusion (Download trial)
- Flash Builder 4 (Download trial)
Sample files
- mxml_cf_services (1761 KB)
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.
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.
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.
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.
More Like This
- Working with spreadsheets in ColdFusion
- Moving from Dreamweaver to ColdFusion Builder 2
- Extending ColdFusion Builder
- Working with PDF forms in ColdFusion
- Developing Adobe AIR offline applications using the ColdFusion 9.0.1 ActionScript ORM Library
- Using ColdFusion 8 and Flex 3 to export visual components
- Build a ColdFusion-powered Flex application
- Beyond HTML: Using Ajax, PDF, and more to create engaging applications with ColdFusion 8
- Using DDX to unlock the potential of PDF manipulation in ColdFusion 8
- What's new in ColdFusion Builder 2
Tutorials & Samples |
Samples
ColdFusion Blogs |
More |
ColdFusion Cookbooks |
More |
