Creating a Form Handler

You can create a form handler at any time during the design process. Usually, the creation of a form and its form handler takes place at the same time. The form fields exist in the form handler as form object variables.

You can access a form field by using form. formfieldname. The <CFOUTPUT> tag displays a form field in the form handler.

Designing and Handling Radio Buttons

Radio buttons allow the end user to select one option from a group of mutually exclusive options. A radio button must be checked when the form is submitted to pass the form fields to the processing template. You can use the <INPUT> tag to create a radio button. The syntax for the Radio Button control is

 <INPUT TYPE="radio"          NAME="common_name"          VALUE="radio_button_value"> 

The NAME attribute stores the name of the Radio Button control. Radio buttons that are part of the same group (or the same category) share the same name. The VALUE parameter assigns a unique value to each radio button. This value is passed to the Web server when the radio button is selected. The selected radio button sends its value back to the form handler in the variable form.radio_button_common_name.

Note

The optional CHECKED attribute specifies that the radio button is checked by default.

Designing and Handling Checkboxes

You can use a checkbox group to allow an end user to select one or more options from a group of related choices. Since checkboxes are not mutually exclusive, the end user can perform multiple selections. For example, if an end user is asked to select his hobbies on a form, he can select multiple hobbies that include singing, dancing, and playing soccer. The checkbox captures this information.

You can use the INPUT tag to create a checkbox. The syntax for the Checkbox control is

 <INPUT TYPE="checkbox"         NAME="common_name"         VALUE="checkbox_value"> 

The NAME attribute stores the name of the Checkbox control. Checkboxes that are part of the same group (or same category) share the same name. The VALUE parameter assigns a unique value to each checkbox. This value is passed to the Web server when the checkbox is selected.

Note

You can use the optional CHECKED attribute to specify a checkbox that is checked when the form is displayed.

When you use a checkbox that has its own unique name, the checkbox sends its value back to the form handler in the variable form.checkbox_common_name. According to HTTP specifications, if an end user does not select a checkbox, a variable is not sent back to the Web server. In such cases, the <CFPARAM> tag should be used to process unselected checkboxes. The syntax is

 <CFPARAM NAME="variable_name"            DEFAULT="default_value"> 

This tag allows you to check for the existence of a variable specified in the NAME attribute. If the variable doesn't exist, it's created and assigned the value specified in the DEFAULT attribute.

Note

You should use the <CFPARAM> tag in the form handler for each checkbox control. This ensures that a form variable always exists in the form handler, whether the end user selects the checkbox or not.

Handling Multiple Checkboxes

In real-life applications, a checkbox group can contain more than one checkbox and an end user can select all, some, or none of the checkboxes in the group.

To process a checkbox group, you can use the LIST loop flow control. Refer to the syntax of the LIST loop in Chapter 2, "Overview of CFML." The checkbox group sends a comma-separated value list back to the Web server when the form is processed. The value of each checkbox that's selected is placed in the list.

Use the <CFPARAM> tag with multiple checkboxes to ensure that a variable is created in the form handler. This method processes multiple checkboxes named options:

 <CFLOOP INDEX="c"          LIST="#form.options">          <CFOUTPUT>#c#</CFOUTPUT> </CFLOOP> 

Designing and Handling Select Boxes

The Select box is also known as a list box or a drop-down menu. You can use it while presenting an end user with many related options. The syntax for a Select Box control is

 <SELECT NAME="select_box_name">          <OPTION VALUE="value1">first option          OPTION VALUE="value2">second option </SELECT> 

The NAME attribute of the SELECT tag stores the name of the Select control. The VALUE parameter of the OPTION tag assigns a unique value to each choice in the list. The text following the OPTION tag is the description displayed in the list box. The OPTION tag can also use an optional SELECTED attribute to specify the default selection.

Note

The <SELECT> tag also uses an optional SIZE attribute. SIZE indicates the number of lines to be displayed when the form is opened. By default, the value of SIZE is 1. You can use the optional MULTIPLE attribute with the <SELECT> tag to allow the end user to select more than one choice from the select box.

When you use a select box that only allows a single selection, this box sends its value back to the form handler in the variable form.select_box_name. If the select box allows multiple selections, you can use the LIST loop to handle the comma-delimited values that are returned. To ensure that a form variable always exists in the form handler, use the <CFPARAM> tag in the form handler for each Select Box control.

Designing and Handling Scrolling Text Boxes

You can use the Scrolling Text Box control when you need to collect data that spans more than a short phrase, such as a long address. The <TEXTAREA> tag creates a scrolling text box. The syntax for the Scrolling Text Box control is

 <TEXTAREA NAME="text_box_name"            COLS="num_cols"            ROWS="num_rows"            WRAP="wrap_value"> Default Text </TEXTAREA> 

The NAME attribute specifies the name of the text area. The ROWS and COLS attributes allow you to specify the size of the text area. The WRAP attribute can be set to "soft" to enable text wrap in the text area automatically. When you set the value of the WRAP attribute to "soft", the text entered by the end user is sent back to the Web server as one long line for processing. The text after the <TEXTAREA> tag is displayed in the text box when the form is first displayed. The text entered in the text box is sent back to the form handler in the variable form.text_box_name.

Designing and Handling Hidden Fields

You often need to create form controls with values that are hidden from the end user. For example, a hidden field may be used to determine if the end user has selected a radio button. If not, he would be redirected to make the choice again. As a result, hidden fields allow you to pass information from one Web page to another. The syntax for creating a hidden field is

 <INPUT TYPE="hidden" NAME="hidden_field_name" VALUE="value"> 

The TYPE parameter must be set to hidden. The NAME attribute specifies the name of the hidden field. The VALUE attribute specifies a value for the field. The end user cannot change the content of a hidden field. The value of a hidden field is sent back to the form handler in the variable form.hidden_field_name.

Designing and Handling Image Buttons

You may want to use graphical or image buttons to submit and reset forms to make the forms more attractive. In this case, you need to include a parameter to display the image. To do this, use the INPUT tag with TYPE set to image. The syntax for an Image Button control is

 <INPUT TYPE="image" src="/books/1/524/1/html/2/image_location"> 

The SRC attribute is assigned the URL location of the image to display. When the end user submits a form with an image button, two additional parameters are sent to the form handler. X and Y specify the pixel coordinates where the end user clicked on the image. These values simulate image maps.