Macromedia COLDFUSION 5-DEVELOPING APPLICATIONS User Manual

Developing

ColdFusion Applications

MacroMedia ColdFusion® 5

Macromedia® Incorporated

be used or copied only in accordance with the terms of such license. The content of this manual is furnished for informational use only, is subject to change without notice, and should not be constru ed as a commitm ent by Macrom edia, Incorpor ated. Macromedia, Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in this book.

Except as permitted by such license, no part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Macromedia, Incorporated.

ColdFusion, HomeSite, and Macromedia are registered trademarks of Macromedia Incorporation in the United States and internationally. Allaire Spectra, the Allaire Spectra logo, Generator, Macromedia Generation, and JRun are trademarks of Macromedia, Incorporated. Java is a trademark of Sun Microsystems, Inc. Microsoft, Windows, Windows NT, Windows 95, Microsoft Access, and FoxPro are registered trademarks of Microsoft Corporation. PostScript is a trademark of Adobe Systems Inc. Solaris is a trademark of Sun Microsystems Inc. UNIX is a trademark of The Open Group. All other company names, brand names, and product names are trademarks of their respective holder(s).

Part number: ZCF50MDEV

About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xvi

Developer Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

About ColdFusion Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii

Getting Answers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx

Contacting Macromedia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx

Chapter 1 Introduction to ColdFusion . . . . . . . . . . . . . . 1

A Quick Web Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

What is ColdFusion?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

ColdFusion Features and Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

How ColdFusion Server Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Printed and online documentation set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

Viewing online documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

Printing ColdFusion documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Relational database design and management . . . . . . . . . . . . . . . . . . . . . . . . . 3

SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Editions of ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

About the features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

About the components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Chapter 2 Writing Your First ColdFusion Application . 9

The Development Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Working with ColdFusion Application Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

About applicaton pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Creating application pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Saving application pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Viewing application pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

iv Contents

Working with Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

About variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Adding more variables to the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Development Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Chapter 3 Querying a Database . . . . . . . . . . . . . . . . . . 17

Publishing Dynamic Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Understanding Database Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Understanding Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

About Open Database Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Accessing Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Adding data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Specifying data sources dynamically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Retrieving Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

The cfquery tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

The cfquery tag syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Writing SQL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Basic SQL syntax elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

SQL notes and considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Building Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Query notes and considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Outputting Query Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Query output notes and considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Getting Information About Query Results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Query properties notes and considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Using Query Results in Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Query of query benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Creating queries of queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Performing a query on a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Chapter 4 Retrieving and Formatting Data . . . . . . . . . 39

Using Forms to Specify the Data to Retrieve. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

form tag syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Form controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Form notes and considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Working with Action Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Processing form variables on action pages . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Dynamically generating SQL statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Creating action pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

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

Form variable notes and considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Working with Queries and Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

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

Formatting individual data items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Performing pattern matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Filtering data based on multiple conditions . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Creating table joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Building flexible search interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Returning Results to the User. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

If there are no query results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Returning results incrementally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Chapter 5 Graphing Data . . . . . . . . . . . . . . . . . . . . . . . . 59

Creating a Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Graph types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Creating a basic graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Graphing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Graphing a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Graphing individual data points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Combining a query and data points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Controlling Graph Appearance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Common graph characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Setting bar and horizontal bar chart characteristics . . . . . . . . . . . . . . . . . . . 68

Setting pie chart characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Setting line and area graph characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Linking Dynamically from Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Chapter 6 Making Variables Dynamic . . . . . . . . . . . . . 81

Dynamically Populating List Boxes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Creating Dynamic Check Boxes and Multiple-Selection List Boxes. . . . . . . . . . . 84

Check boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Multiple selection lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Ensuring that Variables Exist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Using cfparam to test for variables and set default values . . . . . . . . . . . . . 88

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

Validating Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Using cfparam to validate the data type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Validating form field data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Checking query parameters with cfqueryparam . . . . . . . . . . . . . . . . . . . . . . 94

Dynamic SQL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Implementing dynamic SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Chapter 7 Updating Your Database . . . . . . . . . . . . . . 101

Inserting Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Creating an HTML insert form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Developing Web Applications with ColdFusionDRAFT 5/9/01 Path/Filename/Au thor

vi Contents

Data entry form notes and considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 103

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

Updating Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Creating an update form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

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

Deleting Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Deleting a single record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Deleting multiple records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Chapter 8 Handling Complex Data

with Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

About Arrays. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Basic Array Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Creating an array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Adding elements to an array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Referencing elements in dynamic arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Populating Arrays with Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Populating an array with ArraySet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Populating an array with cfloop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Using nested loops for 2D and 3D arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Populating an array from a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Array Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

About Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Structure notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Creating and Using Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Creating structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Adding data elements to structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Updating values in structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Getting information about structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Copying structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Deleting structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Structure example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Looping through structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Structure Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Chapter 9 Building Dynamic Forms . . . . . . . . . . . . . . 135

Creating Forms with the cfform Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Using HTML and cfform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

cfform controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Preserving input data with preservedata . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Browser considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Input Validation with cfform Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Validating with regular expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

vii

Input Validation with JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Handling failed validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

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

Building Tree Controls with cftree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 47

Grouping output from a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

cftree form variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Input validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Structuring Tree Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Image names in a cftree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Embedding URLs in a cftree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Specifying the tree item in the URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Creating Data Grids with cfgrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Populating a grid from a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Creating an Updateable Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Navigating and entering data in a grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Controlling cell contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

How user edits are returned . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Editing data in cfgrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Updating the database with cfgridupdate . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Updating the database with cfquery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Building Slider Bar Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Building Text Entry Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Building Drop-Down List Boxes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Embedding Java Applets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Registering a Java applet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Using cfapplet to embed an applet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Handling form variables from an applet . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Chapter 10 Reusing Code . . . . . . . . . . . . . . . . . . . . . . 171

Ways to Reuse Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Reusing Common Code with cfinclude . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Using Custom Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Using existing custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

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

Variable scopes and special variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Using tag attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

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

Passing custom tag attributes via CFML structures . . . . . . . . . . . . . . . . . . 177

Custom tag example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Nesting Custom Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Passing Data Between Nested Custom Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

What data is accessible? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Developing Web Applications with ColdFusionDRAFT 5/9/01 Path/Filename/Au thor

viii Contents

Where is data accessible? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

High-level data exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Executing Custom Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Tag instance data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Modes of execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Specifying execution modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Terminating tag execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Access to generated content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Installing Custom Tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Local tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Shared tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Managing Custom Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Resolving filename conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Securing custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Encoding custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Chapter 11 Preventing and Handling Errors . . . . . . . 191

Debug Settings in the ColdFusion Administrator . . . . . . . . . . . . . . . . . . . . . . . . . 192

Generating debug information for an individual page . . . . . . . . . . . . . . . . 192

Generating debug information for an individual query . . . . . . . . . . . . . . . 192

Error messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

CFML Code Validation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Runtime validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

The CFML syntax checker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Troubleshooting Common Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

ODBC data source configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

HTTP/URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

CFML syntax errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Error Handling in ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Understanding ColdFusion errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Generating Custom Error Messages with cferror . . . . . . . . . . . . . . . . . . . . . . . . . 199

Creating an error application page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

Logging Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Handling Exceptions in ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Types of recoverable exceptions supported . . . . . . . . . . . . . . . . . . . . . . . . . 205

Exception information in cfcatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Exception handling strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Exception handling example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Custom Exception Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Chapter 12 Using the Application Framework . . . . . 213

Understanding the Web Application Framework. . . . . . . . . . . . . . . . . . . . . . . . . . 214

Application-level settings and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Client, Session, Application, and Server scope variables . . . . . . . . . . . . . . 214

Custom error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Web server security integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Mapping an Application Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Processing Application.cfm and OnRequestEnd.cfm . . . . . . . . . . . . . . . . . 216

Defining the directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Creating the Application.cfm File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

Naming the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

Setting application default variables and constants . . . . . . . . . . . . . . . . . . 219

Managing the Client State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

About Client and Session variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

About client cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Managing client state in a clustered envi ronment . . . . . . . . . . . . . . . . . . . 222

Managing client state without cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Configuring and Using Client Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

Setting up Client variable options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

Using Client variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Using Session Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

Enabling Session variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

What is a session? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

Storing session data in Session variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

Standard Session variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

Getting a list of Session variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

Using Application Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

Storing application data in Application variables . . . . . . . . . . . . . . . . . . . . 230

Application variable timeouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Tips for using Application variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Getting a list of Application variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Using Server Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Locking Code with cflock. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Using cflock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

How cflock works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Using administrative lock management . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Nesting locks and avoiding deadlocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

Examples of cflock. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Chapter 13 Extending ColdFusion Pages with CFML

Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

About CFScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

CFScript example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

Supported statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

The CFScript Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

Developing Web Applications with ColdFusionDRAFT 5/9/01 Path/Filename/Au thor

x Contents

Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

Reserved words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

Differences from JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

Interaction of CFScript with CFML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Defining and Using Custom Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

Defining functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

Calling functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

Using arguments and variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

Identifying custom functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

Examples of custom functons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

Using custom functions effectively . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

Chapter 14 Using Regular Expressions in Functions . . . .

259

About Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

Basic Regular Expression Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Character classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Multicharacter Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

Limiting input string size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Anchoring a regular expression to a string . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Using Backreferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Using backreferences in replacement strings . . . . . . . . . . . . . . . . . . . . . . . 265

Returning Matched Subexpressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Regular Expression Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Regular expressions in CFML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Chapter 15 Indexing and Searching Data . . . . . . . . . 269

Searching a ColdFusion Web Site. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

Advantages of using Verity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

Supported File Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Support for International Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Creating a Searchable Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Creating a Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Populating and indexing a collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Selecting an indexing method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

Building a search interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

Indexing Query Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

Indexing database query results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

Indexing cfldap query results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

Indexing cfpop query results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

Using Query Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Simple query expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Explicit query expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

Expression syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

Composing search expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

Searching with wildcards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

Searching for special characters as literals . . . . . . . . . . . . . . . . . . . . . . . . . . 289

Operators and modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

Modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

Managing Collections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

Maintenance options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

Securing a collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

Chapter 16 Sending and Receiving E-mail . . . . . . . . 301

Using ColdFusion with Mail Servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

Sending E-mail Mess ages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

Sending SMTP mail with cfmail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

Sample Uses of cfmail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

Sending form-based e-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

Sending query-based e-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

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

Customizing E-mail for Multiple Recipients. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

Attaching a MIME file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 07

Advanced Sending Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

Sending mail as HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

Error logging and undelivered messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

Receiving E-mail Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Using cfpop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

cfpop query variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Handling POP Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Retrieving only message headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Retrieving an entire message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

Retrieving attachments with messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

Deleting messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Chapter 17 Managing Files on the Server . . . . . . . . . 317

Using cffile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

Uploading Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

Resolving conflicting filenames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Controlling the type of file uploaded . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Setting File and Directory Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

Developing Web Applications with ColdFusionDRAFT 5/9/01 Path/Filename/Au thor

xii Contents

Evaluating the Results of a File Upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

Moving, Renaming, Copying, and Deleting Server Files. . . . . . . . . . . . . . . . . . . . 326

Reading, Writing, and Appending to a Text File . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Reading a text file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Writing a text file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Performing Directory Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Returning file information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Chapter 18 Interacting with Remote Servers . . . . . . 331

Using cfhttp to Interact with the Web. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

Using the cfhttp Get Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

Creating a Query from a Text File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

Using the cfhttp Post Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

Performing File Operations with cfftp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

Caching connections across multiple pages . . . . . . . . . . . . . . . . . . . . . . . . 343

Connection actions and attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344

Moving Complex Data Structures Across the Web with WDDX . . . . . . . . . . . . . 345

An overview of distributed data for the Web . . . . . . . . . . . . . . . . . . . . . . . . 345

WDDX and Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

WDDX components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

Working with application-level data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

Data exchange across application servers . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

How WDDX works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

Converting CFML Data to a JavaScript Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

Transferring Data from Browser to Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

Storing Complex Data in a String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

Chapter 19 Application Security . . . . . . . . . . . . . . . . . 355

ColdFusion Security Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

Remote Development Services (RDS) Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

Overview of User Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

Using Adva nced Security in Application Pages. . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

Using the cfauthenticate tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

Authentication and Authorization Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

Using the IsAuthenticated function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

Using the IsAuthorized function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

Catching Security Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

Using the cfimpersonate Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362

Example of User Authentication and Authorization . . . . . . . . . . . . . . . . . . . . . . . 363

xiii

Authenticating users in Application.cfm . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363

Checking for authentication and authorization . . . . . . . . . . . . . . . . . . . . . 365

Chapter 20 Using cfobject to Invoke Component Objects .

367

Component Object Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

About COM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

About CORBA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

About Java objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

Invoking Component Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

Using properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

Calling methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

Calling nested objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

Getting Started with COM/DCOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

Requirements for COM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

Registering the object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371

Finding the component ProgID and methods . . . . . . . . . . . . . . . . . . . . . . . 371

Creating and Using COM Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

Connecting to COM objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

Setting properties and invoking methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

Getting Started with CORBA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

Calling CORBA Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

Declaring structures and sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

Exception handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

Calling Java Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

Getting Started with Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

Java and Cold Fusion Data Type Conversions . . . . . . . . . . . . . . . . . . . . . . . 381

Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

The class loading mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

A more complex Java example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

Chapter 21 Building Custom CFXAPI Tags . . . . . . . . 389

What Are CFX Tags?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390

Before You Begin Developing CFX Tags in Java. . . . . . . . . . . . . . . . . . . . . . . . . . . . 391

Sample Java CFXs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391

Setting up your development environment to develop CFXs in Java . . . 391

Customizing and Configuring Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392

Writing a Java CFX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393

Processing requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393

Loading Java CFX classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

Automatic class reloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

Life cycle of Java CFXs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

Calling the CFX from a ColdFusion page . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

Developing Web Applications with ColdFusionDRAFT 5/9/01 Path/Filename/Au thor

xiv Contents

ZipBrowser Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397

Approaches to Debugging Java CFXs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398

Outputting debug information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398

Using the debugging classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399

Developing CFX Tags in C++. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

Sample C++ CFXs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

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

Using the Tag Wizard to create CFXs in C++ . . . . . . . . . . . . . . . . . . . . . . . . 401

Compiling C++ CFXs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

Implementing C++ CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

Debugging C++ CFXs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

Registering CFXs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404

Distributing CFX Tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407

About This Book

Developing ColdFusion Applications describes the process of developing Web applications using ColdFusion. In the first eight chapters, you can follow the instructions presented to learn how to create basic ColdFusion applications. Then, chapters nine through 19 cover various topics of interest in enhancing your applications. Finally, chapters 20 through 23 explain how to extend ColdFusion’s capabilities.

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

Contents

• Intended Audi ence...................................................................................................xvi

• New Features ............................................................................................................ xvi

• Developer Resources...............................................................................................xvii

• About ColdFusion Documentation......................................................................xviii

• Getting Answers .........................................................................................................xx

• Contacting Macromedia............................................................................................x x

xvi About This Book

Intended Audience

Developing ColdFusion Applications is intended for Web application programmers who are learning ColdFusion orwish to extended their ColdFusion programming knowledge. It provides a solid grouding in the tools that ColdFusion provides to develop Web applications. The initial chapters provide e instructions for creating a basic ColdFusion application and are intended for those who are new to ColdFusion. Later chapters cover more specific features in greater detail and are intended for both new ColdFusion programmers and for those who are looking to extend existing skill.

New Features

The following table lists the new features in ColdFusion 5:

Benefit Feature Description

Breakthrough productivity

Powerful business intelligence capabilities

User-defined functions Create reusable functions to

accelerate development.

Query of queries

Easily integrate data from heterogeneous sour ce s by merging and querying data in memory using standard SQL.

Server analysis and troublshooting

Quickly detect and diagnose server errors with built-in server reporting and the new Log File Analyzer.

Charting engine

Create professional-quality charts and graphs from queried data without leaving the ColdFusion environment.

Enhanced V erity K2 fu ll-text search

Index and search up to 250,000 documents and enjoy greater performance.

Reporting interface for Crystal Reports 8.0

Create professional-quality tabular reports from queried data and applications.

Developer Resources xvii

Benefit Feature Description

Enhanced performance

Core engine tuning

Take advantage of dramatically improved server performance and reduced memory usage to deliver faster, more scalable applications.

Incremental page delivery

Improve response time by delivering page output to users as it is built.

Easy managment

Wire protocol database drivers

Application deployment services

Deliver high-performance ODBC connectivity using new drivers.

Effortlessly and reliably deploy, archive, or restore entire applications using ColdFusion archive files.

Enhanced application monitoring

Keep track of server performance and availability with customizable alerts and recovery.

SNMP support

Monitor ColdFusion applicatio ns from enterprise management systems.

Expanded integration

Expanded Linux support

Deploy on additional Linux distributions, including SuSE and Cobalt.

Enhanced hardware load balancer integration

Apply optimized, agent-based support for hardware load balancers, including new support for the Cisco CSS 11000.

Enhanced COM support

Experience easier integration with COM components.

Developer Resources

Macromedia, Inc. is committed to setting the standard for customer support in developer education, technical support, and professional services. The Web site is

xviii About This Book

designed to give you quick access to the entire range of online resources, as the following table describes.

Resource Description URL

Macromedia W eb site

Information on ColdFusion

Technical Support

ColdFusion Support Forum

Installation Support

Professional Education

Developer Community

ColdFusion Dev Center

Macromedia Alliance

General inf ormation about Macrom edia products and services

Detailed product information on ColdFusion and related topics

Professional support programs that Macromedia offers .

Access to experienced ColdFusion developers through participation in the Online Forums, where you can post messages and read replies on many subjects relating to ColdFusion.

Support for installation-related issues for all Macromedia produc t s

Information about classes, on-s ite training, and online courses offered by Macromedia

All the resources that you need to stay on the cutting edge of ColdFusion development, including online discussion groups, Knowledge Base, technical papers and more

Development tips, articles, documentation, and white papers

Connection with the growing network of solution providers, appli ca tio n developers, resellers, and hosting services creating solutions with ColdFusion

www.macromedia.com/

www.coldfusion.com/products/coldfusion/

www.coldfusion.com/support/

http://forums.coldfusion.com/spectraconf/

www.coldfusion.com/support/installation/

www.coldfusion.com/developer/training.cfm

www.coldfusion.com/developer/

www.coldfusion.com/developer/ coldfusionreferencedesk/

www.coldfusion.com/partners/

About ColdFusion Documentation

ColdFusion documentation is designed to provide support for the comp lete spectrum of participant s . T he p rint a nd onl ine v e rsions are organized to allow y ou to quickly locate the information that you need. The C oldF usion online documentation is provided in HTML and Adobe Acrobat formats.

About ColdFusion Documentation xix

Printed and online documentation set

The ColdFusion documentation set consists of the following titles.

Book Description

Installing and Configuring ColdFusion Server

Advanced ColdFusion Server Administration

Developing ColdFusion Applications

CFML Reference The online-only ColdFusion Reference provides descriptions,

CFML Quick Reference

Using ColdFusion Studio

Describes system installation and basic configuration for Windows NT, Windows 2000, Solaris, Linux, and HP-UX

Describes how to connect your data sources to the ColdFusion Server, configure security for your applications, and how to use ClusterCATS to manage scalability, clustering, and load-bal ancing for your site

Describes on how to develop your dynamic Web applications, including retrievi ng and u pdating y our dat a, usin g structu res, an d forms.

syntax, usage, and code examples for all ColdFusion tags, functions, and variables.

A brief guide that shows the syntax of ColdFusion tags, functions, and variables

Describes how to use ColdFusion Studio to build, test, and deploy Web content, including using the built-in editor for a variety of scripting and markup languages

Viewing online documentation

All ColdFusion documentation is available online in HTML and Adobe Acrobat PDF formats. To view the HTML documentation, open the following URL on the We b server running ColdFusion: http://localhost/coldfusio n/docs/dochome.htm.

To view and print ColdFusion documentation in Acrobat format, open the following URL on the Web server running ColdFusion: http://localhost/coldfusion/docs/ AcrobatDocs/index.htm.

Printing ColdFusion documentation

T o r ead printe d documentation, locate the Ado be Acroba t PDF files installe d with the product. The PDF files offer excellent print output. You can print an entire book or individual sections.

Locate the ColdFusion PDF files by opening the following URL on the host system: http://localhost/coldfusion/docs/AcrobatDocs/index.htm

xx About This Book

Getting Answers

One of the best ways to solve particular programming problems is to tap into the vast expertise of the ColdFusion developer communities on the ColdFusion Forums. Other devel opers on th e forum can help y ou f igur e out ho w to do jus t abo ut a nythin g with ColdFusion. The search facility can also help you search messages from the previous 12 months, allowing you to learn how others have solved a problem that you might be facing. The Fo rums is a gr e at r es our ce for learning C oldF u sion, bu t it is also a great place to see the ColdFusion developer community in action.

Contacting Macromedia

Corporate headquarters

Technical support

Sales

Macromedia, Inc. 600 Townsend street San Francisco, CA 4103

Tel: 415.252.2000 Fax: 415.626.0554

Web: www.macromedia.com

Macromedia offers a range of telephone and Web-based support options. Go to http://www.coldfusion.com/ support/ for a complete description of technical support services.

You can make postings to the ColdFusion Support Forum (http://forums.coldfusion.com/DevConf/index.cfm) at any time.

Toll Free: 888.939.2545 Tel: 617.219.2100

Fax: 617.219.2101 E-mail: sales@macromedia.com Web: http://commerce.coldfusion.com/purchase/

index.cfm

Chapter 1

Introduction to ColdFu sion

This chapter explains the difference between creating static Web pages with HTML and creating dynamic applications with ColdFusion. It also describes what ColdFusion is and how it works.

Contents

• A Quick Web Overview................................................................................................2

• Before You Begin .........................................................................................................3

• What is ColdFusion?............................... ...... ....... ...... ....... ...........................................4

• ColdFusion Features and Components.....................................................................5

• How ColdFusion Server Works................................................................................... 8

2 Chapter 1 Introduction to ColdFusion

A Quick Web Overview

Over the last few years, the Web changed from being simply a collection of static HTML pages to an application development platform. Rather than offering a space where organizations can merely advertise goods and services, similar to traditional yellow pages directories, companies conduct business ranging from e-commerce to managing internal business processes. For example, a static HTML page allows a bookstore to publish its location, list services such as the ability to place special orders, and advertise upcoming events like book signings. A dynamic site for the same bookstore allows customers to order books online, write reviews of books they read, and even get suggestions for purchasing books based on their reading preferences.

ColdFusion is a rapid application development environment that lets you build dynamic sites. You can use the W e b to h andle bu sin ess tr ans actions and con duct the day-t o - da y bu siness of your organiza t i on.

Before You Begin 3

Before You Begin

Before you begin using ColdFusion to create your Web applications, you should be familiar with HTML, relational database design and management, and Structured Query Language (SQL).

HTML

You will find that ColdFusion tags (CFML) are similar in syntax to HTML tags, yet, unlike HTML, they enable you to crea te dy namic Web pages. You should understand how to create a basic HTML page, put information into tables, gather data in forms, and create links.

Relational database design and management

If you plan on creating applications that use data from existing data sources, you should understand how the data is organized. In most cases, this means understanding how tables are organized to prevent unnecessary duplication of data. For example, if you have data about employees, rather than repeating the department number and name in each employee’s record, you most likely have a separate table that lists each department number and name just once.

SQL

Familiarity with some SQL is helpful as you develop y our C oldFu sion application s . In particular, you should be able to use the SELECT, UPDATE , INSERT, and DELETE statements, as well as WHERE clauses and Boolean logic operators.

4 Chapter 1 Introduction to ColdFusion

What is ColdFusion?

ColdFusion lets you create page-based Web applications using ColdFusion Markup Language (CFML), the tag-based language you use to create server-side scripts that dynamically control data integration; application logic; and user interface generation. ColdFusion Web applications can contain XML, HTML, and other client technologies such as CSS and JavaScript.

ColdFusion application pages are different from static HTML pages in the following ways:

• They are saved and referenced with a specifi c file extension.

• The default ColdFusion file extension is cfm.

• They contain ColdFusion Markup Language.

Editions of ColdFusion

There are two editions of ColdFusion: Enterprise and Professional. Using ColdFusion Enterprise or Professional Edition and ColdFusion Studio, you can build Web applications that leverage existing technologies and busines s sy stems such as RDBMS, messaging se rvers, file r epo sitories, d irect ory servers, and d istributed ob ject middleware. ColdFusion Enterprise also offers advanced security features, load balancing, server failover, and visual cluster administration.

ColdFusion Feature s and Comp one nts 5

ColdFusion Features and Components

ColdFusion provides a comprehensive set of features and components for developing and managing your Web applications. Usin g th e ColdFusion components, you can enhance the speed and ease of development, dynamically deploy your applications, integrate new and legacy technologies, and build secure applications.

About the features

The following table des cribes the C oldfF usion featur es that let you manage y our Web site:

Benefits Features

Rapid development

Scalable deployment

• A tag-based server scripting language that is powerful and intuitive

• Two-way visual programming and database tools

• Remote interactive debugging for quickly identifying and fixing

problems

• Web application wizards to automate common development tasks

• Source control integration to enable team development

• Secure file and database access using HTTP for remote

development

• A tag-based component architecture for flexible code reuse

• A multithreaded service architecture that scales across

processors

• Database connection pooling to optimize database performance

• Just-in-time page compilation and caching to accelerate page

request processing

• Dynamic load balancing for scalable performance in a cluster environment (Enterprise Editi on only)

• Automatic server recovery and failover for high availability (Enterprise Edition only)

6 Chapter 1 Introduction to ColdFusion

Benefits Features

Open integration • Database connectiv ity us in g na tiv e d atabase drivers (Enterprise

Edition only), ODBC, or OLE DB

• Embedded support for full-text indexing and searching

• Standards-based in tegration with directory, mail, HTTP, FTP, and

file servers

• Connectivity to distributed object technologies, including CORBA (Enterprise Edition only), COM (Windows Enterprise Edition only), Java objects and EJBs

• Open extensibility with C/C++ and Java

Security • Integration with existing authentication systems, including

Windows NT domain and LDAP directory servers, and proprietary user and group databases

• Advanced access control so that server administrators can control developers’ access to files and data sources

• Support for existing database security

• Server sandbox security for protecting multi ple ap plicat ions on a

single server (Enterprise Edition only)

• Support for existing Web server authentication, security, and encryption

For detailed information about security, see Advanced ColdFusion Administration. For the latest publications from Macromedia on security, visit the Security Zone at

http://www.coldfusion.com/developer/securityzone/. For a complete feature list and more detailed information, see the ColdFusion

product pages at http://www.coldfusion.com/coldfusion.

About the components

ColdFusion applications rely on several core components:

• ColdFusion application pages

• ColdFusion Server

• ColdFusion Administrator

• ODBC data sources and other data source s

In addition to the core components, as you become more familiar with ColdFusion and build more complex applications, you can use ColdFusion Extensions to extend its capabilities.

ColdFusion application pages

ColdFusion application pages (often called templates) look somewhat like HTML pages, but are much more dynamic and powerful. They are the functional parts of a ColdFusion application, including the user interface pages and forms that handle

ColdFusion Feature s and Comp one nts 7

data input and format data output. They can contain ColdFusion (CFML) tags, HTML tags, CFScript, JavaScript, and anything else that you can normally embed in an ordinary HTML page. You can easily access data sources, such as relational databases, from your application pages. The default file extension used for ColdFusion application pages is cfm.

CFML

CFML is a tag-based server scripting language that encapsulates complex processes, such as connecting to databases and LDAP servers, and sending e-mail. The core of the ColdFusion deve lopment platf orm language is mor e tha n 70 server- side tags and more than 200 functions.

ColdFusion Server

ColdFusion Server listens for requests from the Web server to process ColdFusion application pages. It runs as a service under Windows NT and as a process under UNIX.

For information on installing and configuring ColdFusion Server, see Installing and Configuring ColdFusion Server.

ColdFusion Administrator

Data sources

Y o u use the Adm inistr ato r to configure various ColdFusion Server options , inclu ding:

• ColdFusion data sources

• Debugging output

• Server settings

• Application security

• Server clustering

• Scheduling page ex ecu t ion

• Directory mapping

For details on using the Administrator, see Advanced ColdFusion Administration.

ColdFusion applications can interact with any database that supports the ODBC standard. However, ColdFusion is not limited to ODBC data sources. You can also retrieve data us ing OLE-DB, native da tabase drivers , or dir ectory servers that su pport the Lightweight Directory Access Protocol (LDAP). You can also retrieve data from mail servers that support the Post Office Protocol (POP), and index the data in Verity collections.

8 Chapter 1 Introduction to ColdFusion

How ColdFusion Server Works

Regardless of which ColdFusion Server you have installed, ColdFusion application pages are processed on the server at runtime, each time they are requested by a browser.

A page request happens when you click a Web site link to open a Web page in your browser. When you request a ColdFusion application page, ColdFusion Server processes the request, retrieves any data if necessary, and routes the data through the Web server, back to your browser.

The following steps describe in more detail what happens when you open a ColdFusion page:

1 The client requests a page that contains CFML tags. 2 The Web server passes files to ColdFusion Server if a page request contains a

ColdFusion file extension. 3 ColdFusion Server scans the page and proce sses all CFML tags. 4 ColdFusion Server then returns only HTML and other client-side technologies to

the W e b server. 5 The Web server passes the page back to the browser.

Chapter 2

Writing Your First Co ldFusion Application

This chapter guides you through the ColdFusion development process as you create a ColdFusion application page, save it, and view it in a browser.

Contents

• The Development Process........................................................................................10

• Working with ColdFusion Application Pa ges.......................................................... 10

• Wor king with Variables............................................. ....... ....... ...... ....... ...... ............... 13

• Development Considerations ..................................................................................16

10 Chapter 2 Writing Your First ColdFusion Application

The Development Process

Whether you are creating a static HTML page or a ColdFusion application page, you follow the same iterative process:

1Write some code. 2 Save the code to a document or page. 3 View the page in a browser. 4 Modify the page. 5 Save the page again. 6 View it in a browser.

Working with ColdFusion Application Pages

While you can code your application pages using NotePad or any HTML editor, this book uses ColdFusion Studio because it provides many features that make ColdFusion development easier. You should install ColdFusion Studio if you have not done so already.

About applicaton pages

From a coding perspective, the major difference between a static HTML page and a ColdFusion application page is that ColdFusion pages contain ColdFusion Markup Language (CFML). CFML is a markup language that is very similar in syntax to HTML, so Web developers find it intuitive. Unlike HTML, which defines how things are displayed and formatted on the client, CFML identifies specific operations that are performed by ColdFusion Server.

Creating application pages

The following procedure creates a simple ColdFusion Application page, which you use for other examples in this chapter.

To create a ColdFusion application page:

1Open ColdFusion Studio. 2Select File > New and select the Default Template for your new page. 3 Edit the file so that it appears as follows:

<html>

<head>

<title>Call Department</title>

</head>

<body>

<strong>Call Department</strong><br>

+ 408 hidden pages