Ensuring variable existence

ColdFusion generates an error if you try to use a variable value that does not exist. Therefore, before you use any variable whose value is assigned dynamically, you must ensure that a variable value exists. For example, if your application has a form, it must use some combination of requiring users to submit data in fields, providing default values for fields, and checking for the existence of field variable values before they are used.

There are several ways to ensure that a variable exists before you use it, including:

You can use the IsDefined function to test for the variable's existence.
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 also use a cfform 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. For more information on this technique, see "Requiring users to enter values in form fields," in Chapter 26.

Testing for a variable's existence

Before relying on a variable's existence in an application page, you can test to see if it exists by using the IsDefined function.

For example, if you submit a form with an unsettled check box, the action page does not get a variable for the check box. The following example from a form action page makes sure the Contractor check box Form variable exists before using it:

<cfif IsDefined("Form.Contractor")>
  <cfoutput>Contractor: #Form.Contractor#</cfoutput>
</cfif>

You must always enclose the argument passed to the IsDefined function in double quotes. For more information on the IsDefined function, see CFML Reference.

If you attempt to evaluate a variable that you did not define, ColdFusion cannot process the page and displays an error message. To help diagnose such problems, use the interactive debugger in ColdFusion Studio or turn on debugging in the ColdFusion Administrator. The Administrator debugging information shows which variables are being passed to your application pages.

Variable existence notes

If a variable is part of a scope that is available as a structure, you might get a minor performance increase by testing the variable's existence using the StructKeyExists function instead of the IsDefined function.

You can also determine which Form variables exist by inspecting the contents of the Form.fieldnames built-in variable. This variable contains a list of all the filed submitted by the form. Remember, however, that form Text fields are always submitted to the action page, and may contain an empty string if the user did not enter data.

The IsDefined function always Returns False if you specify an array or structure element using bracket notation. For example IsDefined("myArray[3]") always returns False, even if the array element myArray[3] has a value. To check for the existence of an array element, copy the element to a simple variable and use IsDefined to test whether the simple variable exists.

Using the cfparam tag

You can ensure that a variable exists by using the cfparam tag, which tests for the variable's existence and optionally supplies a default value if the variable does not exist. The cfparam tag has the following syntax:

<cfparam name="VariableName"
  type="data_type"
  default="DefaultValue">

Note: For information on using the type attribute to validate the parameter data type, see CFML Reference.

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 the cfparam tag with the name attribute 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 cfparam tags indicate 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 14, "Handling Errors".

Example: setting default values

The following example uses the cfparam tag to see if optional variables exist. If they do exist, processing continues. If they do not exist, the ColdFusion Server creates them and sets them to the default values.

<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, you could include the following code on the action page to ensure that a SelectDepts variable exists:

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