MACROMEDIA ColdFusion Server 5 Develop Manual

Macromedia® Incorporated

Developing

ColdFusion

Applications

MacroMedia ColdFusion

®

5

Copyright Notice

This book, as well as the software described in it, is furnished under license and may

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 construed as a commitment by Macromedia, Incorporated.

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

Contents

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Developing Web Applications with ColdFusionDRAFT 5/9/01 Path/Filename/Author

v

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

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

Developing Web Applications with ColdFusionDRAFT 5/9/01 Path/Filename/Author

vii

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

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

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

Building Tree Controls with cftree. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

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

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

Developing Web Applications with ColdFusionDRAFT 5/9/01 Path/Filename/Author

ix

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 environment . . . . . . . . . . . . . . . . . . . 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

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

Developing Web Applications with ColdFusionDRAFT 5/9/01 Path/Filename/Author

xi

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 Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

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

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 Advanced 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

Developing Web Applications with ColdFusionDRAFT 5/9/01 Path/Filename/Author

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

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 Audience................................................................................................... xvi

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

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

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

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

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

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

User-defined functions Create reusable functions to

accelerate development.

Query of queries

Easily integrate data from

heterogeneous sources 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.

Powerful

business

intelligence

capabilities

Charting engine

Create professional-quality charts

and graphs from queried data

without leaving the ColdFusion

environment.

Enhanced Verity K2 full-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

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

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.

Wire protocol database

drivers

Deliver high-performance ODBC

connectivity using new drivers.

Easy

managment

Application deployment

services

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 applications

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.

Benefit Feature Description

xviii About This Book

designed to give you quick access to the entire range of online resources, as the

following table describes.

About ColdFusion Documentation

ColdFusion documentation is designed to provide support for the complete

spectrum of participants. The print and online versions are organized to allow you to

quickly locate the information that you need. The ColdFusion online documentation

is provided in HTML and Adobe Acrobat formats.

Resource Description URL

Macromedia Web

site

General information about Macromedia

products and services

www.macromedia.com/

Information on

ColdFusion

Detailed product information on

ColdFusion and related topics

www.coldfusion.com/products/coldfusion/

Technical

Support

Professional support programs that

Macromedia offers.

www.coldfusion.com/support/

ColdFusion

Support Forum

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.

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

Installation

Support

Support for installation-related issues

for all Macromedia products

www.coldfusion.com/support/installation/

Professional

Education

Information about classes, on-site

training, and online courses offered by

Macromedia

www.coldfusion.com/developer/training.cfm

Developer

Community

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

www.coldfusion.com/developer/

ColdFusion Dev

Center

Development tips, articles,

documentation, and white papers

www.coldfusion.com/developer/

coldfusionreferencedesk/

Macromedia

Alliance

Connection with the growing network of

solution providers, application

developers, resellers, and hosting

services creating solutions with

ColdFusion

www.coldfusion.com/partners/

About ColdFusion Documentation xix

Printed and online documentation set

The ColdFusion documentation set consists of the following titles.

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 Web

server running ColdFusion: http://localhost/coldfusion/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

To read printed documentation, locate the Adobe Acrobat PDF files installed 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

Book Description

Installing and

Configuring

ColdFusion Server

Describes system installation and basic configuration for

Windows NT, Windows 2000, Solaris, Linux, and HP-UX

Advanced

ColdFusion Server

Administration

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-balancing for your site

Developing

ColdFusion

Applications

Describes on how to develop your dynamic Web applications,

including retrieving and updating your data, using structures, and

forms.

CFML Reference The online-only ColdFusion Reference provides descriptions,

syntax, usage, and code examples for all ColdFusion tags,

functions, and variables.

CFML Quick

Reference

A brief guide that shows the syntax of ColdFusion tags,

functions, and variables

Using ColdFusion

Studio

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

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 developers on the forum can help you figure out how to do just about anything

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 Forums is a great resource for learning ColdFusion, but it is

also a great place to see the ColdFusion developer community in action.

Contacting Macromedia

Corporate

headquarters

Macromedia, Inc.

600 Townsend street

San Francisco, CA 4103

Tel: 415.252.2000

Fax: 415.626.0554

Web: www.macromedia.com

Technical

support

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.

Sales

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

Page is loading ...

MACROMEDIA ColdFusion Server 5 Develop Manual

This manual is also suitable for

MACROMEDIA ColdFusion Server 5 Develop Manual

Related papers

Other documents