MACROMEDIA COLDFUSION MX 61-DEVELOPING COLDFUSION MX 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