Detailed instructions for use are in the User's Guide.
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
CONTENTS
INTRODUCTION
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Using this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 About Macromedia ColdFusion MX documentation . . . . . . . . . . . . . . . . . . . . . . 26 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
CHAPTER 1: Introduction to ColdFusion MX
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 40 40 40 40 41 41 42 42 43 43 44 44 44
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Character case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tag syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Built-in tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Built-in functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variable scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3
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 84 84 87 87 89 89 90 90 91 91 92 92 92 93 94 98 99
Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operator types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operator precedence and evaluation ordering . . . . . . . . . . . . . . . . . . . . . . . . . . Using functions as operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using pound signs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using pound signs in ColdFusion tag attribute values. . . . . . . . . . . . . . . . . . . . Using pound signs in tag bodies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using pound signs in strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Nested pound signs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using pound signs in expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dynamic expressions and dynamic variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About dynamic variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About dynamic expressions and dynamic evaluation. . . . . . . . . . . . . . . . . . . . . Dynamic variable naming without dynamic evaluation . . . . . . . . . . . . . . . . . . Using dynamic evaluation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the IIF function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examp ...
