Ensuring that Variables Exist

The sample code in the previous sections is incomplete. Either the form or the action page should make sure that the SelectDepts variable has a value before it is used in the SQL Select statement. Otherwise, users who do not select any department get an error message. There are several ways to ensure that a variable exists before you use it:

You can use the IsDefined function, as described in the section "Testing for a variable's existence," in Chapter 4.
You can use the cfparam tag to test for a variable and set it to a default value if it does not exist.
You can use a form input tag with a hidden attribute to tell ColdFusion to display a helpful message to any user who does not enter data in a required field.

Using cfparam to test for variables and set default values

One way to ensure a variable exists is to use the cfparam tag, which tests for the variable's existence and optionally supplies a default value if the variable does not exist. The following code shows the syntax of the cfparam tag:

<cfparam name="VariableName"

  type="data_type"

  default="DefaultValue">

Note

For information on using the type attribute to validate the parameter data type, see the "Using cfparam to validate the data type" section of this chapter.

There are two ways to use the cfparam tag to test for variable existence, depending on how you want the validation test to proceed:

With only the name attribute to test that a required variable exists. If it does not exist, the ColdFusion Server stops processing the page and displays an error message.
With the name and default attributes to test for the existence of an optional variable. If the variable exists, processing continues and the value is not changed. If the variable does not exist, it is created and set to the value of the default attribute, and processing continues.

The following example shows how to use the cfparam tag to check for the existence of an optional variable and to set a default value if the variable does not already exist:

<cfparam name="Form.Contract" default="Yes">

Example: Testing for variables

Using cfparam with the name variable is one way to clearly define the variables that a page or a custom tag expects to receive before processing can proceed. This can make your code more readable, as well as easier to maintain and debug.

For example, the following series of cfparam tags indicates that this page expects two form variables named StartRow and RowsToFetch:

<cfparam name="Form.StartRow">

<cfparam name="Form.RowsToFetch">

If the page with these tags is called without either one of the form variables, an error occurs and the page stops processing. By default, ColdFusion displays an error message; you can also handle the error as described in Chapter 11, "Preventing and Handling Errors".

Example: setting default values

This example uses cfparam to see if optional variables exist. If they do exist, processing continues. If they do not exist, they are created and set to the default value.

<cfparam name="Cookie.SearchString" default="temple">

<cfparam name="Client.Color" default="Grey">

<cfparam name="ShowExtraInfo" default="No">

You can use cfparam to set default values for URL and Form variables, instead of using conditional logic. For example, the action page could have the following code to ensure that a SelectDepts variable exists:

<cfparam name="Form.SelectedDepts" default="Marketing,Sales">

Requiring users to enter values in form fields

One of the limitations of HTML forms is the inability to define input fields as required. Because this is a particularly important requirement for database applications, ColdFusion provides a server-side mechanism for requiring users to enter data in fields.

To require entry in an input field, use a hidden field that has a name attribute composed of the field name and the suffix "_required." For example, to require that the user enter a value in the FirstName field, use the syntax:

<input type="hidden" name="FirstName_required">

If the user leaves the FirstName field empty, ColdFusion rejects the form submittal and returns a message informing the user that the field is required. You can customize the contents of this error message using the value attribute of the hidden field. For example, if you want the error message to read "You must enter your first name," use the following syntax:

<input type="hidden" 

  name="FirstName_required"

  value="You must enter your first name.">

Developing ColdFusion Applications
Making Variables Dynamic