Using Ajax User Interface Components and Features

ColdFusion data and development features help you develop effective Ajax applications that use ColdFusion to provide dynamic data. They include many features that you can use with other Ajax frameworks, including Spry.

The following data and development features are important for use with form and layout tags:

• ColdFusion supports data binding in many tags. Binding allows form and display tags to dynamically display information based on form input. In the simplest application, you display form data directly in other form fields. But usually, you pass form field data as parameters to CFC or JavaScript functions or CFM pages, and use the results to control the display.

• The cfajaximport tag specifies the location of the JavaScript and CSS files that a ColdFusion page imports or to selectively import files required by specific tags. The ability to change the file location lets you support a wide range of configurations and use advanced techniques, such as application-specific styles.

For more information about the data and development features and how to use them, see Using Ajax Data and Development Features.

Several ColdFusion user interface elements incorporate Ajax features. The tags and tag-attribute combinations can be divided into the following categories:

• Container tags that lay out or display contents

• File management tags that handle files

• Form tags that dynamically display data

• A menu tag that lets you create menu bars and pull-down menus

• User assistance features that provide tool tips and form completion

• Four other tags for using geographical maps, progress bar, media player, and message box.

The following table lists the basic tags and attributes that display the Ajax-based features. For information on additional forms-specific features, see Using Ajax form controls and features.

In addition to the tags and attributes, ColdFusion provides many JavaScript functions that let you control and manage the display. Many functions control the display of specific tags. For example, you can use JavaScript functions to dynamically display and hide the window. There are also several utility tags, such as the ColdFusion.getElementValue function that gets the value of a control attribute, or the ColdFusion.navigate function that displays the results of a URL in a container tag. For a complete list of all ColdFusion Ajax JavaScript functions, and detailed function descriptions, see Ajax JavaScript Functions in the CFML Reference.

The cflayout and cflayoutarea tags have style attributes. The cflayout tag style attribute controls the style of the layout container, and sets default values for many, but not all, styles for the layout areas. For example, the color and background color styles of the cflayout tag set the default text and background colors in the layout areas. But the cflayout tag border style sets only the color of the border around the entire layout, not the layout area borders. The cflayoutarea tag style attribute controls the style of the individual layout area and overrides any corresponding settings in the cflayout tag.

As is often the case with complex controls, the effects of layout and layout area styles can vary. For example, do not often specify the height style in the cflayout tag; instead, specify height styles on each of the cflayoutarea tags.

The following simple example shows a tab layout with two layout areas. The layout has a light pink background color, and the layout areas have three pixel-wide red borders.:

<cflayout name="layout1" type="tab" style="background-color:##FFCCCC"> 
    <cflayoutarea title="area1" style="border:3px solid red"> 
        Layout area 1 
    </cflayoutarea> 
    <cflayoutarea title="area1" style="border:3px solid red"> 
        Layout area 2 
    </cflayoutarea> 
</cflayout>

You display a window in the following ways:

• By using a ColdFusion cfwindow tag with an initShow attribute value of to create and show the window.

• By using a ColdFusion cfwindow tag with an initShow attribute value of false and calling the ColdFusion.Window.show JavaScript function to display it.

• By using ColdFusion.Window.create and ColdFusion.Window.show JavaScript functions.

You can hide a window that is currently showing by calling the ColdFusion.Window.hide function. You can use the ColdFusion.Window.onShow and ColdFusion.Window.onhide functions to specify JavaScript functions to run when a window shows or hides.

The following example shows how you can create, display, and hide a window. It also shows several of the configuration options that you can set, including whether the user can close, drag, or resize the window. When you run the application, the cfwindow tag creates and shows Window 1. You can then hide it and reshow it. To show Window 2, click the Create Window 2 button, followed by the Show Window 2 button. You can then hide and show it.

The following example shows the main application page:

<html> 
<head> 
<script>  
    <!-- 
    //Configuration parameters for window 2. 
    var config = 
    {x:250,y:300,height:300,width:300,modal:false,closable:false, 
        draggable:true,resizable:true,initshow:false,minheight:200,minwidth:200 
    } 
    --> 
</script> 
 
</head> 
<body> 
 
<!--- Create a window with a title and show it. Don't allow dragging or resizing. ---> 
<cfwindow name="window1" title="CFML Window" draggable="false" 
        resizable="false" initshow="true" height="250" width="250" x=375 y=0>  
    <p> 
    This content was defined in the cfwindow tag body. 
    </p> 
</cfwindow> 
 
<form> 
<!--- Use the API to show and hide Window 1. ---> 
    <input type="button" value="Show Window1"  
            onClick="ColdFusion.Window.show('window1')"> 
    <input type="button" value="Hide Window1" 
            onClick="ColdFusion.Window.hide('window1')"><br /> 
 
<!--- Use the API to create, show, and hide Window 2 ---> 
    <input type="button" value="Create Window2" 
            onClick="ColdFusion.Window.create('window2', 'JavaScript Window', 
            'window2.cfm', config)"> 
    <input type="button" value="Show Window2" 
            onClick="ColdFusion.Window.show('window2')"> 
    <input type="button" value="Hide Window2" 
        onClick="ColdFusion.Window.hide('window2')"> 
</form> 
 
</body> 
</html>

The window2.cfm file with the contents of Window 2 has the following contents:

<cfoutput> 
<p> 
This content was loaded into window 2 from a URL.<br /> 
</p> 
</cfoutput>

You can use the onShow and onHide events that are triggered each time a window shows and hides to control your application. To do so, call the ColdFusion.Window.onShow and ColdFusion.Window.onHide functions to specify the event handlers. Both functions take the window name and the handler function as parameters. The event handler functions can take a single parameter, the window name.

The following example displays an alert message when a window hides or shows. The alert message includes the window name. The alert does not show when the window first appears, because the cfwindow tag uses the initShow attribute to initially display the window. An alert message does appear when the user hides the window by clicking the Toggle Window button or the close button on the window.

<html> 
<head> 
    <script language="javascript"> 
        //Boolean value tacking the window state. 
        var shown=true; 
 
        //Functions to display an alert box when  
        function onshow(name) { 
            alert("window shown = " + name); 
        } 
        function onhide(name) { 
            alert("window hidden = " + name); 
        } 
 
        //Initialize the window show/hide behavior. 
        function initWindow() { 
            ColdFusion.Window.onShow("testWindow", onshow); 
            ColdFusion.Window.onHide("testWindow", onhide); 
        } 
 
        //Show or hide the window, depending on its current state. 
        function toggleWindow() { 
            if (shown) { 
                ColdFusion.Window.hide("testWindow"); 
                shown = false; 
            } 
            else { 
                ColdFusion.Window.show("testWindow"); 
                shown = true; 
            }             
        } 
 
    </script> 
</head> 
<!-- The body tag onLoad event calls the window show/hide initializer function. --> 
<body onLoad="initWindow()"> 
 
<cfwindow name="testWindow" initshow=true title="test window" closable=true> Window contents 
</cfwindow> 
 
<cfform> 
    <cfinput name="button" value="Toggle Window" onclick="javascript:toggleWindow()" type="button"/> 
</cfform> 
</body> 
</html>

The page/URL that handles the upload operation on the server can send back a struct with the keys status and message as shown here:

<cffile action = "upload" 
destination = "#Expandpath('./upload')#" 
nameconflict="makeunique"> 
<cfset str.STATUS = 200> 
<cfset str.MESSAGE = "File Upload Successful">        <cfoutput>#serializeJSON(str)#</cfoutput>

The following example illustrates the error handler:

<cftry> 
<cffile action = "upload" 
destination = "#Expandpath('./upload')#"> 
<cfcatch type="any"> 
<cfset str.STATUS = 500> 
<cfset str.MESSAGE = "Error occurred while uploading the file">            <cfoutput>#serializeJSON(str)#</cfoutput> 
</cfcatch> 
</cftry>

If the user tries to upload a file already present in the upload directory, it results in an error. The status and message are set to the specifications in the catch block.

The attributes headercolor, textcolor, bgcolor, titletextalign, titletextcolor, and rollovercolor lets you style the file upload control.

The following example illustrates the styling of file upload control:

<cffileupload 
          url="uploadAll.cfm" 
          name="myuploader3" 
          align="right" 
    style="headercolor:silver;textcolor:1569C7;titletextalign:right;titletextcolor:black;bgcolor:74BBFB;"/>

The following code shows how the attribute onUploadComplete is used:

<!--- upload.cfm ---> 
<!--- <cffile action = "upload" destination = "#Expandpath('./upload')#" nameconflict="makeunique"> ---> 
<script language="javascript"> 
    var uploadCompleteHandler = function(obj){ 
        var result = "Upload Details:" + "\n\n"; 
        for(var i=0;i < obj.length; i++){ 
            result = result + "FILENAME: " + obj[i].FILENAME + "\n" + "STATUS: " + obj[i].STATUS + "\n" + "MESSAGE: " + obj[i].MESSAGE + "\n\n"; 
        } 
    } 
</script> 
<br> 
<cffileupload 
    url="uploadall.cfm" 
    name="myuploader" 
    onUploadComplete="uploadCompleteHandler" 
    maxUploadSize=100 
    stopOnError=false 
    />

The ColdFusion Ajax container tags, cfdiv, cflayoutarea, cfpod, and cfwindow, automatically submit any forms that they contain asynchronously. When the form is submitted, the result returned by the action page replaces the contents of the container, but has no effect on the rest of the page.

The following example shows this behavior in the submitSimple.cfm page:

<html xmlns="http://www.w3.org/1999/xhtml"> 
<head> 
</head> 
<body> 
<cflayout type="vbox" name="layout1"> 
    <cflayoutarea> 
        <h3>This area is not refreshed when the form is submitted.</h3> 
        <br /> 
    </cflayoutarea> 
 
    <cflayoutarea> 
        <h3>This form is replaced by the action page</h3> 
        <cfform name="myform" format="html" action="showName.cfm"> 
            <cfinput type = "Text" name = "name">  
             <cfinput type = "submit" name = "submit" value = "Enter name"> 
        </cfform>  
    </cflayoutarea> 
</cflayout> 
 
</body> 
</html>

In the following example, when you enter a name in the text input and click the Enter name button, the entered text replaces the form on the page, but the rest of the page is not refreshed. This example shows the showName.cfm action page:

<cfif IsDefined("Form.name")> 
    <cfoutput>The Name is : <strong>#Form.name#</strong></cfoutput>  
</cfif> 

The SetForm function of the proxy object created by the cfajaxproxy tag causes the proxy to pass the form values as arguments to the next CFC function that you call after the SetForm function. This way, you can pass the current values of fields in a form to a CFC function, which can then do the necessary processing and return a result.

When you use the SetForm function, the following rules apply to the arguments in the called CFC function:

• The function does not need to specify the form fields in cfargument tags, and the function gets the field values passed by name.

• Form fields that have the same names as CFC arguments override the CFC argument values.

• If you do not specify form fields in the cfargument tags, they do not necessarily follow any declared arguments, when you use positional (array) notation to access them in the arguments structure.

• The arguments scope in the CFC function includes two fields that ColdFusion uses to control its behavior. These fields are intended for internal use, and their names might change in future releases. Both field values are set to true:

  • _CF_NODEBUG tells ColdFusion not to return debugging output in the call response.

  • _CF_NOCACHE tells ColdFusion to send a no cache header on the response, which prevents the browser from caching the response and ensures that every Ajax request results in a network call.

The following example shows how to use the SetForm tag to submit the contents of a login form. When the user clicks the Login! button, the doLogin function calls the proxy setForm function and then the AuthenticationSystem.cfc validateCredentials method. The validateCredentials method checks the password of the user and if it is valid, returns true to the proxy. Because the proxy is synchronous (the default), the doLogin method gets the returned value. If the value is true, it hides the login window; the user can then access the page contents. If the return value is false, the doLogin function displays a message in the login window title bar.

The following example shows the setForm.cfm application:

<html> 
<head> 
        <script type="text/javascript"> 
            function doLogin() { 
                // Create the Ajax proxy instance. 
                var auth = new AuthenticationSystem(); 
 
                // setForm() implicitly passes the form fields to the CFC function. 
                auth.setForm("loginForm"); 
                //Call the CFC validateCredentials function. 
                if (auth.validateCredentials()) { 
                    ColdFusion.Window.hide("loginWindow"); 
                } else { 
                    var msg = document.getElementById("loginWindow_title"); 
                    msg.innerHTML = "Incorrect username/password. Please try again!"; 
                } 
            } 
        </script> 
</head> 
 
<body> 
<cfajaxproxy cfc="AuthenticationSystem" /> 
 
<cfif structKeyExists(URL,"logout") and URL.logout> 
    <cflogout /> 
</cfif> 
 
<cflogin> 
    <cfwindow name="loginWindow" center="true" closable="false" 
                draggable="false" modal="true"  
                title="Please login to use this system" 
                initshow="true" width="400" height="200"> 
        <!--- Notice that the form does not have a submit button. 
            Submit action is performed by the doLogin function. ---> 
        <cfform name="loginForm" format="xml"> 
            <cfinput type="text" name="username" label="username" /><br /> 
            <cfinput type="password" name="password" label="password" /> 
            <cfinput type="button" name="login" value="Login!" onclick="doLogin();" /> 
        </cfform> 
    </cfwindow> 
</cflogin> 
 
<p> 
This page is secured by login.  
You can see the window containing the login form. 
The window is modal; so the page cannot be accessed until you log in. 
<ul> 
    <li><a href="setForm.cfm">Continue using the application</a>!</li> 
    <li><a href="setForm.cfm?logout=true">Logout</a>!</li> 
</ul> 
</p> 
</body> 
</html>

The following example shows the AuthenticationSystem.cfc file:

<cfcomponent output="false"> 
 
    <cffunction name="validateCredentials" access="remote" returntype="boolean" 
            output="false"> 
        <cfargument name="username" type="string"/> 
        <cfargument name="password" type="string"/> 
 
        <cfset var validated = false/> 
        <!--- Ensure that attempts to authenticate start with new credentials. ---> 
        <cflogout/> 
                 
        <cflogin> 
            <cfif arguments.username is "user" and arguments.password is "secret"> 
                <cfloginuser name="#arguments.username#" 
                        password="#arguments.password#" roles="admin"/> 
                <cfset validated = true/> 
            </cfif> 
        </cflogin> 
 
        <cfreturn validated/> 
    </cffunction> 
</cfcomponent>

You can use the ColdFusion.Ajax.submitForm function to submit form contents to a CFML page (or other active page) at any time. For example, you could use this function to automatically save a partially completed form. This function does not support uploading a file attachment to the form.

When you use this function, you pass it the name of the form to submit and the URL of the page that processes the form. You can also specify the following optional parameters:

• A callback function that handles the returned results

• An error handler that takes two parameters, an HTTP error code and a message

• The HTTP method (by default, POST)

• Whether to submit the form asynchronously (by default, true)

The following proof of concept example uses the ColdFusion.Ajax.submitForm function to submit two form fields to an asyncFormHandler.cfm page, which simply echoes the form values. The callback handler displays an alert with the returned information.

<html> 
<head> 
<!--- The cfajaximport tag is required for the submitForm function to work 
            because the page does not have any Ajax-based tags. ---> 
<cfajaximport> 
 
<script> 
    function submitForm() { 
        ColdFusion.Ajax.submitForm('myform', 'asyncFormHandler.cfm', callback, 
            errorHandler); 
    } 
     
    function callback(text) 
    { 
        alert("Callback: " + text); 
    } 
     
    function errorHandler(code, msg) 
    { 
        alert("Error!!! " + code + ": " + msg); 
    } 
</script> 
 
</head> 
<body> 
 
<cfform name="myform"> 
    <cfinput name="mytext1"><br /> 
    <cfinput name="mytext2"> 
</cfform> 
 
<a href="javascript:submitForm()">Submit form</a> 
</body> 
</html>

The asynchFormHandler.cfm page consists of a single line, as follows:

<cfoutput>Echo: #form.mytext1# #form.mytext2#</cfoutput>

The ColdFusion.navigate JavaScript function can submit a form to a URL and have the returned output appear in a specified container control, such as a cfdiv, cflayout, cfpod, or cfwindow tag. This function lets you populate a control other than the one that contains the form when the user submits the data. You can also use the function to submit the form asynchronously when a user performs an action outside the form, such as clicking a menu item.

For an example that uses this function, see the ColdFusion.navigate function in the CFML Reference.

HTML grids can dynamically fill the grid data by using a bind attribute with a bind expression that calls a CFC or JavaScript function, or a URL. The bind expression uses bind parameters to specify dynamic information provided by the grid and the values of any other form field attributes.

Pass the following bind parameters to the bind expression. If you omit any of the parameters in the function call or URL, you get an error. These parameters send information about the grid and its state to the data provider function. The data for these parameters is provided automatically. You do not set any values manually.

For more information on binding and bind parameters, see Using Ajax Data and Development Features in the CFML Reference.

You can use optional parameters to specify additional information to pass to the called function. These parameters provide data that the called function requires to determine the data to return. For example, if the function returns the cities in a state, you would pass it the state name. Any or all of the optional function parameters can be bind parameters. A state name, for example, could come from the selection in a states cfselect control.

If you do not want the grid to refresh automatically when other controls change, you can use the @none specifier on all optional bind parameters. Doing this, prevents automatic updating of the grid based on the bound control values. Use the ColdFusion.Grid.refresh JavaScript function to explicitly refresh the grid contents. For more information on the use of the @none specifier and explicitly refreshing the control, see Specifying bind parameters.

If the grid supports user sorting of the data (the sort attribute is true), the function called by the bind expression must return data in the desired sorted order, and must use the values of the cfgridsortcolumn and cfgridsortdirection bind parameters to determine the order. Even if you do not allow user sorting, still pass these parameters to the function; otherwise, you get an error. Also, your function or action page must handle cases where these parameters are empty strings, because their values are not set until the user selects a column header to sort the grid, or you call the JavaScript ColdFusion.Grid.sort function.

The format of the returned data depends on how you get the data:

When you specify a CFC in the bind attribute, use the queryConvertForGrid function to convert a query directly into a structure that you can use as your CFC return value.

When you specify a CFML page in the bind attribute, use the queryConvertForGrid function to convert a query into a structure, and then use the serializeJSON function to convert the structure into a JSON representation.

If you manually create a JavaScript object or its JSON representation, it must have two top-level keys:

• TOTALROWCOUNT: The total number of rows in the query data set being returned. This value is the total number of rows of data in all pages in the grid, and not the number of rows in the current page.

• QUERY: The contents of the query being returned. The QUERY value must also be an object with two keys:

  • COLUMNS: An array of the column names.

  • DATA: A two-dimensional array, where the first dimension corresponds to the rows and the second dimension corresponds to the field values, in the same order as the COLUMNS array.

The following example defines an object that a JavaScript bind function can return to provide the data for a cfgrid tag:

var myobject = 
    {"TOTALROWCOUNT":6,"QUERY":{"COLUMNS":["EMP_ID","FIRSTNAME", 
        "EMAIL"],"DATA":[[1,"Carolynn","CPETERSON"], 
        [2,"Dave","FHEARTSDALE"], [3,"Linda","LSTEWART"], 
        [4,"Aaron","ASMITH"], [5,"Peter","PBARKEN"], 
        [6,"Linda","LJENNINGS"],]}};

The following example uses a bind expression and a CFC to populate a dynamic, paged, data grid. The CFML page contains the following form:

<html xmlns="http://www.w3.org/1999/xhtml"> 
<head> 
</head> 
 
<body> 
<cfform name="form01"> 
    <cfgrid format="html" name="grid01" pagesize=5 sort=true 
            bind="cfc:places.getData({cfgridpage},{cfgridpagesize}, 
            {cfgridsortcolumn},{cfgridsortdirection})"> 
        <cfgridcolumn name="Emp_ID" display=true header="eid" /> 
        <cfgridcolumn name="FirstName" display=true header="Name"/> 
        <cfgridcolumn name="Email" display=true header="Email" />  
    </cfgrid> 
</cfform> 
</body> 
</html>

The places.cfc file looks as follows. Notice that the query gets the full data set each time the function gets called. the QueryConvertForGrid function selects and returns only the required page of data:

<cfcomponent> 
    <cffunction name="getData" access="remote" output="false"> 
        <cfargument name="page"> 
        <cfargument name="pageSize"> 
        <cfargument name="gridsortcolumn"> 
        <cfargument name="gridsortdirection"> 
        <cfquery name="team" datasource="cfdocexamples">  
            SELECT Emp_ID, FirstName, EMail  
            FROM Employees 
            <cfif gridsortcolumn neq "" or gridsortdirection neq "">  
                order by #gridsortcolumn# #gridsortdirection# 
            </cfif>  
        </cfquery>  
        <cfreturn QueryConvertForGrid(team, page, pageSize)> 
    </cffunction> 
</cfcomponent>

The following example is equivalent to the previous one, but uses a URL bind expression in the main page and a CFML page to return the data.

The main page contains the following form:

<html xmlns="http://www.w3.org/1999/xhtml"> 
<head> 
</head> 
 
<body> 
<cfform name="form01"> 
    <cfgrid format="html" name="grid01" pagesize=5 sort=true 
        bind="url:getdata.cfm?page={cfgridpage}&pageSize={cfgridpagesize} 
            &sortCol={cfgridsortcolumn}&sortDir={cfgridsortdirection}"> 
        <cfgridcolumn name="Emp_ID" display=true header="eid" /> 
        <cfgridcolumn name="FirstName" display=true header="Name"/> 
        <cfgridcolumn name="Email" display=true header="Email" />  
    </cfgrid> 
</cfform> 
</body> 
</html>

The following example shows the getdata.cfm page:

<!--- Empty string; the default end of the query SQL. ---> 
<cfset queryEnd=""> 
 
<cfquery name="team" datasource="cfdocexamples"> 
    SELECT Emp_ID, FirstName, EMail 
    FROM Employees 
    <cfif sortcol neq "" or sortdir neq "">  
        order by #sortcol# #sortdir# 
    </cfif>  
</cfquery> 
 
<!--- Format the query so that the bind expression can use it. ---> 
<cfoutput>#serializeJSON(QueryConvertForGrid(team, page, pageSize))# 
</cfoutput>

If your database lets you specify SQL to retrieve only the required page of data in a query, you can optimize efficiency by using such a query. Do not use the QueryConvertForGrid function. Instead, manually create the return structure and return only the single page of data. Ensure that you set the TotalRowCount field to the number of rows in the entire data set, not the number of rows in the returned page of data.

The bindOnLoad attribute causes a control to execute its bind expression immediately when it loads, and not wait until the event that normally triggers the bind expression evaluation to occur. This way, the control can be filled with an initial value. This attribute is false by default for all ColdFusion Ajax controls that have the attribute, except cfdiv and cfgrid, for which it is true by default. Having a truebindOnLoad value on these controls ensures that they are populated when they load.

When a control with a truebindOnLoad attribute is bound to a control that also binds when the page loads, the first and second control load themselves at the onLoad page event. Then the first control loads itself again in response to a change event from the second control when that control completes loading. So, the first control makes two Ajax calls, whereas it must make only one, when the second control finished loading.

Because the cfinput, cfselect, and cftextarea control bindOnLoad attributes are false by default, you do not encounter any problems if a cfgrid or cfdiv tag binds to any of these controls and you do not explicitly set the bindOnLoad attributes. However, if the control does set its bindOnLoad attribute to true, set the cfgrid or cfdiv attribute to false to ensure that the control only fetches data when the control that it is bound to returns.

You can also get a double loading if a grid binds to a Spry data set. By default, the grid and data set load data at page load, and then the grid loads data again in response to a selection change event from the data set when it sets focus to its first row. Set bindOnLoad to false to ensure that the grid fetches data only when it receives a selection change event from the data set.

When you use a bind expression to get cfgrid data dynamically, you can also update the data source dynamically with user input, without requiring the user to submit the form. You can use dynamic updating to update or delete data in the data source. (To edit cfgrid data, select the contents of a field and type the new value; to delete a row, select a field in the row and click the delete button at the bottom of the grid.)

You cannot insert new rows directly in a grid that uses a bind expression. To add rows, enter the data in a form, and make sure that the grid refreshes after the form has been submitted.

To update or delete data dynamically, do the following:

• Specify selectmode="edit" in the cfgrid tag. This lets the user edit the grid.

• Specify an onChange attribute in the cfgrid tag. The attribute must use a bind expression to specify a CFC method, JavaScript function, or URL of a page that updates the data source. The bind expression has the same format as the bind expression described in Dynamically filling form data; however, it must take the following bind parameters that the grid automatically passes. These parameters send information about the grid and its state to the onChange function.

  Parameter name	Description
  cfgridaction	The action performed on the grid. 'U' for update, or 'D' for delete.
  cfgridrow	A structure or JavaScript Object whose keys are the column names and values are the original values of the updated or deleted row.
  cfgridchanged	A structure or JavaScript Object with a single entry, whose key is the name of the column with the changed value, and whose value is the new value of the field. If the grid action is delete, this structure exists but is empty.

When you update data dynamically, you can also use the onError attribute to specify the name of a JavaScript function to handle any errors that result in a CFC or URL returning an HTTP error status. The method must take two parameters: the HTTP error code and a text message that describes the error. The following example shows an onError handler function:

<script type="text/javascript"> 
    function errorhandler(id,message) { 
        alert("Error while updating \n Error code: "+id+" \nMessage: 
        "+message);} 
</script>

The following example displays the members of a department and lets users edit the data in the fields. When the focus leaves the edited field an onChange event triggers and the form calls the editData CFC function to update the data source.

<html xmlns="http://www.w3.org/1999/xhtml"> 
<head> 
<script type="text/javascript"> 
    function errorhandler(id,message) { 
        alert("Error while updating\n Error code: "+id+"\n Message: "+message); 
    } 
</script> 
</head> 
 
<body> 
<cfform name="form01"> 
    <cfgrid format="html" name="grid01" pagesize=11  
            stripeRows=true stripeRowColor="gray" 
            bind="cfc:places.getData({cfgridpage},{cfgridpagesize}, 
                {cfgridsortcolumn},{cfgridsortdirection})"  
            delete="yes" selectmode="edit" 
            onchange="cfc:places.editData({cfgridaction},{cfgridrow},{cfgridchanged})"> 
        <cfgridcolumn name="Emp_ID" display=true header="Employee ID"/> 
        <cfgridcolumn name="FirstName" display=true header="Name"/>  
        <cfgridcolumn name="Email" display=true header="Email"/>  
    </cfgrid> 
</cfform> 
</body> 
</html>

The getData function is identical to the getData function in Dynamically filling form data. This example shows the editData function in the CFC:

<cffunction name="editData" access="remote" output="false"> 
    <cfargument name="gridaction"> 
    <cfargument name="gridrow"> 
    <cfargument name="gridchanged"> 
     
    <cfif isStruct(gridrow) and isStruct(gridchanged)> 
        <cfif gridaction eq "U"> 
            <cfset colname=structkeylist(gridchanged)> 
            <cfset value=structfind(gridchanged,#colname#)> 
            <cfquery name="team" datasource="cfdocexamples">  
                update employees set <cfoutput>#colname#</cfoutput> =  
                    '<cfoutput>#value#</cfoutput>' 
                where Emp_ID = <cfoutput>#gridrow.Emp_ID#</cfoutput> 
            </cfquery> 
        <cfelse> 
            <cfquery name="team" datasource="cfdocexamples">  
                delete from employees where emp_id = <cfoutput>#gridrow.Emp_ID# 
                    </cfoutput> 
            </cfquery>  
        </cfif> 
    </cfif> 
</cffunction>

You can bind the contents of a form control to the data in a grid field by specifying a bind parameter as the form control bind attribute value. To do so, use the following syntax:

<cfinput name="name" type="text" bind="{gridName.columnName}">

By default, each time the selected row in the grid changes, the bind parameter is re-evaluated, and the control value changes to the value of the specified column of selected grid cell.

You can use the following JavaScript functions to manage an HTML format grid:

For more information, see the ColdFusion.Grid.getGridObject, ColdFusion.Grid.refresh, and ColdFusion.Grid.sort functions in the CFML Reference.

The example in this section shows how to use the Boolean column. The code also illustrates how to group data in a grid on a selected grid column.

This example uses all types of Boolean representations. For grouping, groupField is set to active and the grid data is grouped accordingly.

<cfset emps = querynew("firstname,department, salary,active")> 
<cfset queryaddrow(emps,10)> 
<cfset querysetcell(emps,"firstname","Debra",1)> 
<cfset querysetcell(emps,"department","Accounting",1)> 
<cfset querysetcell(emps,"salary","100000",1)> 
<cfset querysetcell(emps,"active","Y",1)> 
<cfset querysetcell(emps,"firstname","Doherty",2)> 
<cfset querysetcell(emps,"department","Finance",2)> 
<cfset querysetcell(emps,"salary","120000",2)> 
<cfset querysetcell(emps,"active","Yes",2)> 
<cfset querysetcell(emps,"firstname","Ben",3)> 
<cfset querysetcell(emps,"department","Law",3)> 
<cfset querysetcell(emps,"salary","200000",3)> 
<cfset querysetcell(emps,"active","true",3)> 
<cfset querysetcell(emps,"firstname","Aaron",4)> 
<cfset querysetcell(emps,"department","Accounting",4)> 
<cfset querysetcell(emps,"salary","200000",4)> 
<cfset querysetcell(emps,"active","1",4)> 
<cfset querysetcell(emps,"firstname","Josh",5)> 
<cfset querysetcell(emps,"department","CF",5)> 
<cfset querysetcell(emps,"salary","400000",5)> 
<cfset querysetcell(emps,"active",true,5)> 
<cfset querysetcell(emps,"firstname","Peterson",6)> 
<cfset querysetcell(emps,"department","Accounting",6)> 
<cfset querysetcell(emps,"salary","150000",6)> 
<cfset querysetcell(emps,"active","0",6)> 
<cfset querysetcell(emps,"firstname","Damon",7)> 
<cfset querysetcell(emps,"department","Finance",7)> 
<cfset querysetcell(emps,"salary","100000",7)> 
<cfset querysetcell(emps,"active","N",7)> 
<cfset querysetcell(emps,"firstname","Tom",8)> 
<cfset querysetcell(emps,"department","CF",8)> 
<cfset querysetcell(emps,"salary","100000",8)> 
<cfset querysetcell(emps,"active","false",8)> 
<cfset querysetcell(emps,"firstname","Adam",9)> 
<cfset querysetcell(emps,"department","CF",9)> 
<cfset querysetcell(emps,"salary","300000",9)> 
<cfset querysetcell(emps,"active",false,9)> 
<cfset querysetcell(emps,"firstname","Sean",10)> 
<cfset querysetcell(emps,"department","CF",10)> 
<cfset querysetcell(emps,"salary","250000",10)> 
<cfset querysetcell(emps,"active","No",10)> 
<cfform name="form01"> 
    <cfgrid format="html"  insert="yes" insertButton="Add Row" 
        name="grid01" 
        selectmode="edit" 
        width=600 
        collapsible="true" 
        title="Employees" 
        autowidth="yes" 
        query="emps" 
        sort="yes" 
        groupField="active"> 
            <cfgridcolumn name="FirstName" header="FirstName"/> 
            <cfgridcolumn name="Department" header="Department" /> 
            <cfgridcolumn name="Salary" display=true header="Salary" type="numeric" values="1000000,1200000" valuesdisplay="1000000,1200000"/> 
            <cfgridcolumn name="Active"  display=true header="Contract" type="boolean" /> 
    </cfgrid> 
</cfform>

The following example shows how to use the date column. In the code, startdatecolumn is of type date. A mask,Y/m/d is used. Y is year in four digits, m months with leading zero, and d the days with leading zero.

<!--- using cfgridcolum type="date" ---> 
<cfset emps = querynew("firstname,department, salary,startdate")> 
<cfset queryaddrow(emps,3)> 
<cfset querysetcell(emps,"firstname","Debra",1)> 
<cfset querysetcell(emps,"department","Accounting",1)> 
<cfset querysetcell(emps,"salary","100000",1)> 
<cfset querysetcell(emps,"startdate","2009/1/1",1)> 
<cfset querysetcell(emps,"firstname","Doherty",2)> 
<cfset querysetcell(emps,"department","Finance",2)> 
<cfset querysetcell(emps,"salary","120000",2)> 
<cfset querysetcell(emps,"startdate","2005/2/21",2)> 
<cfset querysetcell(emps,"firstname","Ben",3)> 
<cfset querysetcell(emps,"department","Law",3)> 
<cfset querysetcell(emps,"salary","200000",3)> 
<cfset querysetcell(emps,"startdate","2008/03/03",3)> 
<cfform name="form01"> 
    <cfgrid format="html"  insert="yes" insertButton="Add Row" 
        name="grid01" 
        selectmode="edit" 
        width=600 
        collapsible="true" 
        title="Employees" 
        autowidth="yes" 
        query="emps" 
        sort="yes" 
        groupField="department"> 
            <cfgridcolumn name="FirstName" header="FirstName"/> 
            <cfgridcolumn name="Department" header="Department" /> 
            <cfgridcolumn name="Salary" display=true header="Salary" type="numeric" values="1000000,1200000" valuesdisplay="1000000,1200000"/> 
            <cfgridcolumn name="StartDate"  display=true header="StartDate" type="date" mask="Y/m/d"/> 
    </cfgrid> 
</cfform>

For details of various types of masks that can be used, see the CFML Reference Guide.

If the attribute mask is applied to a datefield column in an HTML grid, ColdFusion converts the date to an intermediate format as shown here:

MMMMM, dd yyyy HH:mms

for example,

January, 19 2005 07:35:42

This is required for proper date conversion and is applicable both when data is sent to the server (for example, when using an onChange grid event) and when data is received from the server (for example, populating a date field in a grid). Therefore, in some cases, users might have to format the date if they are updating a date column in the database.

You use the bind attribute and bind expressions to dynamically and incrementally load and display tree data as the user navigates the tree. The child tree items do not exist until the parent node expands. This behavior avoids prefilling a tree with large amounts of data. It lets the tree children change dynamically (you can optionally get the children each time the item expands) and can enhance application responsiveness.

For more information about binding and bind parameters, see Binding data to form fields.

Bind expressions in trees work in the following ways:

• If you use a bind expression, the cftree tag can have only a single cftreeitem tag. Therefore, the function or URL called by the bind expression must be able to populate all levels of the tree.

• When a tree item expands, the CFC or JavaScript function or active page specified by the bind attribute returns an array with the values for the child nodes of the item. The dynamic tree code on the client constructs the child items by using these values.

• When a control to which the tree is bound generates an event that the tree is listening for, the tree is refreshed. For example, if the tree uses a bind expression that includes a select box as a bind parameter, the tree collapses to the root nodes when the selected value in the select box changes.

When you use a bind expression to populate a cftree control, specify a CFC function, JavaScript function, or URL, and pass the following bind parameters. If you omit either of the parameters from your function call or URL, you get an error. These parameters provide information about the tree and its state, and are automatically provided by the control.

The called function or URL cannot return nested arrays and structures, that is, it can only return a single level of items.

When a function or URL is first called to populate the root-level tree items, the value passed in the cftreeitemvalue variable is the empty string. Your bind function can test for an empty string to determine that it is populating the root level of the tree.

The @none event specifier is also useful if you use the ColdFusion.Tree.refresh JavaScript function to manually refresh the tree. When you call the Refresh function, the bind expression fetches data from all bind parameters, including @none parameters. If you specify @none in all bind parameters that specify other controls, the tree does not respond automatically to changes in the other controls, but it does pick up data from the bind parameters when you use the ColdFusion.Tree.Referesh function to explicitly refresh the tree.

The format of the data that the function or URL in a bind expression must return depends on the type of bind expression

Each structure in the array of structures or objects defines the contents and appearance of the node for a child item. Each structure must have a VALUE field, and can have the following fields. Except for LEAFNODE, these structure keys correspond to cftreeitem attributes.

• DISPLAY

• EXPAND

• HREF

• IMG

• IMGOPEN

• LEAFNODE

• TARGET

The LEAFNODE structure element is only used in the bind response structures. It must be a Boolean value that identifies whether the node is a leaf. If the value is true, the tree does not show a +/- expansion indicator in front of the node, and users cannot expand the node.

If your bind expression specifies a JavaScript function, the function must use all-uppercase letters for the field names; for example, use VALUE and DISPLAY, not value and display. ColdFusion uses all capital letters in the structure key names. ColdFusion is not case-sensitive, so CFCs can use lowercase letters for the field names; JavaScript is case-sensitive, so the JavaScript function must match the uppercase field names.

If you use a URL to get the tree items from a CFML page, you can use the serializeJSON function to convert the array to JSON format. If the array with the tree items is named itemsArray, for example, the following line specifies the page output:

<cfoutput>#serializeJSON(itemsArray)#</cfoutput>

The following simple example creates a simple hierarchical tree of unlimited depth, with one node per level. Each node label (specified by the display attribute) identifies the node depth:

The following example shows the CFML page:

<cfform name="testform"> 
    <cftree name="t1" format="html"> 
        <cftreeitem bind="cfc:makeTree.getNodes({cftreeitemvalue},{cftreeitempath})"> 
    </cftree> 
</cfform>

The following example shows the maketree.cfc file with the getNodes method that is called when the user expands a node:

<cfcomponent> 
    <cffunction name="getNodes" returnType="array" output="no" access="remote"> 
        <cfargument name="nodeitemid" required="true"> 
        <cfargument name="nodeitempath" required="true"> 
        <!--- The initial value of the top level is the empty string. ---> 
        <cfif nodeitemid IS ""> 
            <cfset nodeitemid =0> 
        </cfif> 
        <!--- Create an array with one element defining the child node. ---> 
        <cfset nodeArray = ArrayNew(1)> 
        <cfset element1 = StructNew()> 
        <cfset element1.value = nodeitemid + 1> 
        <cfset element1.display = "Node #nodeitemid#"> 
        <cfset nodeArray[1] = element1> 
        <cfreturn nodeArray> 
    </cffunction> 
</cfcomponent>

The following tree uses the cfartgallery database to populate a tree where the top level is the art medium, the second level is the artist, and the leaf nodes are individual works of art. When the user clicks an artwork, the application shows the art image.

This example shows how to generate return values that are specific to the level in the tree and the parent value. It also shows the use of the LEAFNODE return structure element.

In this application, the CFC return structure keys are specified in lowercase letters, and ColdFusion automatically converts them to uppercase. Notice that the database contains entries only for the painting, sculpture, and photography categories, so just those top-level tree nodes have child nodes.

The following example shows the main application page:

<html xmlns="http://www.w3.org/1999/xhtml"> 
<head> 
<!--- The loadimage function displays the image of the selected art. 
        It is called when the user clicks the image item. ---> 
<script> 
    function loadImage(img) { 
        var imgURL = '<img src="/cfdocs/images/artgallery/'+img+'">'; 
        var imgDiv = document.getElementById('image'); 
            imgDiv.innerHTML = imgURL; 
    } 
</script> 
 
</head> 
<body> 
 
<!--- The form uses a table to place the tree and the image. ---> 
<cfform name="ex1" action="ex1.cfm" method="post"> 
    <table> 
        <tr valign="top"> 
            <td> 
                <cftree name="mytree" format="html"> 
                    <!--- When you use a bind expression, you must have only one 
                            cftreeitem, which populates the tree level. ---> 
                    <cftreeitem bind="cfc:tree.getItems({cftreeitempath}, 
                        {cftreeitemvalue})"> 
                </cftree> 
            </td> 
            <td> 
                <div id="image"></div> 
            </td> 
        </tr> 
    </table> 
</cfform> 
</body> 
</html>

The following example shows the tree.cfc file:

<cfcomponent output="false"> 
 
<cfset variables.dsn = "cfartgallery"> 
 
<!--- Function to populate the current level of the tree. ---> 
<cffunction name="getItems" returnType="array" output="false" access="remote"> 
    <cfargument name="path" type="string" required="false" default=""> 
    <cfargument name="value" type="string" required="false" default=""> 
    <cfset var result = arrayNew(1)> 
    <cfset var q = ""> 
    <cfset var s = ""> 
     
    <!--- The cfif statements determine the tree level. ---> 
    <!--- If there is no value argument, the tree is empty. Get the media types. ---> 
    <cfif arguments.value is ""> 
        <cfquery name="q" datasource="#variables.dsn#"> 
        SELECT mediaid, mediatype 
        FROM media 
        </cfquery> 
        <cfloop query="q"> 
            <cfset s = structNew()> 
            <cfset s.value = mediaid> 
            <cfset s.display = mediatype> 
            <cfset arrayAppend(result, s)>         
        </cfloop> 
 
    <!--- If the value argument has one list entry, it is a media type. Get the artists for 
            the media type.---> 
    <cfelseif listLen(arguments.value) is 1> 
        <cfquery name="q" datasource="#variables.dsn#"> 
        SELECT artists.lastname, artists.firstname, artists.artistid 
        FROM art, artists 
        WHERE art.mediaid = <cfqueryparam cfsqltype="cf_sql_integer" 
                value="#arguments.value#"> 
        AND art.artistid = artists.artistid  
        GROUP BY artists.artistid, artists.lastname, artists.firstname 
        </cfquery> 
        <cfloop query="q"> 
            <cfset s = structNew()> 
            <cfset s.value = arguments.value & "," & artistid> 
            <cfset s.display = firstName & " " & lastname> 
            <cfset arrayAppend(result, s)>         
        </cfloop> 
     
    <!--- We only get here when populating an artist's works. ---> 
    <cfelse> 
        <cfquery name="q" datasource="#variables.dsn#"> 
        SELECT art.artid, art.artname, art.price, art.description, 
                art.largeimage, artists.lastname, artists.firstname 
        FROM art, artists 
        WHERE art.mediaid = <cfqueryparam cfsqltype="cf_sql_integer" 
                value="#listFirst(arguments.value)#"> 
        AND art.artistid = artists.artistid  
        AND artists.artistid = <cfqueryparam cfsqltype="cf_sql_integer"  
                value="#listLast(arguments.value)#"> 
        </cfquery> 
        <cfloop query="q"> 
            <cfset s = structNew()> 
            <cfset s.value = arguments.value & "," & artid> 
            <cfset s.display = artname & " (" & dollarFormat(price) & ")"> 
            <cfset s.href = "javaScript:loadImage('#largeimage#');"> 
            <cfset s.children=arrayNew(1)> 
            <!--- leafnode=true prevents node expansion and further calls to the 
                bind expression. ---> 
            <cfset s.leafnode=true> 
            <cfset arrayAppend(result, s)>         
        </cfloop> 
         
    </cfif> 
         
    <cfreturn result> 
</cffunction> 
 
</cfcomponent>

You can customize the rich text editor in many ways. The cftextarea attributes support some basic customization techniques. For more detailed information, see the FCKEditor website at http://wiki.fckeditor.net/.

You can use the following techniques to control the appearance of the toolbar:

• Specify the toolbar name in the toolbar attribute

• Create custom toolbars in the fckconfig.js file.

The editor has a single toolbar consisting of a set of active icons and fields, and separators. The toolbar attribute lets you select the toolbar configuration. The attribute value specifies the name of a toolbar set, which you define in a FCKConfig.ToolbarSets entry in the cf_webRoot/CFIDE/scripts/ajax/FCKEditor/fckconfig.js file.

The rich text editor comes configured with two toolbar sets: the Default set, which contains all supported editing controls, and a minimal Basic set. By default, the editor uses the Default set. To create a custom toolbar named BasicText with only text-editing controls, create the following entry in the fckconfig.js file, and specify toolbar="BasicText" in the textarea tag.

FCKConfig.ToolbarSets["BasicText"] = [ 
        ['Source','DocProps','-','NewPage','Preview'], 
        ['Cut','Copy','Paste','PasteText','PasteWord','-','Print','SpellCheck'], 
        ['Undo','Redo','-','Find','Replace','-','SelectAll','RemoveFormat'], 
        ['Bold','Italic','Underline'], 
        ['Outdent','Indent'], 
        ['JustifyLeft','JustifyCenter','JustifyRight','JustifyFull'], 
        '/', 
        ['Style','FontFormat','FontName','FontSize'], 
        ['TextColor','BGColor'], 
        ['FitWindow','-','About'] 
    ];

This configuration defines a toolbar with two rows that contain a subset of the full tool set designed to support basic text editing.

Follow these rules when you define a toolbar:

• Start the definition with FCKConfig.ToolbarSets.

• Specify the toolbar name in double quotation marks and brackets ([""]). Use this name, case correct, in the cftextarea tag toolbar attribute.

• Follow the toolbar name with an equal sign (=).

• Place all the toolbar controls inside a set of brackets, and follow the definition with a semicolon (;).

• Group controls in brackets.

• Place each entry in single quotation marks (') and separate the entries with commas (,).

• Use the hyphen (-) character to specify a separator.

• Use a forward slash (/) character to start a new row.

For a complete list of the valid toolbar entries, see the Default configuration in fckconfig.js.

You can add custom styles that users choose in the Styles selector and apply to selected text. To create a custom style, add a Style element to /CFIDE/scripts/ajax/FCKEditor/fckstyles.xml. The Style XML element has the following format:

• The name attribute specifies the name that appears in the Style selector.

• The element attribute specifies the HTML element that surrounds the text.

• Each Attribute child element defines the name and value of an attribute of the HTML tag.

For example, the following definition creates a style that makes the selected text bold and underlined:

<Style name="Custom Bold And Underline " element="span"> 
    <Attribute name="style" value="font-weight: bold; text-decoration: underline;"/> 
</Style>

If you use a custom XML file, instead of fckstyles.xml, to define your styles, specify the filepath in the stylesXML attribute.

The editor includes a set of basic templates that insert HTML formatting into the textarea control. For example, the ImageandTitle template places a placeholder for an image on the left of the area, and a title and text to the right of the image. Then right-click the image area to specify the image source and other properties, and replace the placeholder title and text.

You create your own templates by creating entries in cf_webRoot/CFIDE/scripts/ajax/FCKEditor/fcktemplates.xml file. Each template XML entry has the following format:

    <Template title="template title" image="template image"> 
        <Description>template description</Description> 
        <Html> 
            <![CDATA[ 
                HTML to insert in the text area when the user selects the template. 
            ]]> 
        </Html> 
    </Template>

The template title, image, and description appear in the Templates dialog box that appears when the user clicks the template icon on the rich text editor toolbar.

The following example template defines a title followed by text:

<Template title="Title and Text" image="template1.gif"> 
    <Description>A Title followed by text.</Description> 
    <Html> 
        <![CDATA[ 
            <h3>Type the title here</h3> 
            Type the text here 
        ]]> 
    </Html> 
</Template>

The name "Title and Text" and the template1.gif image appear in the template selection dialog box.

If you use a custom XML file, instead of fcktemplates.xml, to define your templates, specify the file path in the templatesXML attribute.

To create a custom skin that you specify in the skin attribute, create a subdirectory of the cf_webRoot/CFIDE/scripts/ajax/FCKeditor/editor/skins directory. The name of this subdirectory is the name that you use to specify the skin in the skin attribute. The custom skin directory must contain an images subdirectory and have the following files:

• fck_editor.css: Defines the main interface, including the toolbar, its items (like, buttons, panels) and the context menu.

• fck_dialog.css: Defines the basic structure of dialog boxes (standard for all dialogs).

• fck_strip.gif: Defines the Default toolbar buttons and context menu icons. It is a vertical image that contains all icons placed one above the other. Each icon must correspond to a 16x16 pixels image. You can add custom images to this strip.

• images/toolbar.buttonarrow.gif: Defines the small arrow image used in the toolbar combos and panel buttons.

Place all other images used by the skin (that are specified in the CSS files) in the images subfolder.

The most common way of customizing the skin is to change the fck_editor.css and fck_dialog.css files. For information on the skin format and contents, see the comments in those files.

The following code illustrates how you can manipulate a slider at runtime:

 <script language="javascript"> 
    //use Coldfusion AJAX functions 
    var sliderChange = function(slider,value) 
    { 
        //get slider name 
        slidername = slider.getId(); 
        //get slider value 
        currValue = ColdFusion.Slider.getValue(slidername); 
        //set a new slider value 
        newValue = parseInt(currValue+10); 
        ColdFusion.Slider.setValue(slidername,newValue); 
        //hide slider 
        if(confirm("Do you want to hide slider?")) 
        { 
            ColdFusion.Slider.hide(slidername); 
        } 
        //show slider 
        if(confirm("Do you want to show slider?")) 
        { 
                ColdFusion.Slider.show(slidername); 
        } 
        //disable slider 
        if(confirm("Do you disable the slider?")) 
        { 
            ColdFusion.Slider.disable(slidername); 
        } 
        //enable slider 
        if(confirm("Do you enable the slider?")) 
        { 
            ColdFusion.Slider.enable(slidername); 
        } 
    } 
    var sliderDrag = function(slider) 
    { 
        //get slider name 
        slidername = slider.getId(); 
        document.getElementById('currentSliderValue').innerHTML =  "Current Slider value : <font color='red'><strong>" + ColdFusion.Slider.getValue(slidername) + "<strong></font>"; 
    } 
</script> 
<br> 
<cfform name="frm1"> 
    <p> 
    <span id="currentSliderValue">Current Slider Value: <font color="red"><strong>50</strong></font></span><br> 
    </p> 
</cfform> 
<p> 
<br><b>Volume</b>: 
<cfslider 
    name="s" 
    format="html" 
    min=1 
    max=100 
    value="50" 
    tip="yes" 
    onChange="sliderChange" 
    onDrag = "sliderDrag" 
    vertical="no" 
    width="200pt" 
    > 
</p>

To manually populate data in the marker window, specify the value in the markerwindowcontent attribute.

To dynamically populate data, use the markerbind attribute with a bind expression that calls a CFC, JavaScript function, or a URL. The bind expression uses bind parameters to specify dynamic information and the values of any other form field attributes.

Pass the bind parameters to the bind expression. If you omit any of the parameters in the function call or URL, you get an error. These parameters send information about the map and its state to the data provider function. The data for these parameters is provided automatically. You do not set any values manually.

Provide the data as provided in the following code:

<br> 
<cfoutput> 
<table> 
    <tr> 
        <td bgcolor='red'><h4><font color='white'>URL Bind Example</font></td> 
    </tr> 
</table> 
Map Name: #cfmapname#<br> 
Latitude, Longitude: (#DecimalFormat(cfmaplatitude)#,#DecimalFormat(cfmaplongitude)#)<br> 
Address: #cfmapaddress#<br> 
</cfoutput>

The following table provides details of the parameters:

The format of the returned data depends on how you get the data:

Use the showmarkerwindow attribute to control the display of the window.

The following example uses a bind expression and a CFC to populate dynamic data using a CFC bind expression. The CFML page contains the following:

<br> 
<cfmap 
        centeraddress="Hobart, Tasmania, Australia" 
        name="map1" 
        type="map" 
        tip="Hobart, Tasmania, Australia" 
        zoomControl="small3d" 
        markerbind="cfc:maps.getMapData({cfmapname}, {cfmaplatitude}, {cfmaplongitude},             {cfmapaddress})" 
        showmarkerwindow = true> 
    <cfmapitem name="m1" address="Taj Mahal, Agra, India" tip="Taj Mahal, Agra, India"> 
    <cfmapitem name="m2" latitude="40.46" longitude="117.05" showmarkerwindow=true                 tip="Great Wall of China, Bejing"> 
    <cfmapitem name="m3" address="Stonehenge, England" tip="Stonehenge, England"     showmarkerwindow = false> 
</cfmap>

The map.cfc is as follows:

<cfcomponent> 
    <cffunction name="getMapData" access="remote"> 
        <cfargument name="cfmapname"> 
        <cfargument name="cfmaplatitude"> 
        <cfargument name="cfmaplongitude"> 
        <cfargument name="cfmapaddress"> 
        <cfsavecontent variable="markup"> 
            <br> 
            <cfoutput> 
            <table> 
                <tr> 
                    <td bgcolor='red'><h4><font color='white'>CFC Bind Example</font></td> 
                </tr> 
            </table> 
            Map Name: #cfmapname#<br> 
            Latitude, Longitude: (#DecimalFormat(cfmaplatitude)#,#DecimalFormat(cfmaplongitude)#)<br> 
            Address: #cfmapaddress#<br> 
            </cfoutput> 
        </cfsavecontent>     
        <cfreturn markup> 
    </cffunction> 
</cfcomponent>

The following example shows how to populate dynamic data using a JavaScript bind expression:

<script language="JavaScript"> 
    var getMapData = function(cfmapname, cfmaplatitude, cfmaplongitude, cfmapaddress){ 
        var msg = ""; 
        msg = msg + "Map Name: " + cfmapname + "<br>"; 
        msg = msg + "Latitude,longitude: " + "("  + cfmaplatitude + "," + cfmaplongitude + ")" + "<br>"; 
        msg = msg + "Address: " + cfmapaddress + "<br>"; 
        //alert(msg); 
        return "<br><table><tr><td bgcolor='red'><h4><font color='white'>" + "Javascript Bind Example" + "</font></td></tr></table><hr>" + msg; 
    } 
</script> 
<cfmap 
    centeraddress="Hobart, Tasmania, Australia" 
    name="map1" 
    type="map" 
    tip="Hobart, Tasmania, Australia" 
    zoomControl="small3d" 
    markerbind="javascript:getMapData({cfmapname}, {cfmaplatitude}, {cfmaplongitude}, {cfmapaddress})" 
    showmarkerwindow = true> 
    <cfmapitem name="m1" address="Taj Mahal, Agra, India" tip="Taj Mahal, Agra, India"> 
    <cfmapitem name="m2" latitude="40.46" longitude="117.05" showmarkerwindow=true tip="Great Wall of China, Bejing"> 
    <cfmapitem name="m3" address="Stonehenge, England" tip="Stonehenge, England" showmarkerwindow = false> 
</cfmap>

The following example shows how to populate dynamic data using a URL bind expression:

<cfmap 
    centeraddress="Hobart, Tasmania, Australia" 
    name="map1" 
    type="map" 
    tip="Hobart, Tasmania, Australia" 
    zoomControl="small3d" 
markerbind="url:mapdata.cfm?cfmapname={cfmapname}&cfmaplatitude={cfmaplatitude}&cfmaplongitude={cfmaplongitude}&cfmapaddress={cfmapaddress}" 
    showmarkerwindow = true    > 
    <cfmapitem name="m1" address="Taj Mahal, Agra, India" tip="Taj Mahal, Agra, India"> 
    <cfmapitem name="m2" latitude="40.46" longitude="117.05" showmarkerwindow=true tip="Great Wall of China, Bejing"> 
    <cfmapitem name="m3" address="Stonehenge, England" tip="Stonehenge, England" showmarkerwindow = false> 
</cfmap>