Adobe ColdFusion 8

Ajax programming rules and techniques

The following techniques can help you to prevent Ajax application errors, improve application security, and develop more effective applications.

Preventing errors

The following rules and techniques can help you prevent errors in your applications:

  • To ensure that your code works properly, make sure that all your pages, including dynamically loaded content and pages that contain dynamic regions, have valid html, head, and body tags, and that all script tags are located in the page head. This is particularly important for any page with ColdFusion Ajax tags and script tags, where it ensures that the script code is processed and that code is generated in the correct order. It can also prevent problems in some browsers, such as Internet Explorer.
  • All JavaScript function definitions on pages that you include dynamically, for example by using a bind expression, the ColdFusion.navigate function, or a form submission within a ColdFusion Ajax container tag, must have the following syntax format:
    functionName = function(arguments) {function body}

    Function definitions that use the following format might not work:

    function functionName (arguments) {function body}

    However, Adobe recommends that you include all custom JavaScript in external JavaScript files and import them on the application's main page, and not write them in-line in code that you get dynamically. Imported pages do not have this restriction on the function definition format.

  • As a general rule, the id attributes or name attributes, when you do not specify id attributes, of controls should be unique on the page, including on any pages that you specify in source attributes. Exceptions to this rule include the following:
    • You can use the same name attribute for all options in a radio button group. Bind expressions get information about the selected button.
    • You can use the same name attribute for check boxes in a group if you want a single bind expression to get information about all selected controls in the group.
    • If you have multiple similar forms on a page, you might have controls in each form with the same name or ID. You specify the individual controls in bind expressions by including the form name in the bind parameter.
  • Do not use an Application.cfc onRequestEnd function or onRequestEnd.cfm page that creates output in applications that use the cfajaxproxy tag or bind expressions that call CFC functions to get data. ColdFusion Ajax features normally require that all returned data from the server be in JSON format; the onRequestEnd method onRequestEnd.cfm page appends any output as non-JSON information to the end of the returned data.
  • By default, all ColdFusion structure element names are in all uppercase characters. Therefore, your client-side Ajax code, such as an onSuccess function specified by a cfajaxproxy tag, must use uppercase letters for the returned object's element names if you do not explicitly ensure that the element names are not all uppercase. (You can create structure element names with lowercase characters by specifying the names in associative array notation, for example, myStruct["myElement"]="value".)
  • ColdFusion Ajax controls can throw JavaScript errors if badly formed HTML causes errors in the browser DOM hierarchy order. One example of such badly formed HTML is a table that contains a cfform tag, which in turn contains table rows. In this situation, you should put the table tag inside the cfform tag.

For browser-specific issues and other issues that might affect application appearance and behavior, see the ColdFusion Release Notes on the Adobe website at www.adobe.com/go/prod_doc, and the ColdFusion Developer Center on the Adobe website at www.adobe.com/go/prod_techarticles.

Improving security

ColdFusion includes several capabilities that help to ensure the security of Ajax application. Also, the ColdFusion Administrator disables output to the client-side logging window by default (see Enabling logging output).

  • To prevent cross-site scripting, you cannot use remote URLs in code that executes on the client. For example, if you use a URL such as http://www.myco.com/mypage.cfm in a cfwindow tag source attribute, the remote page does not load in the window and the window shows an error message. If you must access remote URLs, you must do so in CFML code that executes on the server, for example, by using a cfhttp tag on the page specified by a source attribute.
  • When a CFC function returns remote data in JSON format, by default, the data is sent without any prefix or wrapper. To help prevent cross-site scripting attacks where the attacker accesses the JSON data, you can tell ColdFusion to prefix the returned data with one or more characters. You can specify this behavior in several ways. The value of an item in the following list is determined by the preceding item in this list:
    1. In the Administrator, enable the Prefix Serialized JSON option on Server Settings > Settings page (the default value is false). You can also use this setting to specify the prefix characters. The default prefix is //, which is the JavaScript comment marker that turns the returned JSON code into a comment from the browser's perspective. The // prefix helps prevent security breaches because it prevents the browser from converting the returned value to the equivalent JavaScript objects.
    2. Set the Application.cfc file This.secureJSON and This.secureJSONPrefix variable values, or set the cfapplication tag secureJSON and secureJSONPrefix attributes.
    3. Set the cffunction tag secureJSON attribute. (You cannot use the cffunction tag to set the prefix.)

    As a general rule, you should use one of these techniques for any CFC or CFML page that returns sensitive data, such as credit card numbers.

    When you use any of these techniques, the ColdFusion Ajax elements that call CFC functions, including bind expressions and the CFC proxies created by the cfajaxproxy tag, automatically remove the security prefix when appropriate. You do not have to modify your client-side code.

  • ColdFusion provides capabilities that help prevent security attacks where an unauthorized party attempts to perform an action on the server, such as changing a password. You can use the following techniques to help make sure that a request to a CFML page or remote CFC function comes from a ColdFusion Ajax feature, such as a bind expression or CFC proxy, that is a valid part of your application:
    • In the cffunction tag in a CFC function that returns data to an Ajax client, specify a verifyClient attribute with a value of yes.
    • At the top of a CFML page or function that can be requested by a ColdFusion Ajax client, call the VerifyClient ColdFusion function. This function takes no parameters.

    The VerifyClient function and attribute tell ColdFusion to require an encrypted security token in each request. To use this function, enable client management or session management in your application; otherwise, you do not get an error, but ColdFusion does not verify clients.

    Enable client verification only for code that responds to ColdFusion Ajax client code, because only the ColdFusion Ajax library contains the client-side support code. Enabling client verification for clients other than ColdFusion Ajax applications can result in the client application not running.

    As a general rule, use this function for Ajax requests to the server to perform sensitive actions, such as updating passwords. You should typically not enable client verification for public APIs that do not need protected, search engine web services. Also, do not enable client verification for the top-level page of an application, because the security token is not available when the user enters a URL in the browser address bar.

Programming effectively

The following recommendations can help improve or customize your ColdFusion Ajax application.

  • Use the AjaxOnLoad function, which specifies a JavaScript function to run when the page loads, to perform any initialization actions that are required for a page to function properly. You should use the AjaxOnLoad function to call functions when a page is loaded in a container tag. One use for this function could be on a page that pops up a login window if the user is not already logged in when it displays. You can use the AjaxOnLoad function to specify a JavaScript function that determines the login status and pops up the window only if required.
  • Use the following ColdFusion JavaScript functions to access the Ext JS or Yahoo YUI JavaScript library objects that underlie border and tab style cflayout controls, cfwindow controls, and HTML format cfgrid and cftree controls. Then you can use the raw object to modify the displayed control.

    For documentation on the objects and how to manage them, see the Ext documentation and the Yahoo toolkit documentation.