Using Forms and Action Pages

This chapter describes how to build forms, the characteristics of form variables, and how to work with form variables on action pages. During chapter practices, you will create a form and action page so that you can see how they work together.

In subsequent chapters, you will learn how to incorporate the logic into forms and actions pages so that you can create search engines and web front ends.

Contents

Using Forms
Building Forms
Form Notes and Considerations
Dynamically Populating Select Boxes
Understanding Action Pages
Working with Form Variables
Creating Action Pages
Form Variable Notes and Considerations
Development Considerations

Using Forms

You can use forms in ColdFusion applications to:

Gather user input.

For example, to gather user data for a login.

Provide the front end for search engines.

For example, users could enter employee information and then send this data to a database to selectively retrieve data.

Allow your users to add and update database records.

For example, users could enter employee information and that data would be used to populate a database.

When a form is submitted:

Its data is stored in form variables.
Forms can’t store or manipulate these form variables.
You pass form variables to an associated page called an action page.
The action page processes the data collected on the form.

For example, it is the action page that would process login information, perform the search, and handle database updates.

Building Forms

HTML forms begin with an opening FORM tag and end with a closing FORM tag. The FORM tag accepts two major attributes that you will use to describe the form’s associated action page and how to submit values to it.

Within the form block, you'll describe the form controls needed to gather and submit user input.

Note Because forms are not ColdFusion-specific, the syntax and examples that follow provide you with just enough detail to get going with ColdFusion Express.

FORM tag syntax

...

</FORM>

Specify an action page to pass form variables using the ACTION

attribute.
Use the METHOD attribute to specify how the variables are submitted

from the browser to the action page on the server.

Submit ColdFusion forms with an attribute setting of METHOD="Post".

Note GET is the default METHOD. It will be used if you don’t specify a METHOD attribute in the form tag.

Form control syntax

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. For example:

This code creates a text contol:

This code creates a series of radio buttons:

<INPUT TYPE="RadioButton" NAME="ControlName" VALUE="Value1">DisplayName1

<INPUT TYPE="RadioButton" NAME="ControlName" VALUE="Value2">DisplayName2

<INPUT TYPE="RadioButton" NAME="ControlName" VALUE="Value3">DisplayName3

This code creates a drop down select box:

<OPTION VALUE="Value1 ">DisplayName1

<OPTION VALUE="Value2">DisplayName2

<OPTION VALUE="Value3">DisplayName3

</SELECT>

This code creates a check box:

<INPUT TYPE="Checkbox" NAME="ControlName" VALUE="Yes|No">Yes

This code creates a reset button:

This code creates a submit button:

Form usage example

The code below creates a form for users to enter employee information. The comments explain the code in this context.

<HTML>

<HEAD>

<TITLE>Input form</TITLE>

</HEAD>

<BODY>

<H4>Employee Data Form</H4>

<P>

Employee Last Name<BR>

</P>

<P>

Department<BR>

<OPTION VALUE="Training">Training</OPTION>

<OPTION VALUE="Marketing">Marketing</OPTION>

<OPTION VALUE="Sales">Sales</OPTION>

</SELECT>

</P>

<P>

Contract Employee?<BR>

<INPUT TYPE="Checkbox" NAME="Contract" VALUE="Yes">Yes

</P>

<P>

</P>

<P>

</P>

</FORM>

</BODY>

</HTML>

To create a form to accept user input:

Create a new application page in HomeSite.
Save the page as FormPage.CFM within the CFDOCS directory. Remember

that CFDOCS resides under your web root directory.
Title the page Chapter 7 Form Page.
Add an opening FORM tag directly under the BODY tag:

Add a heading for the form page:

<H4>Employee Data Form </H4>

Add P tags to format the heading.
Add a text input control so that users can enter a last name on the

form:

Add a label above the form control to describe it on the form: Last

Name <BR>
Add a select box so that users can select a department:

<OPTION VALUE="Training">Training</OPTION>

<OPTION VALUE="Marketing">Marketing</OPTION>

<OPTION VALUE="Sales">Sales</OPTION>

</SELECT>

Add a label above the select box to describe it on the form:

Department<BR>

Add a checkbox so that users can identify contract employees:

<INPUT TYPE="Checkbox" NAME="Contract" VALUE="Yes">Yes

Add a label above the checkbox to describe it on the form:

Contract employee?<BR>

Add a submit form control to pass the data to the action page:

Add a reset form control so that users can reset the data on the
form page:

Add a closing FORM tag before the closing BODY tag to end the form:

</FORM>

Add <P> tags throughout the code to format the page.
Save the page.
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.

Modify as needed.

Note You will receive errors if you submit the form for processing at this time. You will learn about action pages and the characteristics of form variables later on in this chapter.

Form Notes and Considerations

To make the coding process easy to follow, name form controls the
same as target database fields.

Refer to Chapter 5, “Building Pages that Retrieve Data,” on page 45 and Chapter 9, “Building Search Interfaces,” on page 97 to learn more about dynamically generating SQL.

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.
Checkbox and radio button variables do not pass to action pages

unless a user selects them on a form. If you reference these variables on the action page, your users will receive an error if they are not present.
You can dynamically populate dropdown select boxes using query data.

Before creating an action page, move on to the next heading to learn how to dynamically populate select boxes.

Dynamically Populating Select Boxes

During the last procedure, you hard-coded a form’s select box options.

Instead of manually entering department information on a form, you can dynamically populate a select box with database column fields. When you code this way, changes that you make to a database are automatically reflected on the form page.

To dynamically populate a select box:

Use the CFQUERY tag to retrieve the column data from a database

table.
Use the CFOUTPUT tag with the QUERY attribute within the SELECT tag

to dynamically populate the OPTIONS of this form control.

Usage example

This code retrieves department data for a form page and stores it in the GetDepartments query variable:

SELECT Department_Name FROM Departments

</CFQUERY>

GetDepartments is the query name.
The query uses the HRApp data source to connect to the database.
The data is retrieved from the Department_Name column in the

Departments table.

This code dynamically populates the Department_Name select box with the GetDepartments query data:

<OPTION VALUE="#Department_Name#"> #Department_Name#

</OPTION>

</CFOUTPUT>

</SELECT>

Hard-code an All option.
The CFOUTPUT block generates one select box option for each column

returned from the query.

To dynamically populate a select box:

Open FormPage.cfm in HomeSite.
Build a query to retrieve the Department_Name column from the

HRExpress Departments table by adding this code between the opening BODY tag and the opening FORM tag:

<CFQUERY NAME="GetDepartments" DATASOURCE="HRExpress"> SELECT Department_Name

FROM Departments

</CFQUERY>

Locate the select box on the form.
Change the select box NAME attribute to DEPARTMENT_NAME:

Delete all current select box OPTION blocks.
Add an OPTION block within the SELECT block so that users can select

ALL departments.

Add a second OPTION block within the SELECT block that dynamically
populates the select box with the GetDepartments query result set:

<OPTION VALUE="#Department_Name#"> #Department_Name#

</OPTION>

</CFOUTPUT>

Save the page.
View FormPage.cfm in a browser.

The changes that you just made appear in the form. Remember that you need an action page to submit values.

Move on in this chapter to learn how to create action pages and work with form variables.

Note The behind the scenes code refers to a different action page than the one that you are building.

You will receive errors if you submit the form for processing at this time. You will learn about action pages and the characteristics of form variables later on in this chapter.

Understanding Action Pages

A ColdFusion action page is just like any other application page except that you can use the form variables that are passed to it from an associated form - a form variable is passed for every form control that contains a value when the form is submitted.

Note If multiple controls have the same name, one form variable containing a comma delimited list containing all occurences of that name passes to the action page.

Working with Form Variables

A form variable’s name is the name that you assigned to the form control on the form page.

Refer to form variable by name within tags, functions and other expressions on an action page.

Because form variables extend beyond the local page - their scope is the action page, prefix them with form. to explicitly tell ColdFusion that you are referring to a form variable.

Note Checkboxes and radio buttons do not pass to action pages unless they are enabled 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.

Usage example

For example this code references the LastName form variable for output on an action page:

#Form.LastName#

</CFOUTPUT>

Creating Action Pages

To create an action page for the form:

Create a new application page in HomeSite.
Save the page as ActionPage.cfm within the CFDOCS directory.

Remember that the form that you just created will pass values to a page called

ActionPage.cfm when the form is submitted.

Title the page Chapter 7 Action Page.
Add a heading for the action page output:

<H4>Employee Data Passed to the Action Page </H4>

Add a CFOUTPUT block after the heading:

</CFOUTPUT>

Label and define form variables within the CFOUTPUT block to return
them back to the user:

Last Name: #Form.LastName#<BR> Department: #Form.Department_Name#<BR> Contract Employee? #Form.Contract#<BR>

Save the page.
View FormPage.cfm in your browser.
Enter data for each form control and submit it.

ActionPage.cfm should return the values that you submitted.

If you receive errors, read the message and check for spelling mistakes.

Return to the form in your browser.
Reset the values.
Do not check the checkbox and submit the form again.

An error occurs when the checkbox does not pass to the action page.

During the next chapter, you will learn how to use conditional logic to handle this form limitation.

Note Remember that, if you submit the form without checking the checkbox, you will receive errors. You will learn how to apply conditional logic to your action page to compensate for this HTML limitation in the next chapter.

Form Variable Notes and Considerations

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

A form variable’s scope is the action page.
Prefix variables when referencing them on the action page.
Surround variable values with pound signs (#) for output.
Text control form variables are always passed to the action page.
Checkboxes and radio buttons are only passed to the action page if

an option is selected.
Checkboxes and radio buttons form variables generate errors on

action pages if nothing is selected for the form controls.

Development Considerations

During this chapter, you learned about:

Building forms
Dynamically populating select boxes
Creating action pages
Working with form variables on an action page

Note The CFPARAM tag can be used to test for a variable’s existence and to set default values. Refer to the CFExPress_Language_Reference/contents.htmCFML Language Reference for more information.

Where to go from here

Refer to Chapter 4, “Creating and Manipulating Variables,” on page

29 to learn about working with variables.
Move on to the next chapter to learn about how you can use

programatic logic to perform conditional procedures, reuse code, and redirect users.

C HA PT ER 8