User manual MACROMEDIA COLDFUSION MX 61 - DEVELOPING COLDFUSION MX APPLICATIONS

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example: a dynamic shopping cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CHAPTER 5: Using Arrays and Structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 104 104 104 106 106 106 108 109 109 110 110 110 112 113 113 114 114 116 116 117 117 117 119 121 121 122 125 About arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic array concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About ColdFusion arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic array techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Referencing array elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding elements to an array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting elements from an array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Copying arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Populating arrays with data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Populating an array with the ArraySet function . . . . . . . . . . . . . . . . . . . . . . . Populating an array with the cfloop tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Populating an array from a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Array functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Structure notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Referencing complex structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating and using structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding data elements to structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Updating values in structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting information about structures and keys . . . . . . . . . . . . . . . . . . . . . . . . Copying structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting structure elements and structures . . . . . . . . . . . . . . . . . . . . . . . . . . . Looping through structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Structure example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Structure functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 412 413 414 414 415 415 415 416 418 420 422 422 424 What is a database? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using multiple database tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Commits, rollbacks, and transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database design guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SQL example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic SQL syntax elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reading data from a database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying a database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Writing queries using an editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Writing queries using Dreamweaver MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . Writing queries using Macromedia HomeSite+. . . . . . . . . . . . . . . . . . . . . . . . CHAPTER 20: Accessing and Retrieving Data . . . . . . . . . . . . . . . . . . . . . . . . . . 427 428 428 429 429 430 431 433 433 434 435 435 435 Working with dynamic data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Retrieving data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The cfquery tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The cfquery tag syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Outputting query data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Query output notes and considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting information about query results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Query variable notes and considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enhancing security with cfqueryparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About query string parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using cfqueryparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 560 560 561 563 564 564 564 565 566 Using forms to specify the data to retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . HTML form tag syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Form controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Form notes and considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with action pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Processing form variables on action pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dynamically generating SQL statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating action pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing for a variable's existence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 642 642 643 646 648 649 650 About using the Flash Remoting service with ColdFusion . . . . . . . . . . . . . . . . . . Planning your Flash application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Flash Remoting service with ColdFusion pages . . . . . . . . . . . . . . . . . . Using Flash with ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Flash Remoting service with server-side ActionScript . . . . . . . . . . . . . Using the Flash Remoting service with ColdFusion Java objects . . . . . . . . . . . . . Handling errors with ColdFusion and Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . CHAPTER 30: Using Server-Side ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . 651 652 652 653 653 653 653 654 654 655 655 656 657 657 657 About server-side ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client-side ActionScript requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Server-side requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Software requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Location of server-side ActionScript files . . . . . . . . . . . . . . . . . . . . . . . . . . . . Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What to do next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connecting to the Flash Remoting service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using server-side ActionScript functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the function results in ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . Global and request scope objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About the Cf.query function and data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . Publishing dynamic data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About ColdFusion MX data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the cfwddx tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validating WDDX data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using JavaScript objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Converting CFML data to a JavaScript object . . . . . . . . . . . . . . . . . . . . . . . . Transferring data from the browser to the server . . . . . . . . . . . . . . . . . . . . . . . Storing complex data in a string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CHAPTER 32: Using Web Services. 702 702 702 702 703 703 706 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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