|
ColdFusion 9.0 Resources |
cfajaxproxyDescriptionCreates a JavaScript proxy for a ColdFusion component, for use in an AJAX client. Alternatively, creates a proxy for a single CFC method, JavaScript function, or URL that is bound to one or more control attribute values. Syntax<cfajaxproxy
cfc = "CFC name"
jsclassname = "JavaScript proxy class name">
OR
<cfajaxproxy
bind = "bind expression"
onError = "JavaScript function name"
onSuccess = "JavaScript function name">
Note: You can specify this tag’s attributes in an attributeCollection whose value
is a structure. Specify the structure name in the attributeCollection and
use the tag’s attribute names as structure keys.
See alsoDeserializeJSON, IsJSON, SerializeJSON, Using Ajax Data and Development Features in the Developing ColdFusion Applications Attributes
UsageMake sure that the Enable HTTP Status Codes option on the Server Settings > Settings page of the ColdFusion Administrator is selected. Otherwise, the proxy cannot determine if an error occurs in invoking the CFC function and cannot call the error handler. A cfajaxproxy tag with a bind attribute does not refresh any control that is not specified in the bind expression. If you specify a URL in the bind attribute, the HTTP response must consist of a single JSON representation of an object, array, or simple value, corresponding to the onSuccess argument. Creating a CFC proxyThe cfajaxproxy tag with a cfc attribute generates a JavaScript proxy that represents a CFC on the web client. The tag and the proxy it generates have the following characteristics:
For detailed information on using AJAX CFC proxies, see Using ColdFusion Ajax CFC proxies in Using Ajax Data and Development Features in the Developing ColdFusion Applications. Note: The proxy passes a _CF_NODEBUG Boolean
argument to called CFC functions. ColdFusion checks this value,
and when it is true, does not append to the response
any debugging information that it normally would send. This behavior ensures
that the JSON responses to AJAX requests do not include any non-JSON
(i.e., debug information) text.
CFC proxy utility functionsWhen you use the cfc option, the JavaScript proxy object provides the following functions that you can use to control interaction with the server:
ExampleThe following example uses a remote CFC method to populate a drop-down list of employees. When you select a name from the list, it uses a call to the CFC method to get information about the employee, and displays the results. The application page has the following lines: <!--- The cfajaxproxy tag creates a client-side proxy for the emp CFC.
View the generated page source to see the resulting JavaScript.
The emp CFC is in the components subdirectory of the directory that
contains this page. --->
<cfajaxproxy cfc="components.emp" jsclassname="emp">
<html>
<head>
<script type="text/javascript">
// Function to find the index in an array of the first entry
// with a specific value.
// It is used to get the index of a column in the column list.
Array.prototype.findIdx = function(value){
for (var i=0; i < this.length; i++) {
if (this[i] == value) {
return i;
}
}
}
// Use an asynchronous call to get the employees for the
// drop-down employee list from the ColdFusion server.
var getEmployees = function(){
// create an instance of the proxy.
var e = new emp();
// Setting a callback handler for the proxy automatically makes
// the proxy's calls asynchronous.
e.setCallbackHandler(populateEmployees);
e.setErrorHandler(myErrorHandler);
// The proxy getEmployees function represents the CFC
// getEmployees function.
e.getEmployees();
}
// Callback function to handle the results returned by the
// getEmployees function and populate the drop-down list.
var populateEmployees = function(res)
{
with(document.simpleAJAX){
var option = new Option();
option.text='Select Employee';
option.value='0';
employee.options[0] = option;
for(i=0;i<res.DATA.length;i++){
var option = new Option();
option.text=res.DATA[i][res.COLUMNS.findIdx('FIRSTNAME')]
+ ' ' + res.DATA[i][[res.COLUMNS.findIdx('LASTNAME')]];
option.value=res.DATA[i][res.COLUMNS.findIdx('EMP_ID')];
employee.options[i+1] = option;
}
}
}
// Use an asynchronous call to get the employee details.
// The function is called when the user selects an employee.
var getEmployeeDetails = function(id){
var e = new emp();
e.setCallbackHandler(populateEmployeeDetails);
e.setErrorHandler(myErrorHandler);
// This time, pass the employee name to the getEmployees CFC
// function.
e.getEmployees(id);
}
// Callback function to display the results of the getEmployeeDetails
// function.
var populateEmployeeDetails = function(employee)
{
var eId = employee.DATA[0][0];
var efname = employee.DATA[0][1];
var elname = employee.DATA[0][2];
var eemail = employee.DATA[0][3];
var ephone = employee.DATA[0][4];
var edepartment = employee.DATA[0][5];
with(document.simpleAJAX){
empData.innerHTML =
'<span style="width:100px">Employee Id:</span>'
+ '<font color="green"><span align="left">'
+ eId + '</font></span><br>'
+ '<span style="width:100px">First Name:</span>'
+ '<font color="green"><span align="left">'
+ efname + '</font></span><br>'
+ '<span style="width:100px">Last Name:</span>'
+ '<font color="green"><span align="left">'
+ elname + '</font></span><br>'
+ '<span style="width:100px">Email:</span>'
+ '<font color="green"><span align="left">'
+ eemail + '</span></font><br>'
+ '<span style="width:100px">Phone:</span>'
+ '<font color="green"><span align="left">'
+ ephone + '</font></span><br>'
+ '<span style="width:100px">Department:</span>'
+ '<font color="green"><span align="left">'
+ edepartment + '</font></span>';
}
}
// Error handler for the asynchronous functions.
var myErrorHandler = function(statusCode, statusMsg)
{
alert('Status: ' + statusCode + ', ' + statusMsg);
}
</script>
</head>
<body>
<!--- The form to display the employee drop-down list and
employee data. --->
<form name="simpleAJAX" method="get">
List of Employees:
<select name="employee" onChange="getEmployeeDetails(this.value)">
<script language="javascript">
getEmployees();
</script>
</select>
<br><br>
<span id="empData"></span>
</form>
</body>
</html>
The following component, which gets the data from the data source, must be in a file named emp.cfc in the components subdirectory of the application directory. The CFC uses the cfdocexamples data source that is installed with ColdFusion if you install the documentation. <cfcomponent>
<cfset this.dsn = "cfdocexamples">
<cffunction name="getEmployees" access="remote" returnFormat="json"
output="false">
<cfargument name="empid" required="no" type="string" default="0">
<cfquery name="qryEmp" datasource="#this.dsn#">
select * from Employees
<cfif empid neq 0>
where Emp_ID = #empid#
</cfif>
</Cfquery>
<cfreturn qryEmp>
</cffunction>
</cfcomponent>
|
