ColdFusion Variables Part One: The form and variables Scopes

By: Adrian Senior

Page 1 of 2

Set for printing


Variables can be a little confusing as you set out to learn ColdFusion, they needn't be, but we do need to understand about variable scopes and how ColdFusion handles them. If we don't get a handle on that, well it can lead to a few problems and we'll investigate those problems as we progress. It is important to remember that local variables are only available to the calling template and any included files within that template, once the request by the calling template is completed the local variable is destroyed by ColdFusion.

Several test files are available in the download section at the foot of this page, you may want to download these files now in order to complete the tests as we work through the tutorial.

What Are Variable Scopes?

You can look at each scope as an individual entity living in its own layer within ColdFusion. A variable passed in by a form using the post method would reside in the form scope, a variable set using the cfset tag would reside in the variables scope - also referred to as the local scope.

In this, the first tutorial in this series, we will investigate the variables scope and the form scope and look at how best practices can avoid such problems as name collisions. We will also look at how we can debug error messages given out by ColdFusion when our variables may be incorrectly set.

Probably the most common method of creating a variable is with the use of the cfset tag, so we will begin there by looking at the syntax we might use to create a variable.

<cfset MyVariable ="Adrian">

Listing 1: Creating a variable with cfset

With the above code I can insert the name "Adrian" for display anywhere in my template, by simply referencing the variable MyVariable. You can open the test.cfm template available in the download section at the foot of this page to see this code execute. We have simply declared a variable and a value for that variable, we haven't scoped the variable at all, yet ColdFusion still found it without a problem. How come?

Scope Hunting

ColdFusion is quite forgiving, it will hunt down your variable by searching through the scopes until it finds a match. Cool, well not really, we can't really afford to let ColdFusion hunt for our variable, this could give us problems as we build on our application.

<cfset form.MyVariable ="">
<cfset MyVariable ="Adrian">

Listing 2: Scoping our variables

In listing 2 we have added a new cfset variable, this time it is set to the value of a form element called select, this variable has been placed in the form scope using the following syntax: scope.variablename="value". With our new form variable safely scoped, this should be the end of any problems we might have, right? Well, no, not really, let's take a look at how the form variable is set with the cfset within our template.

Open the test1.cfm template in Dreamweaver's code view. You will see that I have added a select list that submits back to the same template, it contains three options and each option returns a number, 1, 2 or 3. Preview test1.cfm in your browser, uh oh, now ColdFusion is throwing an error!

Image 1: Error! Select is undefined in form

Fortunately ColdFusion tends to give decent information when it throws an error, let's look at what we can see in the error message and see if we can fix the problem.

The main heading in the error message "Element SELECT is undefined in FORM" is our first clue. SELECT - don't worry about the case, that is ColdFusion's way of emphasising a point - is the name of our select list and FORM is the scope in which we want to place this variable. Next ColdFusion provides the path to the template that caused the error, which was of course, our test1.cfm template, further to this, ColdFusion provides the line on which the error occurred, line 9.

So what is causing the error? From the information given in the error we can ascertain that ColdFusion was looking for the value of the select list in the form scope, this variable did not exist. ColdFusion could not complete its task and threw an error instead.

We can avoid this situation by providing a default value with the cfparam tag or we can use an isdefined function to hide the variable on the initial page load. Open the defaultparam.cfm template and you will see the default cfparam setting at the top of template.

<cfparam name="" default="1">

Listing 3: Providing a default value for our form variable

Notice how we have scoped the default value into the form scope, preview the defaultparam.cfm template and you will see that the template loads correctly.

Another option we have is to check to see if the select form element exists within the form scope, we can carry out this check by using the isdefined function as the template loads. The syntax for this can be seen in listing 4, open the defined.cfm template in Dreamweaver, the code starts at line 9.

<cfif isdefined ("")>
<cfset form.MyVariable ="">

Listing 4: Using the isdefined function

Preview the defined.cfm template in your browser and you will see that the template loads just fine. The variable created with our cfset tag for our variable has not been initiated as no element with the name of select was present in the form scope. The MyVariable in this instance is placed in the form scope, the syntax for this is scope.variablename, as we can see.

Page 1 of 2 1 2 Next

Download Support Files

Downloads are disabled during your trial period.

ColdFusion, scopes, variables scope, form scope, name, collisions, debugging, cfset, cfparam, isdefined. function