Adobe ColdFusion 8

Binding data to form fields

Many ColdFusion Ajax features use binding to provide dynamic interactivity based on user input or changing data. When you use binding, a bind expression gets evaluated, and the display gets updated based on new data each time a specific event (onChange by default) occurs on a form control field specified by a bind parameter. This way, the value of the tag that specifies the bind expression, and the display, get updated dynamically based on changing information, including user-entered form data. When you use binding the page contents updates, but the entire page is not refreshed.

Note: When a bound window is not visible, or a tab is not selected, its contents is not updated when the controls it is bound to change. When the tab or window is made visible, it is updated only if events have been received from the bound controls while the control was not visible.

Depending on the specific ColdFusion tag, a bind expression can use bind parameter values directly or pass bind parameter values as parameters to a CFC function, a JavaScript function, or an HTTP request and use the function or request response to update the page. You can use the following as the data source for a bind expression:

  • ColdFusion form control attributes and values. You can bind to the following controls:
    • cfgrid
    • cfinput with checkbox, datefield, file, hidden, radio, or text types
    • cfselect
    • cftextarea
    • cftree
  • Spry data set elements

Note: You cannot use a bind expression to bind to controls in a dynamically loaded region. For example, you cannot bind from a control on one page to a control in a layout area on that page if the cflayoutarea tag uses a source attribute for its contents. However, a dynamically loaded region can bind to controls on the page that loads it, so the file specified by the source attribute can use bind expressions that specify controls on the page that contains the cflayoutarea tag.

The results of the bind expression determine the value of the tag that uses the expression. For example, if you specify a URL in a bind expression as the source attribute of a cfwindow control, the page specified by the URL must return the full contents of the window.

For more examples, see Using Ajax UI Components and Features and the reference pages for controls that support binding.

Using bind expressions

To specify a bind expression, use one of the following formats:

  • cfc:componentPath.functionName(parameters)

    Note: The component path cannot use a mapping. The componentPath value must be a dot-delimited path from the web root or the directory that contains the current page.

  • javascript:functionName(parameters)
  • url:URL?parameters
  • URL?parameters
  • A string containing one or more instances of {bind parameter}, such as {firstname}.{lastname}@{domain}

In formats 1-4 the parameters normally include one or more bind parameters. The following table lists the tag attributes that support bind expressions and the formats each can use:

Attribute

Tags

Supported formats

autosuggest 

cfinput type="text"

1, 2, 3

bind

cfdiv, cfinput, cftextarea

1, 2, 3, 5

bind

cfajaxproxy, cfgrid, cfselect, cfsprydataset, cftreeitem

1, 2, 3

onChange

cfgrid

1, 2, 3

source

cflayoutarea, cfpod, cfwindow

4

The following examples show some of these uses:

bind="cfc:myapp.bookorder.getChoices({book})"
source="/myApp/innerSource/cityWindow.cfm?cityname={inputForm:city}

In these examples, {book} and {inputForm:city} specify bind parameters that dynamically get data from the book and city controls, and the city control is in the inputForm form.

If a bind attribute specifies a page that defines JavaScript functions, the function definitions on that page must have the following format:

functionName = function(arguments) {function body}

Function definitions that use the following format may 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 using the source attribute. Imported pages do not have this function definition format restriction.