Macromedia COLDFUSION 4.5-DEVELOPING WEB APPLICATIONS User Manual

Developing Web

Applications with ColdFusion

ColdFusion 4.5

Allaire Corporation

This manual, 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 Allaire Corporation. Allaire Corporation 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 Allaire Corporation.

ColdFusion and HomeSite are federally registered trademarks of Allaire Corporation. HomeSite, the ColdFusion logo and the Allaire logo are trademarks of Allaire Corporation in the USA and other countries. Microsoft, Windows, Windows NT, Windows 95, Microsoft Access, and FoxPro are registered trademarks of Microsoft Corporation. All other products or name brands are the trademarks of their respective holders. Solaris is a trademark of Sun Microsystems Inc. UNIX is a trademark of The Open Group. PostScript is a trademark of Adobe Systems Inc.

Part number: AA-45WEB-RK

Contents

Preface: Welcome to ColdFusion ..................................................................xv

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

Welcome to the ColdFusion 4.5 Web Application Server...........................................................xvi

Products and System Requirements ...........................................................................................xvii

New features in ColdFusion 4.5 ................................................................................................. xviii

New visual tools................................................................................................................... xviii

Enhancements to CFML ........................................................................................................xix

Better reliability ......................................................................................................................xix

Improved performance..........................................................................................................xix

Enterprise connectivity features ............................................................................................xx

Security enhancements...........................................................................................................xx

Developer Resources .....................................................................................................................xxi

About ColdFusion Documentation.............................................................................................xxii

Documentation updates.......................................................................................................xxii

ColdFusion manuals .............................................................................................................xxii

ColdFusion Server online documentation........................................................................ xxiii

Printing ColdFusion documentation................................................................................. xxiii

Documentation conventions...............................................................................................xxiv

Getting Answers ...........................................................................................................................xxiv

Contacting Allaire.................................................................................................................xxiv

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

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

What You Should Already Know..................................................................................................... 2

What is ColdFusion? ........................................................................................................................ 3

Editions of ColdFusion............................................................................................................. 3

ColdFusion Features........................................................................................................................ 3

Rapid development.................................................................................................................. 4

Scalable deployment................................................................................................................ 4

Open integration ...................................................................................................................... 4

Complete security..................................................................................................................... 5

ColdFusion Components ................................................................................................................ 5

ColdFusion Studio.................................................................................................................... 6

ColdFusion application pages................................................................................................. 6

iv Developing Web Applications with ColdFusion

ColdFusion Server.....................................................................................................................6

ColdFusion Administrator........................................................................................................6

Data sources ..............................................................................................................................7

How ColdFusion Server Works ........................................................................................................7

Chapter 2: Writing Your First ColdFusion Application..................................9

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

Writing Code ...................................................................................................................................10

Saving Application Pages ...............................................................................................................11

Viewing Application Pages.............................................................................................................11

Variables ..........................................................................................................................................13

Adding More Variables to the Application....................................................................................14

Development Considerations........................................................................................................14

Chapter 3: Querying a Database...................................................................15

Publishing Dynamic Data..............................................................................................................16

Database Basics...............................................................................................................................16

Understanding Data Sources.........................................................................................................18

Open Database Connectivity (ODBC) ...................................................................................18

Adding Data Sources ......................................................................................................................19

Data Source Notes and Considerations.................................................................................20

Retrieving Data................................................................................................................................20

The CFQUERY Tag ..................................................................................................................20

Writing SQL .....................................................................................................................................21

Basic SQL Syntax elements.....................................................................................................22

SQL Notes and Considerations..............................................................................................23

Building Queries .............................................................................................................................24

Query Notes and Considerations...........................................................................................25

Outputting Query Data...................................................................................................................25

Query Output Notes and Considerations..............................................................................26

Getting Information About Query Results....................................................................................27

Query Properties Notes and Considerations ........................................................................28

Chapter 4: Retrieving and Formatting the Data You Want.........................29

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

FORM tag syntax......................................................................................................................30

Form Controls..........................................................................................................................30

Form Notes and Considerations............................................................................................34

Processing Form Variables on Action Pages.................................................................................34

Dynamically Generating SQL Statements ....................................................................................34

Creating Action Pages.....................................................................................................................35

Form Variable Notes and Considerations.............................................................................36

Using HTML Tables to Layout Query Results...............................................................................37

Formatting Individual Data Items.................................................................................................38

Performing Pattern Matching........................................................................................................39

Filtering Data Based on Multiple Conditions...............................................................................39

Contents v

Creating Table Joins........................................................................................................................40

Building Flexible Search Interfaces...............................................................................................40

Code Review ............................................................................................................................41

Returning Query Results to the User.............................................................................................42

Chapter 5: Making Variables Dynamic .........................................................45

Dynamically Populating Select Boxes...........................................................................................46

Creating Dynamic Checkboxes and Multiple Select Boxes.........................................................47

Checkboxes..............................................................................................................................47

Multiple select lists..................................................................................................................49

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

Creating Default Variables with CFPARAM ..................................................................................51

Checking Query Parameters with CFQUERYPARAM ..................................................................52

Dynamic SQL...................................................................................................................................53

Chapter 6: Updating Your Data.....................................................................59

Inserting Data..................................................................................................................................60

Creating an HTML Insert Form .....................................................................................................60

Data Entry Form Notes and Considerations.........................................................................61

Creating an Action Page to Insert Data.........................................................................................61

Updating Data.................................................................................................................................62

Creating an Update Form ..............................................................................................................63

Creating an Action Page to Update Data ......................................................................................65

Deleting Data ..................................................................................................................................66

Requiring Users to Enter Values in Form Fields...........................................................................67

Validating the Data That Users Enter in Form Fields ..................................................................68

Chapter 7: Reusing Code ...............................................................................71

Ways to Reuse Code........................................................................................................................72

Reusing Common Code with CFINCLUDE ..................................................................................72

About Custom Tags in CFML.........................................................................................................73

Using Existing Custom Tags...........................................................................................................73

Writing Custom CFML Tags...........................................................................................................73

Passing Attribute Values between Custom Tags ..........................................................................74

Nesting Custom Tags......................................................................................................................77

Passing Data Between Nested Custom Tags ................................................................................78

What data is accessible?..........................................................................................................78

Where is data accessible?........................................................................................................78

High-level data exchange .......................................................................................................78

Passing Custom Tag Arguments via CFML Structures.........................................................81

Executing Custom Tags..................................................................................................................82

Tag instance data.....................................................................................................................82

Pattern of execution................................................................................................................83

Modes of execution.................................................................................................................83

Specifying execution modes...................................................................................................83

Terminating tag execution .....................................................................................................84

vi Developing Web Applications with ColdFusion

Access to generated content...................................................................................................84

Installing Custom Tags...................................................................................................................85

Local tags..................................................................................................................................85

Shared tags...............................................................................................................................85

Managing Custom Tags..................................................................................................................85

Resolving file name conflicts..................................................................................................85

Securing Custom Tags ............................................................................................................86

Encoding Custom Tags...........................................................................................................86

Chapter 8: Debugging and Error Handling ..................................................89

Debug Settings in the ColdFusion Administrator........................................................................90

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

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

Error messages.........................................................................................................................90

CFML Code Validation ...................................................................................................................91

Troubleshooting Common Problems ...........................................................................................91

ODBC data source configuration...........................................................................................91

HTTP/URL ...............................................................................................................................92

CFML syntax errors .................................................................................................................92

Generating Custom Error Messages (CFERROR) ........................................................................93

Creating an error application page........................................................................................93

Overview of Exception Handling in ColdFusion..........................................................................94

Types of recoverable exceptions supported .........................................................................95

Exception Information in CFCATCH ............................................................................................97

Tag context information.........................................................................................................98

Database exceptions...............................................................................................................99

Expression exceptions ............................................................................................................99

Locking exceptions..................................................................................................................99

MissingInclude exceptions...................................................................................................100

Exception handling strategies......................................................................................................100

Exception handling example .......................................................................................................100

Custom Exception Types..............................................................................................................102

Chapter 9: Handling Complex Data

with Structures..............................................................................................103

About Arrays..................................................................................................................................104

Creating an Array ..........................................................................................................................105

Multidimensional Arrays......................................................................................................106

Basic Array Techniques................................................................................................................106

Adding elements to an array.................................................................................................107

Referencing Elements in Dynamic Arrays ..................................................................................107

Additional referencing methods..........................................................................................108

Populating Arrays with Data........................................................................................................108

Populating an array with ArraySet.......................................................................................108

Populating an array with CFLOOP.......................................................................................108

Using Nested Loops for 2D and 3D Arrays..........................................................................109

Populating an Array from a Query...............................................................................................110

Contents vii

Array Functions.............................................................................................................................111

About Structures...........................................................................................................................113

Structure notation.................................................................................................................113

Creating and Using Structures.....................................................................................................114

Creating structures................................................................................................................114

Adding data to structures .....................................................................................................114

Finding information in structures .......................................................................................115

Getting information about structures .................................................................................115

Copying structures................................................................................................................116

Deleting structures................................................................................................................116

Structure Example ........................................................................................................................117

Using Structures as Associative Arrays .......................................................................................119

Looping through structures..................................................................................................119

Structure Functions......................................................................................................................120

Chapter 10: Building Dynamic Forms.........................................................123

Creating Forms with the CFFORM Tag.......................................................................................124

Using HTML in a CFFORM...................................................................................................124

CFFORM controls..................................................................................................................124

Improving performance with ENABLECAB........................................................................125

Browsers that disable Java....................................................................................................125

Input Validation with CFFORM Controls ...................................................................................126

Input Validation with JavaScript .................................................................................................127

JavaScript objects passed to the validation routine ...........................................................127

Handling failed validation....................................................................................................127

Building Tree Controls with CFTREE..........................................................................................129

Grouping output from a query.............................................................................................130

CFTREE form variables.........................................................................................................131

Input validation.....................................................................................................................132

Structuring Tree Controls.............................................................................................................132

Image names in a CFTREE....................................................................................................133

Embedding URLs in a CFTREE....................................................................................................134

Specifying which tree items to send to the action page.....................................................135

Creating Data Grids with CFGRID...............................................................................................135

Populating a grid from a query.............................................................................................136

Creating an Updateable Grid.......................................................................................................137

Editing data in a CFGRID......................................................................................................138

Building Slider Bar Controls.........................................................................................................142

CFSLIDER form variable.......................................................................................................142

Building Text Entry Boxes............................................................................................................142

CFTEXTINPUT form variable...............................................................................................143

Building Drop-Down List Boxes ..................................................................................................143

Embedding Java Applets ..............................................................................................................144

Registering a Java applet.......................................................................................................145

Using CFAPPLET to embed an applet .................................................................................146

Handling form variables from an applet.............................................................................147

viii Developing Web Applications with ColdFusion

Chapter 11: Indexing and Searching Data .................................................149

Searching a ColdFusion Web Site................................................................................................150

Advantages of using Verity ...................................................................................................150

Online Verity training ...........................................................................................................151

Supported File Types....................................................................................................................151

Support for International Languages..........................................................................................152

Steps in Creating a Searchable Data Source...............................................................................153

Creating a Collection....................................................................................................................153

Using the ColdFusion Administrator to create a collection ..............................................154

Creating a collection with the CFCOLLECTION tag...........................................................154

Populating and Indexing a Collection.........................................................................................157

Selecting an indexing method..............................................................................................157

Building a Search Interface..........................................................................................................159

Using the Verity wizard in Studio ........................................................................................159

Basic search operations ........................................................................................................160

Summarization......................................................................................................................161

CFSEARCH properties...........................................................................................................162

Indexing database query results..................................................................................................162

Indexing CFLDAP Query Results.................................................................................................163

Indexing CFPOP Query Results ...................................................................................................164

Using Query Expressions .............................................................................................................165

Simple query expressions.....................................................................................................166

Explicit query expressions....................................................................................................166

Expression syntax..................................................................................................................166

Special characters..................................................................................................................168

Composing Search Expressions...................................................................................................168

Searching with Wildcards.............................................................................................................170

Searching for wildcards as literals........................................................................................170

Searching for special characters as literals..........................................................................170

Operators and Modifiers..............................................................................................................171

Operators ...............................................................................................................................171

Modifiers................................................................................................................................178

Managing Collections...................................................................................................................180

Maintenance options............................................................................................................180

Securing a collection.............................................................................................................181

Chapter 12: Using the Application Framework .........................................183

Understanding the Web Application Framework......................................................................184

Application-level settings and functions in Application.cfm............................................184

Client state management......................................................................................................184

Custom error handling .........................................................................................................185

Web server security integration ...........................................................................................185

Mapping Out an Application Framework...................................................................................185

Behavior with CFINCLUDE..................................................................................................187

Creating the Application.cfm File................................................................................................187

Naming the application........................................................................................................188

Setting up client state management options..............................................................................188

Contents ix

Choosing a client variable storage method.........................................................................189

Managing Client State in a Clustered Environment ..................................................................190

Using Client State Management..................................................................................................190

Creating a client variable......................................................................................................191

Using Client Variables ..................................................................................................................191

Standard client variables ......................................................................................................191

Using client state management without cookies................................................................191

Getting a list of client variables............................................................................................192

Deleting client variables .......................................................................................................192

Exporting the client variable database................................................................................193

Application and Session Variables ..............................................................................................193

Enabling application and session variables........................................................................193

Differentiating client, session, and application variables..................................................194

Using Session Variables................................................................................................................194

What is a session?..................................................................................................................194

Storing session data in session variables.............................................................................195

Using Application Variables.........................................................................................................196

Storing application data in application variables...............................................................196

Application variable time-outs.............................................................................................196

Tips for Using Session and Application Variables......................................................................197

Getting a list of application and session variables..............................................................197

Default Variables and Constants.................................................................................................197

Using CFLOCK for Exclusive Locking .........................................................................................198

Using CFLOCK.......................................................................................................................199

Avoiding deadlocks ...............................................................................................................199

CFLOCK Examples........................................................................................................................200

Chapter 13: Sending and Receiving Email .................................................205

Using ColdFusion with Mail Servers ...........................................................................................206

Sending Email Messages..............................................................................................................206

Sending SMTP mail with CFMAIL........................................................................................207

Samples uses of CFMAIL..............................................................................................................207

Sending form-based email ...................................................................................................208

Sending query-based email..................................................................................................208

Sending email to multiple recipients...................................................................................209

Customizing Email for Multiple Recipients................................................................................209

Attaching a MIME file ...........................................................................................................210

Advanced Sending Options..........................................................................................................211

Sending mail as HTML..........................................................................................................211

Error logging and undelivered messages ............................................................................211

Receiving Email Messages............................................................................................................211

Using CFPOP .........................................................................................................................212

CFPOP query variables .........................................................................................................212

Handling POP Mail .......................................................................................................................213

Returning only message headers.........................................................................................213

Returning an entire message................................................................................................214

Returning attachments with messages................................................................................215

Deleting messages.................................................................................................................216

x Developing Web Applications with ColdFusion

Chapter 14: Managing Files on the Server .................................................219

Using CFFILE ................................................................................................................................220

Uploading Files .............................................................................................................................220

Resolving conflicting file names ..........................................................................................222

Controlling the type of file uploaded...................................................................................222

Setting File and Directory Attributes...........................................................................................223

UNIX.......................................................................................................................................223

Windows.................................................................................................................................224

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

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

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

Reading a text file ..................................................................................................................227

Writing a text file ...................................................................................................................227

Performing Directory Operations................................................................................................229

Returning file information....................................................................................................229

Chapter 15: Interacting with Remote Servers............................................231

Using CFHTTP to Interact with the Web ....................................................................................232

Allaire Alive ............................................................................................................................232

Using the CFHTTP Get Method...................................................................................................232

Creating a Query from a Text File................................................................................................234

Using the CFHTTP Post Method .................................................................................................236

Using Secure Sockets Layer (SSL) with CFHTTP........................................................................238

Performing File Operations with CFFTP.....................................................................................239

Caching connections across multiple pages.......................................................................240

Connection caching actions and attributes........................................................................241

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

An Overview of Distributed Data for the Web............................................................................242

WDDX Components.....................................................................................................................242

Working With Application-Level Data ........................................................................................243

Data Exchange Across Application Servers ................................................................................243

Time zone processing...........................................................................................................243

How WDDX Works........................................................................................................................244

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

Transferring Data From Browser to Server.................................................................................246

Chapter 16: Connecting to LDAP Directories.............................................249

What is LDAP? ...............................................................................................................................250

LDAP attributes .....................................................................................................................251

Key Terms ..............................................................................................................................251

ColdFusion Support for LDAP.....................................................................................................252

Working with LDAP Directories...................................................................................................253

Viewing the Directory Schema ....................................................................................................253

Querying an LDAP Directory .......................................................................................................254

Updating an LDAP Directory.......................................................................................................256

Creating searchable CFLDAP output...................................................................................261

Contents xi

Chapter 17: Application Security................................................................263

ColdFusion Security Features......................................................................................................264

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

Overview of User Security............................................................................................................265

Using Advanced Security in Application Pages..........................................................................265

Using the CFAUTHENTICATE tag...............................................................................................266

Authentication and Authorization Functions ............................................................................267

Using the IsAuthenticated Function....................................................................................267

Using the IsAuthorized Function.........................................................................................267

Catching Security Exceptions......................................................................................................268

Using the CFIMPERSONATE Tag................................................................................................269

Example of User Authentication and Authorization..................................................................270

Authenticating users in Application.cfm.............................................................................271

Checking for authentication and authorization .................................................................272

Chapter 18: Building Custom CFAPI Tags ..................................................275

What Are CFX Tags? ......................................................................................................................276

Before You Begin Developing CFX Tags in C++ .........................................................................276

Sample C++ CFXs ..................................................................................................................276

Setting Up Your C++ Development Environment..............................................................276

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

Compiling C++ CFXs ...............................................................................................................277

Debugging C++ CFXs....................................................................................................................277

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

Sample Java CFXs..................................................................................................................278

Setting Up Your Development Environment to Develop CFXs in Java ............................279

Writing a Java CFX ........................................................................................................................279

Processing Requests..............................................................................................................280

Java CFX Class Loading.........................................................................................................282

Automatic Class Reloading...................................................................................................283

Life cycle of Java CFXs...........................................................................................................283

Calling the CFX from a ColdFusion Template ....................................................................284

ZipBrowser Example.....................................................................................................................284

Approaches to Debugging Java CFXs..........................................................................................286

Outputting Debug Information............................................................................................286

Using the Debugging Classes...............................................................................................286

Debugging Classes Reference ..............................................................................................288

Java Customization and Configuration.......................................................................................289

Implementing C++ CFX Tags.......................................................................................................289

Implementing Java CFX Tags.......................................................................................................289

Registering CFXs ...........................................................................................................................289

Distribution ...........................................................................................................................291

C++ CFX Reference .......................................................................................................................293

CCFXException Class ...................................................................................................................294

Class members.......................................................................................................................294

CCFXException::GetError.....................................................................................................294

CCFXException::GetDiagnostics..........................................................................................294

xii Developing Web Applications with ColdFusion

CCFXQuery Class..........................................................................................................................295

Class members.......................................................................................................................295

CCFXQuery::AddRow............................................................................................................296

CCFXQuery::GetColumns.....................................................................................................296

CCFXQuery::GetData............................................................................................................297

CCFXQuery::GetName..........................................................................................................297

CCFXQuery::GetRowCount..................................................................................................297

CCFXQuery::SetData.............................................................................................................298

CCFXQuery::SetQueryString ................................................................................................299

CCFXQuery::SetTotalTime ...................................................................................................299

CCFXRequest Class.......................................................................................................................299

Class Members ......................................................................................................................299

CCFXRequest::AddQuery......................................................................................................300

CCFXRequest::AttributeExists..............................................................................................301

CCFXRequest::CreateStringSet ............................................................................................301

CCFXRequest::Debug............................................................................................................302

CCFXRequest::GetAttribute..................................................................................................302

CCFXRequest::GetAttributeList ...........................................................................................302

CCFXRequest::GetCustomData ...........................................................................................303

CCFXRequest::GetQuery.......................................................................................................303

CCFXRequest::GetSetting .....................................................................................................304

CCFXRequest::ReThrowException ......................................................................................304

CCFXRequest::SetCustomData............................................................................................305

CCFXRequest::SetVariable....................................................................................................306

CCFXRequest::ThrowException...........................................................................................306

CCFXRequest::Write..............................................................................................................307

CCFXRequest::WriteDebug ..................................................................................................307

CCFXStringSet Class.....................................................................................................................308

Class members.......................................................................................................................308

CCFXStringSet::AddString....................................................................................................308

CCFXStringSet::GetCount.....................................................................................................309

CCFXStringSet::GetIndexForString......................................................................................309

CCFXStringSet::GetString.....................................................................................................310

Java CFX Reference.......................................................................................................................311

Interface CustomTag....................................................................................................................311

Method Detail........................................................................................................................311

Interface Query .............................................................................................................................312

Method Detail........................................................................................................................312

Interface Request..........................................................................................................................316

Method Detail........................................................................................................................317

Interface Response .......................................................................................................................321

Method Detail........................................................................................................................321

Chapter 19: Using CFOBJECT to Invoke Component Objects...................325

Component Object Overview ......................................................................................................326

About COM ............................................................................................................................326

About CORBA.........................................................................................................................326

About Java Objects ................................................................................................................326

Contents xiii

Invoking Component Objects......................................................................................................327

Coding guidelines..................................................................................................................327

Calling methods ....................................................................................................................327

Calling nested objects...........................................................................................................328

Getting Started with COM/DCOM..............................................................................................328

Requirements for COM.........................................................................................................328

Registering the object ...........................................................................................................328

Finding the component ProgID and methods....................................................................329

Creating and Using COM Objects ...............................................................................................331

Connecting to COM objects.................................................................................................331

Setting properties and invoking methods...........................................................................332

Getting Started with CORBA........................................................................................................332

Calling a CORBA Object ...............................................................................................................333

Declaring structures and sequences....................................................................................333

Exception handling ...............................................................................................................334

Calling Java Objects ......................................................................................................................335

Calling EJBs............................................................................................................................335

Exception handling ...............................................................................................................335

Chapter 20: Extending ColdFusion Pages with CFML Scripting...............337

About CFScript..............................................................................................................................338

CFScript example ..................................................................................................................338

Supported statements...........................................................................................................338

The CFScript Language ................................................................................................................339

Statements .............................................................................................................................339

Expressions............................................................................................................................342

Variables.................................................................................................................................342

Comments..............................................................................................................................342

Differences from JavaScript..................................................................................................342

Reserved words......................................................................................................................343

Interaction of CFScript with CFML .............................................................................................343

Chapter 21: Accessing the Windows NT Registry ......................................345

Overview of Registry Access in ColdFusion................................................................................346

Getting Registry Values.................................................................................................................346

Setting Registry Values .................................................................................................................347

Deleting Registry Values...............................................................................................................348

Index ..............................................................................................................349

xiv Developing Web Applications with ColdFusion

Preface Welcome to ColdFusion

This manual describes the process of developing Web applications using ColdFusion. In the first six chapters, you can follow the instructions presented to learn how to create basic ColdFusion applications. Then, chapters seven through 17 cover various topics of interest in enhancing your applications. Finally, chapters 18

through 21 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 Language Reference for details about various tags and functions.

Contents

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

• Welcome to the ColdFusion 4.5 Web Application Server............................. xvi

• Products and System Requirements............................................................. xvii

• New Features in ColdFusion 4.5................................................................... xviii

• Developer Resources....................................................................................... xxi

• About ColdFusion Documentation .............................................................. xxii

• Getting Answers .............................................................................................xxiv

xvi Developing Web Applications with ColdFusion

Intended Audience

This manual is particularly useful for Web application developers who are new to ColdFusion. In particular, Chapters 1 through 6 provide instructions for creating a basic ColdFusion application. If you are somewhat familiar with ColdFusion, but want to learn more about a particular topic such as sending and receiving email, refer to

Chapters 7 through 17. Finally, if you want to extend ColdFusion’s capabilities with CFML scripting or creating custom tags, Chapters 18 through 21 will be helpful.

Welcome to the ColdFusion 4.5 Web Application Server

The ColdFusion 4.5 release focuses on fundamentals — the fundamentals of delivering your e-business: faster development, better reliability, enhanced scalability, expanded integration, and stronger security.

At the center of the ColdFusion 4.5 release is an application server platform that's been highly optimized with new functionality and native support for UNIX. As a result, your e-business systems will run better and do more. With this release we're launching a new edition of ColdFusion Server for Linux so you can take advantage of the reliability and performance of the hottest new Internet server operating system.

While optimizing the core server, we also enhanced fundamental features including email integration, server-side FTP and HTTP, advanced security, scheduling, and database connectivity — again giving you more reliability and new functionality.

The focus on fundamentals extends to new features. As part of a broad new commitment to Java, ColdFusion 4.5 has a range of new Java integration options from Java CFXs to Java Servlet support to Java object and EJB connectivity. In ColdFusion Studio 4.5, we added new tools to make you more productive including a flexible new project architecture that makes managing and deploying complex Web applications a snap. On the server, we focused on reliability, performance and security with features such as service-level fail-over, Cisco Local Director integration, and OS security integration.

Whether you're revolutionizing your company's HR operations, building the next generation of your firm's global intranet, or launching the next killer .COM company, you'll find the speed, scalability, connectivity, and security you need in ColdFusion 4.5.

Preface xvii

Products and System Requirements

ColdFusion has been fully tested on the following platforms and with the following configurations.

ColdFusion Server 4.5 Enterprise Edition for Windows

• Windows NT 4.0 SP4+

• Intel Pentium or above

• 150 MB hard disk space

• 128 MB RAM (256 MB recommended for clustering)

ColdFusion Server 4.5 Enterprise Edition for Solaris

• SPARC Solaris 2.5.1, 2.6, or 7 (patch 103582-1B or higher)

• 128 MB RAM (256 MB recommended for clustering)

• 200 MB hard disk space

ColdFusion Server 4.5 Enterprise Edition for Linux

• Red Hat Linux 6.0 or 6.1

• Intel Pentium or above

• 128 MB RAM (256 MB recommended for clustering)

• 150 MB hard disk space

ColdFusion Server 4.5 Professional Edition for Windows

• Windows 95/98 or Windows NT 4.0

• Intel Pentium or above

• 50 MB hard disk space

• 32 MB RAM (128 MB recommended)

ColdFusion Server 4.5 Professional Edition for Linux

• Red Hat Linux 6.0 or 6.1

• Intel Pentium or above

• 64 MB RAM (128 MB recommended)

• 100 MB hard disk space

xviii Developing Web Applications with ColdFusion

ColdFusion Studio 4.5

• Windows 95/98/NT4

• Intel Pentium or above

• 35 MB hard disk space

• 32 MB RAM (64 MB recommended)

New Features in ColdFusion 4.5

A wide range of new features are available in ColdFusion 4.5.

New visual tools

Universal File Browser — Access all your files from a single explorer that integrates access to the Windows file system, ColdFusion RDS servers, and FTP servers. Dragand-drop between any of these services all in an integrated file browser.

Advanced Project Management — Manage your complex Web application development projects with a new project architecture that gives you more flexibility and control using physical, virtual, and auto-inclusive project folders as well as project resource browsing.

Scriptable Deployment — Deploy applications to complex server configurations with FTP or ColdFusion Remote Development Services (RDS). Use VBScript or Java Script to fully script deployment of projects with granular control over how files uploaded. Setup deployment scripts using a powerful wizard and save scripts for re-use.

Collapsible Code — Work with large, complex scripts and pages more easily by collapsing sections of the code in the editor so you can build sophisticated applications more quickly.

Function Insight — Find the parameters and format for functions instantly and inline as you code.

Image Map Editor — Create image maps right in ColdFusion Studio with a new easyto-use visual tool.

Configuration Wizard — Setup your work environment so it meets all your needs using any of more than dozen common configurations.

TopStyle CSS Editor — Create and edit standards-compliant cascading style sheets to easily control the look and feel of your web applications.

WML Support — Build wireless Web applications quickly and easily with the complete set of Wireless Markup Language (WML) visual tools.

Preface xix

Enhancements to CFML

Object Scripting — Instantiate and script objects using CFML script in addition to the CFOBJECT tag easier integration with distributed object middleware such as COM and CORBA.

Structured Exception Handling — Exception handling now offers hierarchical exception handling that supports both greater customization and greater access to internal exceptions.

String Conversion Functions — Convert strings quickly and easily to be compatible with Java Script and XML standards.

Better reliability

Server Probes — Guarantee high availability by automatically detecting when a ColdFusion Server or Web server hangs or stops, failing-over to a new machine in a ColdFusion cluster, and restarting the server with problems. (Enterprise Edition only)

Improved Automatic Server Recovery — Monitor and automatically restart server process in case of failures or critical errors on individual servers not deployed in a cluster.

Clustering Support for Apache — Setup ColdFusion clusters on Linux and Solaris using the Apache Web Server. (Enterprise Edition only)

Automatic Shared Variable Locking — Lock user and session variable reads automatically at the server level to prevent destabilizing conflicts and control thread write contentions. Configure variable locking to meet the specific needs of your applications.

Individual Data Source Control — Enable and disable individual data sources individually without affecting server availability for runtime data source maintenance without server restarts.

Improved performance

Cisco Local Director Integration — Deliver very large scale sites with Cisco Local Director intelligently balancing load based on the load metrics provided by the ColdFusion Servers in a cluster. (Enterprise Edition only)

Client-Side Page Caching — Leverage browser page caching to avoid unnecessary downloads of unchanged pages and improve overall site performance. Programmatically control refresh of client-side cache to ensure users see most up-todate output.

White Space Removal — Reduce white space left by processed code in application pages to make the pages smaller and faster. Control white space removal programmatically or administratively.

xx Developing Web Applications with ColdFusion

Scriptable Performance Metrics — Track key server metrics at run time through your own scripts for intelligent diagnosis of performance bottlenecks of stability problems in your applications.

Performance Debugging Data — Access detailed debugging information on the performance of each individual page included in an application page that is being debugged.

Enterprise connectivity features

Transaction Commit and Rollback — Control database transactions with programmable commit and rollback support for more reliable and better-managed database interactions.

Java Object and EJB Connectivity — Connect to any Java object or Enterprise JavaBean (EJB) hosted by any major EJB server to extend ColdFusion and access complex business logic or third party distributed components.

Java Servlets — Call Java Servlets hosted by a Servlet Engine such as Allaire JRun from within a ColdFusion application to access extended functionality

Java-based ColdFusion Extensions (CFX) — Extend ColdFusion with new functionality through CFXs created with Java.

Binary Object Support — Use Character Large Binary Object (CLOB) support to encoded binary objects, transmit them via XML, and store them in databases or files.

SQL Bind Parameters — Improve query performance, security and flexibility with explicitly typed query parameters.

WDDX 1.0 — Exchange complex data, including encoded images, between servers and with other programming environments even faster using the latest version of Web Distributed Data Exchange (WDDX).

OS Command Execution — Execute OS shell scripts, services, executables and batch files from within ColdFusion applications.

LDAP 3.0 — Use all the power of LDAP 3.0 for directory access including file filtering, SSL encryption, and Microsoft Active Directory integration.

Enhanced Mail Integration — Develop more sophisticated and robust email applications with new support for controlling mail headers, BCC, and multiple file attachments.

Improved Server-Side HTTP — Use URL redirection, SSL, cookies, return headers, and more robust server-side HTTP support for building distributed Web applications.

Security enhancements

General OS Security Integration — Secure entire Web applications and control access to files and objects through your existing Windows NT security architecture. Authenticated users in your applications can be limited to privileges authorized through Windows security. (Windows NT Only)

Preface xxi

OS Server Sandbox Security — Secure shared hosting environments more easily by creating Server Sandboxes with Windows NT security. OS Server Sandboxes process all requests under the privileges of a designated Windows NT user account (Enterprise Edition for Windows only).

Enhanced Advanced Security — Secure CFML functions and enable CFML code segments to be executed using the run-time security permissions of a designated user.

New Advanced Security Interface — Manage Advanced Security configuration more quickly and easily with a completely redesigned browser-based resource view.

Scriptable Advanced Security Administration — Configure ColdFusion Advanced Security through your own CFML scripts for easier maintenance of ColdFusion Servers.

Developer Resources

Allaire Corporation is committed to setting the standard for customer support in developer education, technical support, and professional services. Our Web site is designed to give you quick access to the entire range of online resources.

Allaire Developer Services

Resource Description

Allaire Web site www.allaire.com

Technical Support www.allaire.com/support

Training and Consulting www.allaire.com/services

Developer Community www.allaire.com/developer

Allaire Partners www.allaire.com/partners

General information about Allaire products and services.

Allaire offers a wide range of professional support programs. This page explains all of the available options.

Information about training classes, online courses, and consulting services offered by Allaire.

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

The Allaire Alliance is a network of solution providers, application developers, resellers, and hosting services creating solutions with ColdFusion.

xxii Developing Web Applications with ColdFusion

About ColdFusion Documentation

ColdFusion documentation is designed to provide support for all components of the ColdFusion development system. Both the print and online versions are organized to allow you to quickly locate the information you need.

In addition to the book set, the documentation is provided in two other formats:

• HTML — Browser-based Help references.

• Adobe Acrobat (PDF) — Available from the root level on the product CD-ROM

and from the Developer area of Allaire’s Web site at http://www.allaire.com/

developer

Documentation updates

Late additions and corrections to ColdFusion printed documentation are listed in the Documentation Updates page. To reach this page, open the Welcome to ColdFusion page installed with ColdFusion, where you’ll find links to the update page as well as links to other pages containing useful information about ColdFusion, Allaire support options, and Allaire products and services.

For ColdFusion Studio users, you can access the documentation update page by clicking on the Help resource tab and browsing your way through the online help tree to the Allaire Support folder.

ColdFusion manuals

The core ColdFusion documentation set consists of the following titles.

Administering ColdFusion Server

Includes instructions for installing ColdFusion Server. Describes configuration options for maximizing performance, managing data sources, setting security levels, and a range of development and site management tasks. If you are administering a ColdFusion site, you’ll need this book to help plan and implement ColdFusion security, load balancing, and for details about tuning the ColdFusion application server.

Developing Web Applications with ColdFusion

Presents the fundamentals of ColdFusion application development and deployment. Also includes detailed information about ColdFusion data sources, user interfaces, and Web technologies.

CFML Language Reference

Provides the complete syntax, with example code, of all CFML tags and functions.

Preface xxiii

Using ColdFusion Studio

Documents everything you need to know about using ColdFusion Studio, including features like projects, source control integration, as well as the Studio workspace and interface.

ColdFusion Quick Reference Guide

A valuable quick reference to CFML tags, functions, and variables.

ColdFusion Server online documentation

To view the HTML documentation, open the following URL: http://127.0.0.1/

cfdocs/dochome.htm

Note that because the Verity search libraries are not available on Linux for this release, the online documentation search facility is not functional on Linux. If you try to open the search page, a message box opens to explain why the facility is not available.

Acrobat versions of all ColdFusion documentation are available from the root level on

the product CD. If you don’t have a product CD, you can download ColdFusion documentation from the Allaire web site by visiting

developer

and clicking the Documentation link.

http://www.allaire.com/

ColdFusion Studio online documentation

Click the Help resource tab in ColdFusion Studio to view online Help pages. The help tree contains ColdFusion documentation and a number of additional developer resources. Studio online documentation is searchable and individual pages can be bookmarked.

Printing ColdFusion documentation

If you are working with an evaluation version of ColdFusion and would like printed documentation, access the Adobe Acrobat files found from the root level on the product CD. If you do not have access to a product CD, you can download the Acrobat files from the Allaire web site: Documentation link.

The Acrobat files offer excellent print output. You can print an entire manual, individual sections, or page ranges of your choice. To get the Acrobat reader, visit:

http://www.acrobat.com.

http://www.allaire.com/developer, click the

xxiv Developing Web Applications with ColdFusion

Documentation conventions

When reading, please be aware of these formatting cues:

• Code samples, filenames, and URLs are set in a

• Notes and tips are identified by bold type

• Bulleted lists present options and features

• Numbered steps indicate procedures

• Tool button icons are generally shown with procedure steps

• Menu levels are separated by the greater than (>) sign

• Text for you to type in is set in italics

monospaced font

Getting Answers

One of the best ways to solve particular programming problems is to tap into the vast expertise of the ColdFusion developer community on the Allaire Forums. Other ColdFusion 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 going back 12 months, allowing you to learn how others have solved a problem you may be

facing. The Forums is a great resource for learning ColdFusion, but it’s also a great place to see the ColdFusion developer community in action.

Contacting Allaire

Corporate headquarters

Allaire Corporation One Alewife Center Cambridge, MA 02140

Tel: 617.761.2000 Fax: 617.761.2001

http://www.allaire.com

Preface xxv

Technical support

Telephone support is available Monday through Friday 8 A.M. to 8 P.M. Eastern time (except holidays)

Toll Free: 888.939.2545 (U.S. and Canada)

Tel: 617.761.2100 (outside U.S. and Canada) For complete details about Allaire Product Support options, please refer to the Allaire

Support pages on the Allaire web site: Postings to the ColdFusion Support Forum (

made any time.

http://www.allaire.com/support.

http://forums.allaire.com) can be

Sales

Toll Free: 888.939.2545 Tel: 617.761.2100

Fax: 617.761.2101 Email: sales@allaire.com Web:

http://www.allaire.com/store

xxvi Developing Web Applications with ColdFusion

C HAPTER 1

Chapter 1 Introduction to ColdFusion

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

• What You Should Already Know........................................................................ 2

• What is ColdFusion?...........................................................................................3

• ColdFusion Features..........................................................................................3

• ColdFusion Components ..................................................................................5

• How ColdFusion Server Works.......................................................................... 7

2 Developing Web Applications with ColdFusion

A Quick Web Overview

Over the last few years, the Web has 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 ecommerce to managing internal business processes. For example, a static HTML page would allow 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 would allow customers to order books online, write reviews of books they’ve 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 Web to handle business transactions, and even to conduct the day to day business of your organization.

What You Should Already Know

Before you begin using ColdFusion to create your Web applications, you should be familiar with the following topics:

HTML

You’ll find that ColdFusion tags (CFML) are similar in syntax to HTML tags, yet, unlike HTML, they enable you to create dynamic 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 would most likely have a separate table that lists each department number and name just once.

SQL

Familiarity with some Structured Query Language (SQL) will be helpful as you develop your ColdFusion applications. In particular, you should be able to use the SELECT, UPDATE, INSERT, and DELETE statements, as well as WHERE clauses and boolean logic operators.

Chapter 1: Introduction to ColdFusion 3

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 specific file extension.

• The default ColdFusion file extension is CFM.

• They contain ColdFusion Markup Language.

Editions of ColdFusion

There are three editions of ColdFusion: Enterprise, Professional, and Express. Using ColdFusion Enterprise and Professional editions and ColdFusion Studio, you can build Web applications that leverage existing technologies and business systems such as RDBMS, messaging servers, file repositories, directory servers, and distributed object middleware. ColdFusion Enterprise also offers advanced security features, load balancing, server fail-over, and visual cluster administration. Using ColdFusion Express, you can build Web applications that interact with desktop databases that support the ODBC standard.

ColdFusion Features

ColdFusion provides a comprehensive set of features that enable:

• Rapid development

• Scalable deployment

• Open integration

• Complete security

4 Developing Web Applications with ColdFusion

Rapid development

The ColdFusion development platform enhances the speed and ease of development through the following features:

• 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 via HTTP for remote development.

• A tag-based component architecture for flexible code reuse.

Scalable deployment

ColdFusion delivers a high-performance platform for application deployment through the following features:

• A multi-threaded 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 Edition only).

• Automatic server recovery and fail-over for high availability (Enterprise Edition

only).

Open integration

ColdFusion integrates with new and legacy technologies through the following features:

• Database connectivity using native database drivers (Enterprise Edition only),

ODBC, or OLE-DB.

• Embedded support for full text indexing and searching.

• Standards-based integration 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.

+ 350 hidden pages