Creating and Manipulating Variables

This chapter describes what variables are supported by ColdFusion Express and how to create and reference ColdFusion variables. During chapter practices, you will use two of the most frequently used CFML tags, CFSET and CFOUTPUT, to create and output local variables. You will also learn how to reference CGI variables and set and reference cookies in your ColdFusion applications.

Contents

• Variables 30

• Variable Types 30

• Variable Scope 31

• Local Variables 32

• CFSET Syntax Example 32

• Creating Local Variables 33

• Referencing Variables 34

• Outputting Variables 34

• CFOUTPUT Syntax Example 34

• Variable Prefixing 35

• Variable Lookup Order 36

• Outputting Local Variables 36

• Working with CGI Variables 38

• Working with Cookie Variables 40

• Development Considerations 42

• Variable Table 43

Variables

A Web application page is different from a static Web page because it can publish data dynamically. This involves creating, manipulating, and outputting variables.

A variable stores data that can be used in applications. As with other programming languages, you’ll set variables in ColdFusion to store data that you want to access later. And you’ll reference a range of variables to perform different types of application processing.

For example, you would store a user's preferences in a variable in order to use that data to customize the page that’s returned to the browser.

Variable Types

There are a variety of variable types that you can create and reference in your ColdFusion applications and many of them are available for you to use with ColdFusion Express.

Also note that ColdFusion variables are typeless. This means that you don’t need to define whether or not the variable value is numeric, text, or time-date.

The table below describes the variables that you can use with ColdFusion Express.

Variable Scope

The primary differences between variable types are where they exist, how long they exist, and where their values are stored. These considerations are referred to as a variable’s scope.

The table below describes the ColdFusion Express variables by their scope.

You will learn more about scope on an as needed basis throughout this book.

Creating Variables

Variables are created in different ways depending on the variable type. The table below describes how ColdFusion Express supported variables are created.

During this chapter, you will create and reference a local variable, learn how to reference some CGI variables and, learn how to set cookie variables. You will create other variables on an as needed basis throughout this book. For example, you will create and reference query variables in Chapter 5, “Building Pages that Retrieve Data,” on page 45 and form variables in Chapter 7, “Using Forms and Action Pages,” on page 71.

Local Variables

Create a local variable so that you can store and reference variable values on a page.

As shown in the variable scope table above, a local variable’s scope is local. This means that a local variable is only valid for the application page on which it is created.

Use the CFSET tag to create a ColdFusion local variable and assign it a value. The CFSET tag is one of the most frequently used CFML tags. You can use it to initialize a variable with a text string, numeric value, another variable, or the results of an expression. You can also use it to overwrite an existing variable’s value.

CFSET Syntax Example

The code below creates the local variable, ProductName, and assigns it the text string value ColdFusion:

<CFSET ProductName="ColdFusion">

• On the left side of the equal sign (=) you assign the variable a

  name.

• On the right side of the equal sign you assign the variable its

  value.

• Always place double quotes (“) around your variable values.

Note The CFSET tag can also be used to create arrays and structures and other variable types, refer to the CFExPress_Language_Reference/contents.htmCFML Language Reference for more information.

Creating Local Variables

To create a local variable:

1. Return to MyFirstPage.cfm in ColdFusion HomeSite.

2. Below the begin BODY tag, create a local variable called ProductName

   and set its value to ColdFusion:

<CFSET ProductName="ColdFusion">

If you performed the procedures presented in the last chapter, then you already have this variable created.

1. Save the file.

Ctrl S saves the file.

Your page should look like this:

<HTML>

<HEAD>

<TITLE>My First Page</TITLE>

</HEAD>

<BODY>

<STRONG>ColdFusion</STRONG>

<CFSET ProductName="ColdFusion">

</BODY>

</HTML>

1. Return to the browser and refresh

   http://127.0.0.1/CFDOCS/MyFirstPage.cfm. Ctrl R refreshes the page in the browser.

The variable is not output to the page; its value is just stored with the page. You will learn how to output the variable value during the next procedure.

1. View the page source in the browser.

The CFML tag was processed on the server. Only HTML is returned to the browser.

Note The CFPARAM tag can also be used to set and initialize variables. Refer to the CFExPress_Language_Reference/contents.htmCFML Language Reference for more information.

You have created a local variable on your page. Move on in this chapter to learn how to reference a variable on an application page.

Referencing Variables

Reference variables in ColdFusion applications so that you can manipulate them, output them, and use them as a testing mechanism for conditional processing.

During this chapter, you will output variables to an application page.

In subsequent chapters, you will manipulate variables, and use them as a foundation for conditional processing.

Outputting Variables

After you create a variable, you need a way to output it to the page for further manipulation or just to display its value to users.

Use the CFOUTPUT block tag to tell ColdFusion Server to replace variable references with variable values.

The CFOUTPUT tag is one of the most frequently used CFML tags. You can use it in with many other CFML tags, HTML tags, and text to format the data that’s returned to the user. ColdFusion processes the CFML on the server and returns the rest to the browser.

You will learn more about formatting output and what to enclose in a CFOUTPUT tag in the next several chapters.

Refer to the CFExPress_Language_Reference/contents.htmCFML Language Reference

to learn more about how you can use the CFOUTPUT tag.

CFOUTPUT Syntax Example

The code below outputs the current value of the ProductName local variable:

<CFOUTPUT>

#ProductName#

</CFOUTPUT>

• The CFOUTPUT tag is a block tag.

• Place CFML variables inside the CFOUTPUT block to output them to a

  page.

• Always place pound signs (#) around a variable name so that

  ColdFusion knows to replace the variable reference with its current value.

• Because application pages are processed top-down, always place the

  CFOUTPUT block after the CFSET block.

• You can include text, HTML,other CFML tags, and client-side

  technologies inside a CFOUTPUT block.

Variable Prefixing

Because variables can differ in scope and can overlap, you need to be aware that sometimes a variety of variables will be available to a ColdFusion application page and some may variables may share the same name.

To ensure ColdFusion evaluates the appropriate variable, reference a variable by prefixing a variable name with its type. The table below describes each variable by its prefix.

• Where QueryName is the NAME attribute that you assigned in the

  CFQUERY tag. You will learn more about querying a database in the next chapter.

Variable prefixing example

The code below outputs the current value of the ProductName local variable:

<CFOUTPUT>

#Variables.ProductName#

</CFOUTPUT>

• Prefix variables with the variable type. (This is optional for local

  variables.)

• Surround the variable reference with pound signs (#) so that

  ColdFusion knows to replace the variable name with the variable value.

The code below outputs the current value of the ProductName form variable:

<CFOUTPUT>

#Form.ProductName#

</CFOUTPUT>

The code below outputs the current value of the ProductName query results:

<CFOUTPUT QUERY="ProductName" DATASOURCE="HRApp">

#ProductName.ProductName#

</CFOUTPUT>

Note Allaire recommends that you prefix any variables other than local when referencing them.

Variable Lookup Order

When you don’t prefix variables, if more than one variable with the same name exists, ColdFusion evaluates which variable type to use in this order:

1. Query result variables

2. Local variables

3. CGI variables

4. URL variables

5. Form variables

6. Cookie variables

Outputting Local Variables

To output the local variable that you created:

1. Return to MyFirstPage.cfm in HomeSite.

2. Add a CFOUTPUT block tag under the CFSET tag.

3. Reference the ProductName local variable within the block:

<CFOUTPUT>

#Variables.ProductName#

</CFOUTPUT>

If you performed the procedures presented in the last chapter, then you have already referenced the ProductName local variable. Prefix the variable now.

1. Save your changes.

Your page should look like this now:

<HTML>

<HEAD>

<TITLE>My First Page</TITLE>

</HEAD>

<BODY>

<STRONG>ColdFusion</STRONG>

<CFSET ProductName="ColdFusion">

<CFOUTPUT>

#Variables.ProductName#

</CFOUTPUT>

</BODY>

</HTML>

1. Refresh your page in the browser.

2. View the page source in the browser.

The CFML tags were processed on the server.

The current variable value is returned as text to the browser.

1. Return to HomeSite.

2. Apply HTML formatting to make the ProductName value appear in bold:

<CFOUTPUT>

<STRONG>#Variables.ProductName#</STRONG>

</CFOUTPUT>

1. Add some text surrounding the local variable reference:

<CFOUTPUT>

The product name is <STRONG>#Variables.ProductName#</STRONG>.

</CFOUTPUT>

1. Save your changes.

2. Refresh the page in the browser.

The HTML formatting and text is returned to the browser.

1. View the page source in the browser.

The CFML tags were processed on the server.

You have output the current value of a local variable. You will perform the same procedure to output other types of variables. Move on in this chapter to learn about how you work with and output CGI variables.

Working with CGI Variables

Each browser request creates a set of read-only variables that store data about the actual browser and server transactions.

For example, these variables store relevant IP addresses and the browser type that’s being used for the client request.

We refer to these variables as CGI environment variables even when the Web server uses an API instead of CGI to communicate with ColdFusion Server.

You can reference CGI environment variables anywhere in a page, for example, to perform conditional processing based on the type of browser that requested the page.

CGI variables

Different browsers and servers support different CGI variables. The table below describes the most common CGI environment variables that are created on the server or created on the client and passed to the server in the request (HTTP) header.

Note ColdFusion stores an empty string value for a CGI variable when detailed information is not available for a particular session. For this reason, when performing conditional processing based on a CGI variable, test for null (") rather than a variable’s existence.

You will learn about conditional processing in Chapter 8, “Programming with ColdFusion,” on page 81.

Referencing CGI variables

Reference CGI environment variables anywhere on a page to use their values. As with any variable that you reference:

• Prefix the variable name with its variable type.

• Surround the variable name with pound signs (#).

Referencing CGI variables example

The code below outputs the current value of the HTTP_USER_AGENT to display the browser type and version:

<CFOUTPUT>

#CGI.HTTP_USER_AGENT#

</CFOUTPUT>

• Prefix the variable name with CGI.

• Reference CGI variables within a CFOUTPUT block to read their values

  on page.

• Always place pound signs (#) around a variable name so that

  ColdFusion knows to replace the variable reference with its current value.

As you can see, you reference and output CGI variables using the same procedure that you follow when outputting local variables. Move on in this chapter to learn about how you work with and output cookie variables.

Working with Cookie Variables

Cookies are general variables used by application servers such as ColdFusion Server to store data in and retrieve data from individual browsers.

As shown in the variable scope table above, a cookie is available from a specific browser to a specific server across sessions. This means that the cookie variables that you set in an individual browser can be referenced in different application pages.

For example, you may create a cookie and send it back to the browser during a user’s login. That way, you can reference the cookie to pass specific data from page to page and each time the browser returns to the application. This is extremely important to site personalization strategies.

Cookies are characterized as:

• Persistent - they stay stored in the browser until they expire or

  are deleted.

• Widely-supported - almost all commercial browsers support them.

• Domain specific - they are set and retrieved for a specific server,

  such as www.allaire.com or 127.0.0.1.

20 cookies can be set in a user’s browser for each domain. ColdFusion Server reserves two of these cookies, for CFID and CFTOKEN.

Create cookies using either the CFCOOKIE tag or the CFSET tag on an application page. When you create a cookie:

• It is set on the client after the entire page is processed.

• You can set it to expire.

• You can delete it later if you want to.

• It persists until the browser is closed unless you set it to expire.

Note Use Secure Sockets Layer (SSL), to exchange cookies securely.

Setting Cookies example

The code below creates the cookie variable, User_ID, assigns it a numeric value of 2344, and sets it to expire after 100 days:

<CFCOOKIE NAME="User_ID" VALUE="2344" EXPIRES="100">

• Use the NAME attribute to assign the variable a name.

• Use the VALUE attribute to assign the variable a value.

• Use the EXPIRES attribute to assign the number of days that the

  cookie should live before it expires.

Optional when creating a cookie. Use a value of now to delete a cookie.

• Always surround attribute values with double quotes (“).

For more information on CFCOOKIE, see the ./CFML Language Reference for ColdFusion Express.

Referencing Cookies

Once a server stores a cookie in a browser, that cookie is automatically sent back to the server each time a page is requested by that browser. This means that you can reference that cookie as needed throughout application pages on that server.

Reference cookie variables anywhere on a page to use their values. As with any variable that you reference:

• Prefix the variable name with its variable type.

• Surround the variable name with pound signs (#).

Note Because cookies need to be set by the server before you can use them, always test whether a cookie exists before you use it in an application page.

Always prefix the cookie variable when referencing it.

Referencing Cookies example

For example, you may output a cookie’s current value within another CFML tag so that you can use its value to perform conditional processing. The code below outputs the current value of the User_ID.

<CFOUTPUT>

#Cookie.User_ID#

</CFOUTPUT>

Development Considerations

During this chapter you learned:

• About the different variables that you can use to perform dynamic

  page processing

• How to create a local variable and assign it a value using the CFSET

  tag

• How to reference a ColdFusion local variable for output to a page

  using the CFOUTPUT tag

• How to reference CGI variables

• How to create and reference cookie variables

When creating and referencing variables in ColdFusion applications, keep these guidelines in mind:

• Variable names should be all one word and begin with a letter.

• Variable names can contain only letters, numbers and the underscore.

• Variable names should not contain special characters.

• ColdFusion variables are not case-sensitive but use a consistent

  capitalization scheme.

• Always use double quotes (") to surround a value when assigning a

  value to a variable name.

• Always surround a variable name with pound signs (#) when

  referencing the variable to use its current value.

• Prefix variable names with variable type to ensure that ColdFusion

  references the correct variable during processing.

Where to go from here

• Move on to the next chapter to learn how to query a database and

  work with query variables.

Variable Table

The table below describes the ColdFusion Express variables by their scope and prefix.

44 Developing Web Applications with ColdFusion Express

C HA PT ER 5