Macromedia Getting Started Building ColdFusion MX Applications User Manual

Getting Started Building

ColdFusion MX Applications

Trademarks

Afterburner, AppletAce, Attain, Attain Enterprise Learning System, Attain Essentials, Attain Objects for Dreamweaver, Authorware, Authorware Attain, Authorware Interactive Studio, Authorware Star, Authorware Synergy, Backstage, Backstage Designer, Backstage Desktop Studio, Backstage Enterprise Studio, Backstage Internet Studio, ColdFusion, Design in Motion, Director, Director Multimedia Studio, Doc Around the Clock, Dreamweaver, Dreamweaver Attain, Drumbeat, Drumbeat 2000, Extreme 3D, Fireworks, Flash, Fontographer, FreeHand, FreeHand Graphics Studio, Generator, Generator Developer's Studio, Generator Dynamic Graphics Server, JRun, Knowledge Objects, Knowledge Stream, Knowledge Track, Lingo, Live Effects, Macromedia, Macromedia M Logo & Design, Macromedia Flash, Macromedia Xres, Macromind, Macromind Action, MAGIC, Mediamaker, Object Authoring, Power Applets, Priority Access, Roundtrip HTML, Scriptlets, SoundEdit, ShockRave, Shockmachine, Shockwave, Shockwave Remote, Shockwave Internet Studio, Showcase, Tools to Power Your Ideas, Universal Media, Virtuoso, Web Design 101, Whirlwind and Xtra are 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, servicemarks, or tradenames of Macromedia, Inc. or other entities and may be registered in certain jurisdictions including internationally.

This product includes code licensed from RSA Data Security.

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.

Apple Disclaimer

APPLE COMPUTER, INC. MAKES NO WARRANTIES, EITHER EXPRESS OR IMPLIED, REGARDING THE ENCLOSED COMPUTER SOFTWARE PACKAGE, ITS MERCHANTABILITY OR ITS FITNESS FOR ANY PARTICULAR PURPOSE. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME STATES. THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. THIS WARRANTY PROVIDES YOU WITH SPECIFIC LEGAL RIGHTS. THERE MAY BE OTHER RIGHTS THAT YOU MAY HAVE WHICH VARY FROM STATE TO STATE.

Copyright © 1999–2003 Macromedia, Inc. All rights reserved. This manual may not be copied, photocopied, reproduced, translated, or converted to any electronic or machine-readable form in whole or in part without prior written approval of Macromedia, Inc. Part Number ZCF61M300

Acknowledgments

Project Management: Randy Nielsen

Writer: Randy Nielsen

Editor: Linda Adler, Noreen Maher

First Edition: May 2002 Second Edition: August 2003

Macromedia, Inc. 600 Townsend St. San Francisco, CA 94103

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

About Macromedia ColdFusion MX documentation . . . . . . . . . . . . . . . . . . . . . . . 7

Documentation set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Viewing online documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

PART I: Welcome to ColdFusion

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

What is ColdFusion MX? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

The ColdFusion application server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

The ColdFusion Markup Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

The ColdFusion MX Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Using ColdFusion MX with Macromedia Flash MX . . . . . . . . . . . . . . . . . . . . . . . 14

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

Working with ColdFusion pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Creating a ColdFusion page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Understanding CFML elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Creating variables with the cfset tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Displaying variable output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

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

Building expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Understanding conditional processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

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

Form processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Commenting your code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

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

Understanding database basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

What is a relational database? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Understanding relational tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

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

Using SQL to interact with a database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Using SQL with ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

About data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Writing SQL and CFML statements to interact with a data source. . . . . . . . . . 35

CFML tags that interact with a database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

CHAPTER 4: Configuring Your Development Environment . . . . . . . . . . . . . . . . . 37

Verifying the tutorial file structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Configuring database connection and debugging options . . . . . . . . . . . . . . . . . . . 39

Configuring the connection to the sample database file . . . . . . . . . . . . . . . . . . 39

Enabling debugging options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Macromedia development environment tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

The Dreamweaver MX environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Configuring Dreamweaver MX for ColdFusion development. . . . . . . . . . . . . . 46

Configuring HomeSite+ for ColdFusion development . . . . . . . . . . . . . . . . . . . 46

PART II: Building a ColdFusion Application

CHAPTER 5: Lesson 1: Preparing to Build the Sample Application . . . . . . . . . . . 49

Application development steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Determining the application functional requirements . . . . . . . . . . . . . . . . . . . . . . 50

Determining the data requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Designing the database for your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Developing the sample application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

How to proceed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

CHAPTER 6: Lesson 2: Writing Your First ColdFusion Application . . . . . . . . . . . 57

Creating your first ColdFusion application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Application development steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Using a web page to list trips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Converting to a dynamic web page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Using SQL with cfquery to dynamically retrieve information . . . . . . . . . . . . . . 62

Creating a dynamic web page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Developing a search capability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Designing the search criteria page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Building the Search Results page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Completing the Trip Search Results page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

In the next lesson . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

4 Contents

CHAPTER 7: Lesson 3: Creating a Main Application Page . . . . . . . . . . . . . . . . . 77

Enhancing the Trip Maintenance application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Showing additional trip details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Avoiding the potential security risk when using dynamic SQL . . . . . . . . . . . . . 84

Linking the Search Results page to the Trip Detail page . . . . . . . . . . . . . . . . . . 85

Enhancing the look of the search results and detail pages . . . . . . . . . . . . . . . . . 86

Creating the main application page from the Trip Detail page . . . . . . . . . . . . . 89

Adding navigation buttons to browse database . . . . . . . . . . . . . . . . . . . . . . . . . 89

Adding database maintenance buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

In the next lesson . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

CHAPTER 8: Lesson 4: Validating Data to Enforce

Business Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Enhancing the Trip Maintenance application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Using an HTML form to collect data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Developing code to validate data and enforce business rules . . . . . . . . . . . . . . . . . 95

Validating data using a server-side action page . . . . . . . . . . . . . . . . . . . . . . . . . 96

Validating data on the client using ColdFusion form tags . . . . . . . . . . . . . . . . . 99

Using cfselect tag to present valid event types . . . . . . . . . . . . . . . . . . . . . . . . . 102

Using other client-side script to reduce edits on the server . . . . . . . . . . . . . . . 104

Validating the existence of the trip photo file . . . . . . . . . . . . . . . . . . . . . . . . . 106

Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

In the next lesson . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

CHAPTER 9: Lesson 5: Implementing the Browsing and Maintenance Database

Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Enhancing the Trip Maintenance application . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Application development steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Using dynamic SQL to browse (navigate) the Trips table . . . . . . . . . . . . . . . . 111

Building the maintenance action page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Linking the Trip Detail page to the Trip Search page . . . . . . . . . . . . . . . . . . . 114

Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

In the next lesson . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

CHAPTER 10: Lesson 6: Adding and Updating SQL Data . . . . . . . . . . . . . . . . . 117

Completing the Trip Maintenance application . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Writing code to save new trips to the database . . . . . . . . . . . . . . . . . . . . . . . . 118

Updating a SQL row using cfupdate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Linking the Trip Edit page to the main page. . . . . . . . . . . . . . . . . . . . . . . . . . 125

SQL Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Updating multiple records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

INDEX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Contents 5

6 Contents

INTRODUCTION

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

About Macromedia ColdFusion MX documentation

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

Documentation set

The ColdFusion documentation set includes the following titles:

Book Description

Installing and Using ColdFusion MX

Configuring and Administering ColdFusion MX

Developing ColdFusion MX Applications

Getting Started Building ColdFusion MX Applications

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

CFML Quick Reference A brief guide that shows the syntax of ColdFusion tags, functions, and

Describes system installation and basic configuration for Windows, Solaris, Linux, and HP-UX.

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.

Describes how to develop your dynamic web applications, including retrieving and updating your data, using structures, and forms.

Contains an overview of ColdFusion features and application development procedures. Includes a tutorial that guides you through the process of developing an example ColdFusion application.

tags, functions, and variables.

variables.

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.

8 Introduction

PART I

Welcome to ColdFusion

Part I provides an introduction to ColdFusion. It defines ColdFusion and provides an overview of the ColdFusion Markup Language (CFML). It also provides generic database concepts, and information about how to prepare your development environment for using the tutorial in Part II of this book.

Introducing ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

CFML Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Database Fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Configuring Your Development Environment . . . . . . . . . . . . . . . . . . . . . . 37

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.

Contents

What is ColdFusion MX? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Using ColdFusion MX with Macromedia Flash MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

What is 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 server

• ColdFusion Markup Language (CFML)

• ColdFusion Administrator

The following sections describe these core components in more detail.

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 file extension. A ColdFusion page looks like an HTML page but contains special tags that instruct the ColdFusion server to perform specific operations.

How ColdFusion processes pages

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

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

ColdFusion instructions:

■ Tags that begin with cf.

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

2 If the ColdFusion server finds any HTML or plain text in the page, the ColdFusion server

returns it to the web server untouched.

3 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.

The ColdFusion Markup Language

ColdFusion Markup Language (CFML) is a 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 easy-to-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; for example:

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 JSP tag libraries).

12 Chapter 1: Introducing ColdFusion MX

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 Language (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.

Development tools

While you can code your ColdFusion application with NotePad or any HTML editor, 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 4, “Configuring Your Development

Environment,” on page 37.

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.

What is ColdFusion MX? 13

Using ColdFusion MX with Macromedia Flash MX

Macromedia Flash MX is designed to overcome the many limitations of HTML and solve the problem of providing efficient, interactive, user interfaces for Internet applications. ColdFusion MX is designed to provide a fast, efficient environment for developing and providing data-driven Internet applications.

By using ColdFusion MX and Flash MX together, you can easily create complete visually interactive applications for the Internet. ColdFusion MX provides a native Flash connectivity that ensures visual applications created with Flash MX can easily and securely interact with ColdFusion. Flash MX clients communicate efficiently with ColdFusion by using an Action Message Format protocol over HTTP. This protocol provides fast, lightweight, binary transfer of data between the Flash client and ColdFusion.

By using the following features of ColdFusion MX and Flash MX, you can create efficient datadriven Internet applications with visually interactive user interfaces:

• Flash MX ActionScript commands Lets you connect to ColdFusion components (CFC)

and ColdFusion pages.

• Flash MX development application debugger Lets you trace your application logic as it

executes between Flash and ColdFusion.

• ColdFusion MX Server-Side ActionScript Lets Flash programmers familiar with

ActionScript create ColdFusion services, such as SQL queries, for use by Flash clients.

For more information about using Server-Side ActionScript and developing Flash applications in ColdFusion, see Developing ColdFusion MX Applications. For more information about using Flash MX, go to Macromedia on the web (www.macromedia.com).

14 Chapter 1: Introducing ColdFusion MX

CHAPTER 2

CFML Basics

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

Contents

Working with ColdFusion pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Understanding CFML elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

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

Understanding conditional processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

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

Commenting your code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Working with ColdFusion pages

As discussed in Chapter 1, “Introducing ColdFusion MX,” on page 11, 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 4,

“Configuring Your Development Environment,” on page 37.

Note: This book shows 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

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

16 Chapter 2: CFML Basics

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

To create a ColdFusion page:

1 Open your editor and create a blank file. 2 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>

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), then you can save the pages locally; if you are using a remote server, then 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 using the J2EE configuration with JRun, you save pages under jrun_root/servers/cfusion/cfusion- ear/cfusion-war. When using 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 you typed to create a ColdFusion page:

1 Create a new directory called test under the web_root or web_application_root directory. 2 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:

1 Open a web browser and go to the following URL:

http://127.0.0.1/test/cfpage.cfm The address 127.0.0.1 refers to the localhost and 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, 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://127.0.0.1/cfmx/test/cfpage.cfm.

Working with ColdFusion pages 17

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

2 Do the following tasks:

a View the source code that was returned to the browser. In most browsers, you can view the

source by right-clicking on page then selecting View Source.

b 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.

Understanding 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 you want to accomplish with ColdFusion will involve using tags and functions.

You will use another important element known as a variable. Variables are an important part of most programming languages and are equally important with CFML. Va ri ab les 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

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 containing a value in dollars, the code to write this statement might look like this:

#DollarFormat(price)#

Understanding CFML elements 19

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

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

Nesting functions

DateFormat() or TimeFormat() 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.

Functions and pound signs

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

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

The following figure shows the output of this example:

20 Chapter 2: CFML Basics

If you did not include the pound signs around the DateFormat(Now(), "mm/ddyyy") 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 pound signs with functions, see Developing ColdFusion MX Applications.

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 a variable 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. The syntax for this tag is:

Understanding 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 (') or double (") quotation marks. Numeric or Boolean values assigned to a variable do not require single or double quotation marks.

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

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

ColdFusion supports many types of variables. Each type 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 are named based on the column names that you select

Variables Variables created using

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

cfinclude.

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. Most often you define the

You will use these other types of variables in Part II of this book. 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

<cfoutput> {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 pound 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:

<cfset my_first_name = "Kaleigh"> <cfset my_last_name = "Smith"> <cfset my_full_name = variables.my_first_name & " " & variables.my_last_name> <cfoutput> #variables.my_full_name# </cfoutput>

The following is the output:

Kaleigh Smith

cfoutput tag. The cfoutput

cfoutput start and end tags. The

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)

Many examples of expressions were shown in this chapter; 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 program.

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 book.)

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

• Character case consistency

• When to use the pound (#) sign

• 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 pound signs to denote functions or variables

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

The following list identifies some common ways to use pound signs:

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

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

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

• In the following example, you do not include the pound signs because you are using cfset to

assign one variable’s value to another value:

<cfset my_full_name = variables.my_first_name & " " &

variables.my_last_name>

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

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

The result is the following output: #1. Your name.

For more information and examples on using pound signs in expressions, see Developing ColdFusion MX Applications.

24 Chapter 2: CFML Basics

Specifying quotation marks around values

When assigning literal values to variables, you must surround the literal value with double quotation marks or single 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; for example:

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

" and my age is " & variables.my_age>

My name is

references quotation marks. ColdFusion uses the values of the referenced variables ( respectively) when 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

Kaleigh and 5,

the_string.

To display quotation marks on a page as literal characters, you must double the quotation marks; for example:

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

room."> <cfoutput> #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 using 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 these operators as the start or end of a tag.

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

Nonsupported logical operator

= IS, EQUAL, EQ Tests for equality.

< LT, LESS THAN Tests for less than.

<= LTE, LE,

>GT

Equivalent ColdFusion decision operator Description

Tests for less than or equal to.

LESS THAN OR EQUAL TO

Tests for greater than.

GREATER THAN

Working with CFML expressions 25

Nonsupported logical operator

>= GTE,

< > IS NOT, NEQ,

Equivalent ColdFusion decision operator Description

Tests for greater than or equal to

GREATER THAN OR EQUAL TO

Tests for nonequality.

NOT EQUAL

CONTAINS Tests whether a value is contained within a

second value.

DOES NOT CONTAIN Tests whether a value is not contained

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 either positive or

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

\ Divides two integer values. Use the \ (trailing slash) to separate the integers. 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.

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.

String operator

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

Operator Description

& Concatenates strings.

Understanding conditional processing

To this point, all the coding examples shown 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 if a user entered a value in a form field.

• Display results based on user input.

• Display messages based on the time of day.

26 Chapter 2: CFML Basics

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

if, then, and else.

Conditional processing tags

ColdFusion provides several tags that let you control how a page is processed. When 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 book, 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 Developing ColdFusion MX Applications.

Using cfif 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

<cfif expression> HTML and CFML tags executed if expression is True. </cfif>

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

In the previous 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 tag. For example, if the following

cfelse tag and the cfif tag is processed:

HTML and CFML tags executed if expression is True. <cfelse>

HTML and CFML tags executed if expression is False. </cfif>

cfif expression evaluates to False, then the code between the

cfelse

Using cfelseif to evaluate multiple expressions

To evaluate multiple expressions in a cfif statement, you can use cfelseif and cfelse in your statement; for example:

HTML and CFML tags executed if expression 1 is True. <cfelseif expression 2>

HTML and CFML tags executed if expression 2 is True. <cfelse>

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. In this example, you created a form in which users can enter their state to determine their state tax:

#form.state# State Tax: 8.5% <cfelseif form.state IS "VA">

#form.state# State Tax: 8.2% <cfelse>

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

Understanding conditional processing 27

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:

1 Creating the layout for the form itself. 2 Writing the code to process the submitted information.

Form processing

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.

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

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

Submit

form.var1=value1 form.var2=value2

Action

page

ColdFusion server & web server

Database

28 Chapter 2: CFML Basics

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 processes 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 book, you will use ColdFusion form tags to create forms and write collected values to a database.

Commenting your code

As in other programming languages, it is important to include comments in the 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:

<!--- This is a CFML comment --- >

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.

Commenting your code 29

30 Chapter 2: CFML Basics

+ 104 hidden pages