Binding

When it comes to programming, the two most commonly used features are CFAJAXProxy and binding. The binding feature allows us to bind or tie things together by using a simpler technique than we would otherwise have needed to create. Binding acts as a double-ended connector in some scenarios. You can set the bind to pull data from another ColdFusion tag on the form. These must be AJAX tags with binding abilities.

There are four forms of bindings, on page, CFC, JavaScript, and URL. Let’s work through each style so that we will understand them well. We will start with on page binding. Remember that the tag has to support the binding. This is not a general ColdFusion feature, but we can use it wherever we desire.

On Page Binding

We are going to bind ‘cfdiv’ to pull its content to show on page binding. We will set the value of a text input to the div. Refer to the following code. ColdFusion AJAX elements work in a manner different from how AJAX is written traditionally. It is more customary to name our browser-side HTML elements with id attributes. This is not the case with the binding features. As we can see in our code example, we have used the name attribute. We should remember to be case sensitive, since this is managed by JavaScript. When we run the code, we will notice that we must leave the input field before the browser registers that there has been a change in the value of the field. This is how the event model for the browser DOM works.

<cfform id="myForm" format="html">
  This is my edit box.<br />
  <cfinput type="text" name="myText">
</cfform>
<hr />
And this is the bound div container.<br />
<cfdiv bind="{myText}"></cfdiv>

Notice how we use curly brackets to bind the value of the ‘myText’ input box. This inserts the contents into ‘div’ when the text box loses focus.

This is an example of binding to in-page elements. If the binding we use is tied to a hidden window or tab, then the contents may not be updated.

CFC Binding

Now, we are going to bind our div to a CFC method. We will take the data that was being posted directly to the object, and then we will pass it out to the CFC. The CFC is going to repackage it, and send it back to the browser. The binding will enable the modified version of the content to be sent to the div. Refer to the following CFC code:

<cfcomponent output="false">
 <cffunction name="getDivContent" returntype="string" access="remote">
  <cfargument name="edit">
  <cfreturn "This is the content returned from the CFC for 
   the div, the calling page variable is '<strong>#arguments.edit#</strong>'.">
 </cffunction>
</cfcomponent>

From the previous code, we can see that the CFC only accepts the argument and passes it back. This could have even returned an image HTML segment with something like a user picture. The following code shows the new page code modifications.

<cfform id="myForm" format="html">
  This is my edit box.<br />
  <cfinput type="text" name="myText">
</cfform>
<hr />
And this is the bound div container.<br />
<cfdiv bind="cfc:bindsource.getDivContent({myText})"></cfdiv>

The only change lies in how we bind the cfdiv element tag. Here, you can see that it starts with CFC. Next, it calls bindsource, which is the name of a local CFC. This tells ColdFusion to wire up the browser page, so it will connect to the CFC and things will work as we want. You can observe that inside the method, we are passing the bound variable to the method. When the input field changes by losing focus, the browser sends a new request to the CFC and updates the div. We need to have the same number of parameters going to the CFC as the number of arguments in our CFC method. We should also make sure that the method has its access method set to remote. Here we can see an example results page.

It is valid to pass the name of the CFC method argument with the data value. This can prevent exceptions caused by not pairing the data in the same order as the method arguments. The last line of the previous code can be modified as follows:

<cfdiv bind="cfc:bindsource.getDivContent(edit:{myText})"></cfdiv>

JavaScript Binding

Now, we will see how simple power can be managed on the browser. We will create a standard JavaScript function and pass the same bound data field through the function. Whenever we update the text box and it looses focus, the contents of the div will be updated from the function on the page. It is suggested that we include all JavaScript rather than put it directly on the page. Refer to the following code:

<cfform id="myForm" format="html">
  This is my edit box.<br />
  <cfinput type="text" name="myText">
</cfform>
<hr />
And this is the bound div container.<br />
<cfdiv bind="javascript:updateDiv({myText})"></cfdiv>
<script>									
updateDiv = function(myEdit){							
  return 'This is the result that came from the JavaScript function 		
  with the edit box sending "<strong>'+myEdit+'</strong>"';			
}										
</script>

Here is the result of placing the same text into our JavaScript example.

URL Binding

We can achieve the same results by calling a web address. We can actually call a static HTML page. Now, we will call a .cfm page to see the results of changing the text box reflected back, as for CFC and JavaScript. Here is the code for our main page with the URL binding.

<cfform id="myForm" format="html">
  This is my edit box.<br />
  <cfinput type="text" name="myText">
</cfform>
<hr />
And this is the bound div container.<br />
<cfdiv bind="url:bindsource.cfm?myEdit={myText}"></cfdiv>

In the above code, we can see that the binding type is set to URL. Earlier, we used the CFC method bound to a file named bindsource.cfc. Now, we will bind through the URL to a .cfm file. The bound myText data will work in a manner similar to the other cases. It will be sent to the target; in this case, it is a regular server-side page. We require only one line. In this example, our variables are URL variables. Here is the handler page code:

<cfoutput>
  'This is the result that came from the server page with the edit 
  box sending "<strong>#url.myEdit#</strong>"'
</cfoutput>

This tells us that if there is no prefix to the browse request on the bind attribute of the <cfdiv> tag, then it will only work with on-page elements. If we prefix it, then we can pass the data through a CFC, a URL, or through a JavaScript function present on the same page. If we bind to a variable present on the same page, then whenever the bound element updates, the binding will be executed.

Bind with Event

One of the features of binding that we might overlook its binding based on an event. In the previous examples, we mentioned that the normal event trigger for binding took place when the bound field lost its focus. The following example shows a bind that occurs when the key is released.

<cfform id="myForm" format="html">
  This is my edit box.<br />
  <cfinput type="text" name="myText">
</cfform>
<hr />
And this is the bound div container.<br />
<cfdiv bind="{myText@keyup}"></cfdiv>

This is similar to our first example, with the only difference being that the contents of the div are updated as each key is pressed. This works in a manner similar to CFC, JavaScript, and URL bindings. We might also consider binding other elements on a click event, such as a radio button. The following example shows another feature. We can pass any DOM attribute by putting that as an item after the element id. It must be placed before the @ symbol, if you are using a particular event. In this code, we change the input in order to have a class in which we can pass the value of the class attribute and change the binding attribute of the cfdiv element.

<cfform id="myForm" format="html">
  This is my edit box.<br />
  <cfinput type="text" name="myText" class="test">			
</cfform>
<hr />
And this is the bound div container.<br />
<cfdiv bind="{myText.class@keyup}.{myText}"></cfdiv>

Here is a list of the events that we can bind.

• @click
• @keyup
• @mousedown
• @none

The @none event is used for grids and trees, so that changes don’t trigger bind events.

Extra Binding Notes

If you have an ID on your CFForm element, then you can refer to the form element based on the container form. The following example helps us to understand this better.

Bind = "url:bindsource.cfm?myEdit={myForm:myText}"

The ColdFusion 8 documents give the following guides in order to specify the binding expressions.

1. cfc: componentPath.functionName (parameters)

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 page.

2. javascript: functionName (parameters)
3. url: URL?parameters
4. ULR?parameters
5. A string containing one or more instances of {bind parmeter}, such as {firstname}.{lastname}@{domain}

The following table represents the supported formats based on attributes and tags:

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