How Are FORM Variables Created?

How Are FORM Variables Created?

As with URL variables, you do not create FORM variables by explicitly declaring name=value pairs. To create a FORM variable, you must first create an HTML form, name all the controls in that form, and then submit it. The data entered or selected on a form by the Web visitor are the values for the FORM variables.

Local variables were introduced in Chapter 2, "Working with Variables and Expressions."

NOTE

This study guide is written to help you review your ColdFusion knowledge and to fill in some of the gaps. In other words, we are assuming that you are a seasoned developer and have a good working knowledge of ColdFusion and Web development. Therefore, we will assume you know how to create HTML form controls and will not discuss them in detail here.

The following sample code creates a short form:

 <form action="actionpage.cfm" method="post"> First Name: <input type="text" NAME="FName"><br> Favorite Color:  <input type="checkbox" name="FavColor" value="R">Red  <input type="checkbox" name="FavColor" value="G">Green  <input type="checkbox" name="FavColor" VALUE="B">Blue<BR> <input type="submit"> </form> 

NOTE

You may have multiple forms on the form page, but only one can be submitted at a time. As soon as you click a Submit button, the FORM variables are passed on to the action page referenced in this form's ACTION attribute.

You can also have more than one submit button per form. If you click either of the submit buttons, the FORM variables are passed on to the action page. The trick to determining which submit button was clicked is to give each button a unique name or value. Only the name and value of the clicked button will be passed to the action page.

Be sure to note these important points about the above code:

• The action attribute of the form tag specifies to which page the information from the form will be submitted.

• The text box is named FName.

• The checkboxes are all named FavColor.

• No ColdFusion functions or tags appear in this code.

CAUTION

When you're working with HTML forms in ColdFusion, it's a good idea to always make sure that the method attribute is set to post, not get. By HTML rules, if method is not declared, its value defaults to get. You will find that if you have method="get", your FORM variables are actually sent instead as URL variables. (You can verify this by looking in your server debugging information.) Additionally, if you misspell the words method or post, you will find that the form submission automatically defaults to get.

Debugging is discussed in Chapter 25, "Debugging."

In this section we describe how to create FORM variables. Even though you've created HTML form elements, you have not yet actually created any FORM variables. FORM variables don't exist until they get to the action page. Really, you're just naming the variables when you create the form element. A user enters the values when she types data into the form fields. It's not until she submits the form that the values she entered are matched up with the name of the field, and then the name=value pairs are actually created as FORM variables and passed on to the action page.

So, in the preceding example, if the user entered the name Emily into the text box, selected the Blue checkbox, and clicked the submit button, the FORM variable name=value pairs passed on to the action page would be FName=Emily, FavColor=B.

NOTE

Because the submit button was not named, it is not passed as a FORM variable.

NOTE

The name you assign to a form control is very important. When many form controls on a page have the same name (as in the case of checkboxes or radio buttons), ColdFusion compiles the submitted values and converts them into a list. Consider the following code:

 <input type="checkbox" name="FavColor" value="R">Red <input type="checkbox" name="FavColor" value="G">Green <input type="checkbox" name="FavColor" value="B">Blue 

If the user checked the checkbox for Red and Blue, the action page would receive the name=value pair FavColor=R,B.

You can use what you know about ColdFusion lists to work with this data

Youll learn about lists in Chapter 13, "Lists."

TIP

When you create a form, you are usually creating it to gather information that will be inserted into a database. Therefore, it is recommended that you name your form fields with the same name as the corresponding database column, or the name of the component or tag to which the fields will be submitted.

As we just discussed, the name=value pair for each form element is passed to the action page. However, if you just want a list of all the names of all form elements passed to the action page, you can access the list using the variable FORM.fieldnames. The ColdFusion application server automatically generates this variable for you when the form is submitted. It is a very useful variable for dynamically determining the names of all form elements. Again, you can use what you know about lists to manipulate this information.

NOTE

FORM itself is a ColdFusion structure which can be accessed like any other structure as will be explained in Chapter 15, "Structures."