Macromedia COLDFUSION MX7 User Manual

COLDFUSION®MX 7

Getting Started Building ColdFusion MX Applications

Trademarks

1 Step RoboPDF, ActiveEdit, ActiveTest, Authorware, Blue Sky Software, Blue Sky, Breeze, Breezo, Captivate, Central, ColdFusion, Contribute, Database Explorer, Director, Dreamweaver, Fireworks, Flash, FlashCast, FlashHelp, Flash Lite, FlashPaper, Flex, Flex Builder, Fontographer, FreeHand, Generator, HomeSite, JRun, MacRecorder, Macromedia, MXML, RoboEngine, RoboHelp, RoboInfo, RoboPDF, Roundtrip, Roundtrip HTML, Shockwave, SoundEdit, Studio MX, UltraDev, and WebHelp are either registered trademarks or trademarks of Macromedia, Inc. and may be registered in the United States or in other jurisdictions including internationally. Other product names, logos, designs, titles, words, or phrases mentioned within this publication may be trademarks, service marks, or trade names of Macromedia, Inc. or other entities and may be registered in certain jurisdictions including internationally.

This product includes code licensed from RSA Data Security.

Third-Party Information

This guide contains links to third-party websites that are not under the control of Macromedia, and Macromedia is not responsible for the content on any linked site. If you access a third-party website mentioned in this guide, then you do so at your own risk. Macromedia provides these links only as a convenience, and the inclusion of the link does not imply that Macromedia endorses or accepts any responsibility for the content on those third-party sites.

Copyright © 1999–2005 Macromedia, Inc. All rights reserved. U.S. Patents Pending. This manual may not be copied, photocopied, reproduced, translated, or converted to any electronic or machine-readable form in whole or in part without written approval from Macromedia, Inc. Notwithstanding the foregoing, the owner or authorized user of a valid copy of the software with which this manual was provided may print out one copy of this manual from an electronic version of this manual for the sole purpose of such owner or authorized user learning to use such software, provided that no part of this manual may be printed out, reproduced, distributed, resold, or transmitted for any other purposes, including, without limitation, commercial purposes, such as selling copies of this documentation or providing paid-for support services. Part Number ZCF70M200

Acknowledgments

Project Management: Randy Nielsen

Writer: Anne Sandstrom

Editors: Linda Adler, Noreen Maher

Production Management: Patrice O’Neill,

Media Design and Production: John Francis, Adam Barnett

Special thanks to Sawako Gensure, Seungmin Lee, Takashi Koto, Nozomi Kugita, Masayo Noda, Hiroshi Okugawa, Bowne Global Solutions

First Edition: January 2005

Macromedia, Inc. 600 Townsend St.

San Francisco, CA 94103

INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

PART I: Welcome to ColdFusion

CHAPTER 1: Introducing ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

About ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

How ColdFusion processes pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Building applications with CFML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

CHAPTER 2: CFML Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Working with ColdFusion pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

About CFML elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Working with CFML expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

About conditional processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Processing form data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Commenting your code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

CHAPTER 3: Database Fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

About database basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

About SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Using SQL with ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

PART II: Building a ColdFusion Application

CHAPTER 4: Lesson 1: Preparing to Build the Sample Application . . . . . . . . . . . 41

Application development steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Exercise 1: Determining the application functional requirements . . . . . . . . . . . . . 42

Exercise 2: Determining the data requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Exercise 3: Designing the database for your application. . . . . . . . . . . . . . . . . . . . . 43

Exercise 4: Developing the sample application. . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

CHAPTER 5: Lesson 2: Configuring Your Development Environment. . . . . . . . . 49

Exercise 1: Verifying the tutorial file structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Exercise 2: Setting up your development environment. . . . . . . . . . . . . . . . . . . . . . 50

Exercise 3: Configuring a database connection . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Exercise 4: Configuring debugging options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

CHAPTER 6: Lesson 3: Retrieving Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Exercise 1: About the trip list. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Exercise 2: Retrieving the information for the trip list . . . . . . . . . . . . . . . . . . . . . . 61

Exercise 3: Displaying the query result using the cfoutput tag . . . . . . . . . . . . . . . . 62

Exercise 4: Writing structured, reusable code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Exercise 5: Creating additional queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

CHAPTER 7: Lesson 4: Building Dynamic Queries. . . . . . . . . . . . . . . . . . . . . . . . 71

Exercise 1: Creating the trip search form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Exercise 2: Building a query that uses dynamic SQL . . . . . . . . . . . . . . . . . . . . . . . 75

Exercise 3: Constructing the initial Trip Search Results page . . . . . . . . . . . . . . . . . 79

Exercise 4: Testing the Trip Search Results page. . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Exercise 5: Enabling the departure and price criteria on the Trip Search form . . . . 82

Exercise 6: Testing the revised Trip Search Results page . . . . . . . . . . . . . . . . . . . . . 83

Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

CHAPTER 8: Lesson 5: Creating a Trip Detail Page. . . . . . . . . . . . . . . . . . . . . . . 85

Exercise 1: Creating a Trip Detail page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Exercise 2: Avoiding the potential security risk when using dynamic SQL. . . . . . . 91

Exercise 3: Linking the Trip Search Results page with the Trip Detail page . . . . . . 92

Exercise 4: Enhancing the look of the Trip Search Results and Trip Detail pages . . 93

Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

CHAPTER 9: Lesson 6: Creating a Main Application Page . . . . . . . . . . . . . . . . . 97

Exercise 1: Creating the main application page from the Trip Detail page . . . . . . . 98

Exercise 2: Adding database maintenance buttons . . . . . . . . . . . . . . . . . . . . . . . . 100

Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

CHAPTER 10: Lesson 7: Validating Data to Enforce Business Rules. . . . . . . . . 103

Exercise 1: Using an HTML form to collect data. . . . . . . . . . . . . . . . . . . . . . . . . 104

Exercise 2: Creating a simple action page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Exercise 3: About data validation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Exercise 4: Providing server-side validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Exercise 5: Validating data on the client using ColdFusion form tags. . . . . . . . . . 114

Exercise 6: Dynamically populating the list of event types . . . . . . . . . . . . . . . . . . 119

Exercise 7: Validating the existence of the trip photo file . . . . . . . . . . . . . . . . . . . 120

Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

4 Contents

CHAPTER 11: Lesson 8: Implementing Browsing and Searching . . . . . . . . . . . . 123

Exercise 1: Enabling users to browse trip details . . . . . . . . . . . . . . . . . . . . . . . . . 123

Exercise 2: Determining actions based on which button a user clicks. . . . . . . . . . 127

Exercise 3: Enabling searching from the Trip Detail page . . . . . . . . . . . . . . . . . . 127

Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

CHAPTER 12: Lesson 9: Enabling Database Maintenance . . . . . . . . . . . . . . . . 129

Exercise 1: Deleting the current trip record shown on the Trip Detail page . . . . . 129

Exercise 2: Adding trips with SQL INSERT statements . . . . . . . . . . . . . . . . . . . 131

Exercise 3: Adding data using the cfinsert tag . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Exercise 4: Updating a SQL row using the cfupdate tag. . . . . . . . . . . . . . . . . . . . 137

Exercise 5: Linking the Trip Edit page to the main page . . . . . . . . . . . . . . . . . . . 138

Exercise 6: Inserting values in the edit form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

CHAPTER 13: Lesson 10: Restricting Access to ColdFusion Applications . . . . 143

Exercise 1: About the Login Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Exercise 2: Requiring users to log in to the Compass Travel application. . . . . . . . 147

Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Contents 5

6 Contents

INTRODUCTION

Getting Started Building ColdFusion MX Applications is intended for anyone who needs to begin programming in the Macromedia ColdFusion MX 7 development environment. This manual includes a tutorial, which uses supporting files that are installed if you chose to install sample applications. If you did not install the ColdFusion MX sample applications, you can download the tutorial files from the ColdFusion Support center on the Macromedia website.

About Macromedia ColdFusion MX 7 documentation

The ColdFusion MX 7 documentation is designed to provide support for the complete spectrum of participants.

Documentation set

The ColdFusion MX 7 documentation set includes the following titles:

Book Description

Installing and Using ColdFusion MX

Configuring and Administering ColdFusion MX

ColdFusion MX Developer’s Guide

Getting Started Building ColdFusion MX Applications

Describes system installation and basic configuration for Microsoft Windows, Solaris, and Linux. To see this manual, go to http:// www.macromedia.com/go/livedocs_cfmx7docs_installing.

Part I describes how to manage the ColdFusion environment, including connecting to your data sources and configuring security for your applications. Part II describes Verity search tools and utilities that you can use for configuring the Verity K2 Server search engine, as well as creating, managing, and troubleshooting Verity collections. To see this manual, go to

www.macromedia.com/go/livedocs_cfmx7docs_configadmin.

Describes how to develop your dynamic web applications, including retrieving and updating your data, and using structures and forms. This manual includes two volumes. To see this manual, go to

www.macromedia.com/go/livedocs_cfmx7docs_dev.

Contains an overview of ColdFusion features and application development procedures. This manual includes a tutorial that guides you through the process of developing a sample ColdFusion application. To see this manual online, go to www.macromedia.com/go/livedocs_cfmx7docs_gs.

Book Description

CFML Reference Provides descriptions, syntax, usage, and code examples for all ColdFusion

CFML Quick Reference Shows the syntax of ColdFusion tags, functions, and variables in a brief

tags, functions, and variables. This manual includes two volumes. To see this manual, go to www.macromedia.com/go/

livedocs_cfmx7docs__cfml_reference.

guide.

Viewing online documentation

All ColdFusion MX documentation is available online in HTML and Adobe Acrobat Portable Document Format (PDF) files. Go to the documentation home page for ColdFusion MX on the Macromedia website: www.macromedia.com. In addition, you can view the documentation in LiveDocs, which lets you add comments to pages and view the latest comments added by Macromedia, by going to www.macromedia.com/go/livedocs_cfmx7docs.

8 Introduction:

PART I

Welcome to ColdFusion

Part I provides an introduction to Macromedia ColdFusion MX 7. It defines ColdFusion MX 7 and provides an overview of the ColdFusion Markup Language (CFML). It also provides generic database concepts.

The following chapters are included in Part I:

Chapter 1: Introducing ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Chapter 2: CFML Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Chapter 3: Database Fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

PART I

CHAPTER 1

Introducing ColdFusion MX

This chapter introduces the core technologies that are the foundation for Macromedia ColdFusion MX. In addition, it introduces the basic concepts about ColdFusion MX, how it works, and the various components that comprise it.

About ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

How ColdFusion processes pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Building applications with CFML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

About ColdFusion MX

ColdFusion MX is a powerful web application server that lets you create robust sites and applications without a long learning curve. ColdFusion MX does not require coding in traditional programming languages (for example, C, C++, Java, XML), although it supports these traditional programming languages.

ColdFusion MX consists of the following core components:

• ColdFusion application server

• ColdFusion Markup Language (CFML)

• ColdFusion MX Administrator

The following sections describe these core components in more detail. In addition, the Getting Started Experience, which you can view by opening the Macromedia ColdFusion MX Administrator and clicking Getting Started, provides introductory information about ColdFusion and code snippets that highlight the new features of ColdFusion MX 7.

The ColdFusion application server

The ColdFusion application server is itself a web application that typically resides on the same computer as your web server software. It is the program that parses (reads and interprets) and processes supplied instructions. These instructions are passed to ColdFusion through ColdFusion pages, which use a .cfm or .cfc filename extension. A ColdFusion page looks like an HTML page, but contains special tags that instruct the ColdFusion server to perform specific operations.

The ColdFusion Markup Language

ColdFusion Markup Language (CFML) is a tag-based language similar to HTML that uses special tags and functions. With CFML, you can enhance your standard HTML files with database commands, conditional operators, and high-level formatting functions, and rapidly produce easyto-maintain web applications.

CFML looks similar to HTML: it includes start and end tags, and each tag is enclosed in angle brackets. All ending tags are preceded with a forward slash (/) and all tag names are preceded with cf.

The ColdFusion MX Administrator

You use the ColdFusion MX Administrator to configure and maintain the ColdFusion application server. It is a web-based application that you can access using any web browser, from any computer with an Internet connection.

You can manage the following configuration options with the ColdFusion MX Administrator:

• ColdFusion data sources

• Debugging output

• Server settings

• Application security

For further details about the ColdFusion MX Administrator, see Installing and Using ColdFusion MX or Configuring and Administering ColdFusion MX.

How ColdFusion processes pages

The following steps explain how the ColdFusion server processes a ColdFusion page:

The ColdFusion server looks at the content of the page and searches for the following ColdFusion instructions:

■ Tag names that begin with cf.

■ Variables and functions that are always surrounded by number signs (#).

If the ColdFusion server finds any HTML or plain text in the page, the ColdFusion server returns it to the web server unchanged.

The ColdFusion server processes all the ColdFusion instructions found, and returns any remaining results to the web server. The web server then sends the entire output to the browser.

12 Chapter 1: Introducing ColdFusion MX

Building applications with CFML

You build ColdFusion applications as a series of pages that use CFML. Developers can extend this language by creating their own custom tags or user-defined functions (UDF), or by integrating COM, C++, and Java components, such as Java Server Page (JSP) tag libraries.

Interacting with data sources

ColdFusion applications can interact with any database that supports a JDBC technology-based driver. A JDBC technology-based driver uses an Application Programming Interface (API) to execute SQL statements to databases on most platforms. However, ColdFusion is not limited to JDBC data sources. You can also interact with existing Open Database Connectivity (ODBC) data sources by using ODBC Socket, a driver that interacts with an existing ODBC driver.

Interacting with mobile devices

ColdFusion MX 7 lets you create applications that can respond to events and messages from diverse sources, including instant messaging, mobile phone Short Message Service (SMS) text messages, Internet socket requests, and system events. For information, see Chapter 42, “Using

Event Gateways” in ColdFusion MX Developer’s Guide.

Development tools

You can code your ColdFusion application with NotePad or any HTML editor; however, Macromedia recommends that you build your applications using Macromedia Dreamweaver MX. Dreamweaver MX offers features and wizards that enhance ColdFusion development. For more information about Dreamweaver MX, see Chapter 5, “Lesson 2: Configuring Your

Development Environment,” on page 49.

Building applications with CFML 13

14 Chapter 1: Introducing ColdFusion MX

CHAPTER 2

CFML Basics

This chapter introduces the basic elements of CFML, including how to create Macromedia ColdFusion pages, and use variables, functions, conditional processing, and form processing.

Working with ColdFusion pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

About CFML elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Working with CFML expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

About conditional processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Processing form data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Commenting your code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Working with ColdFusion pages

ColdFusion pages are plain text files that you use to create web applications. You can create your ColdFusion applications by writing all the code manually or by using wizards (provided with some editors) to generate the majority of the code for you.

You can use the following editors to create your ColdFusion pages:

• Macromedia Dreamweaver MX

• Macromedia HomeSite+

• Macromedia ColdFusion Studio

• Any HTML editor

• Windows Notepad

• Vi or Emacs (UNIX systems)

The best choice for creating ColdFusion pages is Macromedia Dreamweaver MX. Dreamweaver MX includes many CFML features for building applications, such as rapid visual development, robust CFML editing, and integrated debugging. Dreamweaver MX also includes a copy of HomeSite+ for users who are familiar with developing their application code using ColdFusion Studio or HomeSite 5. HomeSite+ combines all the features of ColdFusion Studio and HomeSite 5, along with support for the latest ColdFusion MX tags. For more information, see

Chapter 5, “Lesson 2: Configuring Your Development Environment,” on page 49.

Note: This manual describes how to create ColdFusion applications by writing your code manually. It does not address how to create ColdFusion pages by generating code with wizards. For information about using wizards to generate CFML code, see the product documentation for Dreamweaver MX and HomeSite+.

Creating a ColdFusion page

Creating a ColdFusion page involves using tags and functions. The best way to understand this process is to create a ColdFusion page.

In the following procedure, you will create a simple ColdFusion page by using HTML tags, one ColdFusion tag, and two ColdFusion functions. The following table briefly explains the ColdFusion tags and functions:

Element Description

Now()

DateFormat()

cfoutput

A function supported in CFML that you can use to retrieve information from your system. You will use the that is retrieved from your system.

A function that instructs ColdFusion to format the date returned by the Now() function.

A ColdFusion tag that you use to return dynamic data (data retrieved from a database) to a web page.

You will use the retrieved from your system.

Now() function in the following procedure to return the current date

cfoutput tag in the following procedure to display the current date

Note: ColdFusion tags and functions are considered primary elements of CFML. You will learn more about these elements and others later in this manual.

To create a ColdFusion page:

Open your editor and create a blank file.

Enter the following code on the page:

<html> <head> <title>A ColdFusion Page</title> </head> <body> <strong>Hello world, this is a ColdFusion page.</strong> <br> <cfoutput> Today’s date is #DateFormat(Now())# </cfoutput> </body> </html>

16 Chapter 2: CFML Basics

Saving your ColdFusion page

In order for the ColdFusion server to process the page, you must save the ColdFusion page on a computer where the ColdFusion MX is installed. If you are creating your pages on a local server (on which ColdFusion is running), you can save the pages locally; if you are using a remote server, you must save your pages on that server.

If you are using the ColdFusion MX J2EE configuration, you typically save ColdFusion pages under the ColdFusion web application root. For example, in the default directory structure when you use the J2EE configuration with JRun, you save pages under jrun_root/servers/cfusion/ cfusion-ear/cfusion-war. When you use JRun, you can also run the Web Server Configuration Tool and save pages under your web root directory.

Tip: ColdFusion MX on Macintosh OS X uses the J2EE configuration.

To save the code that you typed to create a ColdFusion page:

Create a directory called test under the web_root or web_application_root directory.

In the test directory, save the file as cfpage.cfm.

Browsing your code

To ensure that the code you wrote is working as expected, you must view the ColdFusion page in a browser. The following procedure describes how to view the ColdFusion page that you created earlier.

To view the ColdFusion page:

Open a web browser and go to the following URL:

http://localhost/test/cfpage.cfm

Note: If you are using the built-in web server, specify the port to use in the URL as follows:

http://localhost:8500/test/cfpage.cfm.

The address localhost is only valid when you view pages locally. The URL for a remote site would include the server name or IP address of the server where ColdFusion is installed; for example, http://<serveripaddress>/test/cfpage.cfm.

If you are using the ColdFusion MX J2EE configuration, you may also need to include a context root in the URL; for example, http://<server>/<context-root>/<page>.cfm. For example, if you deploy an EAR file and use the default context root of cfmx, you specify http:/ /localhost/cfmx/test/cfpage.cfm.

Working with ColdFusion pages 17

The following figure shows the cfpage.cfm page in the browser:

Do the following tasks:

View the source code that was returned to the browser. In most browsers, you can view the source by right-clicking on the page, and then selecting View Source.

Compare the browser source code with the source code that appears in your editor. Notice that the CFML tags were processed on the page but did not appear in the source that was returned to your browser.

As described in Chapter 1, “Introducing ColdFusion MX,” on page 11, ColdFusion processes all the instructions (CFML tags and functions) it receives on a page, and then returns the results of the instructions that your browser can interpret and display.

About CFML elements

CFML consists of two primary language elements: tags and functions. Ta g s let you perform operations such as accessing a database. Functions can return data and do other operations like retrieving the system date. Almost everything that you want to accomplish with ColdFusion involves using tags and functions.

You use another important element known as a variable. Variables are an important part of most programming languages and are equally important with CFML. Var ia bl es let you store information in memory and enable you to pass data.

The following sections describe how to use these three elements.

Functions

Typically, a function acts on data. It can generate a value or a set of values, usually from some input. You can perform the following operations (actions) with functions:

• Manipulate data and time values

• Examine a value or variable

• Display and format information

• Manipulate string data

• Retrieve system information and resources

• Perform mathematical operations

About CFML elements 19

Functions and number signs

You use number signs (#) with functions to display the results of a function on the page. Number signs tell the ColdFusion server to evaluate the content between the number signs and display the value, for example:

Hello world, <br> Today’s date is #DateFormat(Now(), "mm/dd/yyyy")#

</cfoutput>

The following figure shows the output of this example:

If you did not include the number signs around the

DateFormat(Now(), "mm/dd/yyyy")

function, ColdFusion would not evaluate the function and the previous example would display your source code, as follows:

For more information about how to use number signs with functions, see ColdFusion MX Developer’s Guide.

Functions and parentheses

All functions have parentheses, regardless of whether the function acts on data. Consider the following function:

#Now()#

If you put anything inside the parentheses of the Now() function, an error would occur. The

Now() function returns an unformatted date and time. However, you can format the results of

this function with other functions, such as the

DateFormat() or TimeFormat() functions.

20 Chapter 2: CFML Basics

Using functions on values

Usually, a function performs an operation on a value, and the value can include the value of a variable. For example, to format the value of a variable that contains a value in dollars, the code to write this statement might look like this:

#DollarFormat(price)#

The DollarFormat function returns a value as a string and formats that value with two decimal places, a thousands separator, and a dollar sign. The number signs (#) around the function instruct ColdFusion to evaluate the content between the number signs and display the value.

Nesting functions

Functions can generate data, as well as act on data. Consider the following example:

#DateFormat(Now(), "mm/dd/yyyy")#

In this example, the Now() function generates the date, and then the DateFormat function formats the date.

Variables

Variables let you store data in memory on the server. Variables always have a name and a value. You can assign a value to a variable, or you can instruct ColdFusion to assign variable values based on data that it retrieves from a data source, such as a database table.

Naming variables

You must use the following rules for naming ColdFusion variables:

• Names are case-insensitive (uppercase, lowercase, or mixed case).

• Names can contain only letters, numbers, and underscore characters.

• Each name must begin with a letter.

• Special characters (such as double-quotation marks ("), reserved names (such as functions and

tags), and spaces are not allowed.

Ways to use variables

You can use variables for the following purposes:

• Store data collected from a form.

• Store results of a calculation (such as the number of database records returned).

• Use as input to a function.

Creating variables with the cfset tag

ColdFusion lets you create variables as you need them. You create the variable (name and value) using the

cfset tag. This tag has the following syntax:

About CFML elements 21

In the following examples, the variables are assigned a string literal value. All string literal values are surrounded by double-quotation marks.

In the next example, ColdFusion uses the values of the my_first_name and my_last_name variables to set the value for the (

&) string operator joins the variables, and the space surrounded by double-quotation marks (" ")

my_full_name variable in the last line of code. The ampersand

adds a space between the variables.

Tip: String values assigned to a variable must be enclosed in single-quotation marks (') or doublequotation marks ("). Numeric or Boolean values assigned to a variable do not require single- or double-quotation marks.

So far, all the variable examples have shown local variables. Local variables are variables that you can use only on the current ColdFusion page. The previous example used a variables prefix to reference an existing variable on the page. Using a prefix when referencing a variable is important because ColdFusion supports many types of variables. Use the following syntax to reference a local variable:

variables.variablename

Because ColdFusion lets you use the same name with variables of more than one type, ColdFusion relies on scope referencing. In scope referencing, you preface the variable’s name with the scope when you refer to that variable.

Other variables and their scope

Each type of variable that ColdFusion supports has it own scope, or where it can be referenced, and its own way of referencing that variable type. The following table identifies some of the more common types of variables and their prefixes:

Scope Prefix Description

Variables (local variable)

Form Form Data entered in tags in an HTML form or ColdFusion form and

URL URL Variables passed to a page as URL string parameters.

Query QueryName Variables that have names based on the column names that you select

Variables Variables created using a

the variable on the current page or on a page that you include using the

cfinclude tag.

processed on the action page.

in the database table. The values are created when you execute the query that selects data from the database.

cfset or cfparam tag. Most often you define

You will use these other types of variables in Part II of this manual. For additional information about variables, see CFML Reference.

22 Chapter 2: CFML Basics

Displaying variable output

Output is what remains after the ColdFusion server processes the CFML tags on a page. Usually the output has two parts:

• Information that the user sees (for example, a confirmation message)

• Information that is stored by the server as a result of processing (for example, user input

collected from a form)

One of the tags that ColdFusion provides to display output is the tag instructs ColdFusion to process all the code between the syntax for the

{normal html, text, and ColdFusion processing instructions}

</cfoutput>

cfoutput tag looks like this:

To return the value of a variable, you must always surround the variable name with number signs (#) and place the variable name between the

cfoutput start and end tags. For example, the

following code creates a variable and instructs the ColdFusion server to return the value of the variable:

#variables.my_full_name#

</cfoutput>

The following text is the output:

cfoutput tag. The cfoutput

cfoutput start and end tags. The

Kaleigh Smith

Working with CFML expressions

Expressions are an important part of the ColdFusion language. Expressions are a collection of different elements, ColdFusion variables, functions, and operators. You can think of them as strings of text that consist of one or more of the following elements:

• Literal text (string), numbers, dates, and other values

• Variables

• Functions

• Operators (& for joining statements, + for addition, and so on)

This chapter includes many examples of expressions; for example:

• #variables.my_full_name#

• DateFormat(Now())

• my_first_name= "Kaleigh"

When you build expressions in ColdFusion, you can include simple and complex elements; how you represent these elements determines how ColdFusion processes your application.

Working with CFML expressions 23

Building expressions

In ColdFusion, you build expressions as you need them. The expressions can include simple elements, such as the expressions shown previously, or they can include complex elements, such as arithmetic functions, strings, and decision operators. (You build some complex expressions in Part II of this manual.)

As mentioned, it is important that elements are identified properly in your expression so that ColdFusion processes them as expected, and you avoid unnecessary errors. When you write expressions, consider the following coding practices:

• Use of consistent character case

• When to use number signs (#)

• When quotation marks are needed

Specifying a consistent character case

Because the ColdFusion server is case-insensitive, you can write expressions using all uppercase, all lowercase, or mixed case. However, for code readability and consistency, you should use the same character case in all your programs. If you write your programs using the same case rules, you might prevent errors from occurring when you combine CFML on a page with case-sensitive languages, such as JavaScript.

Specifying number signs to denote functions or variables

In ColdFusion, you specify number signs (#) to denote functions and variables within a string of text. You use number signs to show the results of the function or variable on the page. Number signs instruct the ColdFusion server to evaluate the function (or variable) between the number signs and display the value. The value of the function (or variable) appears in the browser as a result.

The following are some common ways to use number signs:

• In the following example, you include the number signs to return the value to a page:

<cfoutput> Hello #variables.my_first_name# </cfoutput>

If you omit the number signs, the text, not the value, appears on the page.

• In the following example, you do not include the number signs because you are using the

cfset tag to assign one variable’s value to another value:

<cfset my_full_name = variables.my_first_name & " " &

variables.my_last_name>

• To display a number sign on a page, you must designate the number sign as a literal character.

You do this by using two number signs (##); for example:

##1: Your name.

</cfoutput>

The result is the following output:

#1. Your name.

24 Chapter 2: CFML Basics

For more information and examples on using number signs in expressions, see ColdFusion MX Developer’s Guide.

Specifying quotation marks around values

When you assign literal values to variables, you must surround the literal value with single- or double-quotation marks. ColdFusion interprets the content between the quotation marks as a literal value and assigns that value to the variable; for example:

ColdFusion instantiates the variable my_first_name to the string literal Kaleigh. Further, Smith is assigned to the variable

my_last_name and 5 is assigned to age.

When referencing a variable by its name, you do not surround the name with quotation marks. In the following example, when you concatenate literal text and variables using the & operator, you don’t surround the variable references with quotation marks:

<cfset the_string = "My name is " & variables.my_first_name &

" and my age is " & variables.my_age>

My name is

references marks. ColdFusion uses the values of the referenced variables ( assigning the value to the variable

is literal text, and you, therefore, surround it with quotation marks. The variable

variables.my_first_name and variables.my_age are not surrounded by quotation

Kaleigh and 5, respectively) when

the_string.

To display quotation marks on a page as literal characters, you must use two consecutive quotation marks; for example:

<cfset mystring = "We all shouted ""Happy Birthday"" when he entered the

room.">

#mystring#

</cfoutput>

The result is the following output:

We all shouted "Happy Birthday" when he entered the room.

Specifying operators in expressions

In ColdFusion, you use operators to test conditions; for example, you use the

IS operator to test

for equality. When you use operators in expressions, you must only use supported logical operators that ColdFusion can interpret properly. For example, if you use the greater than operator (>) or the less than operator (<), ColdFusion interprets them as the start or end of a tag rather than as an operator.

Working with CFML expressions 25

The following table lists the unsupported logical operators and their equivalent ColdFusion operators:

Unsupported logical operator

= IS, EQUAL, EQ Tests for equality.

< LT, LESS THAN Tests for less than.

<= LTE, LE,

>GT

>= GTE,

< > IS NOT, NEQ,

CONTAINS Tests whether a value is contained within a

DOES NOT CONTAIN Tests whether a value is not contained

Equivalent ColdFusion decision operator

LESS THAN OR EQUAL TO

GREATER THAN

GREATER THAN OR EQUAL TO

NOT EQUAL

Description

Tests for less than or equal to.

Tests for greater than.

Tests for greater than or equal to.

Tests for nonequality.

second value.

within a second value.

Arithmetic operators

The following table lists the arithmetic operators that ColdFusion supports:

Operators Description

+, -, *, / The basic arithmetic operators: addition, subtraction, multiplication, and division.

+, - Unary arithmetic operators for setting the sign of a number as either positive or

Mod Returns the remainder (modulus) after a number is divided by a divisor. The result

\ Divides two integer values. Use the \ (backslash character) to separate the

^ Returns the result of a number raised to a power (exponent). Use the ^ (caret) to

In the case of division, the right operand cannot be zero.

negative (+ or -).

has the same sign as the divisor. The right operand cannot be zero. For example, 11 MOD 4 is 3.

integers. The right operand cannot be zero. For example, 9 \ 4 is 2.

separate the number from the power. The left operand cannot be zero. For example, 2 ^ 3 is 8.

26 Chapter 2: CFML Basics

String operator

The following table describes the one ColdFusion string operator that is a concatenation operator:

Operator Description

& Concatenates strings.

About conditional processing

So far, all the coding examples shown in this chapter are considered linear coding examples. Linear code is when ColdFusion executes code starting with the first line on the page, and processes every line in order. Although you will use linear code in your applications, you will often write code that performs various actions based on conditions, such as the following:

• Determine whether a user entered a value in a form field.

• Display results based on user input.

• Display messages based on the time of day.

You use conditional processing to customize the behavior of your application. Conditional processing facilitates decision making and lets you control how the code on a page is processed.

In ColdFusion, you implement conditional processing with flow control tags. These tags are similar to other programming language control elements, such as using these tags, you can facilitate decision making in your code. The most fundamental tags used to control code execution are the

cfif, cfelse, and cfelseif tags. Because you will see and use

these tags in Part II of this manual, the following sections provide a basic introduction on how to use these tags. For more information about other conditional processing tags, including tags for looping, see ColdFusion MX Developer’s Guide.

if, then, and else. When

Using the cfif tag to evaluate True or False conditions

To create statements that let you evaluate conditions and perform an action based on the result, you use the

HTML and CFML tags executed if expression is True.

</cfif>

cfif tag to create a cfif statement. The basic syntax is as follows:

In this example, ColdFusion only executes the code inside the cfif statement if the expression evaluates to True. To perform actions if the expression is False, you can use the example, if the following the ending

HTML and CFML tags executed if expression is True.

HTML and CFML tags executed if expression is False.

</cfif>

cfif tag is processed:

cfif expression evaluates to False, the code between the cfelse tag and

About conditional processing 27

cfelse tag. For

Using the cfelseif tag to evaluate multiple expressions

To evaluate multiple expressions in a

cfif statement, you can use cfelseif and cfelse tags in

your statement; for example:

HTML and CFML tags executed if expression 1 is True.

HTML and CFML tags executed if expression 2 is True.

HTML and CFML tags executed for expression(s) that is False.

</cfif>

The following example shows you how you can evaluate multiple expressions using these tags. This example uses a form in which users can enter their state to determine their state tax:

#form.state# State Tax: 8.5%

#form.state# State Tax: 8.2%

#form.state# State Tax Unknown </cfif> </cfoutput>

The output of this cfif statement is based on the value entered by the user. If the user enters MA in the state form field, the state tax results returned is 8.5%. If the user enters VA in the state form field, the state tax results returned is 8.2%. If the user enters any other state in the state form field, State Tax Unknown is returned.

Processing form data

Virtually all web applications that gather and write information to a database use a form to accomplish that task. Forms let you collect information from a user (using an order form, registration form, and so on) and write that information to a database. Like HTML, there are two independent steps for creating a form in ColdFusion:

Creating the layout for the form itself.

Writing the code to process the submitted information.

Every form that you create in ColdFusion consist of two parts: the form page and the action page. These two pages work together to process user input. The form page contains the user interface elements, such as input fields and radio buttons. The action page handles the processing of the form page data.

28 Chapter 2: CFML Basics

When a user submits a form, the form values are stored in form variables and sent to the action page for processing. The following figure shows the relationship between the form page and action page:

Form page

Name

E-mail

Submit

The action page contains the code for form processing and interaction with database.

form.var1=value1 form.var2=value2

ColdFusion server & web server

Action

page

Database

In order for the form page to find its corresponding action page, the action statement in the form tag must be correct. The form tag includes the information that tells the server where to send the data that it collects. It also tells the server how to send it. To process these instructions to the server, the form tag uses the following syntax:

HTML and CFML form tags </form>

The first attribute (action) in the form tag lets you specify where to send the data. The page that you specify where to send the data is the name of the action page. The second attribute in the form tag is must set the method attribute to

method. The only method that ColdFusion supports is post. All ColdFusion forms

post.

In Part II of this manual, you use ColdFusion form tags to create forms and write collected values to a database.

Processing form data 29

Commenting your code

As in other programming languages, it is important to include comments in your code. You should comment your code for the following reasons:

• Commented code is easier to debug than code that is not commented.

• If you describe the code on the page, it is easier to make modifications.

• Commented code tends to be better organized.

Comment tag

The ColdFusion comment tag is similar to the HTML comment tag, except that it has three dashes instead of two:

ColdFuions comments can wrap to more than one line. ColdFusion comments are not returned to the browser because the ColdFusion server processes and omits the comments from the page. The user will never be able to read your comments.

30 Chapter 2: CFML Basics

+ 122 hidden pages

Macromedia COLDFUSION MX7 User Manual

CONTENTS

INTRODUCTION

About Macromedia ColdFusion MX 7 documentation

Documentation set

Viewing online documentation

Welcome to ColdFusion

Introducing ColdFusion MX

Contents

About ColdFusion MX

The ColdFusion application server

The ColdFusion Markup Language

The ColdFusion MX Administrator

How ColdFusion processes pages

Building applications with CFML

Interacting with data sources

Interacting with mobile devices

Development tools

CFML Basics

Contents

Working with ColdFusion pages

Creating a ColdFusion page

Saving your ColdFusion page

Browsing your code

About CFML elements

Tags

Functions

Variables

Naming variables

Ways to use variables

Creating variables with the cfset tag

Displaying variable output

Working with CFML expressions

Building expressions

Specifying a consistent character case

Specifying number signs to denote functions or variables

Specifying quotation marks around values

Specifying operators in expressions

About conditional processing

Using the cfif tag to evaluate True or False conditions

Using the cfelseif tag to evaluate multiple expressions

Processing form data

Commenting your code