When you return your results to the user, ensure that your pages respond to the user's needs and are appropriate for the type and amount of information. In particular, consider the following situations:
- When there are no query results
- When you return partial results
Handling no query results
Your code must accommodate the cases in which a query does not return any records. To determine whether a search has retrieved records, use the RecordCount query variable. You can use the variable in a conditional logic expression that determines how to display search results appropriately to users.
Note: For more information on query variables, including RecordCount, see Accessing and Retrieving Data. |
For example, to inform the user when no records are found by the GetEmployees query, insert the following code before displaying the data:
<cfif GetEmployees.RecordCount IS "0"> |
Do the following:
- Prefix RecordCount with the query name.
- Add a procedure after the cfif tag that displays a message to the user.
- Add a procedure after the cfelse tag to format the returned data.
- Follow the second procedure with a </cfif> tag end to indicate the end of the conditional code.
Return search results to users
- Edit the actionpage.cfm page.
Change the page so that it appears as follows:
<html>
<head>
<title>Retrieving Employee Data Based on Criteria from Form</title>
</head>
<body>
<cfquery name="GetEmployees" datasource="cfdocexamples">
SELECT Departmt.Dept_Name,
Employee.FirstName,
Employee.LastName,
Employee.StartDate,
Employee.Salary
FROM Departmt, Employee
WHERE Departmt.Dept_ID = Employee.Dept_ID
<cfif isdefined("Form.Department")>
AND Departmt.Dept_Name = <cfqueryparam value="#Form.Department#"
CFSQLType="CF_SQL_VARCHAR">
</cfif>
<cfif Form.LastName is not "">
AND Employee.LastName = <cfqueryparam value="#Form.LastName#"
CFSQLType="CF_SQL_VARCHAR">
</cfif>
</cfquery>
<cfif GetEmployees.recordcount is "0">
No records match your search criteria. <br>
Please go back to the form and try again.
<cfelse>
<h4>Employee Data Based on Criteria from Form</h4>
<table>
<tr>
<th>First Name</th>
<th>Last Name</th>
<th>Salary</th>
</tr>
<cfoutput query="GetEmployees">
<tr>
<td>#FirstName#</td>
<td>#LastName#</td>
<td>#Salary#</td>
</tr>
</cfoutput>
</cfif>
</table>
</body>
</html>- Save the file.
- Return to the form, enter search criteria, and submit the form.
- If no records match the criteria you specified, the message appears.
Returning results incrementally
You can use the cfflush tag to incrementally display long-running requests to the browser before a ColdFusion page is fully processed. This tag lets you give the user quick feedback when it takes a long time to complete processing a request. For example, when a request takes time to return results, you can use the cfflush tag to display the message, "Processing your request – please wait." You can also use it to incrementally display a long list as it gets retrieved.
The first time you use the cfflush tag on a page, it sends to the browser all of the HTML headers and any other available HTML. Subsequent cfflush tags on the page send only the output that ColdFusion generated after the previous flush.
You can specify an interval attribute to tell ColdFusion to flush the output each time that at least the specified number of bytes become available. (The count does not include HTML headers and any data that is already available when you make this call.) You can use the cfflush tag in a cfloop tag to incrementally flush data as it becomes available. This format is useful when a query responds slowly with large amounts of data.
When you flush data, make sure that a sufficient amount of information is available, because some browsers do not respond if you flush only a small amount. Similarly, if you use an interval attribute, set it for a reasonable size, such as a few hundred bytes or more, but not many thousands of bytes.
Limitations of the cfflush tag: Because the cfflush tag sends data to the browser when it executes, it has several limitations, including the following:
- Using any of the following tags or functions on a page anywhere after the cfflush tag can cause errors or unexpected results: cfcontent, cfcookie, cfform, cfheader, cfhtmlhead, cflocation, and SetLocale. (These tags and functions normally modify the HTML header, but cannot do so after a cfflush tag, because the cfflush tag sends the header.)
- Using the cfset tag to set a cookie anywhere on a page that has a cfflush tag does not set the cookie in the browser.
- Using the cfflush tag within the body of several tags, including cfsavecontent, cfqueryparam, and custom tags, can cause errors.
- If you save Client variables as cookies, any client variables that you set after a cfflush tag are not saved in the browser.
- You can catch cfflush errors, except Cookie errors, with a cfcatch tag. Catch cookie errors with a cfcatch type="Any" tag.
Example: using the cfloop tag and Rand function
The following example uses the cfloop tag and the Rand random number generating function to artificially delay the generation of data for display. It simulates a situation in which it takes time to retrieve the first data and additional information becomes available slowly.
<html> |
Reviewing the code
The following table describes the code and its function:
Code |
Description |
|
|---|---|---|
|
Sends the HTML header and all HTML output to the cfflush tag to the user. This displays the explanatory paragraph and H2 tag contents. |
|
|
Flushes additional data to the user whenever at least 10 bytes are available. |
|
|
Inserts an artificial delay by using the Rand function to calculate many random numbers. |
|
|
Generates and displays 10 random numbers. This code uses two loops. The outer loop repeats ten times, once for each number to display. The inner loop uses the Rand function to create another delay by generating more (unused) random numbers. It then calls the RandRange function to generate a six-digit random number for display. |
