When the user submits a form, ColdFusion runs the action page specified by the cfform or form tag action attribute. A ColdFusion action page is 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.
The action page gets a form variable for every form control that contains a value when the form is submitted.
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.
On the action page, the form variables are in the Form scope, so you should 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>
The Form scope also contains a list variable called Form.fieldnames. It contains a list of all form variables submitted to the action page. If no form variables are passed to the action page, ColdFusion does not create the Form.fieldnames list.
As described in previous chapters, you can retrieve a record for every employee in a database table by composing a query like the following:
<cfquery name="GetEmployees" datasource="cfdocexamples"> SELECTFirstName, LastName, Contract FROM Employee </cfquery>
When you want to return information about employees that matches user search criteria, you use the SQL WHERE clause with a SQL SELECT statement. 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 the following:
<cfquery name="GetEmployees" datasource="cfdocexamples"> 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="cfdocexamples"> SELECT FirstName, LastName, Salary FROM Employee WHERE LastName=<cfqueryparam value="#Form.LastName#" CFSQLType="CF_SQL_VARCHAR"> </cfquery>
For security, this example encapsulates the form variable within the cfqueryparam tag to ensure that the user passed a valid string value for the LastName. For more information on using the cfqueryparam tag with queries and on dynamic SQL, see Accessing and Retrieving Data.
Use the following procedure to create an action page for the formpage.cfm page that you created in the previous example.
Create an action page for the form
The following table describes the highlighted code and its function:
Code |
Description |
---|---|
<cfquery name="GetEmployees" datasource="cfdocexamples"> |
Queries the data source cfdocexamples and names the query GetEmployees. |
SELECT FirstName, LastName, Salary FROM Employee WHERE LastName=<cfqueryparam value="#Form.LastName#" CFSQLType="CF_SQL_VARCHAR"> |
Retrieves 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"> |
Displays results of the GetEmployees query. |
#FirstName# #LastName# #Salary#<br> |
Displays the value of the FirstName, LastName, and Salary fields for a record, starting with the first record, then goes to the next line. Keeps 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> |
Closes the cfoutput block. |
<br> <cfoutput>Contractor: #Form.Contractor# </cfoutput> |
Displays 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. |