MACROMEDIA COLDFUSION MX 61-DEVELOPING COLDFUSION MX User manual

This manual suits for next models

1

Table of contents

Other MACROMEDIA Software manuals

MACROMEDIA

MACROMEDIA FIREWORKS 8-USING FIREWORKS Mounting instructions

MACROMEDIA

MACROMEDIA FLASH REMOTING MX-USING FLASH REMOTING FOR FLASH MX 2004 ACTIONSCRIPT... Mounting instructions

MACROMEDIA

MACROMEDIA COLFUSION MX 7 - INSTALLING AND USING COLDFUSION... User manual

MACROMEDIA

MACROMEDIA COLDFUSION 4.5-DEVELOPING WEB User manual

MACROMEDIA

MACROMEDIA CONTRIBUTE User manual

MACROMEDIA

MACROMEDIA FLASH 8-FLASH Service manual

MACROMEDIA

MACROMEDIA CONTRIBUTE 3 - USING AND ADMINISTERING... Mounting instructions

MACROMEDIA

MACROMEDIA DIRECTOR MX 2004-GETTING STARTED WITH... User manual

MACROMEDIA

MACROMEDIA BREEZE 5-MANAGER User manual

MACROMEDIA

MACROMEDIA FLASH MEDIA SERVER 2-INSTALLING FLASH MEDIA SERVER... User manual

MACROMEDIA

MACROMEDIA FLASH MX 2004 - FLASH LITE AUTHORING GUIDELINES FOR THE I-MODE... Instruction Manual

MACROMEDIA

MACROMEDIA 38000382 - Macromedia JRun - Mac User manual

MACROMEDIA

MACROMEDIA FLASH MEDIA SERVER 2-DEVELOPING MEDIA User manual

MACROMEDIA

MACROMEDIA FREEHAND MX 11 Mounting instructions

MACROMEDIA

MACROMEDIA COLDFUSION 4.5-CFML LANGUAGE Service manual

MACROMEDIA

MACROMEDIA BREEZE-CLUSTERING BREEZE PRESENTATION... User manual

MACROMEDIA

MACROMEDIA FLASH 8-COMPONENTS LANGUAGE Service manual

MACROMEDIA

MACROMEDIA DIRECTOR MX 2004-USING DIRECTOR Mounting instructions

MACROMEDIA

MACROMEDIA COLFUSION MX 7-CFML User manual

MACROMEDIA

MACROMEDIA FLASH 8-FLASH Operation instructions

MACROMEDIA

MACROMEDIA DIRECTOR MX 2004-USING DIRECTOR Mounting instructions

MACROMEDIA

MACROMEDIA COLDFUSION MX 61 - CONFIGURING AND ADMINISTERING COLDFUSION... Guide

MACROMEDIA

MACROMEDIA DREAMWEAVER MX 2004-EXTENDING DREAMWEAVER User manual

MACROMEDIA

MACROMEDIA FLASHLITE2 ACTIONSCRIPT-LANGUAGE Service manual

Popular Software manuals by other brands

COMPRO

COMPRO COMPROFM manual

Muratec

Muratec OFFICEBRIDGE ONLINE user guide

Oracle

Oracle Contact Center Anywhere 8.1 installation guide

Adobe

Adobe 65007312 - Photoshop Lightroom Programmer's guide

Avaya

Avaya NULL One-X for RIM Blackberry user guide

HP

HP ProLiant BL420c user guide

PS Audio

PS Audio PowerPlay Programming manual

Brady

Brady LOCKOUT PRO 3.0 Administrator's guide

Avaya

Avaya Interaction Center user guide

Texas Instruments

Texas Instruments TI-83 Plus Silver Edition Guide book

Novell

Novell GROUPWISE 8 - INTERNET AGENT manual

Oracle

Oracle Application 9i Configuration guide

Acer

Acer RDM user guide

Canon

Canon Vixia HF21 instruction manual

Canon

Canon ZR950 instruction manual

Samsung

Samsung Auto Backup user manual

Polycom

Polycom Vortex EF2201 Application note

Brocade Communications Systems

Brocade Communications Systems Brocade 8/12c user manual

Developing 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 ZCF61M800

Acknowledgments

Project Management: Randy Nielsen

Writing: Hal Lichtin, Randy Nielsen

Editing: Linda Adler, Noreen Maher

First Edition: May 2002

Second Edition: August 2003

Macromedia, Inc.

600 Townsend St.

San Francisco, CA 94103

3

CONTENTS

INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Using this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

About Macromedia ColdFusion MX documentation . . . . . . . . . . . . . . . . . . . . . . 26

CHAPTER 1: Introduction to ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

About Internet applications and web application servers . . . . . . . . . . . . . . . . . . . . 28

About web pages and Internet applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

About web application servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

About ColdFusion MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

The ColdFusion scripting environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

ColdFusion Markup Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

ColdFusion application services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

ColdFusion MX Administrator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Using ColdFusion MX with Macromedia Flash MX . . . . . . . . . . . . . . . . . . . . . . . 32

About J2EE and the ColdFusion architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

About ColdFusion MX and the J2EE platform. . . . . . . . . . . . . . . . . . . . . . . . . 33

ColdFusion features described in this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

PART I: The CFML Programming Language

CHAPTER 2: Elements of CFML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Character case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Tag syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Built-in tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Built-in functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

User-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Variable scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

4 Contents

Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

CFScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Flow control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

cfif, cfelseif, and cfelse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

cfswitch, cfcase, and cfdefaultcase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

cfloop and cfbreak . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

cfabort and cfexit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Special characters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Reserved words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

CHAPTER 3: Using ColdFusion Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Creating variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Variable naming rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Variable characteristics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Boolean values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Date-Time values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Binary data type and Base64 encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Complex data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Using periods in variable references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Understanding variables and periods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Creating variables with periods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Data type conversion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Operation-driven evaluation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Conversion between types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Evaluation and type conversion issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Examples of type conversion in expression evaluation . . . . . . . . . . . . . . . . . . . . 71

About scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Scope types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Creating and using variables in scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Using scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Ensuring variable existence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Testing for a variable’s existence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Using the cfparam tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Validating data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Using the cfparam tag to validate the data type. . . . . . . . . . . . . . . . . . . . . . . . . 81

Passing variables to custom tags and UDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Passing variables to CFML tags and UDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Passing variables to CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Contents 5

CHAPTER 4: Using Expressions and Pound Signs . . . . . . . . . . . . . . . . . . . . . . . . 83

Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Operator types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Operator precedence and evaluation ordering. . . . . . . . . . . . . . . . . . . . . . . . . . 87

Using functions as operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Using pound signs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Using pound signs in ColdFusion tag attribute values. . . . . . . . . . . . . . . . . . . . 89

Using pound signs in tag bodies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Using pound signs in strings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Nested pound signs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Using pound signs in expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Dynamic expressions and dynamic variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

About dynamic variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

About dynamic expressions and dynamic evaluation. . . . . . . . . . . . . . . . . . . . . 92

Dynamic variable naming without dynamic evaluation . . . . . . . . . . . . . . . . . . 93

Using dynamic evaluation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Using the IIF function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Example: a dynamic shopping cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

CHAPTER 5: Using Arrays and Structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

About arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Basic array concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

About ColdFusion arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Basic array techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Referencing array elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Creating arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Adding elements to an array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Deleting elements from an array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Copying arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Populating arrays with data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Populating an array with the ArraySet function . . . . . . . . . . . . . . . . . . . . . . . 110

Populating an array with the cfloop tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Populating an array from a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Array functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

About structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Structure notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Referencing complex structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Creating and using structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Creating structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Adding data elements to structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Updating values in structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Getting information about structures and keys . . . . . . . . . . . . . . . . . . . . . . . . 117

Copying structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Deleting structure elements and structures . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Looping through structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Structure example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Structure functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

6 Contents

CHAPTER 6: Extending ColdFusion Pages with CFML Scripting. . . . . . . . . . . . 127

About CFScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Comparing tags and CFScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

The CFScript language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Identifying CFScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Expressions and operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Statement blocks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Reserved words. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Differences from JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

CFScript limitation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

CFScript functional equivalents to ColdFusion tags . . . . . . . . . . . . . . . . . . . . 131

Using CFScript statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Using assignment statements and functions . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Using conditional processing statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Using looping statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Handling exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

CFScript example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

CHAPTER 7: Using Regular Expressions in Functions . . . . . . . . . . . . . . . . . . . . 143

About regular expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Using ColdFusion regular expression functions. . . . . . . . . . . . . . . . . . . . . . . . 144

Basic regular expression syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Regular expression syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Using character sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Finding repeating characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Case sensitivity in regular expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Using subexpressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Using special characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Using escape sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Using character classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Using backreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Using backreferences in replacement strings . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Omitting subexpressions from backreferences. . . . . . . . . . . . . . . . . . . . . . . . . 154

Returning matched subexpressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Specifying minimal matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Regular expression examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Regular expressions in CFML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Types of regular expression technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Contents 7

PART II: Reusing CFML Code

CHAPTER 8: Reusing Code in ColdFusion Pages . . . . . . . . . . . . . . . . . . . . . . . . 163

About reusable CFML elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Including pages with the cfinclude tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Using the cfinclude tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Recommended uses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Calling user-defined functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Calling UDFs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Recommended uses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

For more information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Using custom CFML tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Calling custom CFML tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Recommended uses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

For more information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Using CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Calling CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Recommended uses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

For more information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

Using ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

Creating and using ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . 170

Recommended uses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

For more information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Selecting among ColdFusion code reuse methods . . . . . . . . . . . . . . . . . . . . . . . . 171

CHAPTER 9: Creating and Using Custom CFML Tags . . . . . . . . . . . . . . . . . . . . 173

Creating custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Creating and calling custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Securing custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Accessing existing custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Passing data to custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Passing values to and from custom tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Using tag attributes summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Custom tag example with attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Passing custom tag attributes using CFML structures . . . . . . . . . . . . . . . . . . . 180

Managing custom tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Securing custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Encoding custom tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Executing custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Accessing tag instance data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Handling end tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Processing body text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Terminating tag execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Nesting custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Passing data between nested custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Variable scopes and special variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

High-level data exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

8 Contents

CHAPTER 10: Writing and Calling User-Defined Functions . . . . . . . . . . . . . . . . 191

About user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Calling user-defined functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Creating user-defined functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Creating functions using CFScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Creating functions using tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Rules for function definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Defining functions in CFScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Defining functions using the cffunction tag . . . . . . . . . . . . . . . . . . . . . . . . . . 200

Calling functions and using variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Passing arguments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Referencing caller variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Using function-only variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Using arguments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

A User-defined function example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Defining the function using CFScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Defining the function using the cffunction tag . . . . . . . . . . . . . . . . . . . . . . . . 205

Using UDFs effectively . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Using Application.cfm and function include files . . . . . . . . . . . . . . . . . . . . . . 206

Specifying the scope of a function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Using the Request scope for static variables and constants . . . . . . . . . . . . . . . 208

Using function names as function arguments . . . . . . . . . . . . . . . . . . . . . . . . . 208

Handling query results using UDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Identifying and checking for UDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

Using the Evaluate function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Passing complex data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Using recursion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Handling errors in UDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

CHAPTER 11: Building and Using ColdFusion Components . . . . . . . . . . . . . . . . 219

About ColdFusion components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

Basic component concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

ColdFusion component features and use . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Using ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Instantiating CFCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

CFC invocation techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Invoking CFC methods with the cfinvoke tag . . . . . . . . . . . . . . . . . . . . . . . . 226

Using components directly in CFScript and CFML . . . . . . . . . . . . . . . . . . . . 229

Invoking CFC methods using forms and URLs . . . . . . . . . . . . . . . . . . . . . . . 230

Accessing CFCs from outside ColdFusion and basic HTML . . . . . . . . . . . . . 232

Invoking components as web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Introspection: getting information about components . . . . . . . . . . . . . . . . . . 233

Building ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Initializing instance data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Defining component methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Providing results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

CFC variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Structuring and reusing code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

Building secure ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

Contents 9

CHAPTER 12: Building Custom CFXAPI Tags. . . . . . . . . . . . . . . . . . . . . . . . . . . 251

What are CFX tags?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Before you begin developing CFX tags in Java. . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Sample Java CFX tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Setting up your development environment to develop CFX tags in Java . . . . . 253

Customizing and configuring Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

Writing a Java CFX tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

Calling the CFX tag from a ColdFusion page . . . . . . . . . . . . . . . . . . . . . . . . . 254

Processing requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

Loading Java CFX classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

Automatic class reloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Life cycle of Java CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

ZipBrowser example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Approaches to debugging Java CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Outputting debugging information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Debugging in a Java IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Using the debugging classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

Developing CFX tags in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Sample C++ CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Setting up your C++ development environment . . . . . . . . . . . . . . . . . . . . . . . 261

Compiling C++ CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

Locating your C++ library files on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

Implementing C++ CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

Debugging C++ CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

Registering CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

PART III: Developing CFML Applications

CHAPTER 13: Designing and Optimizing a ColdFusion Application . . . . . . . . . . 267

About applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Elements of a ColdFusion application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

The application framework. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Application-level settings and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

Reusable application elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

Shared variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

Application security and user identification . . . . . . . . . . . . . . . . . . . . . . . . . . 270

Mapping an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

Processing the Application.cfm and OnRequestEnd.cfm pages. . . . . . . . . . . . 271

Defining the directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Creating the Application.cfm page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Naming the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Setting the client, application, and session variables options . . . . . . . . . . . . . . 273

Defining page processing settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

Setting application default variables and constants . . . . . . . . . . . . . . . . . . . . . 274

Processing logins. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

Handling errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

Example: an Application.cfm page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

10 Contents

Optimizing ColdFusion applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

Caching ColdFusion pages that change infrequently. . . . . . . . . . . . . . . . . . . . 277

Caching parts of ColdFusion pages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

Optimizing database use. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

Providing visual feedback to the user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

CHAPTER 14: Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

About error handling in ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

Understanding errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

About error causes and recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

ColdFusion error types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

About ColdFusion exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

How ColdFusion handles errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

Error messages and the standard error format . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

Determining error-handling strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

Handling missing template errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

Handling form field validation errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

Handling compiler exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

Handling runtime exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

Specifying custom error messages with cferror . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

Specifying a custom error page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

Creating an error application page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

Logging errors with the cflog tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

Handling runtime exceptions with ColdFusion tags . . . . . . . . . . . . . . . . . . . . . . 299

Exception-handling tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Using cftry and cfcatch tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Using cftry: an example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

Using the cfthrow tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

Using the cfrethrow tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Example: using nested tags, cfthrow, and cfrethrow . . . . . . . . . . . . . . . . . . . . 309

CHAPTER 15: Using Persistent Data and Locking . . . . . . . . . . . . . . . . . . . . . . . 315

About persistent scope variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

ColdFusion persistent variables and ColdFusion structures. . . . . . . . . . . . . . . 316

ColdFusion persistent variable issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

Managing the client state. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

About client and session variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

Maintaining client identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

Configuring and using client variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Enabling client variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Using client variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

Configuring and using session variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

What is a session? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

Configuring and enabling session variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Storing session data in session variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Standard session variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Getting a list of session variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Creating and deleting session variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329