A bind parameter specifies a form control value or other attribute, as in the following example:

bind="cfc:myapplication.bookSearch.getStores({form1:bookTitle})"

In this example, the bind parameter is form1:bookTitle and specifies the value attribute of the bookTitle field of the form1 form.

Bind parameters have either of the following formats:

{[formName:]controlName[.attributeName][@event]}
{SpryDataSetName.fieldName}

The square brackets ([]) indicate optional contents and are not part of the parameter.

The formname value

The formname entry identifies the form that contains the control you are binding to. You must specify a form name if multiple forms contain bind targets with the same names. To specify the form name, start the bind expression with the form's id attribute the name attribute if you did not specify an id attribute, and follow it with a colon (:). To specify the book control that is in a form named inputForm, for example, use the following format:

bind="cfc:myapp.bookorder.getChoices({inputForm:book})"

The controlName value

To bind to a form field, the controlName value must be the value of the id or name attribute of the form control to which you are binding. If a control has both an id and a name attribute, you can use either value.

You can bind to any ColdFusion form control, including cfgrid and cftree. You cannot bind to values in other ColdFusion tags, such as cftable.

To bind to a Spry data set, specify the data set name in this part of the bind parameter.

You can bind to multiple radio buttons or check boxes by giving them the same name value. If all the radio buttons in a radio button group have the same name value, the bind parameter represents the selected button. If multiple check boxes have the same name value, the bind parameter represents the values of the selected controls in a comma-delimited list. If you also specify a unique id attribute for each check box or radio button, you can specify an HTML label tag for each button or check box and use the id value in the for attribute; in this case, users can select items by clicking the label, not just the button or box.

If a cfselect control supports multiple selections, the bind expression returns the information about the selected items in a comma-delimited list.

You can bind only to controls that are available in the DOM tree when the bind is registered. Binds are registered when the page with the bind expression loads, either in the browser window or in a container tag. As a result, if you have two cfdiv, layoutarea, cfpod, or cfwindow containers that you load by using a source (or for cfdiv tag, bind) attribute, you cannot bind controls in one container to controls in the other, because one container cannot be assured that the other is loaded when it loads. Similarly, elements on the main page cannot bind to elements on a dynamically loaded container. To prevent this problem, you should define the bind target in line on the main page, instead of using a source or bind attribute to retrieve the markup that contains the bind target. In other words, the "master" form with fields that serve as sources of bind expressions should be loaded statically (on the main page), and the "child" controls that depend on the data can be loaded dynamically, on a page that is specified in a source or bind attribute.

The attributeName value

When you bind to a form control, by default, the bind expression represents the value attribute of the specified control. If the bind target is a cfselect tag, the bind expression represents a comma delimited list of the values of the selected items.

To bind to a different attribute, follow the control name or id with a period (.) and the attribute name. To pass the checked attribute of a checkbox cfinput tag as a CFC parameter, for example, use an expression such as the following:

bind="cfc:myapp.bookorder.useStatus({myForm:approved.checked"@click}"

Grids and trees do not have default bind attributes.

• You must always specify a grid target attribute by using the format {gridID.columnName}. The bind expression gets the value of the specified column in the selected row.
• For trees, you must bind to a specific node in the tree. You can specify the node by using the node ID or an explicit path to the node.

To bind to a Spry data set element or attribute, use standard Spry path notation. For example, specify an element name.

The event value

By default, the bind expression function executes each time the control specified in the bind parameter has an onChange event. To trigger updates on a different JavaScript event, end the bind expression with an at sign (@) and the event name, without the "on" prefix. The following code, for example, executes the getChoices CFC each time the user presses the mouse button while the pointer is over the book control:

bind="cfc:myapp.bookorder.getChoices({inputForm:book@mousedown})"

When you bind to a Spry data set, do not specify an event. The expression is evaluated when the selected row changes in the data set, or when the data set reloads with new data.

You can also specify that a specific bind parameter never triggers bind expression reevaluation, by specifying @none as the event. This is useful, for example, if a bind expression uses multiple bind parameters binding to different form fields, and you want the bind expression to trigger changes only when one of the fields changes, not when the others change. In this case, you would specify @none for the remaining fields, so events from those fields would not trigger the bind. The following code shows this use:

bind="cfc:books.getinfo({iForm:book}, {iForm:author@none})"

The @none event specifier can also be useful when used with autosuggest text inputs, trees and grids, as follows:

• When you use an autosuggest text input, the bind expression is evaluated as a user types in text, and picks up data from all bind parameters, including those with @none specified. Therefore, for autosuggest, you can specify @none for all bind parameters, because there is no way for it to react to changes in the parameters.
• When you call the ColdFusion.Grid.refresh or ColdFusion.Tree.refresh function, the function fetches data from all bind parameters when it evaluates the bind expression, including any parameters with @none specified. If you specify @none for all bind parameters, the tree or grid might not respond to changes in other controls, but it will get data from all the bind parameters each time you explicitly refresh it.