Using forms to specify the data to retrieve

In the examples in previous chapters, you retrieved all of the records from a database table using a SQL query. However, there are many instances when you want to retrieve data based on certain criteria. For example, you might want to retrieve records for everyone in a particular department, everyone in a particular town whose last name is Smith, or books by a certain author.

You can use forms in ColdFusion applications to allow users to specify what data they retrieve in a query. When you submit a form, you pass the variables to an associated page, called an action page, where some type of processing takes place.

The following figure shows a form, defined by FormPage.cfm, and its associated action page, ActionPage.cfm:

A form and action page

Note: Because forms are standard HTML, the syntax and examples that follow provide you with just enough detail to begin using ColdFusion. For information on using ColdFusion forms defined by the cfform tag, see Chapter 27, "Building Dynamic Forms".

HTML form tag syntax

Use the following syntax for the HTML form tag:

<form action="actionpage.cfm" method="post">

  ...
</form>



  
  
     Attribute
     Description
  
  
    action


     Specifies an action page to which you pass form variables for processing.
  
  
    method


     Specifies how the variables are submitted from the browser to the action page on the server. All ColdFusion forms must be submitted with an attribute setting of method="post".

Attribute	Description
action	Specifies an action page to which you pass form variables for processing.
method	Specifies how the variables are submitted from the browser to the action page on the server. All ColdFusion forms must be submitted with an attribute setting of `method="post".`

You can override the server request timeout (set on the ColdFusion Administrator Server Settings page) by adding a RequestTimeout parameter to the action page URL. Requests that take longer than the specified time are terminated. The following example specifies a request time-out of two minutes:

<form name="getReportCriteria"
    action="runReport.cfm?RequestTimeout=120" method="post">

Form controls

Within the form, you describe the form controls needed to gather and submit user input. There are a variety of form controls types available. You select form control input types based on the type input you want to user to provide.

The following figure shows an example form containing different form controls:

Example form page and form control

The following table shows the format of form control tags:

Control

Code

Text control

<input type="Text" name="ControlName" size="Value" maxlength="Value">

Radio buttons

<input type="Radio" name="ControlName" value="Value1">DisplayName1 <input type="Radio" name="ControlName" value="Value2">DisplayName2 <input type="Radio" name="ControlName" value="Value3">DisplayName3

List box

<select name="ControlName"> <option value="Value1">DisplayName1 <option value="Value2">DisplayName2 <option value="Value3">DisplayName3 </select>

Check box

<input type="Checkbox" name="ControlName" value="Yes|No">Yes

Reset button

<input type="Reset" name="ControlName" value="DisplayName">

Submit button

<input type="Submit" name="ControlName" value="DisplayName">

Control	Code
Text control	<input type="Text" name="ControlName" size="Value" maxlength="Value">
Radio buttons	<input type="Radio" name="ControlName" value="Value1">DisplayName1 <input type="Radio" name="ControlName" value="Value2">DisplayName2 <input type="Radio" name="ControlName" value="Value3">DisplayName3
List box	<select name="ControlName"> <option value="Value1">DisplayName1 <option value="Value2">DisplayName2 <option value="Value3">DisplayName3 </select>
Check box	<input type="Checkbox" name="ControlName" value="Yes\|No">Yes
Reset button	<input type="Reset" name="ControlName" value="DisplayName">
Submit button	<input type="Submit" name="ControlName" value="DisplayName">

Use the following procedure to create the form in the previous figure.

To create a form:

Create a ColdFusion page with the following content:

<html>
<head>
<title>Input form</title>
</head>
<body>
<!--- define the action page in the form tag. The form variables will
    pass to this page when the form is submitted --->

<form action="actionpage.cfm" method="post">

<!-- text box -->
<p>
First Name: <input type="Text" name="FirstName" size="20" maxlength="35"><br>
Last Name: <input type="Text" name="LastName" size="20" maxlength="35"><br>
Salary: <input type="Text" name="Salary" size="10" maxlength="10">
</p>

<!-- list box -->
<p>
City
<select name="City">
  <option value="Arlington">Arlington
  <option value="Boston">Boston
  <option value="Cambridge">Cambridge
  <option value="Minneapolis">Minneapolis
  <option value="Seattle">Seattle
</select>
</p>

<!-- radio buttons -->
<p>
Department:<br>
<input type="radio" name="Department" value="Training">Training<br>
<input type="radio" name="Department" value="Sales">Sales<br>
<input type="radio" name="Department"
value="Marketing">Marketing<br>
</p>

<!-- check box -->
<p>
Contractor? <input type="checkbox" name="Contractor" 
value="Yes" checked>Yes
</p>

<!-- reset button -->
<input type="Reset" name="ResetForm" value="Clear Form">
<!-- submit button -->
<input type="Submit" name="SubmitForm" value="Submit">

</form>
</body>
</html>

Save the page as formpage.cfm within the myapps directory under your web root directory.
View the form in a browser.
The form appears in the browser.
Do not click the Submit button yet. Remember that you need an action page in order to submit values; you create one later in this chapter in "Creating action pages".

Reviewing the code

The following table describes the highlighted code and its function:

Code

Description

<form action="actionpage.cfm" method="post">

Gathers the information from this form using the Post method, and do something with it on the page actionpage.cfm.

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

Creates a text box called FirstName where users can enter their first name. Makes it 20 characters wide, but allows input of up to 35 characters.

<input type="Text" name="LastName" size="20" maxlength="35">

Creates a text box called LastName where users can enter their first name. Makes it 20 characters wide, but allows input of up to 35 characters.

<input type="Text" name="Salary" size="10" maxlength="10">

Creates a text box called Salary where users can enter a salary to look for. Makes it 10 characters wide, and allows input of up to 10 characters.

<select name="City"> <option value="Arlington"> Arlington <option value="Boston">Boston <option value="Cambridge"> Cambridge <option value="Minneapolis"> Minneapolis <option value="Seattle">Seattle </select>

Creates a drop-down list box named City and populate it with the values "Arlington," "Boston," "Cambridge," "Minneapolis," and "Seattle."

<input type="checkbox" name= "Contractor" value="Yes" checked>Yes

Creates a check box that allows users to specify whether they want to list employees who are contractors. Box selected by default.

<input type="Reset" name="ResetForm" value="Clear Form">

Creates a reset button to allow users to clear the form. Puts the text Clear Form on the button.

<input type="Submit" name="SubmitForm" value="Submit">

Creates a submit button to send the values that users enter to the action page for processing. Puts the text Submit on the button.

Code	Description
<form action="actionpage.cfm" method="post">	Gathers the information from this form using the Post method, and do something with it on the page actionpage.cfm.
<input type="Text" name="FirstName" size="20" maxlength="35">	Creates a text box called FirstName where users can enter their first name. Makes it 20 characters wide, but allows input of up to 35 characters.
<input type="Text" name="LastName" size="20" maxlength="35">	Creates a text box called LastName where users can enter their first name. Makes it 20 characters wide, but allows input of up to 35 characters.
<input type="Text" name="Salary" size="10" maxlength="10">	Creates a text box called Salary where users can enter a salary to look for. Makes it 10 characters wide, and allows input of up to 10 characters.
<select name="City"> <option value="Arlington"> Arlington <option value="Boston">Boston <option value="Cambridge"> Cambridge <option value="Minneapolis"> Minneapolis <option value="Seattle">Seattle </select>	Creates a drop-down list box named City and populate it with the values "Arlington," "Boston," "Cambridge," "Minneapolis," and "Seattle."
<input type="checkbox" name= "Contractor" value="Yes" checked>Yes	Creates a check box that allows users to specify whether they want to list employees who are contractors. Box selected by default.
`<input type="Reset"` `name="ResetForm"` `value="Clear Form">`	Creates a reset button to allow users to clear the form. Puts the text Clear Form on the button.
`<input type="Submit"` `name="SubmitForm"` `value="Submit">`	Creates a submit button to send the values that users enter to the action page for processing. Puts the text Submit on the button.

Form notes and considerations

When using forms, keep the following guidelines in mind:

To make the coding process easy to follow, name form controls the same as target database fields.
For ease of use, limit radio buttons to between three and five mutually exclusive options. If you need more options, consider a drop-down list.
Use list boxes to allow the user to choose from many options or to chose multiple items from a list.
All the data that you collect on a form is automatically passed as form variables to the associated action page.
Check boxes, radio buttons, and multiple select boxes do not pass to action pages unless they are selected on a form. If you try to reference these variables on the action page, you receive an error if they are not present. For information on how to determine if a variable exists on the action page, see "Testing for a variable's existence".
You can dynamically populate drop-down lists using query data. For more information, see "Dynamically populating list boxes".