Working with Action Pages

A ColdFusion action page is just like any other application page except that you can use the form variables that are passed to it from an associated form. The following sections describe how to create effective action pages.

Processing form variables on action pages

The action page gets a form variable for every form control that contains a value when the form is submitted.

Note

If multiple controls have the same name, one form variable is passed to the action page. It contains a comma-delimited list.

A form variable's name is the name that you assigned to the form control on the form page. Refer to the form variable by name within tags, functions, and other expressions on an action page.

Because Form variables extend beyond the local page-their scope is the action page-prefix them with "Form." to explicitly tell ColdFusion that you are referring to a form variable. For example the following code references the LastName form variable for output on an action page:

<cfoutput>

  #Form.LastName#

</cfoutput>

Dynamically generating SQL statements

As you have already learned, you can retrieve a record for every employee in a database table by composing a query like this:

<cfquery name="GetEmployees" datasource="CompanyInfo">

  SELECT  FirstName, LastName, Contract

  FROM   Employee

</cfquery>

But when you want to return information about employees that match user search criteria, you use the SQL WHERE clause with a SQL SELECT statement to compare a value against a character string field. When the WHERE clause is processed, it filters the query data based on the results of the comparison.

For example, to return employee data for only employees with the last name of Smith, you build a query that looks like this:

<cfquery name="GetEmployees" datasource="CompanyInfo">

  SELECT FirstName, LastName, Contract

  FROM    Employee

  WHERE  LastName = "Smith"

</cfquery>

However, instead of putting the LastName directly in the SQL WHERE clause, you can use the text that the user entered in the form for comparison:

<cfquery name="GetEmployees" datasource="CompanyInfo">

  SELECT FirstName, LastName, Salary

  FROM Employee

  WHERE LastName="#Form.LastName#"

</cfquery>

For more information on Dynamic SQL, see "Dynamic SQL".

Creating action pages

Use the following procedure to create an action page for cormpage.cfm.

To create an action page for the form:

Create a new application page in ColdFusion Studio.

Enter the following code:

<html>

<head>

<title>Retrieving Employee Data Based on Criteria from Form</title>

</head>



<body>

<cfquery name="GetEmployees" datasource="CompanyInfo">

  SELECT FirstName, LastName, Salary

  FROM Employee

  WHERE LastName='#Form.LastName#'

</cfquery>

<h4>Employee Data Based on Criteria from Form</h4>

<cfoutput query="GetEmployees">

#FirstName#

#LastName#

#Salary#<br>

</cfoutput>

<br>

<cfoutput>Contractor: #Form.Contractor#</cfoutput>

</body>

</html>

Save the page as actionpage.cfm within the myapps directory.
View formpage.cfm in your browser.
Enter data, for example, Smith, in the Last Name box and submit the form.
The browser displays a line with the first and last name and salary for each entry in the database that match the name you typed, followed by a line with the text "Contractor: Yes"
Click Return in your browser to redisplay the form.
Remove the check mark from the check box and submit the form again.
This time an error occurs because the check box does not pass a variable to the action page.

Reviewing the code

The following table describes the highlighted code and its function:

Code

Description

<cfquery name="GetEmployees" datasource="CompanyInfo">
Query the data source CompanyInfo and name the query GetEmployees.

SELECT FirstName, LastName, Salary FROM Employee WHERE LastName='#Form.LastName#'
Retrieve the FirstName, LastName, and Salary fields from the Employee table, but only if the value of the LastName field matches what the user entered in the LastName text box in the form on formpage.cfm.

<cfoutput query="GetEmployees">
Display results of the GetEmployees query.

#FirstName# #LastName# #Salary#<BR>
Display the value of the FirstName, LastName, and Salary fields for a record, starting with the first record, then go to the next line. Keep displaying the records that match the criteria you specified in the SELECT statement, followed by a line break, until you run out of records.

</cfoutput>
Close the cfoutput block.

<br> <cfoutput>Contractor: #Form.Contractor#</cfoutput>
Display a blank line followed by the text Contractor: and the value of the form Contractor check box. A more complete example would test to ensure the existence of the variable and would use the variable in the query.

Code	Description
<cfquery name="GetEmployees" datasource="CompanyInfo">	Query the data source CompanyInfo and name the query GetEmployees.
SELECT FirstName, LastName, Salary FROM Employee WHERE LastName='#Form.LastName#'	Retrieve the FirstName, LastName, and Salary fields from the Employee table, but only if the value of the LastName field matches what the user entered in the LastName text box in the form on formpage.cfm.
<cfoutput query="GetEmployees">	Display results of the GetEmployees query.
#FirstName# #LastName# #Salary#<BR>	Display the value of the FirstName, LastName, and Salary fields for a record, starting with the first record, then go to the next line. Keep displaying the records that match the criteria you specified in the SELECT statement, followed by a line break, until you run out of records.
</cfoutput>	Close the `cfoutput` block.
<br> <cfoutput>Contractor: #Form.Contractor#</cfoutput>	Display a blank line followed by the text Contractor: and the value of the form Contractor check box. A more complete example would test to ensure the existence of the variable and would use the variable in the query.

Testing for a variable's existence

Before relying on a variable's existence in an application page, you can test to see if it exists using the IsDefined function. A function is a named procedure that takes input and operates on it. For example, the IsDefined function determines whether a variable is defined. CFML provides a large number of functions, which are documented in the CFML Reference.

The following code prevents the error that you saw in the previous example by checking to see if the Contractor Form variable exists before using it:

<cfif IsDefined("Form.Contractor")>

  <cfoutput>Contractor: #Form.Contractor#</cfoutput>

</cfif>

The argument passed to the IsDefined function must always be enclosed in double quotes. For more information on the IsDefined function, see the CFML Reference.

If you attempt to evaluate a variable that you did not define, ColdFusion cannot process the page and displays an error message. To help diagnose such problems, use the interactive debugger in ColdFusion Studio or turn on debugging in the ColdFusion Administrator. The Administrator debugging information shows which variables are being passed to your application pages.

Form variable notes and considerations

When using form variables, keep the following guidelines in mind:

A Form variable's scope is the action page.
Prefix form variables with "Form." when referencing them on the action page.
Surround variable values with pound signs (#) for output.
Check boxes and radio button variables only get passed to the action page if you select an option. Text boxes pass an empty string if you do not enter text.
An error occurs if the action page tries to use a variable that has not been passed.

Developing ColdFusion Applications
Retrieving and Formatting Data