ColdFusion.navigate

Description

Displays the output of a link target in an Ajax cfdiv, cflayoutarea, cfpod, or cfwindow container. When the browser follows a link that is populated by this function, the link does not replace the current page. Instead, it populates the control specified by the container attribute.

Function syntax

ColdFusion.navigate(URL [, container, callbackhandler, errorHandler, httpMethod, formId])

See also

AjaxLink, cfajaximport, ColdFusion.Ajax.submitForm, Control container contents in the Developing ColdFusion Applications

History

ColdFusion 8: Added this function

Parameters

Parameter

Description

URL

The URL of the link.

container

The name attribute value of the control in which to display the link output. The control must be a container control such as cfdiv, cflayoutarea, cfpod, or cfwindow.

If you omit this argument, the link is treated as a normal URL and the entire page is refreshed.

callbackhandler

The name of a JavaScript function to call after the target has been displayed.

errorHandler

The name of a JavaScript function to call if an error occurs when this function executes. The function can take two parameters: an HTTP error code, and an error message.

formId

The ID or name attribute of a form to submit to the URL.

httpMethod

The HTTP method to use when navigating to the URL:

  • GET (the default)

  • POST

Returns

This function does not return a value.

Usage

If the page that calls this function does not have any ColdFusion AJAX-based controls, you must use a cfajaximport tag on the page to ensure that the page includes the JavaScript definition for this function.

The callbackhandler parameter can be useful for changing the display after the contents has been displayed. For example, before you make the ColdFusion.navigate call you might make a pod's title bar italic to indicate loading; you could then use the callbackhandler function to switch it back to normal or make it bold once navigate completes. Similarly, you could use a callbackhandler to update the page number in a book reader.

The FormID attribute lets you specify a form to submit to the specified URL. You can use the ColdFusion.Navigate function with this attribute to submit form data asynchronously from outside the form, for example, when the user clicks a menu item, and to direct the returned results to a specific container control.

Example

When the user clicks the link in window 1, the ColdFusion.navigate function replaces the text in window 2 with the contents of windowsrc.cfm, and then calls the myCallback callback handler, which changes the innerHTML of the callback div region.

The main application page looks as follows:

<html> 
<head> 
<!--- The Callback handler puts text in the window.cfm callback div. ---> 
<script language="javascript"> 
    var mycallBack = function(){ 
        document.getElementById("callback").innerHTML = "<br><br><b>This is printed by the callback handler.</b>"; 
    }  
 
<!--- The error handler pops an alert with the error code and message. ---> 
    var myerrorhandler = function(errorCode,errorMessage){ 
        alert("[In Error Handler]" + "\n\n" + "Error Code: " + errorCode + "\n\n" + "Error Message: " + errorMessage); 
    }  
</script> 
</head> 
 
<body> 
<cfwindow name="w1" title="CF Window 1" initShow=true  
    x=10 y=10 width="200"> 
    This is a cfwindow control.<br><br> 
    <a href="javascript:ColdFusion.navigate('windowsource.cfm','w2', 
        mycallBack,myerrorhandler);">Click</a> to navigate Window 2</a> 
</cfwindow> 
 
<cfwindow name="w2" title="CF Window 2" initShow=true  
    x=250 y=10 width="200"> 
    This is a second cfwindow control. 
</cfwindow> 
</body> 
</html>

The windowsource.cfm page looks as follows:

This is markup from "windowsource.cfm" 
<!-- The callback handler puts its output in the following div block. --> 
<div id="callback"></div>