Macromedia ColdFusion - MX 6.1 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

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

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

4 Contents

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

Contents 5

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

6 Contents

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

Contents 7

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

8 Contents

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

Contents 9

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

10 Contents

Accessing and changing session variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

Ending a session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

Configuring and using application variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

Configuring and enabling application variables . . . . . . . . . . . . . . . . . . . . . . . 331

Storing application data in application variables . . . . . . . . . . . . . . . . . . . . . . . 331

Using application variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

Using server variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

Locking code with cflock. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

Sample locking scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

Using the cflock tag with write-once variables. . . . . . . . . . . . . . . . . . . . . . . . . 335

Using the cflock tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

Considering lock granularity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

Nesting locks and avoiding deadlocks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

Examples of cflock. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

CHAPTER 16: Securing Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

ColdFusion security features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

About resource and sandbox security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

Resource control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

Sandbox security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

About user security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

Authenticating users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

Using ColdFusion security tags and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

Using the cflogin tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

Getting the user ID and password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

Logging a user in using Flash Remoting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

Logging users out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

Security scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

A web server authentication security scenario . . . . . . . . . . . . . . . . . . . . . . . . . 355

An application authentication security scenario . . . . . . . . . . . . . . . . . . . . . . . 356

Implementing user security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

Web-server–based authentication user security example . . . . . . . . . . . . . . . . . 358

Application-based user security example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

Using an LDAP Directory for security information . . . . . . . . . . . . . . . . . . . . 366

CHAPTER 17: Developing Globalized Applications . . . . . . . . . . . . . . . . . . . . . . . 371

Introduction to globalization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372

Defining globalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372

Importance of globalization in ColdFusion applications . . . . . . . . . . . . . . . . . 373

How ColdFusion MX supports globalization . . . . . . . . . . . . . . . . . . . . . . . . . 373

Character sets, character encodings, and locales . . . . . . . . . . . . . . . . . . . . . . . 373

About character encodings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

The Java Unicode character encoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

Character encoding conversion issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

Locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

Setting the locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

Using the locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

Contents 11

Processing a request in ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377

Determining the character encoding of a ColdFusion page. . . . . . . . . . . . . . . 378

Determining the page encoding of server output . . . . . . . . . . . . . . . . . . . . . . 379

Tags and functions for globalizing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

Tags and functions for controlling character encoding . . . . . . . . . . . . . . . . . . 380

Functions for controlling and using locales . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

Additional globalization tags and functions . . . . . . . . . . . . . . . . . . . . . . . . . . 382

Handling data in ColdFusion MX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

General character encoding issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383

Locale-specific content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383

Input data from URLs and HTML forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . 383

File data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

LDAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

WDDX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

COM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

CORBA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

Searching and indexing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387

CHAPTER 18: Debugging and Troubleshooting Applications . . . . . . . . . . . . . . . 389

Configuring debugging in the ColdFusion MX Administrator . . . . . . . . . . . . . . 390

Debugging Settings page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390

Debugging IP addresses page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392

Using debugging information from browser pages. . . . . . . . . . . . . . . . . . . . . . . . 392

General debugging information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393

Execution Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394

Database Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397

Trace points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398

Scope variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398

Using the dockable.cfm output format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399

Controlling debugging information in CFML . . . . . . . . . . . . . . . . . . . . . . . . . . . 400

Generating debugging information for an individual query . . . . . . . . . . . . . . 400

Controlling debugging output with the cfsetting tag. . . . . . . . . . . . . . . . . . . . 400

Using the IsDebugMode function to run code selectively . . . . . . . . . . . . . . . . 400

Using the cftrace tag to trace execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

About the cftrace tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

Using tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403

Calling the cftrace tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404

Using the Code Compatibility Analyzer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

Troubleshooting common problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

CFML syntax errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

Data source access and queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407

HTTP/URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407

12 Contents

PART IV: Accessing and Using Data

CHAPTER 19: Introduction to Databases and SQL . . . . . . . . . . . . . . . . . . . . . . . 411

What is a database? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412

Using multiple database tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413

Database permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414

Commits, rollbacks, and transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414

Database design guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415

Using SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415

SQL example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415

Basic SQL syntax elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416

Reading data from a database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418

Modifying a database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420

Writing queries using an editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422

Writing queries using Dreamweaver MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422

Writing queries using Macromedia HomeSite+. . . . . . . . . . . . . . . . . . . . . . . . 424

CHAPTER 20: Accessing and Retrieving Data . . . . . . . . . . . . . . . . . . . . . . . . . . 427

Working with dynamic data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428

Retrieving data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428

The cfquery tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429

The cfquery tag syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429

Building queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430

Outputting query data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

Query output notes and considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433

Getting information about query results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433

Query variable notes and considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434

Enhancing security with cfqueryparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435

About query string parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435

Using cfqueryparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435

CHAPTER 21: Updating Your Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437

About updating your dataSbase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438

Inserting data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438

Creating an HTML insert form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438

Data entry form notes and considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . 440

Creating an action page to insert data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440

Updating data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442

Creating an update form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443

Creating an action page to update data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445

Deleting data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448

Deleting a single record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448

Deleting multiple records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450

Contents 13

CHAPTER 22: Using Query of Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451

About record sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452

Referencing queries as objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452

Creating a record set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452

Creating a record set with a function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453

About Query of Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454

Benefits of Query of Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454

Performing a Query of Queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455

Query of Queries user guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462

Using dot notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462

Using joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462

Using unions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463

Using conditional operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

Using aggregate functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468

Using group by and having expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469

Using ORDER BY clauses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469

Using aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470

Handling null values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

Escaping reserved keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

Using Queries of Queries with numeric dates . . . . . . . . . . . . . . . . . . . . . . . . . 473

Understanding Query of Queries performance . . . . . . . . . . . . . . . . . . . . . . . . 473

BNF for Query of Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474

CHAPTER 23: Managing LDAP Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477

About LDAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478

The LDAP information structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479

Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480

Attribute. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480

Distinguished name (DN) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480

Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481

Using LDAP with ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482

Querying an LDAP directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483

Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483

Search filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483

Getting all the attributes of an entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485

Example: querying an LDAP directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485

Updating an LDAP directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488

Adding a directory entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489

Deleting a directory entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493

Updating a directory entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495

Adding and deleting attributes of a directory entry . . . . . . . . . . . . . . . . . . . . . 496

Changing a directory entry’s DN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497

Advanced topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497

Specifying an attribute that includes a comma or semicolon . . . . . . . . . . . . . . 497

Using cfldap output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498

Viewing a directory schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498

Referrals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502

Managing LDAP security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503

14 Contents

CHAPTER 24: Building a Search Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505

About Verity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506

Using Verity with ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506

Advantages of using Verity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507

Supported file types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507

Support for international languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509

Creating a search tool for ColdFusion applications . . . . . . . . . . . . . . . . . . . . . . . 511

Creating a collection with the ColdFusion MX Administrator . . . . . . . . . . . . 512

About indexing a collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513

Indexing and building a search interface with the Verity Wizard. . . . . . . . . . . 514

Creating a ColdFusion search tool programmatically . . . . . . . . . . . . . . . . . . . 518

Using the cfsearch tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523

Working with record sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526

Indexing database record sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526

Indexing cfldap query results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530

Indexing cfpop query results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531

Using database-directed indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532

CHAPTER 25: Using Verity Search Expressions. . . . . . . . . . . . . . . . . . . . . . . . . 535

About Verity query types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536

Using simple queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536

Stemming in simple queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537

Preventing stemming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538

Using explicit queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539

Using AND, OR, and NOT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539

Using wildcards and special characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540

Composing search expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542

Case sensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542

Prefix and infix notation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542

Commas in expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542

Precedence rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543

Delimiters in expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543

Operators and modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543

Refining your searches with zones and fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552

PART V: Requesting and Presenting Information

CHAPTER 26: Retrieving and Formatting Data. . . . . . . . . . . . . . . . . . . . . . . . . . 559

Using forms to specify the data to retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560

HTML form tag syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560

Form controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561

Form notes and considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563

Working with action pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564

Processing form variables on action pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564

Dynamically generating SQL statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564

Creating action pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565

Testing for a variable's existence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566

Contents 15

Requiring users to enter values in form fields . . . . . . . . . . . . . . . . . . . . . . . . . 566

Form variable notes and considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567

Working with queries and data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567

Using HTML tables to display query results . . . . . . . . . . . . . . . . . . . . . . . . . . 567

Formatting individual data items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569

Building flexible search interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569

Returning results to the user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570

Handling no query results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571

Returning results incrementally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572

Dynamically populating list boxes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574

Creating dynamic check boxes and multiple-selection

list boxes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576

Check boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576

Multiple selection lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578

Validating form field data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579

CHAPTER 27: Building Dynamic Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583

Creating forms with the cfform tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584

Using HTML and cfform. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584

The cfform controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584

Preserving input data with preservedata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585

Browser considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585

Building tree controls with cftree. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586

Grouping output from a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587

The cftree form variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589

Input validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589

Structuring tree controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590

Image names in a cftree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591

Embedding URLs in a cftree. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592

Specifying the tree item in the URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593

Building drop-down list boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593

Building text input boxes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594

Building slider bar controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595

Creating data grids with cfgrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595

Working with a data grid and entering data . . . . . . . . . . . . . . . . . . . . . . . . . . 596

Creating an editable grid. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599

Embedding Java applets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606

Registering a Java applet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606

Using cfapplet to embed an applet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608

Handling form variables from an applet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609

Input validation with cfform controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609

Validating with regular expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610

Input validation with JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613

Handling failed validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614

Example: validating an e-mail address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615

16 Contents

CHAPTER 28: Charting and Graphing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617

Creating a chart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618

Chart types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618

Creating a basic chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619

Administering charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620

Charting data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621

Charting a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621

Charting individual data points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624

Combining a query and data points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625

Charting multiple data collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625

Writing a chart to a variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627

Controlling chart appearance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629

Common chart characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629

Setting x-axis and y-axis characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631

Creating a bar chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631

Setting pie chart characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632

Creating an area chart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634

Setting curve chart characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636

Linking charts to URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636

Dynamically linking from a pie chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637

Linking to JavaScript from a pie chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639

CHAPTER 29: Using the Flash Remoting Service . . . . . . . . . . . . . . . . . . . . . . . 641

About using the Flash Remoting service with ColdFusion . . . . . . . . . . . . . . . . . . 642

Planning your Flash application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642

Using the Flash Remoting service with ColdFusion pages . . . . . . . . . . . . . . . . . . 643

Using Flash with ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646

Using the Flash Remoting service with server-side ActionScript . . . . . . . . . . . . . 648

Using the Flash Remoting service with ColdFusion Java objects . . . . . . . . . . . . . 649

Handling errors with ColdFusion and Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650

CHAPTER 30: Using Server-Side ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . 651

About server-side ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652

Client-side ActionScript requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652

Server-side requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653

Software requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653

Location of server-side ActionScript files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653

Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653

What to do next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654

Connecting to the Flash Remoting service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654

Using server-side ActionScript functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655

Using the function results in ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . 655

Global and request scope objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656

About the Cf.query function and data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . 657

Publishing dynamic data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657

About ColdFusion MX data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657

Contents 17

Using the CF.query function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658

About CF.query function syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658

About the CF.query record set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659

Building a simple application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660

Writing the server-side ActionScript function. . . . . . . . . . . . . . . . . . . . . . . . . 661

Creating the Flash movie interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661

Submitting user data to the Flash Remoting service . . . . . . . . . . . . . . . . . . . . 662

Capturing Flash Remoting service results . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662

Checking for a Flash Remoting service connection . . . . . . . . . . . . . . . . . . . . . 663

About the CF.http function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663

Using the CF.http function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664

Referencing HTTP Post parameters in the CF.http function . . . . . . . . . . . . . 665

Using the CF.http Post method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665

Using the CF.http Get method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666

PART VI: Using Web Elements and External Objects

CHAPTER 31: Using XML and WDDX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669

About XML and ColdFusion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670

The XML document object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671

A simple XML document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671

Basic view. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671

DOM node view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672

XML document structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673

ColdFusion XML tag and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676

Using an XML object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677

Referencing the contents of an XML object . . . . . . . . . . . . . . . . . . . . . . . . . . 677

Assigning data to an XML object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678

Creating and saving an XML document object . . . . . . . . . . . . . . . . . . . . . . . . . . 680

Creating a new XML document object using the cfxml tag. . . . . . . . . . . . . . . 680

Creating a new XML document object using the XmlNew function. . . . . . . . 680

Creating an XML document object from existing XML . . . . . . . . . . . . . . . . . 681

Saving and exporting an XML document object . . . . . . . . . . . . . . . . . . . . . . . 681

Modifying a ColdFusion XML object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681

Functions for XML object management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682

Treating elements with the same name as an array . . . . . . . . . . . . . . . . . . . . . 683

XML document object management reference . . . . . . . . . . . . . . . . . . . . . . . . 683

Adding, deleting, and modifying XML elements . . . . . . . . . . . . . . . . . . . . . . 685

Using XML and ColdFusion queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690

Transforming documents with XSLT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691

Extracting data with XPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692

Example: using XML in a ColdFusion application . . . . . . . . . . . . . . . . . . . . . . . 692

Moving complex data across the web with WDDX . . . . . . . . . . . . . . . . . . . . . . . 697

Uses of WDDX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698

How WDDX works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699

18 Contents

Using WDDX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702

Using the cfwddx tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702

Validating WDDX data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702

Using JavaScript objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702

Converting CFML data to a JavaScript object . . . . . . . . . . . . . . . . . . . . . . . . 703

Transferring data from the browser to the server . . . . . . . . . . . . . . . . . . . . . . . 703

Storing complex data in a string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706

CHAPTER 32: Using Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707

Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708

Accessing a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708

Basic web service concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709

Working with WSDL files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710

Creating a WSDL file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710

Viewing a WSDL file using Dreamweaver MX. . . . . . . . . . . . . . . . . . . . . . . . 711

Reading a WSDL file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711

Consuming web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713

About the examples in this section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713

Passing parameters to a web service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713

Handling return values from a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . 714

Using cfinvoke to consume a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714

Using CFScript to consume a web service. . . . . . . . . . . . . . . . . . . . . . . . . . . . 716

Consuming web services that are not generated by ColdFusion MX. . . . . . . . 717

Calling web services from a Flash client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717

Catching errors when consuming web services . . . . . . . . . . . . . . . . . . . . . . . . 717

Handling inout and out parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718

Configuring web services in the ColdFusion MX Administrator. . . . . . . . . . . 718

Data conversions between ColdFusion and WSDL data types . . . . . . . . . . . . 719

Consuming ColdFusion web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719

Publishing web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721

Creating components for web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721

Specifying data types of function arguments and return values . . . . . . . . . . . . 721

Producing WSDL files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722

Using ColdFusion components to define data types for web services . . . . . . . 724

Securing your web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726

Best practices for publishing web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728

Handling complex data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728

Consuming web services that use complex data types . . . . . . . . . . . . . . . . . . . 728

Publishing web services that use complex data types . . . . . . . . . . . . . . . . . . . . 731

CHAPTER 33: Integrating J2EE and Java Elements in CFML Applications . . . 735

About ColdFusion, Java, and J2EE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736

About ColdFusion and client-side JavaScript and applets . . . . . . . . . . . . . . . . 736

About ColdFusion and JSP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736

About ColdFusion and Servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737

About ColdFusion and Java objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737

About CFML variables and Java variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738

Contents 19

Using JSP tags and tag libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739

Using a JSP tag in a ColdFusion page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739

Example: using the random tag library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740

Interoperating with JSP pages and servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740

Integrating JSP and servlets in a ColdFusion application . . . . . . . . . . . . . . . . 740

Examples: using JSP with CFML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742

Using Java objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746

Using basic object techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746

Creating and using a simple Java class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748

Java and ColdFusion data type conversions. . . . . . . . . . . . . . . . . . . . . . . . . . . 751

Handling Java exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753

Examples: using Java with CFML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754

CHAPTER 34: Integrating COM and CORBA Objects in CFML Applications . . 761

About COM and CORBA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762

About objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762

About COM and DCOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762

About CORBA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762

Creating and using objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763

Creating objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763

Using properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763

Calling methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764

Calling nested objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764

Getting started with COM and DCOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764

COM Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765

Registering the object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765

Finding the component ProgID and methods. . . . . . . . . . . . . . . . . . . . . . . . . 765

Creating and using COM objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767

Connecting to COM objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768

Setting properties and invoking methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768

General COM object considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769

Accessing Complex COM Objects using Java proxies. . . . . . . . . . . . . . . . . . . 771

Using the Application Scope to improve COM performance . . . . . . . . . . . . . 774

Getting started with CORBA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777

Creating and using CORBA objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777

Creating CORBA objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777

Using CORBA objects in ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778

Handling exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783

CORBA example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784

20 Contents

PART VII: Using External Resources

CHAPTER 35: Sending and Receiving E-Mail . . . . . . . . . . . . . . . . . . . . . . . . . . 789

Using ColdFusion with mail servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790

Sending e-mail messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790

Sending SMTP e-mail with cfmail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791

Sample uses of cfmail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792

Sending form-based e-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792

Sending query-based e-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792

Sending e-mail to multiple recipients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793

Customizing e-mail for multiple recipients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794

Using cfmailparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795

Attaching files to a message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795

Adding a custom header to a message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796

Advanced sending options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796

Sending mail as HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796

Error logging and undelivered messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797

Receiving e-mail messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797

Using cfpop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797

The cfpop query variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798

Handling POP mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798

CHAPTER 36: Interacting with Remote Servers . . . . . . . . . . . . . . . . . . . . . . . . . 807

About interacting with remote servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808

Using cfhttp to interact with the web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808

Using the cfhttp Get method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808

Creating a query object from a text file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811

Using the cfhttp Post method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812

Performing file operations with cfftp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815

Caching connections across multiple pages . . . . . . . . . . . . . . . . . . . . . . . . . . . 817

Connection actions and attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 818

CHAPTER 37: Managing Files on the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 819

About file management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 820

Using cffile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 820

Uploading files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 820

Moving, renaming, copying, and deleting server files . . . . . . . . . . . . . . . . . . . 825

Reading, writing, and appending to a text file. . . . . . . . . . . . . . . . . . . . . . . . . 826

Using cfdirectory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828

Returning file information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828

Using cfcontent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 830

About MIME types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 830

Changing the MIME content type with cfcontent . . . . . . . . . . . . . . . . . . . . . 830

INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 833

Contents 21

22 Contents

INTRODUCTION

Developing ColdFusion MX Applications provides the tools needed to develop Internet applications using Macromedia ColdFusion MX. This book is intended for web application programmers who are learning ColdFusion MX or wish to extended their ColdFusion MX programming knowledge. It provides a solid grounding in the tools that ColdFusion MX provides to develop web applications.

Because of the power and flexibility of ColdFusion MX, you can create many different types of web applications of varying complexity. As you become more familiar with the material presented in this manual, and begin to develop your own applications, you will want to refer to CFML Reference for details about various tags and functions.

Contents

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

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

Using this book

This book can to help anyone with a basic understanding of HTML learn to develop ColdFusion. However, this book is most useful if you have basic ColdFusion experience, or have read Getting Started Building ColdFusion MX Applications. The Getting Started book provides an introduction to ColdFusion and helps you develop the basic knowledge that will make using this book easier.

Book structure and contents

The book is divided into seven parts, as follows:

Part Description

The CFML Programming Language

Reusing CFML Code Techniques for writing code once and using it many times,

Developing CFML Applications How to develop a complete ColdFusion application. Includes

Accessing and Using Data Methods for accessing and using data sources, including an

Requesting and Presenting Information

Using Web Elements and External Objects

Using External Resources Methods for getting and sending e-mail, accessing remote

The elements of ColdFusion Markup Language (CFML), including variables, expressions, dynamic code, CFScript, and regular expressions.

including the CFML tags, ColdFusion components, and CFXAPI tags.

information on error handling, sharing data, locking code, securing access, internationalization, debugging, and troubleshooting.

introduction to SQL and information on using SQL data bases, LDAP directory services, and the Verity search engine

How to dynamically request information from users and display results on the user’s browser, including graphing data and providing data to Macromedia Flash clients.

How to use XML, Java objects including Enterprise JavaBeans, JSP pages, web services (including creating web services in ColdFusion), and COM and CORBA objects.

servers using HTTP and FTP, and accessing files and directories.

cfinclude tag, user-defined functions, custom

Each chapter includes basic information plus detailed coverage of the topic that should be of use to experienced ColdFusion developers.

Approaches to using this book

This section describes approaches to using this book for beginning ColdFusion developers, developers with some experience who want to develop expertise, and advanced developers who want to learn about the new and enhanced features of ColdFusion MX.

24 Introduction

Beginning with ColdFusion

If you are learning ColdFusion, a path such as the following might be most effective:

1 Introduction to ColdFusion MX through Using Expressions and Pound Signs to learn the basics

of CFML.

2 Introduction to Databases and SQL through Updating Your Database to learn about using

databases.

3 Retrieving and Formatting Data and Building Dynamic Forms to learn about requesting data

from users. At this point, you should have a basic understanding of the basic elements of ColdFusion and

can create simple ColdFusion applications. To learn to produce more complete and robust applications, you could proceed with the following chapters.

4 Designing and Optimizing a ColdFusion Application through Debugging and Troubleshooting

Applications to learn how to build a complete ColdFusion application.

5 Using Query of Queries to learn how to use queries effectively. 6 Using Arrays and Structures through Building and Using ColdFusion Components to learn to

use more advanced features of CFML, including ways to reuse code.

You can then read the remaining chapters as you add new features to your ColdFusion application.

Developing an in-depth knowledge of ColdFusion

If you have a basic understanding of ColdFusion as presented in Getting Started Building ColdFusion MX Applications or the Fast Track to ColdFusion course, you might want to start at

Chapter 1 and work through to the end of the book, skipping any specialized chapters that you are unlikely to need.

Learning about new and modified ColdFusion features

If you are an advanced ColdFusion developer, you might want to learn about new or changed ColdFusion MX features. In this case, you start with Migrating ColdFusion Applications; then read selected chapters in this book. The following chapters document features that are new or substantially enhanced in ColdFusion MX:

• Chapter 10, Writing and Calling User-Defined Functions

• Chapter 11, Building and Using ColdFusion Components

• Chapter 16, Securing Applications

• Chapter 17, Developing Globalized Applications

• Chapter 18, Debugging and Troubleshooting Applications

• Chapter 28, Charting and Graphing Data

• Chapter 29, Using the Flash Remoting Service

• Chapter 31, Using XML and WDDX

• Chapter 32, Using Web Services

• Chapter 33, Integrating J2EE and Java Elements in CFML Applications

Using this book 25

Nearly all chapters contain information that is new in ColdFusion MX, so you should also review all other chapters for useful information. The index and the table of contents are useful tools for finding new features or changed documentation.

About Macromedia ColdFusion MX documentation

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

Documentation set

The ColdFusion MX documentation set includes the following titles:

Book Description

Installing and Using ColdFusion MX

Configuring and Administering ColdFusion MX

use for configuring the Verity K2 Server search engine, as well as creating, managing, and troubleshooting Verity collections.

Developing ColdFusion MX Applications

Getting Started Building ColdFusion MX Applications

CFML Reference

CFML Quick Reference

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.

CHAPTER 1

Introduction to ColdFusion MX

This chapter describes Macromedia ColdFusion MX and the role it plays in Internet applications, including Macromedia Flash MX based applications. This chapter also introduces the topics discussed in this book.

Contents

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

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

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

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

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

About Internet applications and web application servers

With ColdFusion MX, you develop Internet applications that run on web application servers. The following sections introduce Internet applications and web application servers. Later sections explain the specific role that ColdFusion MX plays in this environment.

About web pages and Internet applications

The Internet has evolved from a collection of static HTML pages to an application deployment platform. First, the Internet changed from consisting of static web pages to providing dynamic, interactive content. Rather than providing unchanging content where organizations merely advertise goods and services, dynamic pages enable companies to conduct business ranging from e-commerce to managing internal business processes. For example, a static HTML page lets a bookstore publish its location, list services such as the ability to place special orders, and advertise upcoming events like book signings. A dynamic website for the same bookstore lets customers order books online, write reviews of books they read, and even get suggestions for purchasing books based on their reading preferences.

More recently, the Internet has become the underlying infrastructure for a wide variety of applications. With the arrival of technologies such as XML, web services, J2EE (Java 2 Platform, Enterprise Edition), and Microsoft .NET, the Internet has become a multifaceted tool for integrating business activities. Now, enterprises can use the Internet to integrate distributed activities, such as customer service, order entry, order fulfillment, and billing.

ColdFusion MX is a rapid application development environment that lets you build dynamic websites and Internet applications quickly and easily. It lets you develop sophisticated websites and Internet applications without knowing the details of many complex technologies, yet it lets advanced developers take advantage of the full capabilities of many of the latest Internet technologies.

About web application servers

To understand ColdFusion, you must first understand the role of web application servers. Typically, web browsers make requests, and web servers, such as Microsoft Internet Information Server (IIS) and the Apache web server, fulfill those requests by returning the requested information to the browser. This information includes, but is not limited to, HTML and Macromedia Flash files.

A web server’s capabilities are limited because all it does is wait for requests to arrive and attempt to fulfill those requests as soon as possible. A web server does not let you do the following tasks:

• Interact with a database, other resource, or other application.

• Serve customized information based on user preferences or requests.

• Validate user input.

A web server, basically, locates information and returns it to a web browser.

Chapter 1: Introduction to ColdFusion MX

To extend the capabilities of a web server, you use a web application server, a software program that extends the web server’s capabilities to do tasks such as those in the preceding list.

How a web server and web application server work together

The following steps explain how a web server and web application server work together to process a page request:

1 The user requests a page by typing a URL in a browser, and the web server receives the request. 2 The web server looks at the file extension to determine whether a web application server must

process the page. Then, one of the following actions occur:

■ If the user requests a file that is a simple web page (often one with an HTM or HTML

extension), the web server fulfills the request and sends the file to the browser.

■ If the user requests a file that is a page that a web application server must process (one with

a CFM, CFML, or CFC extension for ColdFusion requests), the web server passes the request to the web application server. The web application server processes the page and sends the results to the web server, which returns those results to the browser. The following figure shows this process:

Because web application servers interpret programming instructions and generate output that a web browser can interpret, they let web developers build highly interactive and data-rich websites, which can do tasks such as the following:

• Query other database applications for data.

• Dynamically populate form elements.

• Dynamically generate Flash application data.

• Provide application security.

• Integrate with other systems using standard protocols such as HTTP, FTP, LDAP, POP, and

SMTP.

• Create shopping carts and e-commerce websites.

• Respond with an e-mail message immediately after a user submits a form.

• Return the results of keyword searches.

About Internet applications and web application servers 29

About ColdFusion MX

ColdFusion MX is a rapid scripting environment server for creating Rich Internet Applications. ColdFusion Markup Language (CFML) is an easy-to-learn tag-based scripting language, with connectivity to enterprise data and powerful built-in search and charting capabilities. ColdFusion MX enables developers to easily build and deploy dynamic websites, content publishing systems, self-service applications, commerce sites, and more.

ColdFusion MX consists of the following core components:

• ColdFusion scripting environment

• CFML

• ColdFusion application services

• ColdFusion MX Administrator

The following sections describe these core components in more detail.

The ColdFusion scripting environment

The ColdFusion scripting environment provides an efficient development model for Internet applications. At the heart of the ColdFusion scripting environment is the ColdFusion Markup Language (CFML), a tag-based programming language that encapsulates many of the low-level details of web programming in high-level tags and functions.

ColdFusion Markup Language

ColdFusion Markup Language (CFML) is a tag-based language, similar to HTML, that uses special tags and functions. With CFML, you can enhance standard HTML files with database commands, conditional operators, high-level formatting functions, and other elements to rapidly produce easy-to-maintain web applications. However, CFML is not limited to enhancing HTML. For example, you can create Macromedia Flash MX applications that consist entirely of Flash elements and CFML. Similarly, you can use CFML to create web services for use by other applications.

The following sections briefly describe basic CFML elements. For more information, see Chapter

2, “Elements of CFML,” on page 39.

CFML tags

CFML looks similar to HTML—it includes starting and, in most cases, ending 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

tag body text and CFML

</cftagname>

cf; for example:

CFML increases productivity by providing a layer of abstraction that hides many low-level details involved with Internet application programming. At the same time, CFML is extremely powerful and flexible. ColdFusion lets you easily build applications that integrate files, databases, legacy systems, mail servers, FTP servers, objects, and components.

30 Chapter 1: Introduction to ColdFusion MX

+ 830 hidden pages