# Using Forms to Specify the Data to Retrieve

Until now, you've retrieved all of the records from a table. However, there are many instances when you'll want to retrieve data based on certain criteria. For example, you may 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 not ColdFusion-specific, the syntax and examples that follow provide you with just enough detail to get going with ColdFusion.

## FORM tag syntax

    <FORM ACTION="actionpage.cfm" METHOD="Post">
        ...
    </FORM>

- Use the ACTION attribute to specify an action page to which you pass form variables for processing.
- Use the METHOD attribute to specify 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".

## Form Controls

Within the form, you'll 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.

###

HTML Form Controls
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
Select 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">

| To create a form:

1. Create a new application page, using Studio.
2. 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>

       <!-- select box -->
       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>

       <!-- 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>

3. Save the page as `formpage.cfm` within the `myapps` directory under your Web root directory.
4. 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.

### Code Review

A form appears on the page, ready for user input.

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 select 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 checkbox that allows users to specify whether they want to list employees who are contractors. Have the box checked 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 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.
- Limit radio buttons to three-to-five mutually exclusive options.

  If you need more than that many options, consider a dropdown select box.

- Use select boxes to allow the user to choose multiple items.
- All the data that you collect on a form is automatically passed as form variables to the associated action page.
- Checkboxes and radio buttons do not pass to action pages unless they are selected on a form. In fact, if you try to reference these variables on the action page, you will receive an error if they are not present.
- You can dynamically populate dropdown select boxes using query data. See "Dynamically Populating Select Boxes" for details.