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 the following:
- 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 use a cfinput 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 the Working with action pages.
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. To check whether a specific entry exists in an array, use the ArrayIsDefined function. To check whether a specific key exists in a structure, use the StructKeyExists 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:
<cfoutput>Contractor: #Form.Contractor#</cfoutput> </cfif>
You must always enclose the argument passed to the IsDefined function in quotation marks. For more information on the IsDefined function, see the CFML Reference.
To test whether an element exists in an array before you display its value, use a format such as the following:
</cfoutput> <cfloop index="i" from="1" to="#Arraylen(myArray)#"> <cfif ArrayIsDefined(myArray, i)> #i#: #myArray[i]#<br> </cfif> </cfloop> </cfoutput>
Notice that in the ArrayIsDefined function, unlike the IsDefined function, you do not surround the variable name in quotation marks.
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, turn on debugging in the ColdFusion Administrator or use the debugger in your editor. The Administrator debugging information shows which variables are being passed to your application pages.
Variable existence considerations
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 fields submitted by the form. Remember, however, that form text fields are always submitted to the action page, and can contain an empty string if the user did not enter data.
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:
type="data_type" default="DefaultValue">
For information on using the type attribute to validate the parameter data type, see the 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.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 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="Client.Color" default="Gray"> <cfparam name="ShowExtraInfo" default="No">
You can use the cfparam tag 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 SelectedDepts variable exists:
<cfparam name="Form.SelectedDepts" default="Marketing,Sales">