Requirements
 
Prerequisite knowledge
CFML, HTML Knowledge of JavaScript would be useful but not must
 
User level
All
 
 
Required products
Adobe ColdFusion Enterprise Edition (2016 release) (Download trial)
Adobe ColdFusion Builder (2016 release) (Download trial)

 
Introduction

ColdFusion 11 and ColdFusion Builder 3 provides a complete workflow for developing HTML5-based mobile applications. You can build your mobile application using the client-side CFML, HTML, and JavaScript. You can also test and inspect the application using Weinre (integrated in ColdFusion 11). Also, ColdFusion Builder allows you to debug your application using the built-in client-side CFML debugger. Once you have the application ready, you can package it using the PhoneGap Build integration feature of ColdFusion Builder 3.
 
The article “Build your first mobile app with ColdFusion 11” focuses on the coding aspect of mobile application development using ColdFusion. This article provides an overview of the entire mobile application development process using ColdFusion. Collectively, this article refers to mobile development features of ColdFusion as CFMobile.
 

 
Developing CFMobile Application

HTML5 mobile applications are developed using HTML, JavaScript, and CSS. What has made HTML5 suitable for mobile application development is availability of embeddable Web Browser component in most native mobile development SDKs (Software Development Kit), like Android and iOS. Just as you can insert a Text Box in a native mobile application, you can also insert a Web Browser component. These native SDKs also provide an interface to call functions from JavaScript running in the built-in browser component to native code and vise versa. This makes it possible to call the device APIs, like Contacts, Camera etc., from the JavaScript code. Libraries like PhoneGap provide a bridge (JavaScript to native APIs), using common programming APIs, that work across different mobile operating systems.  So, you can create a stand-alone mobile application using HTML5 and make use of the device APIs.
 
 
Client-side CFML
ColdFusion 11 enables you to develop mobile applications using CFML, HTML5, and PhoneGap. You do not need to know PhoneGap or be familiar with PhoneGap APIs or its development model. You just need to know ColdFusion Mobile device APIs, which encapsulates corresponding, one or more, PhoneGap APIs.
 
ColdFusion now supports client-side CFML. Client-side CFML is the code that executes in a browser, unlike server-side CFML, which is compiled and executed on the server to generate the HTML output that is sent to a browser. You wrap the client-side CFML in <cfclient> tag. Inside <cfclient> tag you can write tag style and/or script style (within <cfscript> tag) code.
 
 
Translation of CFML to JavaScript
When you develop a standalone mobile application, where pages are not served by any server, all the code in the application must be HTML, JavaScript or CSS. Mobile browser, in such applications, would not be able to execute CFML code, because there is no ColdFusion server to execute it. Client-side CFML must be translated to JavaScript before it could be executed in a browser. ColdFusion 11 does this in two cases:
 
  • When any page with <cfclient> tag is to be served (for example, in the case of mobile web application)
  • When mobile application is to be packaged so that it could be installed as a standalone application in a device.
 
Interoperability between client-side CFML and JavaScript
Since the client-side CFML (inside the <cfclient> tag) is translated to JavaScript, you can use the JavaScript functions within cfclient and call the cfclient functions from JavaScript. For example you can call console.log method of JavaScript from within cfclient.
 
<cfclient> <!--- client side function which will be translated to JS function ---> <cffunction name="getName" > <cfreturn "Ram"> </cffunction> <cfscript> //Calling JS function from cfclient console.log("In cfclient script"); </cfscript> </cfclient> <script> //Calling getName function which is declared in cfclient block document.write("Welcome " + getName() + " !"); </script>
This interoperability allows you to call APIs of JavaScript libraries like JQuery or AngularJS from cfclient to manipulate the DOM of the page.
 
 
Using the device APIs in cfclient
All mobile device APIs in ColdFusion start with cfclient prefix. It is followed by a type of device API, like camera, file etc. and then the function name. For example, API to take picture from cfclient code is – cfclient.camera.getPicture(), to get contacts – cfclient.contacts.getAllContacts().
 
See ColdFusion 11 documentation for all device functions and examples of each device API.
 
 
CFML support in cfclient
CFML support in cfclient is quite comprehensive. It includes:
 
  • Buitl-in datatypes like String, Numeric, Date, Struct, List, Array etc.
  • Data type related functions like structNew, arreyNew etc.
  • Member functions for data types e.g struct.isEmpty()
  • Basic launguage tags that are not specific to server side CFML e.g. cffunction, cfquery, cfloop, cfoutput, cfinclude, cfsavecontent etc. See all supported CFML tags.
  • ColdFusion built-in functions that are not specific to server side CFML e.g. isDefined, isNumeric, createObject etc. See all supported function.
  • Components (CFC). You must flag the component as client side by specifying client=true attribute. cfclient does not support cfinterface
  • Client side custom tags
 
Managing client-side database
It is possbile to create a standalone database application for mobile using cfclient. Most mobile browsers allow you to create client-side databases. You can use SQL statements to manage such databases. cfclient allows you to create and access client-side database using cfquery and queryExecute methods. For example, to create a table in a mobile application, you can write:
 
<cfclient> <!--- create table ---> <cfquery datasource="expenseDB"> create table if not exists expense ( id integer primary key, expense_date integer, amount real, desc text ) </cfquery> <!--- Get expense records from the table ---> <cfquery datasource="expenseDB " name="expenses"> select * from expense order by expense_date desc </cfquery> </cfclient>
The same can be written in script style:
 
<cfclient> <cfscript> queryExecute( "create table if not exists expense (id integer primary key, expense_date integer, amount real, desc text, receipt_path text)", [], {"datasource":"expenseDB"}); queryExecute("select * from expense order by expense_date desc", [], {"datasource":"expenseDB", "name":"rs"}); </cfscript> </cfclient>
This code may look similar to what you would have written in the server-side CFML. But unlike on the server-side, the database and tables are created on the client-side. Note that you do not need to create and configure datasources in client-side CFML. A datasource will be created automatically, if it does not exist.
 
 
Synchronous to Asynchronous API conversion
If you look at PhoneGap APIs, most of them are asynchronous – you call a function and along with necessary arguments to the function, you pass two additional arguments 1. success callback function and 2. error callback function. When the function is successfully executed, success callback function is called. If there is any error in executing the function, then the error callback function is called.
 
For a simple application with a few device API calls, this kind of programming model may not be an issue. But if you have to make many device API calls, one after the other, then you will need to embed the function calls within the success callback functions of previous calls. This makes the code look complicated and difficult to maintain.
 
ColdFusion 11 makes accessing asynchronous device API functions easy. Device APIs provided by ColdFusion can be called synchronously. ColdFusion converts them to asynchronous PhoneGap calls and also puts the code following the device API call in the success callback function of the PhoneGap function. If there is any error in the function execution, then ColdFusion throws an error. So wrap calls to device APIs within try-catch block to handle any errors. Transformation of synchronous device APIs calls to asynchronous PhoneGap API calls happen transparently.
 
Though ColdFusion provides synchronous access to device APIs, there are a few exception – some of the APIs are still asynchronous. Generally, if a function call leaves the device boundry (e.g. a call to a server) or if a function is event-based (e.g. watching change in geo-location coordinates or playing audio) then it remains asynchronous.
 
 
Enabling device APIs
If your application uses device APIs then you need to enable them in your code using this tag:
 
<cfclientsettings enabledeviceapi="true">
If this tag is used, it must be before the first cfclient tag in your application.
 
ColdFusion can also help you detect the device features. For instance, you can detect if the device browser supports canvas, touch events, drag and drop etc, and to get width, height and other properties of a device. See the device detection APIs for more details. To enable device detection APIs call:
 
<cfclientsettings detectdevice="true">
If you want to use both device APIs and device detection APIs, you can set them in one tag call:
 
<cfclientsettings enabledeviceapi="true" detectdevice="true" >
Note that any cfclient block after the enabling device APIs will be executed only after the device APIs are initialized properly. This is equivalent to the deviceready event of PhoneGap.
 
 
General Structure of CFMobile Application
Typically a CFMobile application that uses device APIs will have the following structure:
 
<!DOCTYPE HTML> <html> <head> <!-- include CSS and JS --> </head> <body> <!-- create HTML UI --> </body> </html> <cfclientsettings detectdevice="true"> <cfclient> <!--- call device APIs ---> <!--- Modify DOM, if required using JS APIs ---> </cfclient>
 
Caution about <cfinclude> in cfclient
You might be tempted to create HTML UI by including HTML templates using cfinclude inside cfclient. But we recommend that you do not directly put HTML tags in a CFM file that is included in cfclient.
 
index.cfm <cfclient> <cfinclude template=”include_me.cfm”> </cfclient> include_me.cfm <div id=”div1”> <!-- other HTML tags ---> </div>
Do not write include_me.cfm as shown above. Any non-CFML code in an included file (from cfclient) is added to the page using the document.write API. If this happens after the DOM of the page is already loaded, then you might see an unexpected behavior – it might overwrite the existing DOM content or JS events may not fire properly.
 
We recommend that you clearly separate the HTML code and the CFML code. If you want to update the HTML UI from the cfclient code, then use the DOM APIs. You can write include_me.cfm as:
 
<cfclient> <cfsavecontent variable="divHTML" > <div id="div1"> <!--- Other HTML tags ---> </div> </cfsavecontent> <cfset document.getElementById("parentId").append(divHTML)> </cfclient>
 
Writing cfclient code in ColdFusion builder
The CFML editor in ColdFusion Builder 3 provides you all the support for writing cfclient code. It provides you with code assist for device APIs, tags and functions. Within cfclient you will see the code assist only for tags and functions that are valid on the client-side – you will not see code assist displaying tags and functions for server-side CFML.
 
Similar to CFCs on the server-side, you get CFC introspection support for client-side CFCs. You can also jump to UDF definition by using the code hyperlink feature (CTRL/CMD + Click).
 
ColdFusion Builder also provides Mobile Project Wizard to get you started. You can use the built-in project template or create/use your own templates. See ColdFusion Builder 3 documentation for more details.
 
If you want to debug, inspect or package mobile applications from ColdFusion Builder, you must create a Mobile project or apply the Mobile nature to existing non-mobile projects (right click on a project and select Apply CFMobile Nature option). You should also make sure that the project is associated with correct ColdFusion Server, configured in the CF Servers view. Go to project properties->ColdFusion Server Settings and select a server to be associated with the project. Features like debugging, inspection and packaging will not work if you do not associate proper server with the project.
 

 
Running you mobile applications

During the development of your mobile application, you may want to run and test it at different stages. You can either run the application on a physical device or in a Simulator/Emulator. You can even run your application in a desktop browser, if the application does not use any device APIs – desktop browsers do not support device APIs like Contact, Camera etc.
 
However, you will have to package the application before you run it on a device or Simulator/Emulator. It may not be very efficient to do this frequently during application development. Therefore, the ColdFusion Team has developed native applications, we call them ColdFusion PhoneGap Shell applications, in which you can run and test your application simply by opening the URL.
 
 
PhoneGap Shell Applications
PhoneGap Shell Applications embeds web browser and it is built using the PhoneGap library, so it supports PhoneGap APIs. If you want to quickly test your application on device/simulator/emulator without packaging and installing it, then download and install  the PhoneGap Shell application.
 
We have created an Android APK file for the Shell application, which you can directly install on any Android device. Copy the APK file on to device storage and open it to start the installation process.
 
Installing the shell application on iOS is not easy. You will have to sign the iOS Shell application with you own certificate (developer or distribution certificate obtained from Apple). We have made the source code (Xcode project) avilable for iOS shell application that you can open in Xcode and install the application in a Simulator or on a physical device. 
 
To test the application using the Shell application on a device, it should be on the same network as the CF server. In other words, the CF server should be accessible from the device.
 
Following are the screen shots of the Shell application on Android and iOS:
 
Android PG Shell Application
 
Figure 1: Android PG Shell Application
 
iOS PG Shell Application
 
Figure 2: iOS PG Shell Application
 
When testing the application in the Shell application, it is important that the application includes:
 
<cfinclude template="/CFIDE/cfclient/useragent.cfm" >
This is a server side include and could be placed in the Application.cfm file. But do not include the Application.cfm file while packaging the application.
 

 
Inspecting you mobile application

ColdFusion 11 has integrated Weinre server to inspect applications running on mobile devices. To inspect a CFMlobile application, you first need to start the Weinre server. Open the ColdFusion Administrator and go to ‘Debugging & Logging’  and select ‘Remote Inspection Settings’ . Click ‘Start Weinre Server’ button.
 
Remote Inspection Admin Settings
 
Figure 3: Remote Inspection Admin Settings
 
When the serverhas been sucessfully started, you will see a link at the bottom of the page for Weinre client. Click the link and open the Weinre client page. Initially, you will not see any target, which means no device is currently connected.
 
Weinre Client
 
Figure 4: Weinre Client
 
During development, you can easily inspect your application using the Shell application mentioned above. Simply add the ‘inspect’ parameter to the URL of the application.
 
For example, if your application URL is http://<ip_of_cf_server>:8500/CFMobileExpenseTracker then append ‘?inspect’ to it (http://<ip_of_cf_server>:8500/CFMobileExpenseTracker/?inspect) and open the application in Shell application. You should see a target link visible on the Weinre client page.
 
Weinre Target Connected
 
Figure 5: Weinre Target Connected
 
If you have more than one devices connected, then you will see multiple targets in Weinre client. Even if you run the application again, Weinre client will display it as a separate target. If there are more than one targets, click on a target you want to inspect. You can then inspect various aspects of the application. Click on Elements button to inspect the DOM elements. You can change the CSS values or even the HTML content of your application and see the changes immediately on the mobile device.
 
Inspect Elements
 
Figure 6: Inspect Elements
 
Click on Resources tab to inspect client side (in mobile device) database.
 
Inspect Database
 
Figure 7: Inspect Database
 
It shows the content of the database in your application running on mobile device. You can even execute the SQL statements by clicking on a database node:
 
Execute SQL in Weinre Client
 
Figure 8: Execute SQL in Weinre Client
 
Changes to the table happen in the mobile application running on a device.
 
Click on Console tab to see the JavaScript console messages logged from your mobile application.
 
Inspect JavaScript Console Messages
 
Figure 9: Inspect JavaScript Console Messages
 
 
Inpsecting packaged application
If you want to inspect a packaged application, then you can’t obviously append the ‘inspect’ parameter to the URL, because there is no application URL (or atleast not visible to you) in a packaged application. In this case, you will need to specify the URL of the Weinre server in a project property. In ColdFusion Builder, right click the project (in Navigator View) and select ‘Properties’ menu option. In the properties window, go to ‘ColdFusion Mobile Project’ and then to ‘Inspect’ tab. Enter the URL of the Weinre server. If you want to use the built-in Weinre server, then the Weinre server IP will be same as the ColdFusion server IP.
 
Mobile Project Properties for Remote Inspection
Ensure that the URL displyed at the bottom is the correct URL and is accessible. You can then package the application by right clicking the project (in Navigator View) and selecting ‘PhoneGap Debug’->’Generate Inspect Build’ (we will see how to pacakge an application later in this article).
 
 
Figure 10: Mobile Project Properties for Remote Inspection

 
Debugging Mobile Application

ColdFusion Builder 3, along with ColdFusion 11 supports debugging CFMobile applications running on Mobile devices. But you can also debug web applications created with cfclient. You can set breakpoints, perform step operations and inspect the variables.
 
Just as Shell application makes inspection of moble application easy, as we saw above, it also makes debugging application easy. You do not need to package the application to run and debug it.
 
To launch the debugger, right click the project you want to debug and select ‘Debug As’->’ColdFusion Client Application’ option. If it is successfully launched, you will see the debug configuration with a single ‘CFClient Thread’ in the Debug window of ColdFusion Debugging perspective (to open ColdFusion Debugging perspective, select Window->Open Perspective->Other and then select ColdFusion Debugging perspective.)
 
Set breakpoints in your code by opening the file in ColdFusion Builder and double click in the left margin.
 
Setting BreakPoint
 
Figure 11: Setting BreakPoint
 
Open the application URL in the Shell application. When the code where the breakpoint is set is about to be executed, you will see that the execution stops there and the line is highlighted in the editor. If you switch to ColdFusion Debugger perspective, you will see that options to step over/in are enabled in the toolbar as well as in the main (Run) menu.
 
Debugger Suspended at Breakpoint
 
Figure 12: Debugger Suspended at Breakpoint
 
You can inspect the current variables in Variable window. If you want to watch a variable, you can go to the Expression window and add the variable name there. You can step over/into (function) or continue the execution.
 
 
Debugging packaged application
It you want to debug packaged application, there are a couple of steps involved before you launch the debugger. First, set the client debugger preferences. Go to Window->Preferences menu and open ColdFusion->Client Debug/Inspect Setting page.
 
Client Debugger Preference Settings
 
Figure 13: Client Debugger Preference Settings
 
You may not need to do anything in this page, but just make sure that the IP address is of the same machine where the ColdFusion Builder is running and that the port specified is not already in use.
 
Next, package the application for debugging. Right click the project (in Navigator view) and select PhoneGap Debug->Generate Debug Build option. Once the build is created, install the application in a device and run it. When the code where the breakpoint is set is about to be executed, you will see that the execution is stopped and ColdFusion Builder highlights the line. You can then perform variaous debugging tasks, as explained above. Note that you can debug a packaged application only from the IP address that you had selected in the preferences.
 

 
Packaging CFMobile applications

ColdFusion Builder uses the PhoneGap Build services to package mobile applications. Therefore, you need to have an account with PhoneGap Build to package mobile applications from ColdFusion Builder. You can signup at http://build.phonegap.com. You also need to enter your account details in ColdFusion Builder preferences. Open menu Window->Preferences and then go to ColdFusion->PhoneGap.
 
PhoneGap Build Preference Settings
 
Figure 14: PhoneGap Build Preference Settings
 
Enter the email id and password that you have regestered with the PhoneGap Build. If you want to generate an iOS build, enter the iOS key details. Visit Apple Developer Support Center for information about code signing certificates.
 
The Android key details are required only if you are planning to distribute your application on Google Play Store. Otherwise, you can leave these fields blank. The PhoneGap Build will generate the build even without the Android key details.
 
Click OK to save and close the preferences.
 
 
Selecting files to package
You need to select the files that you want to include in the mobile application. Right click the project in the Navigator view and select Properties. Select ‘ColdFusion Mobile Project’ from the left pane and make sure ‘Resource Selection’ tab is open. Select the files that you want to include in the packaged application.
 
File Selection for Packaging
 
Figure 15: File Selection for Packaging
 
 
Selecting Device APIs for packaged application
You need to instruct the PhoneGap Build server about the device APIs to enable in the application. To do that, open ‘ColdFusion Mobile Project’ properties (as desribed above) and select PhoneGap tab. Click New button and select ‘Feature’ in the left pane. Select all the features that your application uses in this page.
 
PhoneGap Feature Selection
 
Figure 16: PhoneGap Feature Selection
 
 
Packaging the application
Right click the project name (in Navigator view) and select ‘Generate PhoneGap Build’ option from the pop-up menu. ColdFusion Builder starts the process of packaging the application and adds a new application entry in the PhoneGap Status view, if it is not already there. Along with ColdFusion Server, ColdFusion Builder compiles the application, creates a bundle to upload to PhoneGap Build Server, uploads the bundle and waits for the response from the PhoneGap Build server. When the build is ready, you will see the ‘Download’ buttons for the application. Click on the appropriate Dowload button to dowload the IPA (for iOS) or the APK (for Android) file.
 
PhoneGap Status View in ColdFusion Builder
 
Figure 17: PhoneGap Status View in ColdFusion Builder
 
You can install the APK file on a device by copying it to the device storage and opening the file. Use iTunes to install IPA file on an iOS device.
 

 
Where to go from here

 
ColdFusion 11 and ColdFusion Builder 3 provides a complete workflow for mobile application development – code, test, debug, and package. In this article, we read in some details about each of these aspects of mobile application development. Refer to ColdFusion Mobile development documentation for further details. Visit ColdFusion team blog where you will find many articles on how to use the device APIs with fully functional application code. You can also watch short videos on how to use mobile development features of ColdFusion at YouTube channel.
 
 
Share your feedback about this page or the Adobe Developer Connection in general by using Adobe forums