Using Forms to Specify the Data to Retrieve

In the examples in previous chapters, you have retrieved all of the records from a table. However, there are many instances when you want to retrieve data based on certain criteria. For example, you might want to see 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 want to 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.

Note

Because forms are standard HTML, the syntax and examples that follow provide you with just enough detail to begin using ColdFusion.

form tag syntax

Use the following syntax for the create a 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. The following example specifies a request timeout 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 choose form control input types based on the type of input the user should provide.

The following table illustrates 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 a sample form.

To create a form

Create a new application page, using ColdFusion Studio.

Edit the page so that it appears as follows:

<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.
Remember that you need an action page in order to submit values; you will create one later in this chapter.

Reviewing the code

The following table describes the highlighted code and its function:.

Code

Description

<form action="actionpage.cfm" method="post">
Gather 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">
Create a text box called FirstName where users can enter their first name. Make it 20 characters wide, but allow input of up to 35 characters.

<input type="Text" name="LastName" size="20" maxlength="35">
Create a text box called LastName where users can enter their first name. Make it 20 characters wide, but allow input of up to 35 characters.

<input type="Text" name="Salary" size="10" maxlength="10">
Create a text box called Salary where users can enter a salary to look for. Make it 10 characters wide, and allow 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>
Create 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|No" checked>Yes
Create a check box that allows users to specify whether they want to list employees who are contractors. Make the box selected by default.

<input type="Reset" name="ResetForm" value="Clear Form">
Create a reset button to allow users to clear the form. Put the text Clear Form on the button.

<input type="Submit" name="SubmitForm" value="Submit">
Create a submit button to send the values that users enter to the action page for processing. Put the text Submit on the button.

Code	Description
<form action="actionpage.cfm" method="post">	Gather 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">	Create a text box called FirstName where users can enter their first name. Make it 20 characters wide, but allow input of up to 35 characters.
<input type="Text" name="LastName" size="20" maxlength="35">	Create a text box called LastName where users can enter their first name. Make it 20 characters wide, but allow input of up to 35 characters.
<input type="Text" name="Salary" size="10" maxlength="10">	Create a text box called Salary where users can enter a salary to look for. Make it 10 characters wide, and allow 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>	Create 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\|No" checked>Yes	Create a check box that allows users to specify whether they want to list employees who are contractors. Make the box selected by default.
`<input type="Reset" name="ResetForm" value="Clear Form">`	Create a reset button to allow users to clear the form. Put the text Clear Form on the button.
`<input type="Submit" name="SubmitForm" value="Submit">`	Create a submit button to send the values that users enter to the action page for processing. Put the text Submit on the button.

Form notes and considerations

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 select 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 and radio buttons 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.
You can dynamically populate drop-down select lists using query data. See "Dynamically Populating List Boxes" for details.

Developing ColdFusion Applications
Retrieving and Formatting Data