Naming and Scoping Variables  
 
 

This section describes how to name variables, lists the order in which ColdFusion evaluates them, and offers guidelines for using variables in your applications.

 
 
  Variable names  
 
 

When naming ColdFusion variables and form fields, keep these guidelines in mind:

  • Variables must begin with a letter, which can be followed by any number of letters, numbers, or the underscore character.
  • Variables must be all one word.
  • Do not use spaces or special characters in variable names.For example, UserName_1, UserName2, and User_Name are valid, but 1stUser, WhatAName!, and User-Name are not.
  • For field names and variables, use descriptive names, not abbreviations. It will be much easier for others to read your code, and for you to remember how it works yourself, when you revisit it months later.
  • Note that queries and variables cannot have the same name in the same ColdFusion application page.
  • Although ColdFusion variables are not case-sensitive, keep capitalization consistent in order to keep your code consistent.
  • In writing queries and forms, match your form field names with the corresponding database field name.
 
 
  Qualifying, or scoping, variable references  
 
 

ColdFusion distinguishes between identically named parameters from different sources with a specific prefix for each source or "scope." For example, to specify a variable called State that is passed in a form submission, you would use Form.State. To specify a variable named State passed in a URL, you would use URL.State.

You don't need to use the prefix unless two variables in different scopes have the same name. However, for readability and processing speed, it is a good idea to use prefixes. For example, the variable "Form.lastname" is far more self-evident than a variable called "lastname."

The following chart shows the prefixes for each variable type:

Variable Prefix
Type
Reference
Queries
QueryName.variablename
Local
Variables.variablename
URL Parameters
URL.variablename
Form Fields
Form.variablename
Client
Client.variablename
Server
Server.variablename
Session
Session.variablename
Application
Application.variablename
HTTP Cookies
Cookie.variablename
CGI Environment
CGI.variablename

 
 
  Tip  
 

Always use the prefix for application and session variables.

 
 
  Performance and scoping  
 
 

You can improve performance by always qualifying your variables with the proper scope. Adding variable scopes improves processing speed but the trade-off is that it may not be so easy to reuse the same code in other applications or pages.

In the following example, both forms of the following variable are permitted. However, the example that includes a scoping prefix will be evaluated more quickly than the unscoped example:

<CFOUTPUT>
        #Client.fullname#
        #fullname#
</CFOUTPUT>
 
 
  How ColdFusion looks up variables  
 
 

When scoping isn't used, that is, when you don't include a variable prefix, like "Form.myformvar," ColdFusion attempts to find variables in the following order:

  1. Local variables created using CFSET and CFQUERY
  2. CGI variables
  3. File variables
  4. URL variables
  5. Form variables
  6. Cookie variables
  7. Client variables
 
 
  Note  
 

ColdFusion does not attempt to automatically find Application and Session variables. You must use prefixes with these variables.

See Kinds of Variables for information on each type of ColdFusion variable. For information on File variables, see Chapter 13, Managing Files on the Server.

 
 
  Using pound signs  
 
 

Pound signs are required around variables in strings and when variables are used as arguments for parameters in ColdFusion tags, such as CFOUTPUT, CFMAIL, and CFQUERY, and when outputting their values.

To output the value of a variable, rather than its name, you surround the variable name with pound signs and place the name between <CFOUTPUT> and </CFOUTPUT> tags.

Here are some guidelines for using pound signs with variables and expressions:

  • In CFML pound signs are used to distinguish expressions from plain text.
  • In CFOUTPUT and CFQUERY tags, enclose variables and functions in pound signs:

    <CFOUTPUT>The value is #Form.MyTextField#.</CFOUTPUT>

    <CFOUTPUT>The name is #FirstName# #LastName#.</CFOUTPUT>

    <CFOUTPUT>Cos(0) is #Cos(0)#</CFOUTPUT>

    In this example, the SQL statement calls for single quotes to enclose a text string, the value represented by the form variable #FORM.LastName#.

    <CFQUERY NAME="Search" DATASOURCE="Company">

    Select * From Employees

    Where LastName='#FORM.LastName#'

    </CFQUERY>

    Note that pound signs are necessary only where you need to distinguish expressions from text, for example, when variables are embedded in text strings:

    <CFSET A="Hello, #name#">

  • In CFSET statements, do not overuse pound signs. For example, do not use <CFSET x=#Cos(0)#+1>; instead, use <CFSET x=Cos(0)+1>.
  • Similarly, <CFSET FullName=FirstName & " " & LastName> is the same thing as <CFSET FullName="#FirstName# #LastName#">.
  • Pound signs are required when variables are used inside ColdFusion tags such as CFOUTPUT, CFMAIL, and CFQUERY.

    <CFOUTPUT>Your favorite color is #Client.FavoriteColor#.

    </CFOUTPUT>

  • Because pound signs serve as formatting codes in ColdFusion, you need to take special measures when including pound signs in a CFOUTPUT section. To include a pound sign that is not used as a field delimiter, use two consecutive pound signs (##).

For more information on using pound signs in ColdFusion pages, see the Functions and Expressions chapter in the Advanced ColdFusion Development book.



 
 
BackUp LevelNext
 
 

allaire     AllaireDoc@allaire.com
    Copyright © 1998, Allaire Corporation. All rights reserved.