Client-side CFML (for mobile development)

document

This document describes the client-side CFML capabilities. Client-side CFML allows the development of client-side applications using CFML. Client-side CFML can be used to develop CF-based mobile applications wherein the CFML code in the application is converted to HTML/JavaScript by the ColdFusion Server.

The new <cfclient> tag

<cfclient> is a new tag introduced in ColdFusion 11 to support mobile development. This tag has been introduced to convert the CFML code that it encloses into JavaScript code. A ColdFusion developer can now develop mobile applications using CFML by leveraging the transformation functionality offered through the <cfclient> tag. So, you do not need to know JavaScript to write mobile web applications.

Even if you are an experienced JavaScript developer, <cfclient> can still be used to simplify the mobile application development as it abstracts the complexities involved in building a mobile application using JavaScript and HTML.

Note: The CFML constructs to be executed at the client-side have to be embedded within the <cfclient> tag. Not all tags, functions, and CFML functionalities are supported for conversion to HTML/JavaScript. For the complete list of CFML tags and functions that <cfclient> tag supports, see Supported CFML language constructs and Supported CFML tags.

The rationale behind choosing to support only a certain set of tags and functions is to strengthen the relevance of CFML for client-side mobile application development.

How does the transformation work

Let us see how the regular <cfoutput> tag gets rendered on a browser.

Your ColdFusion code:

What the browser gets from the ColdFusion Server:

Hello World

Let us revisit the Hello World <cfclient> example mentioned in the A customary hello world example section.

Now, if your ColdFusion code is:

Check the source of the web page translated by ColdFusion Server. It will be pure JavaScript wrapped in an HTML page.

As you can infer, the CFML code available in the <cfclient> block gets converted to JavaScript. Though this example is simple, the translation works the same way for complex CFML code.

Supported CFML language constructs

The following CFML language constructs are supported in client-side CFML, which includes all the logical/conditional and flow constructs:

• IF/ELSE/ELSEIF
• WHILE/DO WHILE
• CFLoop/CONTINUE/BREAK
• SWITCH/CASE/DEFAULTCASE
• TRY/CATCH/FINALLY
• FOR
• TERNARY OPERATOR
• THROW
• IMPORT
• INCLUDE
• ABORT
• EXIT
• FUNCTION/ARGUMENT/RETURN
• FUNCTION INVOCATION
• CUSTOM TAGS

Supported CFML tags

The following CFML tags are supported in client-side CFML:

• CFSET
• CFOUTPUT
• CFINCLUDE
• CFSCRIPT
• CFOBJECT
• CFINVOKE
• CFMODULE
• CFSAVECONTENT
• CFPARAM
• CFPROPERTY
• CFCOMPONENT
• CFABORT
• CFEXIT
• CFRETURN
• CFBREAK
• CFCONTINUE
• CFQUERY
• CFQUERYPARAM
• CFFLUSH

Note that member functions are also supported in client-side CFML. The <cfparam> tag does not support device APIs.

Where client-side CFML differs from the server-side CFML

Though you can have any valid CFML code in the <cfclient> code block, there are behavioral restrictions on the CFML tags and constructs. Some of the behavioral restrictions are listed here:

• The keys for implicit structure will be static. For instance, you cannot declare {“#a#”:”value”}. Also, {a:a} will become {‘a’:a}.

• In the <cfinclude> tag, dynamic template name(##) is not supported:

  <cfclient> <cfset x=“abc.cfm”> <cfinclude template=“#x#”> </cfclient>

  This limitation is applicable for the <cfmodule> tag too.

• Also, the <cfinclude> tag only supports files with extensions .cfm, .js, and .css.
• The Boolean behavior differs in <cfclient>. For example, In ColdFusion, 0/1, true/false, ‘true’/’false’, yes/no are all treated as Boolean. However, in <cfclient>, only true/false are Boolean.
• In ColdFusion, x=“1” is still a number even with the quotes. However, <cfclient> treats this as a string. Ensure that you follow strict data types for the functions to avoid abnormal behavior.
• In ColdFusion, <cfset x=“1a”> is a date but inside <cfclient> it is not. Note that <cfclient> follows JavaScript date format instead of ColdFusion date format.
• In ColdFusion, <cfset x = 1/2> is 0 but inside <cfclient> it is 0.5.
• ColdFusion server exceptions will not work on client side.

• The format of the Date/Time/DateTime objects created by createDate, createTime, and createDateTime respectively differs from the server side CFML behavior. For instance, the following code:

  <cfoutput>#CreateDateTime( 1776, 7, 4, 12, 59, 0)#</ cfoutput >

  On server side, you will get the output:
  {ts '1776-07-04 12:59:00'}
  
  When you use parseDateTime on client side CFML, ensure that you pass the output obtained from the creatDateTime function as an argument to create the DateTime object.

• The following code will not work because of the strict data types:

  <cfset date1 = #createdatetime(2001,07,04,6,30,45)#> <cfset mytimespan = #createtimespan(2, 1, 16, 30)#> <cfoutput>#date1 + mytimespan#</cfoutput> <cfoutput>#DateFormat(date1 + mytimespan)#</cfoutput>

  
  In the above example, timespan when added to datetime, becomes a string.

• Note: The DateFormat function does not work with Firefox and Internet Explorer. In Chrome, the function displays output correctly. A possible workaround is to use a function like createDateTime(2003,6,11,10,50,32) and pass the date object to dateFormat function.
• Function naming convention – Functions supported by browser and PhoneGap will have server CFML syntax. For instance, FileXXX. The PhoneGap functions will follow the Object access approach. For instance, Camera.XXX.
• Scopes available on server side is not supported on client side.
• Argument Collection will not be supported for passing arguments.

• arraySort function differs in the behavior when its numeric numbers like 0002, 00001, 1.0E+5 and the sort type is text.

  <cfscript> anumeric = arrayNew(1); anumeric[1] = 01; anumeric[2] = 001; anumeric[3] = 1; anumeric[4] = 1.001; anumeric[5] = 1.1; anumeric[6] = 1.101; anumeric[7] = 1.109; anumeric[8] = 1.11; anumeric[9] = 2; anumeric[10] = 02; anumeric[11] = 00002; anumeric[12] = 20; anumeric[13] = 50; anumeric[14] = 1.0E+2; anumeric[15] = 100; anumeric[16] = 1000; anumeric[17] = 1.0E+5; </cfscript> <cfset arraySort(anumeric, "text")> <cfloop array="#anumeric#" index=i> <cfoutput>#i#</cfoutput> </cfloop>

  Actual output for the above code:
  1 1 1 1.001 1.1 1.101 1.109 1.11 100 100 1000 100000 2 2 2 20 50
  Expected output for the above code:
  00002 001 01 02 1 1.001 1.0E+2 1.0E+5 1.1 1.101 1.109 1.11 100 1000 2 20 50
  This is because JavaScript represents 02, 002, 2 in the same way as '2' and hence differs in sort.

• Duplicate function behavior for struct differs when the struct internally has a reference to another struct more than once. On server side, changing the value in the duplicated struct’s referred key will also change the values at other referred points. However, in the case of client side CFML, this does not happen.

  <cfset str1 = {name: 'str1', value: 'org struct'}> <cfset str2 = {name: 'str2', value1: str1, value2: str1}> <cfset str2dup = duplicate(str2)>

  In the above example, if you change the value of str2dup.value1.value, on the server side,  value of str2dup.value2.value is also changed automatically as they both refers to same structure. But on client side, this is not the behavior.

• On client side, calling a super function from an included CFM or CFC is not supported.
• Positional arguments are not supported.

When you use the <cfoutput> tag inside the <cfclient> tag, the contents of the <cfoutput> tag is not immediately processed. Hence, you may encounter certain issues while using this code:

In this case, while the document.getElementById() statement is being invoked, cfoutput is not processed. Hence, you will not find an element with id "result", which will result in a runtime error.

In this case, you can directly write to the DOM, instead of using cfoutput:

Or another workaround is to use flush explicitly after <cfoutput>:

If you follow this approach, ensure that the HTML content in the cfoutput is well formed.

Client-side CFML and JavaScript

From CFML, when you are invoking JavaScript:

• Use the correct case for function name and variable name when referencing CFML functions and variables from CFML as client-side CFML is case sensitive.

From JavaScript, when you are invoking CFML:

• Use the correct case for function name and variable name when referencing CFML functions and variables from JavaScript as client-side CFML is case sensitive.

Loading JavaScript files

You can load content of the JavaScript files in your ColdFusion code using the loadJSFile() function as shown in the following example:

You can also use <cfinclude> to load a JavaScript file.

Synchronous and asynchronous function calls

ColdFusion automatically determines whether a function call is synchronous or asynchronous. However, if you need to invoke an asynchronous function in a synchronous mode, you can use the invokeInSyncMode function. The function call just needs to be wrapped around with the invokeInSyncMode function call. For instance, invokeInSyncMode (myAsyncFunc(arg1,arg2)). See InvokeCFClientFunction.

Asynchronous behavior

As a ColdFusion developer, you have always been using synchronous programming models. However, programming client applications using JavaScript needs to follow an asynchronous model. Fortunately, ColdFusion does most of the synchronous to asynchronous translation automatically.

For instance, see the following script:

The ability to use asynchronous functions in <cfclient> through the ‘known’ synchronous model provides a lot of convenience while building mobile applications using ColdFusion.

Since ColdFusion automatically translates synchronous code to asynchronous code, exception handling becomes easier in client code.

The behavior of certain tags has been modified to support the asynchronous behavior. In the process, functionalities of some tags may differ. For instance, <cfloop> does not support the following features when used along with <cfclient>:

• Looping over a COM collection
• Looping over a date or time range
• Looping over a directory

Support for ColdFusion Functions

You can start writing mobile applications in ColdFusion using existing data types and functions. The <cfclient> tag supports CFML data types and functions.

The following functions depict usage of data types and functions in your ColdFusion-based mobile projects.

Using CFML simple types

The following example shows the usage of simple data types:

Using CFML structures

The following example shows the usage of simple structures:

Using CFML arrays

The following example shows the usage of arrays:

Using CFML functions

The following example shows the usage of functions:

List of all supported functions

The following list shows all the supported Array functions in client-side CFML:

• arraySlice
• arrayAppend
• arrayIsDefined
• arrayAvg
• arrayIsEmpty
• arrayClear
• arrayLen
• arrayMax
• arrayNew
• arrayMin
• arraySort
• arrayDelete
• arrayToList
• arrayPrepend
• isArray
• arrayResize     
• listToArray
• arraySet        
• arrayFind
• arrayFindAll
• arraySum
• arraySwap
• arrayFindNoCase
• arrayFindAllNoCase

The following Array function is NOT supported:

• arrayFilter (closure function)

The following list shows all the supported Structure functions in client-side CFML:

• isStruct
• structDelete
• structAppend
• structInsert
• structClear
• structIsEmpty
• structCopy
• structKeyExists
• structCount
• structNew
• structFind
• structUpdate
• structFindKey
• structFindValue
• structGet
• structKeyArray
• structKeyList
• structSort

The following list shows all the supported List functions in client-side CFML:

• find
• findNoCase
• findOneOf
• formatBaseN
• lCase
• left
• len
• listAppend
• listChangeDelims
• listContains
• listContainsNoCase
• listDeleteAt
• listFind
• listFindNoCase
• listFirst
• listGetAt
• listInsertAt
• listLast
• listLen
• listPrepend
• listQualify
• listRest
• listSetAt
• listSort
• listToArray
• listValueCount
• listValueCountNoCase
• replaceList
• valueList

The following List function is NOT supported:

• getClientVariablesList

The following String functions are NOT supported:          

• binaryEncode
• binaryDecode  
• charsetEncode
• charsetDecode
• toBase64
• toBinary
• toString
• uRLDecode
• uRLEncodeFormat
• lSParseNumber
• lSParseCurrency
• lSParseEuroCurrency
• lSIsDate
• lSIsNumeric
• lSIsCurrency

The following Regex functions are supported:

• rEFind
• rEMatch
• rEFindNoCase
• rEMatchNoCase
• rEReplace
• rEReplaceNoCase

The following Math function is NOT supported:

• precisionEvaluate

The following Date functions are NOT supported:

• createODBCDate
• createODBCTime
• createODBCDateTime
• lSDateFormat
• lSIsDate
• lSParseDateTime
• lSTimeFormat

The following utility functions are supported:

• isBoolean
• isDefined
• decimalFormat
• isNumeric
• dollarFormat
• isNull
• htmlCodeFormat
• isSimpleValue
• htmlEditFormat
• isValid
• numberFormat
• createUUID

Support for custom tags

You have been using custom tags in ColdFusion for the past few releases of ColdFusion. Custom tags allowed you to extend CFML by adding your own tags to the ones shipped with ColdFusion. Custom tags can now be created in <cfclient> too. The following sections provide an overview of the supported features and restrictions while using custom tags for building mobile applications.

Note: Application and Server mappings are also supported in custom tags.

Paths for custom tags

Custom tags are detected when they are made available in the following locations:

• The custom tag available in the same directory as the calling page
• The custom tag available in the cfusion/CustomTags directory
• The custom tag available in sub-directories under the cfusion/CustomTags directory
• The custom tag available in server/application mapped folders

Invoking custom tags

The custom tags can be invoked in the following ways:

• Using the cf_<tagname>. For instance, by calling <cf_mytag>
• Using the <cfmodule> tag. For instance, <cfmodule template="../cf_mytag.cfm">
  • Also, <cfmodule name=”tags.mytag”>
  • For the <cfimport> tag, we use the taglib to import the custom tags:
    • For instance, <cfimport prefix = “myTags” taglib = “/custom”>
    • The DOT(.) notation can be used to access custom tags available inside sub directories. For instance, use <cfmodule name = “tags.mytag”>

<cfimport> supports only path to custom tags and hence you cannot have JSP tag libraries.

Passing values

You can pass values to a custom tag using a name-value pair:

Also, multiple name-value pairs can be passed to a custom tag:

To access the arguments passed to the custom tag, the custom tag CFM file can use the attributes scope as follows:

To send the data back to the calling page, the custom tag CFM file can use the Caller scope as follows:

You can also pass a struct to the custom tag:

Tag instance data

When a custom tag page executes, ColdFusion keeps data related to the tag instance in the thisTag structure. You can access the thisTag structure from within your custom tag to control processing of the tag.

To determine if an end tag is specified, use the hasEndTag as follows:

To determine the tag execution mode, use the executionMode attribute. Three modes are supported:

• Start mode – For processing the start tag
• End mode – For processing the end tag
• Inactive mode – For processing custom tags using nested tags

You can access the body text within the custom tag using the thisTag.generatedContent variable. You can modify this text during processing of the tag. The contents of the thisTag.generatedContent variables are returned to the browser as part of the tag’s output. The content includes all text and HTML code in the body, the results of evaluating ColdFusion variables, expressions, and functions, and the results generated by descendant tags.

See the following example:

The nested sub tag can pass its attributes to the parent tag. A sub tag can use cfassociate to communicate its attributes to the base/ancestor tag.

The following code shows how you can access the subtag attributes in the base tag:

You can also access the ancestral data in the sub tag using the getBaseTagList() helper method as follows:

The getBaseTagList() method returns a comma-delimited list of uppercase ancestor tag names, as a string. You can also use the getBaseTagData() method to return an object that contains all the variables of the nth ancestor.

Aborting custom tag processing

The <cfexit>/<cfabort> tag exits the page execution.

Deviation list for custom tags

The following list contains some known issues and deviations in behavior of the custom tags:

• In <cfclient>, variables scope is supported. But you have to explicitly scope it. 

• If you use the "#attributes.attributename#" syntax in the custom tag after an asynchronous call, you will see an unexpected behavior.

• Numeric values passed to the attributes in caller are passed as a string to the custom tags:

  <cf_custom attr1="1">

  
  In the above example, attr1 is converted to a number, if you are accessing the attribute in a numeric operation. However, it does not work in this manner for client-side custom tags. You need to use:
  

  <cf_custom attr1=1>

  
  Or:
  

  <cfset x = 1> <cf_custom attr1=#x#>

  
  Type conversion is not handled in client custom tags.

• Function declared in the caller CFM is accessible in the custom tag (CFM) using the caller.functionname() on the server-side. However, this is not the behavior on the client side.

• Using variables to pass the path of the included file does not work inside <cfclient>.

• Passing the template/name (with <cfmodule>) attribute as a variable does not work with <cfclient>.

• Exception thrown in the custom tag template will not be handled by the exception handler defined in the caller CFM. If the custom tag name is wrong or if the included CFM name is wrong, in client-side CFML, you will get an exception during the compilation time itself.

Non-<cfclient> custom tags cannot be called from caller CFMs of <cfclient>. Also, a client-side custom tag cannot have server-side ColdFusion tags outside the <cfclient> tag. This is true for client-side included-CFMs too. For better debugging, do not add script blocks/link tags/style tags in the client-side custom tags. Always create a separate JavaScript file or a CSS file and add them using the <cfinclude> tag.

This is applicable for client-side included CFMs too.

Support for CFC (Client-side and Server-side)

A client-side CFC can be written using the client=true attribute for a cfclient component. For instance, a client-side CFC can identify itself by having client=true along with other component attributes. See the following example:

<cfclient> communicates with the ColdFusion Server quite seamlessly so much so that you can create objects of a server component and call functions on that object just like how you do ColdFusion Server programming. The ColdFusion Server facilitates all the various interactions required between a mobile client and the server without any restrictions on the language.

See the following example:

In the above example, you are calling a function on a remote CFC within the <cfclient> tag. The new operator creates a proxy to the server CFC. You can use the instantiated CFC object to invoke remote functions on that CFC.

Note that a server CFC is similar to any other CFC without the client attribute being set to true.

The <cfclient> tag allows the usage of CFCs just like any other CFML constructs. There are multiple ways of using CFCs in the <cfclient> block.

The following example shows a very simple usage:

In the above example, mycfc.cfc can be a client-side CFC or a server-side CFC. As you can infer, CFCs can be created using createObject, new keyword, and cfinvoke techniques.

You can also use a CFC that extends functionalities from another CFC:

You can also use <cfimport> for importing mapped paths:

Support for database queries

You can start using the <cfquery> tag in client-side CFML just like how you are currently using it in server-side CFML code. Note that not all of the <cfquery> features are supported in this release. The support for database queries in client-side CFML is based on Web Database (Web SQL). So, this feature may not work on certain browsers. To check if your browser supports Web SQL, see this web page.

What is supported

The following list shows the extent of <cfquery> support available in client-side CFML:

• The <cfquery> tag supports ONLY the following attributes:
  • name = "query name"
  • dataSource = "data source name"
  • result = "resultVar"

The result variable will contain sql, recordCount, columnList, and sqlparameters.

• You can use the <cfloop> tag to iterate over the query. The <cfloop> tag will support query, startrow, and endrow attributes.
• You can use the <cfqueryparams> tag for parameterized query.

• In the <cfqueryparam> tag, only the value attribute is supported.
• The queryparam attribute value can be provided through position parameters in an array using the queryExecute function:

             queryexecute("sql", queryparams, queryoptionsmap)

• Note that serialization and deserialization of queries from client to server and server to client will be seamless.

• You can use the isQuery function in client-side CFML to check if a variable is of query type.

What is NOT supported

The following features are not supported:

• Performing query of queries.
• In-memory query creation functions like QueryNew and QueryAddRow.

Usage example

The following example shows the basic usage of the <cfquery> tag in client-side CFML:

See the server-side <cfquery> support.