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, 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 placing 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.

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

The following code prevents the error in the previous example by checking to see whether 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-quotation marks. 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, turn on debugging in the ColdFusion Administrator. The Administrator debugging information shows which variables are being passed to your application pages.

One of the limitations of HTML forms is the inability to define input fields as required. Because this is an important requirement for database applications, ColdFusion lets you require users to enter data in fields. To specify a field as required, you can do either of the following:

• Use the required attribute of the cfinput, cfselect, cftextarea, and cftree tags.

• Use a hidden field that has a name attribute composed of the field name and the suffix _required. You can use this technique with CFML and HTML form tags.

For example, to require that the user enter a value in the FirstName field of a cfinput tag, use the following syntax:

<cfinput type="Text" name="FirstName" size="20" maxlength="35" required="Yes">

To require that the user enters a value in the FirstName field of an HTML input tag, use the following syntax:

<input type="Text" name="FirstName" size="20" maxlength="35"> 
<input type="hidden" name="FirstName_required">

In either of these examples, if the user leaves the FirstName field empty, ColdFusion rejects the form submittal and returns a message informing the user that the field is required. You can customize the contents of this error message.

If you use a required attribute, you customize the message by using the message attribute, as follows:

<cfinput type="Text" name="FirstName" size="20" maxlength="35" required="Yes" 
    message="You must enter your first name.">

If you use a hidden field tag, you customize the message using the value attribute of the hidden field, as follows:

<input type="hidden" name="FirstName_required" 
    value="You must enter your first name.">

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

• A form variable is available on the action page and pages that it includes.

• Prefix form variables with "Form."when referencing them on the action page.

• Surround variable values with number signs (#) for output.

• Variables for check boxes, radio buttons, and list boxes with size attributes greater than 1 only get passed to the action page if you select an option. Text boxes, passwords, and text area fields pass an empty string if you do not enter text.

• An error occurs if the action page tries to use a variable that was not passed.

• If multiple controls have the same name, one form variable is passed to the action page with a comma-delimited list of values.

• You can validate form variable values on the client or the server.