Adobe ColdFusion Developer's Guide Cold Fusion 8.0 Developer’s 8 Dev

User Manual: adobe ColdFusion - 8.0 - Developer’s Guide Free User Guide for Adobe ColdFusion Software, Manual

Open the PDF directly: View PDF .
Page Count: 1195

Download
Open PDF In Browser	View PDF

ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
®

™

© 2007 Adobe Systems Incorporated. All rights reserved.
Adobe® ColdFusion® Developers Guide
If this guide is distributed with software that includes an end user agreement, this guide, 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. Except as permitted by any such license, no part of this guide 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 Adobe Systems Incorporated. Please note that the
content in this guide is protected under copyright law even if it is not distributed with software that includes an end user license agreement.
The content of this guide is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in the informational content contained in this guide.
Please remember that existing artwork or images that you may want to include in your project may be protected under copyright law. The unauthorized incorporation of such
material into your new work could be a violation of the rights of the copyright owner. Please be sure to obtain any permission required from the copyright owner.
Any references to company names in sample templates are for demonstration purposes only and are not intended to refer to any actual organization.
Adobe, the Adobe logo, Acrobat, ColdFusion, Dreamweaver, Flash, FlashPaper, Flex, LiveCycle, and Reader, are either registered trademarks or trademarks of Adobe Systems
Incorporated in the United States and/or other countries.
Apple and Macintosh are trademarks of Apple Inc., registered in the United States and other countries. HP-UX is a registered trademark of Hewlett-Packard Company. IBM is a
trademark of International Business Machines Corporation in the United States, other countries, or both. Java, Solaris, and Sun are trademarks or registered trademarks of Sun
Microsystems, Inc. in the United States and other countries. Linux is the registered trademark of Linus Torvalds in the U.S. and other countries. Microsoft and Windows are either
registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Motif is a registered trademark of The Open Group. UNIX is a registered trademark of The Open Group in the US and other countries. All other trademarks are the property of their respective owners.
This product includes software developed by the Apache Software Foundation (http://www.apache.org/)
This product contains either BISAFE and/or TIPEM software by RSA Data Security, Inc.
Portions include technology used under license from Autonomy, and are copyrighted.
Verity and TOPIC are registered trademarks of Autonomy.
Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA.
Notice to U.S. Government End Users. The Software and Documentation are “Commercial Items,” as that term is defined at 48 C.F.R. §2.101, consisting of “Commercial Computer
Software” and “Commercial Computer Software Documentation,” as such terms are used in 48 C.F.R. §12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48 C.F.R.
§12.212 or 48 C.F.R. §§227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software and Commercial Computer Software Documentation are being
licensed to U.S. Government end users (a) only as Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions
herein. Unpublished-rights reserved under the copyright laws of the United States. Adobe agrees to comply with all applicable equal opportunity laws including, if appropriate,
the provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of 1974 (38 USC 4212), and Section 503 of the
Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60, 60-250, and 60-741. The affirmative action clause and regulations contained in
the preceding sentence shall be incorporated by reference.

iii

Contents
Chapter 1: Introduction
Using this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Chapter 1: Introducing ColdFusion
About Internet applications and web application servers
About ColdFusion

................................... 3

......................................................................... 4

About J2EE and the ColdFusion architecture

............................................... 7

Part 1: The CFML Programming Language
Chapter 2: Elements of CFML
CFML Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Comments
Tags

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Functions

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

ColdFusion components

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Constants

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Variables

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Expressions

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Data types

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Flow control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Character case

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Special characters
Reserved words
CFScript

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Chapter 3: Using ColdFusion Variables
Creating variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Variable characteristics
Data types
Strings

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Using periods in variable references
Data type conversion
About scopes

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Ensuring variable existence
Validating data

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Passing variables to custom tags and UDFs

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Chapter 4: Using Expressions and Number Signs
Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Using number signs

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Dynamic expressions and dynamic variables

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

iv

Chapter 5: Using Arrays and Structures
About arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Basic array techniques

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Populating arrays with data
Array functions

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

About structures

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Creating and using structures

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Structure examples

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Structure functions

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Chapter 6: Extending ColdFusion Pages with CFML Scripting
About CFScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
The CFScript language

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Using CFScript statements
Handling exceptions
CFScript example

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Chapter 7: Using Regular Expressions in Functions
About regular expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Regular expression syntax
Using backreferences

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Returning matched subexpressions
Regular expression examples

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Types of regular expression technologies

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Part 2: Building Blocks of ColdFusion Applications
Chapter 8: Creating ColdFusion Elements
About CFML elements that you create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Including pages with the cfinclude tag

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

About user-defined functions

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Using ColdFusion components

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Using custom CFML tags
Using CFX tags

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Selecting among ColdFusion code reuse methods

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Chapter 9: Writing and Calling User-Defined Functions
About user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Creating user-defined functions
Calling user-defined functions

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Working with arguments and variables in functions
Handling errors in UDFs

A user-defined function example
Using UDFs effectively

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Chapter 10: Building and Using ColdFusion Components
About ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

v

Creating ColdFusion components

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Using ColdFusion components

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

Passing parameters to methods

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

CFC variables and scope
Using CFCs effectively

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

ColdFusion component example

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Chapter 11: Creating and Using Custom CFML Tags
Creating custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Passing data to custom tags
Managing custom tags
Executing custom tags
Nesting custom tags

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Chapter 12: Building Custom CFXAPI Tags
What are CFX tags? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Before you begin developing CFX tags in Java
Writing a Java CFX tag
ZipBrowser example

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Approaches to debugging Java CFX tags
Developing CFX tags in C++

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Part 3: Developing CFML Applications
Chapter 14: Designing and Optimizing a ColdFusion Application
About applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Elements of a ColdFusion application
Structuring an application

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Defining the application and its event handlers in Application.cfc
Migrating from Application.cfm to Application.cfc
Using an Application.cfm page

. . . . . . . . . . . . . . . . . . . . . . . . 224

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Optimizing ColdFusion applications

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Chapter 15: Handling Errors
About error handling in ColdFusion

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

Understanding errors

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Error messages and the standard error format
Determining error-handling strategies

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Specifying custom error messages with the cferror tag
Logging errors with the cflog tag

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

Handling runtime exceptions with ColdFusion tags

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Chapter 16: Using Persistent Data and Locking
About persistent scope variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Managing the client state

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

Configuring and using client variables
Configuring and using session variables

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

vi

Configuring and using application variables
Using server variables

Locking code with cflock
Examples of cflock

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

Chapter 17: Using ColdFusion Threads
About ColdFusion threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Creating and managing ColdFusion threads
Using thread data

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

Working with threads

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

Using ColdFusion tools to control thread use
Example: getting multiple RSS feeds

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Chapter 18: Securing Applications
ColdFusion security features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
About resource and sandbox security
About user security

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

Using ColdFusion security tags and functions
Security scenarios

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Implementing user security

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

Chapter 19: Developing Globalized Applications
Introduction to globalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
About character encodings
Locales

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

Processing a request in ColdFusion

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

Tags and functions for globalizing applications
Handling data in ColdFusion

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

Chapter 20: Debugging and Troubleshooting Applications
Configuring debugging in the ColdFusion Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Using debugging information from browser pages
Controlling debugging information in CFML
Using the cftrace tag to trace execution

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362

Using the cftimer tag to time blocks of code
Using the Code Compatibility Analyzer
Troubleshooting common problems

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

Chapter 21: Using the ColdFusion Debugger
About the ColdFusion Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Installing and uninstalling the ColdFusion Debugger
Setting up ColdFusion to use the Debugger
About the Debug perspective

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372

Using the ColdFusion Debugger
Viewing ColdFusion log files

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

vii

Part 4: Accessing and Using Data
Chapter 22: Introduction to Databases and SQL
What is a database? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Using SQL

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

Writing queries by using an editor

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

Chapter 23: Accessing and Retrieving Data
Working with dynamic data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Outputting query data

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

Getting information about query results

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397

Enhancing security with cfqueryparam

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398

Chapter 24: Updating Your Database
About updating your database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Inserting data

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

Updating data

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

Deleting data

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411

Chapter 25: Using Query of Queries
About record sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
About Query of Queries

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414

Query of Queries user guide

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420

Chapter 26: Managing LDAP Directories
About LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
The LDAP information structure
Using LDAP with ColdFusion

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438

Querying an LDAP directory

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439

Updating an LDAP directory

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444

Advanced topics

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452

Chapter 27: Building a Search Interface
About Verity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
Creating a search tool for ColdFusion applications
Creating a search page

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

Enhancing search results

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473

Working with data returned from a query

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480

Chapter 28: Using Verity Search Expressions
About Verity query types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
Using simple queries

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489

Using explicit queries

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490

Using natural queries

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493

Using Internet queries

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493

Composing search expressions

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496

Refining your searches with zones and fields

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505

viii

Part 5: Requesting and Presenting Information
Chapter 29: Introduction to Retrieving and Formatting Data
Using forms in ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
Working with action pages

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514

Working with queries and data
Returning results to the user

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521

Dynamically populating list boxes

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524

Creating dynamic check boxes and multiple-selection list boxes

. . . . . . . . . . . . . . . . . . . . . . . . . . 526

Chapter 30: Building Dynamic Forms with cfform Tags
Creating custom forms with the cfform tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
Building tree controls with the cftree tag
Building drop-down list boxes
Building slider bar controls

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540

Creating data grids with the cfgrid tag
Embedding Java applets

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551

Chapter 31: Validating Data
About ColdFusion validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553
Validating form fields

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558

Handling invalid data

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560

Masking form input values

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561

Validating form data with regular expressions
Validating form data using hidden fields

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565

Validating form input and handling errors with JavaScript

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569

Validating data with the IsValid function and the cfparam tag

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 572

Chapter 32: Creating Forms in Flash
About Flash forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
Building Flash forms

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578

Binding data in Flash forms

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586

Setting styles and skins in Flash forms
Using ActionScript in Flash forms
Best practices for Flash forms

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592

Chapter 33: Creating Skinnable XML Forms
About XML skinnable forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594
Building XML skinnable forms
ColdFusion XML format
Creating XSLT skins

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610

Chapter 34: Using Ajax UI Components and Features
About Ajax and ColdFusion user interface features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613
Controlling Ajax UI layout

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615

Using menus and toolbars

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623

Using Ajax form controls and features

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626

ix

Chapter 35: Using Ajax Data and Development Features
About ColdFusion Ajax data and development features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647
Binding data to form fields

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649

Managing the client-server interaction
Using Spry with ColdFusion

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661

Specifying client-side support files
Using data interchange formats
Debugging Ajax applications

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669

Ajax programming rules and techniques

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671

Chapter 36: Using the Flash Remoting Service
About using the Flash Remoting service with ColdFusion
Configuring the Flash Remoting Gateway

Using the Flash Remoting service with ColdFusion pages
Using Flash with CFCs

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684

Using the Flash Remoting service with ColdFusion Java objects
Handling errors with ColdFusion and Flash

. . . . . . . . . . . . . . . . . . . . . . . . . . 685

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686

Chapter 37: Using Flash Remoting Update
About Flash Remoting Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688
Installing Flash Remoting Update
Using Flash Remoting Update

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688

Chapter 38: Using the LiveCycle Data Services ES Assembler
About ColdFusion and Flex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
Application development and deployment process

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693

Configuring a destination for the ColdFusion Data Service adapter
Writing the ColdFusion CFCs

Notifying the Flex application when data changes
Authentication
Enabling SSL

. . . . . . . . . . . . . . . . . . . . . . . 693

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703

Data translation

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704

Chapter 39: Using Server-Side ActionScript
About server-side ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
Connecting to the Flash Remoting service
Using server-side ActionScript functions
Global and request scope objects

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710

About the CF.query function and data sources
Using the CF.query function
Building a simple application

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714

About the CF.http function

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717

Using the CF.http function

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718

x

Part 6: Working with Documents, Charts, and Reports
Chapter 40: Manipulating PDF Forms in ColdFusion
About PDF forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723
Populating a PDF form with XML data
Prefilling PDF form fields

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725

Embedding a PDF form in a PDF document

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728

Extracting data from a PDF form submission
Application examples that use PDF forms

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732

Chapter 41: Assembling PDF Documents
About assembling PDF documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
Using shortcuts for common tasks

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741

Using DDX to perform advanced tasks
Application examples

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756

Chapter 42: Creating and Manipulating ColdFusion Images
About ColdFusion images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
Creating ColdFusion images
Converting images
Verifying images

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770

Enforcing size restrictions

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771

Compressing JPEG images

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771

Manipulating ColdFusion images
Writing images to the browser

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779

Application examples that use ColdFusion images

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779

Chapter 43: Creating Charts and Graphs
About charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785
Creating a basic chart
Charting data

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 786

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787

Controlling chart appearance
Creating charts: examples
Administering charts

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 804

Writing a chart to a variable
Linking charts to URLs

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806

Chapter 44: Creating Reports and Documents for Printing
About printable output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810
Creating PDF and FlashPaper output with the cfdocument tag
Creating reports with Crystal Reports (Windows only)

. . . . . . . . . . . . . . . . . . . . . . . . . . . 811

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 816

Chapter 45: Creating Reports with Report Builder
About Report Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 818
Getting started

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 820

Common reporting tasks and techniques
Creating a simple report

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840

xi

Chapter 46: Creating Slide Presentations
Part 7: Using Web Elements and External Objects
Chapter 47: Using XML and WDDX
About XML and ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865
The XML document object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866

ColdFusion XML tag and functions
Using an XML object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871

Creating and saving an XML document object
Modifying a ColdFusion XML object
Validating XML documents

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 876

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885

Transforming documents with XSLT
Extracting data with XPath

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886

Example: using XML in a ColdFusion application
Moving complex data across the web with WDDX
Using WDDX

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 894

Chapter 48: Using Web Services
Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 900
Working with WSDL files

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 902

Consuming web services

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904

Publishing web services

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 911

Using request and response headers
Handling complex data types

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 920

Troubleshooting SOAP requests and responses

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924

Chapter 49: Integrating J2EE and Java Elements in CFML Applications
About ColdFusion, Java, and J2EE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927
Using JSP tags and tag libraries

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 930

Interoperating with JSP pages and servlets
Using Java objects

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 931

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936

Chapter 50: Using Microsoft .NET Assemblies
About ColdFusion and .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 950
Accessing .NET assemblies
Using .NET classes

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 953

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 957

.NET Interoperability Limitations
Example applications
Advanced tools

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 966

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 968

Chapter 51: Integrating COM and CORBA Objects in CFML Applications
About COM and CORBA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 972
Creating and using objects

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 973

Getting started with COM and DCOM
Creating and using COM objects
Getting started with CORBA

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 974

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985

xii

Creating and using CORBA objects
CORBA example

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991

Part 8: Using External Resources
Chapter 52: Sending and Receiving E-Mail
Using ColdFusion with mail servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996
Sending e-mail messages

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997

Sample uses of the cfmail tag

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999

Using the cfmailparam tag

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1002

Receiving e-mail messages

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1004

Handling POP mail

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1005

Chapter 53: Interacting with Microsoft Exchange Servers
Using ColdFusion with Microsoft Exchange servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1011
Managing connections to the Exchange server
Creating Exchange items

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1012

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1015

Getting Exchange items and attachments
Modifying Exchange items

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1017

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1024

Deleting Exchange items and attachments

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1027

Working with meetings and appointments

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1028

Chapter 54: Interacting with Remote Servers
About interacting with remote servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1036
Using cfhttp to interact with the web

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1036

Creating a query object from a text file
Using the cfhttp Post method

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1039

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1040

Performing file operations with cfftp

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1042

Chapter 55: Managing Files on the Server
About file management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1047
Using cfdirectory
Using cfcontent

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1054
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1056

Chapter 56: Using Event Gateways
About event gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1060
Event gateway facilities and tools

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1064

Structure of an event gateway application
Configuring an event gateway instance

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1066

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1067

Developing an event gateway application
Deploying event gateways and applications

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1068
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1075

Using the CFML event gateway for asynchronous CFCs

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1075

Using the example event gateways and gateway applications

. . . . . . . . . . . . . . . . . . . . . . . . . . .1077

Chapter 57: Using the Instant Messaging Event Gateways
About ColdFusion and instant messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1083
Configuring an IM event gateway

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1085

xiii

Handling incoming messages

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1087

Sending outgoing messages

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1087

Sample IM message handling application
Using the GatewayHelper object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1088

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1093

Chapter 58: Using the SMS Event Gateway
About SMS and ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1099
Configuring an SMS event gateway

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1103

Handling incoming messages

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1105

Sending outgoing messages

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1107

ColdFusion SMS development tools
Sample SMS application

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1111

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1113

Chapter 59: Using the FMS event gateway
About Flash Media Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1115
Application development and deployment process

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1117

Chapter 60: Using the Data Services Messaging Event Gateway
About Flex and ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1119
Configuring a Data Services Messaging event gateway

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1120

Sending outgoing messages

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1121

Handling incoming messages

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1122

Data translation

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1123

Chapter 61: Using the Data Management Event Gateway
About ColdFusion and Flex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1124
Configuring a Data Management event gateway
Sending messages
Data translation

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1125

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1126

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1127

Chapter 62: Creating Custom Event Gateways
Event gateway architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1128
Event gateway elements

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1129

Building an event gateway
Deploying an event gateway

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1133
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1140

Chapter 63: Using the ColdFusion Extensions for Eclipse
About the ColdFusion Extensions for Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1142
Eclipse RDS Support

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1143

ColdFusion/Flex Application wizard

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1146

ColdFusion/Ajax Application wizard

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1149

ActionScript to CFC wizard

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1149

CFC to ActionScript wizard

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1150

RDS CRUD wizard

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1150

Services Browser

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1152

1

Chapter 1: Introduction
The ColdFusion Developer’s Guide provides the tools needed to develop Internet applications using ColdFusion. This
manual is intended for web application programmers who are learning ColdFusion or wish to extend their
ColdFusion programming knowledge. It provides a solid grounding in the tools that ColdFusion provides to develop
web applications.
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.

Using this manual
This manual can to help anyone with a basic understanding of HTML learn to develop ColdFusion applications.
However, this manual is most useful if you have basic ColdFusion experience or have viewed the Getting Started
experience, which is available from the ColdFusion Administrator. Use this manual in conjunction with the CFML
Reference.

About Adobe ColdFusion 8 documentation
The ColdFusion documentation is designed to provide support for the complete spectrum of participants.

Documentation set
The ColdFusion documentation set includes the following titles:
Manual

Description

Installing and Using ColdFusion

Describes system installation and basic configuration for Windows, Macintoch, Solaris, Linux,
and AIX.

Configuring and Administering ColdFusion

Part I describes how to manage the ColdFusion environment, including connecting to your
data sources and configuring security for yowur applications. Part II describes Verity search
tools and utilities that you can use for configuring the Verity K2 Server search engine, as well
as creating, managing, and troubleshooting Verity collections.

ColdFusion Developer’s Guide

Describes how to develop your dynamic web applications, including retrieving and updating
your data, using structures, and forms.

CFML Reference

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

ADOBE COLDFUSION 8 2
ColdFusion Developer’s Guide

Viewing online documentation
All ColdFusion documentation is available online in HTML and Adobe Acrobat Portable Document Format (PDF)
files. Go to the documentation home page for ColdFusion on the Adobe website:
www.adobe.com/support/documentation/en/coldfusion/. In addition, you can view the documentation in
LiveDocs, which lets you add comments to pages and view the latest comments added by Adobe, by going to
www.adobe.com/go/livedocs_cf8docs.

3

Chapter 1: Introducing ColdFusion
You use Adobe ColdFusion to create dynamic Internet applications.
Contents

About Internet applications and web application servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
About ColdFusion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
About J2EE and the ColdFusion architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

About Internet applications and web application
servers
With ColdFusion, you develop Internet applications that run on web application servers.

About web pages and Internet applications
The Internet has evolved from a collection of static HTML pages to an application deployment platform. First, the
Internet changed from consisting of static web pages to providing dynamic, interactive content. Rather than
providing unchanging content where organizations merely advertise goods and services, dynamic pages enable
companies to conduct business ranging from e-commerce to managing internal business processes. For example, a
static HTML page lets a bookstore publish its location, list services such as the ability to place special orders, and
advertise upcoming events like book signings. A dynamic website for the same bookstore lets customers order books
online, write reviews of books they read, and even get suggestions for purchasing books based on their reading
preferences.
More recently, the Internet has become the underlying infrastructure for a wide variety of applications. With the
arrival of technologies such as XML, web services, J2EE (Java 2 Platform, Enterprise Edition), and Microsoft .NET,
the Internet has become a multifaceted tool for integrating business activities. Now, enterprises can use the Internet
to integrate distributed activities, such as customer service, order entry, order fulfillment, and billing.
ColdFusion is a rapid application development environment that lets you build dynamic websites and Internet applications quickly and easily. It lets you develop sophisticated websites and Internet applications without knowing the
details of many complex technologies, yet it lets advanced developers take advantage of the full capabilities of many
of the latest Internet technologies.

About web application servers
To understand ColdFusion, you must first understand the role of web application servers. Typically, web browsers
make requests, and web servers, such as Microsoft Internet Information Server (IIS) and the Apache web server,
fulfill those requests by returning the requested information to the browser. This information includes, but is not
limited to, HTML and Adobe Flash files.
A web server’s capabilities are limited because all it does is wait for requests to arrive and attempt to fulfill those
requests as soon as possible. A web server does not let you do the following tasks:

•

Interact with a database, other resource, or other application.

•

Serve customized information based on user preferences or requests.

ADOBE COLDFUSION 8 4
ColdFusion Developer’s Guide

•

Validate user input.

A web server, basically, locates information and returns it to a web browser.
To extend the capabilities of a web server, you use a web application server, a software program that extends the web
server’s capabilities to do tasks such as those in the preceding list.
How a web server and web application server work together

The following steps explain how a web server and web application server work together to process a page request:
1

The user requests a page by typing a URL in a browser, and the web server receives the request.

2 The web server looks at the file extension to determine whether a web application server must process the page.
Then, one of the following actions occur:

• If the user requests a file that is a simple web page (often one with an HTM or HTML extension), the web
server fulfills the request and sends the file to the browser.
• If the user requests a file that is a page that a web application server must process (one with a CFM, CFML,
or CFC extension for ColdFusion requests), the web server passes the request to the web application server. The
web application server processes the page and sends the results to the web server, which returns those results to
the browser. The following image shows this process:
1

2

Web browser
requests
a web page.

Web server
receives the
page request.

3
Web server instructs
application server
to process the page.

4
The application server
processes the page
and generates output.

5
The web server
sends the outpu
to the browser

Because web application servers interpret programming instructions and generate output that a web browser can
interpret, they let web developers build highly interactive and data-rich websites, which can do tasks such as the
following:

•

Query other database applications for data.

•

Dynamically populate form elements.

•

Dynamically generate Flash application data.

•

Provide application security.

•

Integrate with other systems using standard protocols such as HTTP, FTP, LDAP, POP, and SMTP.

•

Create shopping carts and e-commerce websites.

•

Respond with an e-mail message immediately after a user submits a form.

•

Return the results of keyword searches.

About ColdFusion
ColdFusion is a rapid scripting environment server for creating dynamic Internet Applications. ColdFusion Markup
Language (CFML) is an easy-to-learn tag-based scripting language, with connectivity to enterprise data and
powerful built-in search and charting capabilities. ColdFusion enables developers to easily build and deploy dynamic
websites, content publishing systems, self-service applications, commerce sites, and more.
ColdFusion pages are plain text files that you use to create web applications. You can create your ColdFusion applications by writing all the code manually or by using wizards (provided with some editors) to generate the majority
of the code for you.

ADOBE COLDFUSION 8 5
ColdFusion Developer’s Guide

Saving ColdFusion pages
In order for the ColdFusion server to process a page, you must save the ColdFusion page on a computer where
ColdFusion is installed. If you are creating your pages on a local server (on which ColdFusion is running), you can
save the pages locally; if you are using a remote server, you must save your pages on that server.
If you are using the J2EE configuration, you typically save ColdFusion pages under the ColdFusion web application
root. For example, in the default directory structure when you use the J2EE configuration with JRun, you save pages
under jrun_root/servers/cfusion/cfusion-ear/cfusion-war.

Testing ColdFusion pages
To ensure that the code you wrote is working as expected, you view the ColdFusion page in a browser by going to
the appropriate URL, for example http://localhost/test/mypage.cfm. If you are using the built-in web server,
specify the port to use in the URL, for example, http://localhost:8500/test/cfpage.cfm. The address
localhost is only valid when you view pages locally.
Note: On Vista, the address ::1 is equivalent to localhost. You can use the ColdFusion GetLocalHostIP function to
get the IP address of localhost.
The URL for a remote site includes the server name or IP address of the server where ColdFusion is installed; for
example, http:///test/mypage.cfm. If you are using the ColdFusion J2EE configuration,
you may also need to include a context root in the URL; for example, http:////mypage.cfm. For example, if you deploy an EAR file and use the default context root of cfconroot, you
specify http://localhost/cfconroot/test/mypage.cfm.

Elements of ColdFusion
ColdFusion consists of the following core elements:

•

ColdFusion scripting environment

•

CFML

•

ColdFusion Administrator

•

Verity Search Server

The following sections describe these core components in more detail.
The ColdFusion scripting environment

The ColdFusion scripting environment provides an efficient development model for Internet applications. At the
heart of the ColdFusion scripting environment is the ColdFusion Markup Language (CFML), a tag-based
programming language that encapsulates many of the low-level details of web programming in high-level tags and
functions.
ColdFusion Markup Language

ColdFusion Markup Language (CFML) is a tag-based language, similar to HTML, that uses special tags and
functions. With CFML, you can enhance standard HTML files with database commands, conditional operators,
high-level formatting functions, and other elements to rapidly produce easy-to-maintain web applications. However,
CFML is not limited to enhancing HTML. For example, you can create Adobe Flash applications that consist entirely
of Flash elements and CFML. Similarly, you can use CFML to create web services for use by other applications.
For more information, see “Elements of CFML” on page 10

ADOBE COLDFUSION 8 6
ColdFusion Developer’s Guide

CFML tags

CFML looks similar to HTML—it includes starting and, in most cases, ending tags, and each tag is enclosed in angle
brackets. All ending tags are preceded with a forward slash (/) and all tag names are preceded with cf; for example:

tag body text and CFML


CFML increases productivity by providing a layer of abstraction that hides many low-level details involved with
Internet application programming. At the same time, CFML is extremely powerful and flexible. ColdFusion lets you
easily build applications that integrate files, databases, legacy systems, mail servers, FTP servers, objects, and components.
CFML tags serve many functions. They provide programming constructs, such as conditional processing and loop
structures. They also provide services, such as charting and graphing, full-text search, access to protocols such as
FTP, SMTP/POP, and HTTP, and much more. The following table lists a few examples of commonly used
ColdFusion tags:
Tag

Purpose

cfquery

Establishes a connection to a database (if one does not exist), executes a query, and returns results to the ColdFusion
environment.

cfoutput

Displays output that can contain the results of processing ColdFusion functions, variables, and expressions.

cfset

Sets the value of a ColdFusion variable.

cfmail

Lets an application send SMTP mail messages using application variables, query results, or server files. (Another tag,
cfpop, gets mail.)

cfchart

Converts application data or query results into graphs, such as bar charts or pie charts, in Flash, JPG, or PNG format.

cfobject

Invokes objects written in other programming languages, including COM (Component Object Model) components,
Java objects such as Enterprise JavaBeans, or Common CORBA (Object Request Broker Architecture) objects.

CFML Reference describes the CFML tags in detail.
CFML functions and CFScript

CFML includes built-in functions that perform a variety of roles, including string manipulation, data management,
and system functions. CFML also includes a built-in scripting language, CFScript, that lets you write code in a
manner that is familiar to programmers and JavaScript writers.
CFML extensions

You can extend CFML further by creating custom tags or user-defined functions (UDFs), or by integrating COM,
C++, and Java components (such as JSP tag libraries). You can also create ColdFusion components (CFCs), which
encapsulate related functions and properties and provide a consistent interface for accessing them.
All these features let you easily create reusable functionality that is customized to the types of applications or websites
that you are building.
CFML development tools

Adobe® Dreamweaver® CS3 helps you develop ColdFusion applications efficiently. It includes many features that
simplify and enhance ColdFusion development, including tools for debugging CFML. Because CFML is written in
an HTML-like text format, and you often use HTML in ColdFusion pages, you can also use an HTML editor or a
text editor, such as Notepad, to write ColdFusion applications.

ADOBE COLDFUSION 8 7
ColdFusion Developer’s Guide

ColdFusion 8 includes a line debugger that you can use to debug your ColdFusion applications in Eclipse™ or Adobe
Flex™ Builder™.

Verity Search Server
The Verity Search Server (also called the Verity search engine) provides full text search capability for documents and
data on a ColdFusion site.

ColdFusion Administrator
ColdFusion Administrator configures and manages the ColdFusion application server. It is a secure web-based
application that you can access using any web browser, from any computer with an Internet connection. It includes
a Server Monitor, which lets you see the status of your ColdFusion server.
For more information about ColdFusion Administrator, see Configuring and Administering ColdFusion.

About J2EE and the ColdFusion architecture
As the Internet software market has matured, the infrastructure services required by distributed Internet applications, including ColdFusion applications, have become increasingly standardized. The most widely adopted
standard today is the Java 2 Platform, Enterprise Edition (J2EE) specification. J2EE provides a common set of infrastructure services for accessing databases, protocols, and operating system functionality, across multiple operating
systems.

About ColdFusion and the J2EE platform
ColdFusion is implemented on the Java technology platform and uses a J2EE application server for many of its base
services, including database connectivity, naming and directory services, and other runtime services. ColdFusion
can be configured to use an embedded J2EE server (in the server configuration) or it can be deployed as a J2EE application on an independent J2EE application server (in the multiserver configuration or the J2EE configuration).
ColdFusion Enterprise includes a fully featured version of the JRun J2EE application server, or can be deployed on
third-party J2EE servers such as IBM WebSphere and BEA WebLogic.
For more information on ColdFusion configurations, see Installing and Using ColdFusion.
By implementing the ColdFusion scripting environment on top of the J2EE platform, ColdFusion takes advantage
of the power of the J2EE platform while also providing an easy-to-use scripting environment and built-in services.
Moreover, because ColdFusion is built on a J2EE platform, you can easily integrate J2EE and Java functionality into
your ColdFusion application. As a result, ColdFusion pages can do any of the following:

•

Share session data with JSPs (Java Server Pages) and Java servlets.

•

Import custom JSP tag libraries and use them like ColdFusion custom tags.

•

Integrate with Java objects, including the J2EE Java API, JavaBeans, and Enterprise JavaBeans.

For more information on using J2EE features in ColdFusion, see “Integrating J2EE and Java Elements in CFML
Applications” on page 927

8

Part 1: The CFML Programming
Language
This part contains the following topics:
Elements of CFML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Using ColdFusion Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Using Expressions and Number Signs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Using Arrays and Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Extending ColdFusion Pages with CFML Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Using Regular Expressions in Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107

10

Chapter 2: Elements of CFML
The basic elements of CFML, including tags, functions, constants, variables, expressions, and CFScript, make it a
powerful tool for developing interactive web applications.
Contents

CFML Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Data types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Flow control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Character case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Special characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Reserved words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
CFScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

CFML Basics
CFML is a dynamic application development tool with many of the features of a programming language, including
functions, expressions, variables and constants, and flow-control constructs, such as if-then and loops. CFML also
has a “language within a language,” CFScript, which enables you to use a syntax similar to JavaScript for many operations.
These elements and other basic CFML entities such as comments, data types, escape characters, and reserved words,
let you create complex applications.

Comments
ColdFusion comments have a similar format to HTML comments. However, they use three dash characters instead
of two; for example:


The ColdFusion server removes all ColdFusion comments from the page before returning it to the web server. As a
result, the page that a user’s browser receives does not include the comment, and users cannot see the comment even
if they view the page source.
You can embed CFML comments in begin tags (not just tag bodies), functions calls, and variable text in number
signs. ColdFusion ignores the text in comments such as the following:

ADOBE COLDFUSION 8 11
ColdFusion Developer’s Guide

>
#Dateformat(now() )#

This technique can be useful if you want to temporarily comment out parts of expressions or optional attributes or
arguments.
You can also nest comments, as the following example shows:



#errormessage1#

--->

This is useful if you want to temporarily disable a section of code while you test your application.
You can embed comments within comments, however, you should use this technique carefully.
Note: You cannot embed comments inside a tag name or function name, such as CustomTag>.
You also cannot embed comments inside strings, as in the following example: IsDefined("MyVariable").

Tags
ColdFusion tags tell the ColdFusion server that it must process information. The ColdFusion server only processes
tag contents; it returns text outside of ColdFusion to the web server unchanged. ColdFusion provides a wide variety
of built-in tags and lets you create custom tags.

Tag syntax
ColdFusion tags have the same format as HTML tags. They are enclosed in angle brackets (< and >) and can have
zero or more named attributes. Many ColdFusion tags have bodies; that is, they have beginning and end tags with
text to be processed between them. For example:

Hello #YourName#! 



Other tags, such as cfset and cfhttp, never have bodies; all the required information goes between the beginning
(<) character and the ending (>) character, as in the following example:


Note: The cfset tag differs from other tags in that it has neither a body nor arguments. Instead, the tag encloses an
assignment statement that assigns a value to a variable. The cfset tag can also call a function without assigning a value
to a result variable.
Sometimes, although the tag can have a body, you do not need to put anything in it because the attributes specify all
the required information. You can omit the end tag and put a forward slash character before the closing (>) character,
as in the following example:


ADOBE COLDFUSION 8 12
ColdFusion Developer’s Guide

In most cases, you specify tag attributes directly in the tag using the format attributeName=”attributeValue”, as the
preceding example shows. However, as an alternative, you can put all the attributes in a structure and specify the
structure in a single attributeCollection attribute, using the following format:


When you use this format for all built-in ColdFusion tags except cfmodule, the tag must have only the
attributeCollection attribute. This format is useful when you use dynamic arguments, where the number and
values of the arguments to a tag can vary based on processing results. The following example shows this usage:



















#cfhttp.fileContent#


Note: The attributeCollection attribute used in the cfmodule tag and when calling custom tags directly is different
from the attributeCollection attribute for all other tags. In the cfmodule tag and in custom tags, you can mix the
attributeCollection attribute and explicit custom tag attributes. Also, in the cfmodule tag, the
attributeCollection attribute cannot contain the name and template attributes. You must specify these attributes
directly in the cfmodule tag.
You can use the attributeCollection attribute in all tags except the following:
cfargument

cfelseif

cflogout

cfset

cfbreak

cffunction

cfloop

cfsilent

cfcase

cfif

cfparam

cfswitch

cfcatch

cfimport

cfprocessingdirective

cftry

cfcomponent

cfinterface

cfproperty

cfdefaultcase

cflogin

cfrethrow

cfelse

cfloginuser

cfreturn

Built-in tags
Built-in tags make up the heart of ColdFusion. These tags have many uses, including the following:

•

Manipulating variables

ADOBE COLDFUSION 8 13
ColdFusion Developer’s Guide

•

Creating interactive forms

•

Accessing and manipulating databases

•

Displaying data

•

Controlling the flow of execution on the ColdFusion page

•

Handling errors

•

Processing ColdFusion pages

•

Managing the CFML application framework

•

Manipulating files and directories

• Using external tools and objects, including Verity collections, COM, Java, and CORBA objects, and executable
programs
•

Using protocols, such as mail, http, ftp, and pop

The CFML Reference documents each tag in detail.

Custom tags
ColdFusion lets you create custom tags. You can create two types of custom tags:

•

CFML custom tags that are ColdFusion pages

•

CFX tags that you write in a programing language such as Java or C++

Custom tags can encapsulate frequently used business logic or display code. These tags enable you to place frequently
used code in one place and call it from many places. Custom tags also let you abstract complex logic into a single,
simple interface. They provide an easy way to distribute your code to others; you can even distribute encrypted
versions of the tags to prevent access to the tag logic.
You can access a variety of free and commercial custom tags on the Adobe developer’s exchange
(www.www.adobe.com/devnet/coldfusion/index.html). They perform tasks ranging from checking if Cookies and
JavaScript are enabled on the client’s browser to moving items from one list box to another. Many of these tags are
free and include source code.
CFML custom tags

When you write a custom tag in CFML, you can take advantage of all the features of the ColdFusion language,
including all built-in tags and even other custom tags. CFML custom tags can include body sections and end tags.
Because they are written in CFML, you do not need to know a programming language such as Java. CFML custom
tags provide more capabilities than user-defined functions, but are less efficient.
For more information on CFML custom tags, see “Creating and Using Custom CFML Tags” on page 190. For information about, and comparisons among, ways to reuse ColdFusion code, including CFML custom tags, user-defined
functions, and CFX tags, see “Creating ColdFusion Elements” on page 126.
CFX Tags

CFX tags are ColdFusion custom tags that you write in a programming language such as Java or C++. These tags can
take full advantage of all the tools and resources provided by these languages, including their access to runtime
environments. CFX tags also generally execute faster than CFML custom tags because they are compiled. CFX tags
can be cross-platform, but are often platform-specific, for example if they take advantage of COM objects or the
Windows API.
For more information on CFX tags, see “Building Custom CFXAPI Tags” on page 205.

ADOBE COLDFUSION 8 14
ColdFusion Developer’s Guide

Functions
Functions typically manipulate data and return a result. You can also create user-defined functions (UDFs),
sometimes referred to as custom functions.
Functions have the following general form:
functionName([argument1[, argument2]]...)

Some functions, such as the Now function take no arguments. Other functions require one or more comma-separated
arguments and can have additional optional arguments. All ColdFusion functions return a value. For example,
Round(3.14159) returns the value 3.

Built-in functions
ColdFusion built-in functions perform a variety of tasks, including, but not limited to, the following:

•

Creating and manipulating complex data variables, such as arrays, lists, and structures

•

Creating and manipulating queries

•

Creating, analyzing, manipulating, and formatting strings and date and time values

•

Evaluating the values of dynamic data

•

Determining the type of a variable value

•

Converting data between formats

•

Performing mathematical operations

•

Getting system information and resources

For alphabetical and categorized lists of ColdFusion functions, see “ColdFusion Functions” on page 636 in the CFML
Reference.
You use built-in functions throughout ColdFusion pages. Built-in functions are frequently used in a cfset or
cfoutput tag to prepare data for display or further use. For example, the following line displays today’s date in the
format October 24, 2007:
#DateFormat(Now(), "mmmm d, yyyy")#

Note that this code uses two nested functions. The Now function returns a ColdFusion date-time value representing
the current date and time. The DateFormat function takes the value returned by the Now function and converts it to
the desired string representation.
Functions are also valuable in CFScript scripts. ColdFusion does not support ColdFusion tags in CFScript, so you
must use functions to access ColdFusion functionality in scripts.

User-defined functions
You can write your own functions, user-defined functions (UDFs). You can use these functions in ColdFusion expressions or in CFScript. You can call a user-defined function anywhere you can use a built-in CFML function. You create
UDFs using the cffunction tag or the CFScript function statement. UDFs that you create using the cffunction
tag can include ColdFusion tags and functions. UDFs that you create in CFScript can only include functions. You
can create stand-alone UDFs or encapsulate them in a ColdFusion component.

ADOBE COLDFUSION 8 15
ColdFusion Developer’s Guide

User-defined functions let you encapsulate logic and operations that you use frequently in a single unit. This way,
you can write the code once and use it multiple times. UDFs ensure consistency of coding and enable you to structure
your CFML more efficiently.
Typical user-defined functions include mathematical routines, such as a function to calculate the logarithm of a
number; string manipulation routines, such as a function to convert a numeric monetary value to a string such as
“two dollars and three cents”; and can even include encryption and decryption routines.
Note: The Common Function Library Project at www.cflib.org includes a number of free libraries of user-defined
functions.
For more information on user-defined functions, see “Writing and Calling User-Defined Functions” on page 134.

ColdFusion components
ColdFusion components encapsulate multiple, related, functions. A ColdFusion component is essentially a set of
related user-defined functions and variables, with additional functionality to provide and control access to the
component contents. ColdFusion components can make their data private, so that it is available to all functions (also
called methods) in the component, but not to any application that uses the component.
ColdFusion components have the following features:

•

They are designed to provide related services in a single unit.

•

They can provide web services and make them available over the Internet.

•

They can provide ColdFusion services that Flash clients can call directly.

• They have several features that are familiar to object-oriented programmers, including data hiding, inheritance,
packages, and introspection.
For more information on ColdFusion components, see “Building and Using ColdFusion Components” on page 158.

Constants
The value of a constant does not change during program execution. Constants are simple scalar values that you can
use within expressions and functions, such as “Robert Trent Jones” and 123.45. Constants can be integers, real
numbers, time and date values, Boolean values, or text strings. ColdFusion does not allow you to give names to
constants.

Variables
Variables are the most frequently used operands in ColdFusion expressions. Variable values can be set and reset, and
can be passed as attributes to CFML tags. Variables can be passed as parameters to functions, and can replace most
constants.
ColdFusion has a number of built-in variables that provide information about the server and are returned by
ColdFusion tags. For a list of the ColdFusion built-in variables, see “Reserved Words and Variables” on page 2 in the
CFML Reference.

ADOBE COLDFUSION 8 16
ColdFusion Developer’s Guide

The following two characteristics classify a variable:

•

The scope of the variable, which indicates where the information is available and how long the variable persists

• The data type of the variable’s value, which indicates the kind of information a variable represents, such as
number, string, or date
The following section lists and briefly describes the variable scopes. “Data types” on page 17 lists data types (which
also apply to constant values). For detailed information on ColdFusion variables, including data types, scopes, and
their use, see “Using ColdFusion Variables” on page 24.

Variable scopes
The following table describes ColdFusion variable scopes:
Scope

Description

Variables (local)

The default scope for variables of any type that are created with the cfset and cfparam tags. A local variable is
available only on the page on which it is created and any included pages.

Form

The variables passed from a form page to its action page as the result of submitting the form.

URL

The parameters passed to the current page in the URL that is used to call it.

Attributes

The values passed by a calling page to a custom tag in the custom tag’s attributes. Used only in custom tag pages.

Caller

A reference, available in a custom tag, to the Variables scope of the page that calls the tag. Used only in custom tag
pages.

ThisTag

Variables that are specific to a custom tag, including built-in variables that provide information about the tag. Used
only in custom tag pages. A nested custom tag can use the cfassociate tag to return values to the calling tag’s
ThisTag scope.

Request

Variables that are available to all pages, including custom tags and nested custom tags, that are processed in
response to an HTTP request. Used to hold data that must be available for the duration of one HTTP request.

CGI

Environment variables identifying the context in which a page was requested. The variables available depend on the
browser and server software.

Cookie

Variables maintained in a user’s browser as cookies.

Client

Variables that are associated with one client. Client variables let you maintain state as a user moves from page to
page in an application and are available across browser sessions.

Session

Variables that are associated with one client and persist only as long as the client maintains a session.

Application

Variables that are associated with one, named, application on a server. The Application.cfc initialization code or the
cfapplication tag name attribute specifies the application name.

Server

Variables that are associated with the current ColdFusion server. This scope lets you define variables that are available to all your ColdFusion pages, across multiple applications.

Flash

Variables sent by an Adobe Flash movie to ColdFusion and returned by ColdFusion to the movie.

Arguments

Variables passed in a call to a user-defined function or ColdFusion component method.

This

Variables that are declared inside a ColdFusion component or in a cffunction tag that is not part of a ColdFusion
component.

function local

Variables that are declared in a user-defined function and exist only while the function executes.

ADOBE COLDFUSION 8 17
ColdFusion Developer’s Guide

Expressions
ColdFusion expressions consist of operands and operators. Operands are comprised of constants and variables, such
as "Hello" or MyVariable. Operators, such as the string concatenation operator (&) or the division operator (/) are
the verbs that act on the operands. ColdFusion functions also act as operators.
The simplest expression consists of a single operand with no operators. Complex expressions consist of multiple
operands and operators. For example, the following statements are all ColdFusion expressions:
12
MyVariable
(1 + 1)/2
"father" & "Mother"
Form.divisor/Form.dividend
Round(3.14159)

For detailed information on using variables, see “Using ColdFusion Variables” on page 24. For detailed information
on expressions and operators, see “Using Expressions and Number Signs” on page 50.

Data types
ColdFusion is considered typeless because you do not explicitly specify variable data types.
However, ColdFusion data, the constants and the data that variables represent, do have data types, which correspond
to the ways the data is stored on the computer.
ColdFusion data belongs to the following type categories:
Category

Description and types

Simple

Represents one value. You can use simple data types directly in ColdFusion expressions. ColdFusion simple data
types are:

•

strings
a test.”

A sequence of alphanumeric characters enclosed in single or double quotation marks, such as “This is

•

integers A sequence of numbers written without quotation marks, such as 356.

•

real numbers, such as -3.14159

•

Boolean values Use True, Yes, or 1 for true and False, No, or 0 for false. Boolean values are not case-sensitive.

•

date-time values ColdFusion supports a variety of data formats. For more information, see “Date and time
formats” on page 29.
Complex

A container for data. Complex variables generally represent more than one value. ColdFusion built-in complex data
types are:

•

arrays

•

structures

•

queries

Binary

Raw data, such as the contents of a GIF file or an executable program file

Object

COM, CORBA, Java, web services, and ColdFusion Component objects: Complex objects that you create and access
using the cfobject tag and other specialized tags.

ADOBE COLDFUSION 8 18
ColdFusion Developer’s Guide

Note: ColdFusion does not have a data type for unlimited precision decimal numbers, but it can represent such numbers
as strings and provides a function that supports unlimited precision decimal arithmetic. For more information, see
PrecisionEvaluate in the CFML Reference.
For more information on ColdFusion data types, see “Using ColdFusion Variables” on page 24.

Flow control
ColdFusion provides several tags that let you control how a page gets executed. These tags generally correspond to
programming language flow control statements, such as if, then, and else. The following tags provide ColdFusion
flow control:
Tags

Purpose

cfif, cfelseif, cfelse

Select sections of code based on whether expressions are True or False.

cfswitch, cfcase,
cfdefaultcase

Select among sections of code based on the value of an expression. Case processing is not limited to True
and False conditions.

cfloop, cfbreak

Loop through code based on any of the following values: entries in a list, keys in a structure or external
object, entries in a query column, an index, or the value of a conditional expression.

cfabort, cfexit

End processing of a ColdFusion page or custom tag.

This section provides a basic introduction to using flow-control tags. CFScript also provides a set of flow-control
statements. For information on using flow-control statements in CFScript, see “Extending ColdFusion Pages with
CFML Scripting” on page 92. For more details on using flow-control tags, see the reference pages for these tags in
the CFML Reference.

cfif, cfelseif, and cfelse
The cfif, cfelseif, and cfelse tags provide if-then-else conditional processing, as follows:
1

The cfif tag tests a condition and executes its body if the condition is True.

If the preceding cfif (or cfelseif ) test condition is False, the cfelseif tag tests another condition and
executes its body if that condition is True.

2

3 The cfelse tag can optionally follow a cfif tag and zero or more cfelseif tags. Its body executes if all the
preceding tags’ test conditions are False.

The following example shows the use of the cfif, cfelseif, and cfelse tags. If the value of the type variable is
“Date,” the date displays; if the value is “Time,” the time displays; otherwise, both the time and date display.

#DateFormat(Now())#

#TimeFormat(Now())#

#TimeFormat(Now())#, #DateFormat(Now())#


cfswitch, cfcase, and cfdefaultcase
The cfswitch, cfcase, and cfdefaultcase tags let you select among different code blocks based on the value of
an expression. ColdFusion processes these tags as follows:

ADOBE COLDFUSION 8 19
ColdFusion Developer’s Guide

The cfswitch tag evaluates an expression. The cfswitch tag body contains one or more cfcase tags and
optionally includes cfdefaultcase tag.

1

Each cfcase tag in the cfswitch tag body specifies a value or set of values. If a value matches the value determined by the expression in the cfswitch tag, ColdFusion runs the code in the body of the cfcase tag and then exits
the cfswitch tag. If two cfcase tags have the same condition, ColdFusion generates an error.

2

If none of the cfcase tags match the value determined by the cfswitch tag, and the cfswitch tag body includes
a cfdefaultcase tag, ColdFusion runs the code in the cfdefaultcase tag body.

3

Note: Although the cfdefaultcase tag does not have to follow all cfcase tags, it is good programming practice to put
it at the end of the cfswitch statement.
The cfswitch tag provides better performance than a cfif tag with multiple cfelseif tags, and is easier to read.
Switch processing is commonly used when different actions are required based on a string variable such as a month
or request identifier.
The following example shows switch processing:



#FirstName# #LastName# is in Sales




#FirstName# #LastName# is in Accounting




#FirstName# #LastName# is in Administration



#FirstName# #LastName# is not in Sales,
Accounting, or Administration.





cfloop and cfbreak
The cfloop tag loops through the tag body zero or more times based on a condition specified by the tag attributes.
The cfbreak tag exits a cfloop tag.
cfloop

The cfloop tag provides the following types of loops:
Loop type

Description

Index

Loops through the body of the tag and increments a counter variable by a specified amount after each loop until the
counter reaches a specified value.

Conditional

Checks a condition and runs the body of the tag if the condition is True.

Query

Loops through the body of the tag once for each row in a query.

List, file, or array

Loops through the body of the tag once for each entry in a list, each line in a file, or each item in an array.

Collection

Loops through the body of the tag once for each key in a ColdFusion structure or item in a COM/DCOM object.

The following example shows a simple index loop:


ADOBE COLDFUSION 8 20
ColdFusion Developer’s Guide

The loop index is #LoopCount#.



The following example shows a simple conditional loop. The code does the following:
1

Sets up a ten-element array with the word “kumquats” in the fourth entry.

Loops through the array until it encounters an array element containing “kumquats” or it reaches the end of the
array.
2

3 Prints out the value of the Boolean variable that indicates whether it found the word kumquats and the array
index at which it exited the loop.













i is #i#

foundit is #foundit#



Note: You can get an infinite conditional loop if you do not force an end condition. In this example, the loop is infinite
if you omit the  statement. To end an infinite loop, stop the ColdFusion application server.
cfbreak

The cfbreak tag exits the cfloop tag. You typically use it in a cfif tag to exit the loop if a particular condition
occurs. The following example shows the use of a cfbreak tag in a query loop:


You cannot order kumquats!



You have ordered #quantity# #fruit#.



cfabort and cfexit
The cfabort tag stops processing of the current page at the location of the cfabort tag. ColdFusion returns to the
user or calling tag everything that was processed before the cfabort tag. You can optionally specify an error message
to display. You can use the cfabort tag as the body of a cfif tag to stop processing a page when a condition, typically
an error, occurs.
The cfexit tag controls the processing of a custom tag, and can only be used in ColdFusion custom tags. For more
information see, “Terminating tag execution” on page 200 and the CFML Reference.

ADOBE COLDFUSION 8 21
ColdFusion Developer’s Guide

Character case
ColdFusion is case-insensitive. For example, the following all represent the cfset tag: cfset, CFSET, CFSet, and
even cfsEt. However, you should get in the habit of consistently using the same case rules in your programs; for
example:

• Develop consistent rules for case use, and stick to them. If you use lowercase characters for some tag names, use
them for all tag names.
• Always use the same case for a variable. For example, do not use both myvariable and MyVariable to represent
the same variable on a page.
Follow these rules to prevent errors on application pages where you use both CFML and case-sensitive languages,
such as JavaScript.

Special characters
The double-quotation marks ("), single-quotation mark ('), and number sign (#) characters have special meaning to
ColdFusion. To include any of them in a string, double the character; for example, use ## to represent a single #
character.
The need to escape the single- and double-quotation marks is context-sensitive. Inside a double-quoted string, you
do not need to escape single-quotation mark (apostrophe) characters. Inside a single-quoted string, you do not
escape double-quotation mark characters.
The following example illustrates escaping special characters, including the use of mixed single- and doublequotation marks:



#mystring#

#mystring2#

Here is a number sign: ##


The output looks like this:
We all said "Happy birthday to you."
Then we said "How old are you now?"
Here is a number sign: #

Reserved words
As with any programming tool, you cannot use just any word or name for ColdFusion variables, UDFs and custom
tags. You must avoid using any name that can be confused with a ColdFusion element. In some cases, if you use a
word that ColdFusion uses—for example, a built-in structure name—you can overwrite the ColdFusion data.
The following list indicates words you must not use for ColdFusion variables, user-defined function names, or
custom tag names. While some of these words can be used safely in some situations, you can prevent errors by
avoiding them entirely. For a complete list of reserved words, see the CFML Reference.

ADOBE COLDFUSION 8 22
ColdFusion Developer’s Guide

•

Built-in function names, such as Now or Hash

•

Scope names, such as Form or Session

• Any name starting with cf. However, when you call a CFML custom tag directly, you prefix the custom tag page
name with cf_.
•

Operators, such as NE or IS

•

The names of any built-in data structures, such as Error or File

•

The names of any built-in variables, such as RecordCount or CGI variable names

•

CFScript language element names such as for, default, or continue

You must also not create form field names ending in any of the following, except to specify a form field validation
rule using a hidden form field name. (For more information on form field validation, see “Introduction to Retrieving
and Formatting Data” on page 511.)

•

_integer

•

_float

•

_range

•

_date

•

_time

•

_eurodate

Because ColdFusion is not case-sensitive, all of the following are reserved words: IS, Is, iS, and is.

CFScript
CFScript is a language within a language. CFScript is a scripting language that is similar to JavaScript but is simpler
to use. Also, unlike JavaScript, CFScript only runs on the ColdFusion server; it does not run on the client system. A
CFScript script can use all ColdFusion functions and all ColdFusion variables that are available in the script’s scope.
CFScript provides a compact and efficient way to write ColdFusion logic. Typical uses of CFScript include:

•

Simplifying and speeding variable setting

•

Building compact flow control structures

•

Encapsulating business logic in user-defined functions

The following sample script populates an array and locates the first array entry that starts with the word “key”. It
shows several of the elements of CFScript, including setting variables, loop structures, script code blocks, and
function calls. Also, the code uses a cfoutput tag to display its results. Although you can use CFScript for output,
the cfoutput tag is usually easier to use.

strings = ArrayNew(1);
strings[1]="the";
strings[2]="key to our";
strings[4]="idea";
for( i=1 ; i LE 4 ; i = i+1 )
{
if(Find("key",strings[i],1))
break; }

ADOBE COLDFUSION 8 23
ColdFusion Developer’s Guide


Entry #i# starts with "key"


You use CFScript to create user-defined functions.
For more information on CFScript, see “Extending ColdFusion Pages with CFML Scripting” on page 92. For more
information on user-defined functions, see “Writing and Calling User-Defined Functions” on page 134.

24

Chapter 3: Using ColdFusion Variables
Adobe ColdFusion variables are the most frequently used operands in ColdFusion expressions. Variable values can
be set and reset, and can be passed as attributes to CFML tags. Variables can be passed as parameters to functions,
and can replace most constants.
To create and use ColdFusion variables, you should know the following:

•

How variables can represent different types of data

•

How the data types get converted

•

How variables exist in different scopes

•

How the scopes are used

•

How to use variables correctly

Contents

Creating variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Variable characteristics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Data types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Using periods in variable references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Data type conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
About scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Ensuring variable existence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Validating data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Passing variables to custom tags and UDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Creating variables
You create most ColdFusion variables by assigning them values. (You must use the ArrayNew function to create
arrays.) Most commonly, you create variables by using the cfset tag. You can also use the cfparam tag, and
assignment statements in CFScript. Tags that create data objects also create variables. For example, the cfquery tag
creates a query object variable.
ColdFusion automatically creates some variables that provide information about the results of certain tags or operations. ColdFusion also automatically generates variables in certain scopes, such as Client and Server. For information
on these special variables, see “Reserved Words and Variables” on page 2 in the CFML Reference and the documentation of the CFML tags that create these variables.
ColdFusion generates an error when it tries to use a variable before it is created. This can happen, for example, when
processing data from an incompletely filled form. To prevent such errors, test for the variable’s existence before you
use it. For more information on testing for variable existence, see “Ensuring variable existence” on page 46.
For more information on how to create variables, see “Creating and using variables in scopes” on page 43.

ADOBE COLDFUSION 8 25
ColdFusion Developer’s Guide

Variable naming rules
ColdFusion variable names, including form field names and custom function and ColdFusion component argument
names, must conform to Java naming rules and the following guidelines:

•

A variable name must begin with a letter, underscore, or Unicode currency symbol.

• The initial character can by followed by any number of letters, numbers, underscore characters, and Unicode
currency symbols.
•

A variable name cannot contain spaces.

•

A query result is a type of variable, so it overwrites a local variable with the same name.

•

ColdFusion variables are not case-sensitive. However, consistent capitalization makes the code easier to read.

• When creating a form with fields that are used in a query, match form field names with the corresponding
database field names.
• Periods separate the components of structure or object names. They also separate a variable scope from the
variable name. You cannot use periods in simple variable names, with the exception of variables in the Cookie and
Client scopes. For more information on using periods, see “Using periods in variable references” on page 35.
The following rule applies to variable names, but does not apply to form field and argument names:
1 Prefix each variable’s name with its scope. Although some ColdFusion programmers do not use the Variables
prefix for local variable names, you should use prefixes for all other scopes. Using scope prefixes makes variable
names clearer and increases code efficiency. In many cases, you must prefix the scope. For more information, see
“About scopes” on page 42.

Note: In some cases, when you use an existing variable name, you must enclose it with number signs (#) to allow
ColdFusion to distinguish it from string or HTML text, and to insert its value, as opposed to its name. For more information, see “Using number signs” on page 55.

Variable characteristics
You can classify a variable using the following characteristics:

• The data type of the variable value, which indicates the kind of information a variable represents, such as
number, string, or date
•

The scope of the variable, which indicates where the information is available and how long the variable persists

The following sections provide detailed information on Data types and scopes.

Data types
ColdFusion is often referred to as typeless because you do not assign types to variables and ColdFusion does not
associate a type with the variable name. However, the data that a variable represents does have a type, and the data
type affects how ColdFusion evaluates an expression or function argument. ColdFusion can automatically convert
many data types into others when it evaluates expressions. For simple data, such as numbers and strings, the data
type is unimportant until the variable is used in an expression or as a function argument.
ColdFusion variable data belongs to one of the following type categories:

ADOBE COLDFUSION 8 26
ColdFusion Developer’s Guide

• Simple: One value. Can use directly in ColdFusion expressions. Include numbers, strings, Boolean values, and
date-time values.
• Complex: A container for data. Generally represent more than one value. ColdFusion built-in complex data
types include arrays, structures, queries, and XML document objects.
You cannot use a complex variable, such as an array, directly in a ColdFusion expression, but you can use simple
data type elements of a complex variable in an expression.
For example, with a one-dimensional array of numbers called myArray, you cannot use the expression myArray
* 5. However, you could use an expression myArray[3] * 5 to multiply the third element in the array by five.

•

Binary: Raw data, such as the contents of a GIF file or an executable program file.

• Objects: Complex constructs. Often encapsulate both data and functional operations. The following table lists
the types of objects that ColdFusion can use, and identifies the chapters that describe how to use them:
Object type

See

Component Object Model (COM)

“Integrating COM and CORBA Objects in CFML Applications” on page 972

Common Object Request Broker Architecture (CORBA)

“Integrating COM and CORBA Objects in CFML Applications” on page 972

Java

“Integrating J2EE and Java Elements in CFML Applications” on page 927

ColdFusion component

“Building and Using ColdFusion Components” on page 158

Web service

“Using Web Services” on page 900

Data type notes

Although ColdFusion variables do not have types, it is often convenient to use “variable type” as a shorthand for the
type of data that the variable represents.
ColdFusion can validate the type of data contained in form fields and query parameters. For more information, see
“Testing for a variable’s existence” on page 517 and “Using cfqueryparam” on page 399.
The cfdump tag displays the entire contents of a variable, including ColdFusion complex data structures. It is an
excellent tool for debugging complex data and the code that handles it.
ColdFusion provides the following functions for identifying the data type of a variable:

•

IsArray

•

IsBinary

•

IsBoolean

•

IsObject

•

IsQuery

•

IsSimpleValue

•

IsStruct

•

IsXmlDoc

ColdFusion also includes the following functions for determining whether a string can be represented as or
converted to another data type:

•

IsDate

•

IsNumeric

ADOBE COLDFUSION 8 27
ColdFusion Developer’s Guide

•

IsXML

ColdFusion does not use a null data type. However, if ColdFusion receives a null value from an external source such
as a database, a Java object, or some other mechanism, it maintains the null value until you use it as a simple value.
At that time, ColdFusion converts the null to an empty string (""). Also, you can use the JavaCast function in a call
to a Java object to convert a ColdFusion empty string to a Java null.

Numbers
ColdFusion supports integers and real numbers. You can intermix integers and real numbers in expressions; for
example, 1.2 + 3 evaluates to 4.2.
Integers

ColdFusion supports integers between -2,147,483,648 and 2,147,483,647 (32-bit signed integers). You can assign a
value outside this range to a variable, but ColdFusion initially stores the number as a string. If you use it in an arithmetic expression, ColdFusion converts it into a floating point value, preserving its value, but losing precision as the
following example shows:


mybignum is: #mybignum#

mybignumtimes10 is: #mybignumtimes10# 


This example generates the following output:
mybignum is: 12345678901234567890
mybignumtimes10 is: 1.23456789012E+020
Real numbers

Real numbers, numbers with a decimal part, are also known as floating point numbers. ColdFusion real numbers
can range from approximately -10300 to approximately 10300. A real number can have up to 12 significant digits. As
with integers, you can assign a variable a value with more digits, but the data is stored as a string. The string is
converted to a real number, and can lose precision, when you use it in an arithmetic expression.
You can represent real numbers in scientific notation. This format is xEy, where x is a positive or negative real
number in the range 1.0 (inclusive) to 10 (exclusive), and y is an integer. The value of a number in scientific notation
is x times 10y. For example, 4.0E2 is 4.0 times 102, which equals 400. Similarly, 2.5E-2 is 2.5 times 10-2, which equals
0.025. Scientific notation is useful for writing very large and very small numbers.
BigDecimal numbers

ColdFusion does not have a special BigDecimal data type for arbitrary length decimal numbers such as
1234567890987564.234678503059281. Instead, it represent such numbers as strings. ColdFusion does, however,
have a PrecisionEvaluate function that can take an arithmetic expression that uses BigDecimal values, calculate
the expression, and return a string with the resulting BigDecimal value. For more information, see
PrecisionEvaluate in the CFML Reference.

Strings
In ColdFusion, text values are stored in strings. You specify strings by enclosing them in either single- or doublequotation marks. For example, the following two strings are equivalent:

ADOBE COLDFUSION 8 28
ColdFusion Developer’s Guide

"This is a string"
'This is a string'
You can write an empty string in the following ways:

•

"" (a pair of double-quotation marks with nothing in between)

•

'' (a pair of single-quotation marks with nothing in between)

Strings can be any length, limited by the amount of available memory on the ColdFusion server. However, the default
size limit for long text retrieval (CLOB) is 64K. The ColdFusion Administrator lets you increase the limit for
database string transfers, but doing so can reduce server performance. To change the limit, select the Enable retrieval
of long text option on the Advanced Settings page for the data source.
Escaping quotation marks and number signs

To include a single-quotation character in a string that is single-quoted, use two single-quotation marks (known as
escaping the single-quotation mark). The following example uses escaped single-quotation marks:

#mystring#


To include a double-quotation mark in a double-quoted string, use two double-quotation marks (known as escaping
the double-quotation mark). The following example uses escaped double-quotation marks:

#mystring#


Because strings can be in either double-quotation marks or single-quotation marks, both of the preceding examples
display the same text:
This is a single-quotation mark: ' This is a double-quotation mark: "
To insert a number sign (#) in a string, you must escape the number sign, as follows:
"This is a number sign ##"
Lists

ColdFusion includes functions that operate on lists, but it does not have a list data type. In ColdFusion, a list is just
a string that consists of multiple entries separated by delimiter characters.
The default delimiter for lists is the comma. If you use any other character to separate list elements, you must specify
the delimiter in the list function. You can also specify multiple delimiter characters. For example, you can tell
ColdFusion to interpret a comma or a semicolon as a delimiter, as the following example shows:


List length using ; and , as delimiters: #listlen(Mylist, ";,")#

List length using only , as a delimiter: #listlen(Mylist)#



This example displays the following output:
List length using ; and , as delimiters: 5
List length using only , as a delimiter: 3
Each delimiter must be a single character. For example, you cannot tell ColdFusion to require two hyphens in a row
as a delimiter.

ADOBE COLDFUSION 8 29
ColdFusion Developer’s Guide

If a list has two delimiters in a row, ColdFusion ignores the empty element. For example, if MyList is "1,2,,3,,4,,,5"
and the delimiter is the comma, the list has five elements and list functions treat it the same as "1,2,3,4,5".

Boolean values
A Boolean value represents whether something is true or false. ColdFusion has two special constants—True and
False—to represent these values. For example, the Boolean expression 1 IS 1 evaluates to True. The expression
"Monkey" CONTAINS "Money" evaluates to False.
You can use Boolean constants directly in expressions, as in the following example:


In Boolean expressions, True, nonzero numbers, and the string “Yes” are equivalent, and False, 0, and the string “No”
are equivalent.
In Boolean expressions, True, nonzero numbers, and the strings “Yes”, “1|”, “True” are equivalent; and False, 0, and
the strings “No”, “0”, and “False” are equivalent.
Boolean evaluation is not case-sensitive. For example, True, TRUE, and true are equivalent.

Date-Time values
ColdFusion can perform operations on date and time values. Date-time values identify a date and time in the range
100 AD to 9999 AD. Although you can specify just a date or a time, ColdFusion uses one data type representation,
called a date-time object, for date, time, and date and time values.
ColdFusion provides many functions to create and manipulate date-time values and to return all or part of the value
in several different formats.
You can enter date and time values directly in a cfset tag with a constant, as follows:


When you do this, ColdFusion stores the information as a string. If you use a date-time function, ColdFusion stores
the value as a date-time object, which is a separate simple data type. When possible, use date-time functions such as
CreateDate and CreateTime to specify dates and times, because these functions can prevent you from specifying
the date or time in an invalid format and they create a date-time object immediately.
Date and time formats

You can directly enter a date, time, or date and time, using standard U.S. date formats. ColdFusion processes the twodigit-year values 0 to 29 as twenty-first century dates; it processes the two-digit-year values 30 to 99 as twentieth
century dates. Time values can include units down to seconds. The following table lists valid date and time formats:

ADOBE COLDFUSION 8 30
ColdFusion Developer’s Guide

To specify

Use these formats

Date

October 30, 2003
Oct 30, 2003
Oct. 30, 2003
10/30/03
2003-10-30
10-30-2003

Time

02:34:12
2:34a
2:34am
02:34am
2am

Date and Time

Any combination of valid date and time formats, such as these:
October 30, 2003 02:34:12
Oct 30, 2003 2:34a
Oct. 30, 2001 2:34am
10/30/03 02:34am
2003-10-30 2am
10-30-2003 2am

Locale-specific dates and times

ColdFusion provides several functions that let you input and output dates and times (and numbers and currency
values) in formats that are specific to the current locale. A locale identifies a language and locality, such as English
(US) or French (Swiss). Use these functions to input or output dates and times in formats other than the U.S.
standard formats. (Use the SetLocale function to specify the locale.) The following example shows how to do this:

#LSDateFormat(Now(), "ddd, dd mmmm, yyyy")#

This example outputs a line like the following:
mar., 03 juin, 2003
For more information on international functions, see “Developing Globalized Applications” on page 336 and the
CFML Reference.
How ColdFusion stores dates and times

ColdFusion stores and manipulates dates and times as date-time objects. Date-time objects store data on a time line
as real numbers. This storage method increases processing efficiency and directly mimics the method used by many
popular database systems. In date-time objects, one day is equal to the difference between two successive integers.
The time portion of the date-and-time value is stored in the fractional part of the real number. The value 0 represents
12:00 AM 12/30/1899.
Although you can use arithmetic operations to manipulate date-and-time values directly, this method can result in
code that is difficult to understand and maintain. Use the ColdFusion date-time manipulation functions instead. For
information on these functions, see the CFML Reference.

ADOBE COLDFUSION 8 31
ColdFusion Developer’s Guide

Binary data type and binary encoding
Binary data (also referred to as a binary object) is raw data, such as the contents of a GIF file or an executable program
file. You do not normally use binary data directly, but you can use the cffile tag to read a binary file into a variable,
typically for conversion to a string binary encoding before transmitting the file using e-mail.
A string binary encoding represents a binary value in a string format that can be transmitted over the web.
ColdFusion supports three binary encoding formats:
Encoding

Format

Base64

Encodes the binary data in the lowest six bits of each byte. It ensures that binary data and non-ANSI character data
can be transmitted using e-mail without corruption. The Base64 algorithm is specified by IETF RFC 2045, at
www.ietf.org/rfc/rfc2045.txt.

Hex

Uses two characters in the range 0-9 and A-F represent the hexadecimal value of each byte; for example, 3A.

UU

Uses the UNIX UUencode algorithm to convert the data.

ColdFusion provides the following functions that convert among string data, binary data, and string encoded binary
data:
Function

Description

BinaryDecode

Converts a string that contains encoded binary data to a binary object.

BinaryEncode

Converts binary data to an encoded string.

CharsetDecode

Converts a string to binary data in a specified character encoding.

CharsetEncode

Converts a binary object to a string in a specified character encoding.

ToBase64

Converts string and binary data to Base64 encoded data.

ToBinary

Converts Base64 encoded data to binary data. The BinaryDecode function provides a superset of the ToBase64
functionality.

ToString

Converts most simple data types to string data. It can convert numbers, date-time objects, and boolean values. (It
converts date-time objects to ODBC timestamp strings.) Adobe recommends that you use the CharsetEncode
function to convert binary data to a string in new applications.

Complex data types
Arrays, structures, and queries are ColdFusion built-in complex data types. Structures and queries are sometimes
referred to as objects, because they are containers for data, not individual data values.
For details on using arrays and structures, see “Using Arrays and Structures” on page 68.
Arrays

Arrays are a way of storing multiple values in a table-like format that can have one or more dimensions. To create an
array and specify its initial dimensions, use the ColdFusion ArrayNew function. For example, the following line
creates an empty two-dimensional array:


You reference elements using numeric indexes, with one index for each dimension. For example, the following line
sets one element of a two-dimensional array to the current date and time:


ADOBE COLDFUSION 8 32
ColdFusion Developer’s Guide

The ArrayNew function can create arrays with up to three dimensions. However, there is no limit on array size or
maximum dimension. To create arrays with more than three dimensions, create arrays of arrays.
After you create an array, you can use functions or direct references to manipulate its contents.
When you assign an existing array to a new variable, ColdFusion creates a new array and copies the old array’s
contents to the new array. The following example creates a copy of the original array:


For more information on using arrays, see “Using Arrays and Structures” on page 68.
Structures

ColdFusion structures consist of key-value pairs, where the keys are text strings and the values can be any ColdFusion
data type, including other structures. Structures let you build a collection of related variables that are grouped under
a single name. To create a structure, use the ColdFusion StructNew function. For example, the following line creates
a new, empty, structure called depts:


You can also create a structure by assigning a value in the structure. For example, the following line creates a new
structure called MyStruct with a key named MyValue, equal to 2:


Note: In previous ColdFusion versions, this line created a Variables scope variable named "MyStruct.MyValue" with the
value 2.
After you create a structure, you can use functions or direct references to manipulate its contents, including adding
key-value pairs.
You can use either of the following methods to reference elements stored in a structure:

• StructureName.KeyName
• StructureName["KeyName"]
The following examples show these methods:
depts.John="Sales"
depts["John"]="Sales"

When you assign an existing structure to a new variable, ColdFusion does not create a new structure. Instead, the
new variable accesses the same data (location) in memory as the original structure variable. In other words, both
variables are references to the same object.
For example, the following line creates a new variable, myStructure2, that is a reference to the same structure as the
myStructure variable:


When you change the contents of myStructure2, you also change the contents of myStructure. To copy the contents
of a structure, use the ColdFusion Duplicate function, which copies the contents of structures and other complex
data types.
Structure key names can be the names of complex data objects, including structures or arrays. This lets you create
arbitrarily complex structures.
For more information on using structures, see “Using Arrays and Structures” on page 68.

ADOBE COLDFUSION 8 33
ColdFusion Developer’s Guide

Queries

A query object, sometimes referred to as a query, query result, or record set, is a complex ColdFusion data type that
represents data in a set of named columns, similar to the columns of a database table. The following ColdFusion tags
can create query objects:

• cfquery
• cfdirectory
• cfhttp
• cfldap
• cfpop
• cfprocresult
In these tags, the name attribute specifies the query object’s variable name. The QueryNew function also creates query
objects.
When you assign a query to a new variable, ColdFusion does not copy the query object. Instead, both names point
to the same record set data. For example, the following line creates a new variable, myQuery2, that references the
same record set as the myQuery variable:


If you make changes to data in myQuery, myQuery2 also shows those changes.
You reference query columns by specifying the query name, a period, and the column name; for example:
myQuery.Dept_ID

When you reference query columns inside tags, such as cfoutput and cfloop, in which you specify the query name
in a tag attribute, you do not have to specify the query name.
You can access query columns as if they are one-dimensional arrays. For example, the following line assigns the
contents of the Employee column in the second row of the myQuery query to the variable myVar:


Note: You cannot use array notation to refer to a row (of all columns) of a query. For example, myQuery[2] does not
refer to the second row of the myQuery query object.
Working with structures and queries

Because structure variables and query variables are references to objects, the rules in the following sections apply to
both types of data.
Multiple references to an object

When multiple variables refer to a structure or query object, the object continues to exist as long as at least one
reference to the object exists. The following example shows how this works:
 depts = structnew();




#newStructure.John#

#depts#


This example displays the following output:
Sales

ADOBE COLDFUSION 8 34
ColdFusion Developer’s Guide

0
After the  tag executes, the depts variable does not refer to a structure; it is a simple variable with
the value 0. However, the variable newStructure still refers to the original structure object.
Assigning objects to scopes

You can give a query or structure a different scope by assigning it to a new variable in the other scope. For example,
the following line creates a server variable, Server.SScopeQuery, using the local myquery variable:


To clear the server scope query variable, reassign the query object, as follows:


This deletes the reference to the object from the server scope, but does not remove any other references that might
exist.
Copying and duplicating objects

You can use the Duplicate function to make a true copy of a structure or query object. Changes to the copy do not
affect the original.
Using a query column

When you are not inside a cfloop, cfoutput, or cfmail tag that has a query attribute, you can treat a query column
as an array. However, query column references do not always behave as you might expect. This section explains the
behavior of references to query columns using the results of the following cfquery tag in its examples:

SELECT FirstName, LastName
FROM Employee


To reference elements in a query column, use the row number as an array index. For example, both of the following
lines display the word "ben":
 #myQuery.Firstname[1]# 

 #myQuery["Firstname"][1]# 


ColdFusion behavior is less straightforward, however, when you use the query column references
myQuery.Firstname and myQuery["Firstname"] without using an array index. The two reference formats produce
different results.
If you refer to myQuery.Firstname, ColdFusion automatically converts it to the first row in the column. For example,
the following lines print the word "ben":

#mycol#

But the following lines display an error message:

#mycol[1]#


If you refer to Query["Firstname"], ColdFusion does not automatically convert it to the first row of the column.
For example, the following line results in an error message indicating that ColdFusion cannot convert a complex type
to a simple value:
 #myQuery['Firstname']# 


Similarly, the following lines print the name "marjorie", the value of the second row in the column:

ADOBE COLDFUSION 8 35
ColdFusion Developer’s Guide


#mycol[2]#


However, when you make an assignment that requires a simple value, ColdFusion automatically converts the query
column to the value of the first row. For example, the following lines display the name "ben" twice:
 #myQuery.Firstname# 


 #myVar# 


Using periods in variable references
ColdFusion uses the period (.) to separate elements of a complex variable such as a structure, query, XML document
object, or external object, as in MyStruct.KeyName. A period also separates a variable scope identifier from the
variable name, as in Variables.myVariable or CGI.HTTP_COOKIE.
With the exception of Cookie and Client scope variables, which must always be simple variable types, you cannot
normally include periods in simple variable names. However, ColdFusion makes some exceptions that accommodate legacy and third-party code that does not conform to this requirement.
For more information, see “About scopes” on page 42, “Using Arrays and Structures” on page 68, and “Using XML
and WDDX” on page 865.

Understanding variables and periods
The following descriptions use a sample variable named MyVar.a.b to explain how ColdFusion uses periods when
getting and setting the variable value.
Getting a variable

ColdFusion can correctly get variable values even if the variable name includes a period. For example, the following
set of steps shows how ColdFusion gets MyVar.a.b, as in  or IsDefined(myVar.a.b):
1

Looks for myVar in an internal table of names (the symbol table).

2

If myVar is the name of a complex object, including a scope, looks for an element named a in the object.
If myVar is not the name of a complex object, checks whether myVar.a is the name of a complex object and skips
step 3.

3

If myVar is the name of a complex object, checks whether a is a complex object.

4 If a or myVar.a is the name of a complex object, checks whether b is the name of a simple variable, and returns
the value of b.

If myVar is a complex object but a is not a complex object, checks whether a.b is the name of a simple variable
and returns its value.
If myVar.a is not a complex object, checks whether myVar.a.b is the name of a simple variable and returns its
value.
This way, ColdFusion correctly resolves the variable name and can get its value.
You can also use array notation to get a simple variable with a name that includes periods. In this form of array
notation, you use the scope name (or the complex variable that contains the simple variable) as the “array” name.
You put the simple variable name, in single- or double-quotation marks, inside the square brackets.

ADOBE COLDFUSION 8 36
ColdFusion Developer’s Guide

Using array notation is more efficient than using plain dot notation because ColdFusion does not have to analyze
and look up all the possible key combinations. For example, both of the following lines write the value of myVar.a.b,
but the second line is more efficient than the first:
myVar.a.b is: #myVar.a.b#

myVar.a.b is: #Variables["myVar.a.b"]#


Setting a variable

ColdFusion cannot be as flexible when it sets a variable value as when it gets a variable, because it must determine
the type of variable to create or set. Therefore, the rules for variable names that you set are stricter. Also, the rules
vary depending on whether the first part of the variable name is the Cookie or Client scope identifier.
For example, assume you have the following code:


If a variable myVar does not exist, it does the following:
1

Creates a structure named myVar.

2

Creates a structure named a in the structure myVar.

3

Creates a key named b in myVar.a.

4

Gives it the value "This is a test".

If either myVar or myVar.a exist and neither one is a structure, ColdFusion generates an error.
In other words, ColdFusion uses the same rules as for getting a variable to resolve the variable name until it finds a
name that does not exist yet. It then creates any structures that are needed to create a key named b inside a structure,
and assigns the value to the key.
However, if the name before the first period is either Cookie or Client, ColdFusion uses a different rule. It treats all
the text (including any periods) that follow the scope name as the name of a simple variable, because Cookie and
Client scope variables must be simple. If you have the following code, you see that ColdFusion creates a single, simple
Client scope variable named myVar.a.b:



Creating variables with periods
You should avoid creating the names of variables (except for dot notation in structures) that include periods.
However, ColdFusion provides mechanisms for handling cases where you must do so, for example, to maintain
compatibility with names of variables in external data sources or to integrate your application with existing code that
uses periods in variable names. The following sections describe how to create simple variable names that include
periods.
Using brackets to create variables with periods

You can create a variable name that includes periods by using associative array structure notation, as described in
“Structure notation” on page 79. To do so, you must do the following:

• Refer to the variable as part of a structure. You can always do this, because ColdFusion considers all scopes to be
structures. For more information on scopes, see “About scopes” on page 42.
•

Put the variable name that must include a period inside square brackets and single- or double-quotation marks.

The following example shows this technique:

ADOBE COLDFUSION 8 37
ColdFusion Developer’s Guide




My.Variable.With.Periods is: #My.Variable.With.Periods#

Request.Another.Variable.With.Periods is:
#Request.Another.Variable.With.Periods#


Creating Client and Cookie variables with periods

To create a Client or Cookie variable with a name that includes one or more periods, simply assign the variable a
value. For example, the following line creates a Cookie named User.Preferences.CreditCard:


Data type conversion
ColdFusion automatically converts between data types to satisfy the requirements of an expression’s operations,
including a function’s argument requirements. As a result, you generally don’t need to be concerned about compatibility between data types and the conversions from one data type to another. However, understanding how
ColdFusion evaluates data values and converts data between types can help you prevent errors and create code more
effectively.

Operation-driven evaluation
Conventional programming languages enforce strict rules about mixing objects of different types in expressions. For
example, in a language such as C++ or Basic, the expression ("8" * 10) produces an error because the multiplication operator requires two numerical operands and "8" is a string. When you program in such languages, you must
convert between data types to ensure error-free program execution. For example, the previous expression might have
to be written as (ToNumber("8") * 10).
In ColdFusion, however, the expression ("8" * 10) evaluates to the number 80 without generating an error. When
ColdFusion processes the multiplication operator, it automatically attempts to convert its operands to numbers.
Since "8" can be successfully converted to the number 8, the expression evaluates to 80.
ColdFusion processes expressions and functions in the following sequence:
1 For each operator in an expression, it determines the required operands. (For example, the multiplication
operator requires numeric operands and the CONTAINS operator requires string operands.)

For functions, it determines the type required for each function argument. (For example, the Min function
requires two numbers as arguments and the Len function requires a string.)
2

It evaluates all operands or function arguments.

3 It converts all operands or arguments whose types differ from the required type. If a conversion fails, it reports
an error.

Conversion between types
Although the expression evaluation mechanism in ColdFusion is very powerful, it cannot automatically convert all
data. For example, the expression "eight" * 10 produces an error because ColdFusion cannot convert the string
"eight" to the number 8. Therefore, you must understand the rules for conversion between data types.

ADOBE COLDFUSION 8 38
ColdFusion Developer’s Guide

The following table explains how conversions are performed. The first column shows values to convert. The
remaining columns show the result of conversion to the listed data type.
Value

As Boolean

As number

As date-time

As string

"Yes"

True

1

Error

"Yes"

"No"

False

0

Error

"No"

True

True

1

Error

"Yes"

False

False

0

Error

"No"

Number

True if Number is not 0;
False otherwise.

Number

See “Date-time values” earlier in String representation
this chapter.
of the number (for
example, “8”).

String

If "Yes", True

If it represents a number (for
example, "1,000" or "12.36E-12"), it is
If "No", False
converted to the corresponding
number. If it represents a date-time
If it can be converted to 0,
(see next column), it is converted to
False
the numeric value of the correIf it can be converted to any sponding date-time object.
other number, True

If it is an ODBC date, time, or
String
timestamp (for example "{ts
'2001-06-14 11:30:13'}", or if it is
expressed in a standard U.S.
date or time format, including
the use of full or abbreviated
month names, it is converted to
the corresponding date-time
value.
Days of the week or unusual
punctuation result in an error.
Dashes, forward-slashes, and
spaces are generally allowed.

Date

Error

The numeric value of the date-time
object.

Date

An ODBC timestamp.

ColdFusion cannot convert complex types, such as arrays, queries, and COM objects, to other types. However, it can
convert simple data elements of complex types to other simple data types.
Type conversion considerations

The following sections detail specific rules and considerations for converting between types.
The cfoutput tag

The cfoutput tag always displays data as a string. As a result, when you display a variable using the cfoutput tag,
ColdFusion applies the type conversion rules to any non-string data before displaying it. For example, the cfoutput
tag displays a date-time value as an ODBC timestamp.
Case-insensitivity and Boolean conversion

Because ColdFusion expression evaluation is not case-sensitive, Yes, YES, and yes are equivalent; False, FALSE, and
false are equivalent; No, NO, and no are equivalent; and True, TRUE, and true are equivalent.
Converting binary data

ColdFusion cannot automatically convert binary data to other data types. To convert binary data, use the ToBase64
and ToString functions. For more information, see “Binary data type and binary encoding” on page 31.
Converting date and time data

To ensure that a date and time value is expressed as a real number, add zero to the variable. The following example
shows this:

ADOBE COLDFUSION 8 39
ColdFusion Developer’s Guide


Use cfoutput to display the result of the now function:

#mynow#

Now add 0 to the result and display it again:


#mynow#

At 1:06 PM on June 6, 2003, its output looked like this:
Use cfoutput to display the result of the now function:
{ts '2003-06-03 13:06:44'}
Now add 0 to the result and display it again:
37775.5463426
Converting numeric values

When ColdFusion evaluates an expression that includes both integers and real numbers, the result is a real number.
To convert a real number to an integer, use a ColdFusion function. The Int, Round, Fix, and Ceiling functions
convert real numbers to integers, and differ in their treatment of the fractional part of the number.
If you use a hidden form field with a name that has the suffix _integer or _range to validate a form input field,
ColdFusion truncates real numbers entered into the field and passes the resulting integer to the action page.
If you use a hidden form field with a name that has the suffix _integer, _float, or _range to validate a form input
field, and the entered data contains a dollar amount (including a dollar sign) or a numeric value with commas,
ColdFusion considers the input to be valid, removes the dollar sign or commas from the value, and passes the
resulting integer or real number to the action page.
ColdFusion does not have an inherent data type for arbitrary precision decimal numbers (BigDecimal numbers).
ColdFusion initially saves such numbers as strings, and if you use them in an expression, converts the value to a
numeric type, often losing precision. You can retain precision by using the PrecisionEvaluate method, which
evaluates string expressions using BigDecimal precision arithmetic and can return the result as a long string of
numbers. For more information, see PrecisionEvaluate in the CFML Reference.

Evaluation and type conversion issues
The following sections explain several issues that you might encounter with type evaluation and conversion.
Comparing variables to True or False

You might expect the following two cfif tag examples to produce the same results:

myVariable equals #myVariable# and is True



myVariable equals #myVariable# and is True



However, if myVariable has a numeric value such as 12, only the first example produces a result. In the second case,
the value of myVariable is not converted to a Boolean data type, because the IS operator does not require a specific
data type and just tests the two values for identity. Therefore, ColdFusion compares the value 12 with the constant
True. The two are not equal, so nothing is printed. If myVariable is 1, "Yes", or True, however, both examples print
the same result, because ColdFusion considers these to be identical to Boolean True.

ADOBE COLDFUSION 8 40
ColdFusion Developer’s Guide

If you use the following code, the output statement does display, because the value of the variable, 12, is not equal to
the Boolean value False:

myVariable equals #myVariable# and IS NOT False



As a result, you should use the test , and not use the IS comparison operator when testing
whether a variable is True or False. This issue is a case of the more general problem of ambiguous type expression
evaluation, described in the following section.
Ambiguous type expressions and strings

When ColdFusion evaluates an expression that does not require strings, including all comparison operations, such
as IS or GT, it checks whether it can convert each string value to a number or date-time object. If so, ColdFusion
converts it to the corresponding number or date-time value (which is stored as a number). It then uses the number
in the expression.
Short strings, such as 1a and 2P, can produce unexpected results. ColdFusion can interpret a single "a" as AM and a
single "P" as PM. This can cause ColdFusion to interpret strings as date-time values in cases where this was not
intended.
Similarly, if the strings can be interpreted as numbers, you might get unexpected results.
For example, ColdFusion interprets the following expressions as shown:
Expression

Interpretation



If 1:00am is 1:00am.



If 1:00pm is later than 2:00am.




Treat the variable age as 4:00 am, convert it to the date-time value 0.16666666667, and add 7 to make it
7.16666666667.



If 0 is 0.

To prevent such ambiguities when you compare strings, use the ColdFusion string comparison functions Compare
and CompareNoCase, instead of the comparison operators.
You can also use the IsDate function to determine whether a string can be interpreted as a date-time value, or to
add characters to a string before comparison to avoid incorrect interpretation.
Date-time functions and queries when ODBC is not supported

Many CFML functions, including the Now, CreateDate, CreateTime, and CreateDateTime functions, return datetime objects. ColdFusion creates Open Database Connectivity (ODBC) timestamp values when it converts date-time
objects to strings. As a result, you might get unexpected results when using dates with a database driver that does not
support ODBC escape sequences, or when you use SQL in a query of queries.
If you use SQL to insert data into a database or in a WHERE clause to select data from a database, and the database
driver does not support ODBC-formatted dates, use the DateFormat function to convert the date-time value to a
valid format for the driver. This rule also applies to queries of queries.
For example, the following SQL statement uses the DateFormat function in a query of queries to select rows that
have MyDate values in the future:

ADOBE COLDFUSION 8 41
ColdFusion Developer’s Guide


SELECT *
FROM DateQuery
WHERE MyDate >= '#DateFormat(Now())#'


The following query of queries fails with the error message “Error: {ts is not a valid date,” because the ColdFusion
Now function returns an ODBC timestamp:

SELECT *
FROM DateQuery
WHERE MyDate >= '#now()#'

Using JavaCast with overloaded Java methods

You can overload Java methods so a class can have several identically named methods that differ only in parameter
data types. At run time, the Java virtual machine attempts to resolve the specific method to use, based on the types
of the parameters passed in the call. Because ColdFusion does not use explicit types, you cannot predict which
version of the method the virtual machine will use.
The ColdFusion JavaCast function helps you ensure that the right method executes by specifying the Java type of
a variable, as in the following example:


The JavaCast function takes two parameters: a string representing the Java data type and the variable whose type
you are setting. You can specify the following Java data types: bool, int, long, float, double, and String.
For more information on the JavaCast function, see the CFML Reference.
Using quotation marks

To ensure that ColdFusion properly interprets string data, surround strings in single- or double-quotation marks.
For example, ColdFusion evaluates “10/2/2001” as a string that can be converted into a date-time object. However,
it evaluates 10/2/2001 as a mathematical expression, 5/2001, which evaluates to 0.00249875062469.

Examples of type conversion in expression evaluation
The following examples demonstrate ColdFusion expression evaluation.
Example 1
2 * True + "YES" - ('y' & "es")

Result value as string: "2"
Explanation: (2*True) is equal to 2; ("YES"- "yes") is equal to 0; 2 + 0 equals 2.
Example 2
"Five is " & 5

Result value as string: "Five is 5"
Explanation: 5 is converted to the string "5".
Example 3
DateFormat("October 30, 2001" + 1)

Result value as string: "31-Oct-01"

ADOBE COLDFUSION 8 42
ColdFusion Developer’s Guide

Explanation: The addition operator forces the string "October 30, 2001" to be converted to a date-time object, and
then to a number. The number is incremented by one. The DateFormat function requires its argument to be a datetime object; thus, the result of the addition is converted to a date-time object. One is added to the date-time object,
moving it ahead by one day to October 31, 2001.

About scopes
Variables differ in how they are set (by your code or by ColdFusion), the places in your code where they are
meaningful, and how long their values persist. These considerations are generally referred to as a variable’s scope.
Commonly used scopes include the Variables scope, the default scope for variables that you create, and the Request
scope, which is available for the duration of an HTTP request.
Note: User-defined functions also belong to scopes. For more information, see “Specifying the scope of a function” on
page 153.

Scope types
The following table describes ColdFusion scopes:
.

Scope

Description

Application

Contains variables that are associated with one, named application on a server. The cfapplication tag name
attribute or the Application.cfc This.name variable setting specifies the application name. For more information, see
“Using Persistent Data and Locking” on page 272.

Arguments

Variables passed in a call to a user-defined function or ColdFusion component method. For more information, see
“About the Arguments scope” on page 142.

Attributes

Used only in custom tag pages and threads. Contains the values passed by the calling page or cfthread tag in the
tag’s attributes. For more information, see “Creating and Using Custom CFML Tags” on page 190 and “Using ColdFusion Threads” on page 300.

Caller

Used only in custom tag pages. The custom tag’s Caller scope is a reference to the calling page’s Variables scope. Any
variables that you create or change in the custom tag page using the Caller scope are visible in the calling page’s Variables scope. For more information, see “Creating and Using Custom CFML Tags” on page 190.

CGI

Contains environment variables identifying the context in which a page was requested. The variables available
depend on the browser and server software. For a list of the commonly used CGI variables, see “Reserved Words and
Variables” on page 2 in the CFML Reference.

Client

Contains variables that are associated with one client. Client variables let you maintain state as a user moves from
page to page in an application, and are available across browser sessions. By default, Client variables are stored in
the system registry, but you can store them in a cookie or a database. Client variables cannot be complex data types
and can include periods in their names. For more information, see “Using Persistent Data and Locking” on page 272.

Cookie

Contains variables maintained in a user’s browser as cookies. Cookies are typically stored in a file on the browser, so
they are available across browser sessions and applications. You can create memory-only Cookie variables, which are
not available after the user closes the browser. Cookie scope variable names can include periods.

Flash

Variables sent by a Flash movie to ColdFusion and returned by ColdFusion to the movie. For more information, see
“Using the Flash Remoting Service” on page 674.

Form

Contains variables passed from a Form page to its action page as the result of submitting the form. (If you use the
HTML form tag, you must use method="post".) For more information, see “Introduction to Retrieving and Formatting Data” on page 511.

function local

Contains variables that are declared inside a user-defined function or ColdFusion component method and exist only
while a function executes. For more information, see “Writing and Calling User-Defined Functions” on page 134.

ADOBE COLDFUSION 8 43
ColdFusion Developer’s Guide

Scope

Description

Request

Used to hold data that must be available for the duration of one HTTP request. The Request scope is available to all
pages, including custom tags and nested custom tags, that are processed in response to the request.
This scope is useful for nested (child/parent) tags. This scope can often be used in place of the Application scope, to
avoid the need for locking variables. Several chapters discuss using the Request scope.

Server

Contains variables that are associated with the current ColdFusion server. This scope lets you define variables that
are available to all your ColdFusion pages, across multiple applications. For more information, see “Using Persistent
Data and Locking” on page 272.

Session

Contains variables that are associated with one client and persist only as long as the client maintains a session. They
are stored in the server’s memory and can be set to time out after a period of inactivity. For more information, see
“Using Persistent Data and Locking” on page 272.

This

Exists only in ColdFusion components or cffunction tags that are part of a containing object such as a ColdFusion
Struct. Exists for the duration of the component instance or containing object. Data in the This scope is accessible
from outside the component or container by using the instance or object name as a prefix.

ThisTag

Used only in custom tag pages. The ThisTag scope is active for the current invocation of the tag. If a custom tag
contains a nested tag, any ThisTag scope values you set before calling the nested tag are preserved when the nested
tag returns to the calling tag.
The ThisTag scope includes three built-in variables that identify the tag’s execution mode, contain the tag’s generated contents, and indicate whether the tag has an end tag.
A nested custom tag can use the cfassociate tag to return values to the calling tag’s ThisTag scope. For more information, see “Accessing tag instance data” on page 198.

Thread

Variables that are created and changed inside a ColdFusion thread, but can be read by all code on the page that
creates the thread. Each thread has a Thread scope that is a subscope of a cfthread scope. For more information, see
“Using ColdFusion Threads” on page 300.

thread local

Variables that are available only within a ColdFusion thread. For more information, see “Using ColdFusion Threads”
on page 300.

URL

Contains parameters passed to the current page in the URL that is used to call it. The parameters are appended to
the URL in the format ?variablename = value[&variablename=value...]; for example www.MyCompany.com/inputpage.cfm?productCode=A12CD1510&quantity=3.
Note: If a URL includes multiple parameters with the same name, the resulting variable in the ColdFusion URL scope
consists of all parameter values separated by commas. For example, a URL of the form http://localhost/urlparamtest.cfm? param=1¶m=2¶m=3 results in a URL.param variable value of 1,2,3 on the ColdFusion page.

Variables (local)

The default scope for variables of any type that are created with the cfset and cfparam tags. A local variable is
available only on the page on which it is created and any included pages (see also the Caller scope).

Important: To prevent data corruption, you lock code that uses Session, Application, or Server scope variables. For more
information, see “Using Persistent Data and Locking” on page 272.

Creating and using variables in scopes
The following table shows how you create and refer to variables in different scopes in your code. For more information on the mechanisms for creating variables in most scopes, see “Creating variables” on page 24.

ADOBE COLDFUSION 8 44
ColdFusion Developer’s Guide

Scope prefix

Prefix required to
reference

Where available

Created by

(function
local, no
prefix)

Prohibited

Within the body of a user-defined function or
ColdFusion component method, only while the
function executes.

In the function or method definition, a var
keyword in a cfset tag or a CFScript var statement.

Application

Yes

For multiple clients in one application over
multiple browser sessions. Surround code that
uses application variables in cflock blocks.

Specifying the prefix Application when you
create the variable.

Arguments

No

Within the body of a user-defined function or
ColdFusion component method.

The calling page passing an argument in the
function call.

Attributes

Yes

On a custom tag page, or inside a thread

For custom tags, the calling page passing the
values to a custom tag page in the custom tag’s
attributes.

(type)

For threads, the cfthread tag specifying
attribute values.
Caller

On the custom tag
page, Yes.

On the custom tag page, by using the Caller
scope prefix.

On the custom tag page, by specifying the prefix
Caller when you create the variable.

On the calling page,
No (Variables prefix
is optional).

On the page that calls the custom tag, as local
variables (Variables scope).

On the calling page, by specifying the prefix Variables, or using no prefix, when you create the
variable.

Cffile

Yes

Following an invocation of cffile.

A cffile tag.

CGI

No

On any page. Values are specific to the latest
browser request.

The web server. Contains the server environment
variables that result from the browser request.

Client

No

For one client in one application, over multiple
browser sessions.

Specifying the prefix Client when you create the
variable.

Cookie

No

For one client in one or more applications and
pages, over multiple browser sessions.

A cfcookie tag. You can also set memory-only
cookies by specifying the prefix Cookie when
you create the variable.

Flash

Yes

A ColdFusion page or ColdFusion component
called by a Flash client.

The ColdFusion Client access. You assign a value
to Flash.You can assign values to the Flash.result
and Flash.pagesize variables.

Form

No

On the action page of a form and in custom tags
called by the action page; cannot be used on a
form page that is not also the action page.

A form or cfform tag. Contains the values of
form field tags (such as input) in the form body
when the form is submitted. The variable name is
the name of the form field.

Request

Yes

On the creating page and in any pages invoked
during the current HTTP request after the variable is created, including in custom tags and
nested custom tags.

Specifying the prefix Request when you create
the variable.

Server

Yes

To any page on the ColdFusion server. Surround
all code that uses server variables in cflock
blocks.

Specifying the prefix Server when you create the
variable.

Session

Yes

For one client in one application and one browser Specifying the prefix Session when you create
session. Surround code that uses Session scope the variable.
variables in cflock blocks.

ADOBE COLDFUSION 8 45
ColdFusion Developer’s Guide

Scope prefix

Prefix required to
reference

Where available

Created by

Yes

Within a ColdFusion component or the body of a
user-defined function that was created using the
cffunction tag and put in an object, structure,
or scope. In the containing page, through the
component instance or containing object.

Within the component or function by specifying
the prefix This when you create the variable.

(type)
This

In the containing page, by specifying the component instance or object that contains the function as a prefix when you create the variable.

ThisTag

Yes

On the custom tag page.

Specifying the prefix ThisTag when you create
the variable in the tag or using the
cfassociate tag in a nested custom tag.

Thread

The thread name.

Any code in the request.

Using the keyword thread or the thread name
as a prefix when you create the variable.

Inside the thread
that creates the variable, you can also
use the keyword

You can create Thread variables only inside the
thread.

thread.

thread-local
(no prefix)

none

Within a thread created by the cfthread tag

Using no prefix when you create the variable.
You can also use the keyword var before the variable name.

URL

No

On the target page of the URL.

The system. Contains the parameters passed in
the URL query string used to access the page.

Variables

No

On the current page. Cannot be accessed by a
form’s action page (unless the form page is also
the action page). Variables in this scope used on
a page that calls a custom tag can be accessed in
the custom tag by using its Caller scope; however,
they are not available to any nested custom tags.

Specifying the prefix Variables, or using no prefix,
when you create the variable. (To create a Variables scope variable inside a ColdFusion thread,
you must use the Variables prefix.)

(Local)

Using scopes
The following sections provide details on how you can create and use variables in different scopes.
Evaluating unscoped variables

If you use a variable name without a scope prefix, ColdFusion checks the scopes in the following order to find the
variable:
1

Function local (UDFs and CFCs only)

2

Thread local (inside threads only)

3

Arguments

4

Variables (local scope)

5

Thread

6

CGI

7

Cffile

8

URL

9

Form

10 Cookie

ADOBE COLDFUSION 8 46
ColdFusion Developer’s Guide

11 Client

Because ColdFusion must search for variables when you do not specify the scope, you can improve performance by
specifying the scope for all variables.
To access variables in all other scopes, you must prefix the variable name with the scope identifier.
Scopes and CFX tags

ColdFusion scopes do not apply to ColdFusion Extension (CFX) tags, custom tags that you write in a programming
language such as C++ or Java. The ColdFusion page that calls a CFX tag must use tag attributes to pass data to the
CFX tag. The CFX tag must use the Java Request and Response interfaces or the C++ Request class to get and return
data.
The Java setVariable Response interface method and C++ CCFX::SetVariable method return data to the
Variables scope of the calling page. Therefore, they are equivalent to setting a Caller scope variable in a custom
ColdFusion tag.
Using scopes as structures

ColdFusion makes all named scopes available as structures. You cannot access the function-local scope for user
defined functions (UDFs) that you define using CFScript as a structure. (In ColdFusion 4.5 and 5, the following
scopes are not available as structures: Variables, Caller, Client, and Server.)
You can reference the variables in named scopes as elements of a structure. To do so, specify the scope name as the
structure name and the variable name as the key. For example, if you have a MyVar variable in the Request scope,
you can refer to it in either of the following ways:
Request.MyVar
Request["MyVar"]

Similarly, you can use CFML structure functions to manipulate the contents of the scope. For more information on
using structures, see “Using Arrays and Structures” on page 68.
Important: Do not call StructClear(Session) to clear session variables. This deletes the SessionID, CFID, and
CFtoken built-in variables, effectively ending the session. If you want to use StructClear to delete your application
variables, put those variables in a structure in the Session scope, and then clear that structure. For example, put all your
application variables in Session.MyVars and then call StructClear(Session.MyVars) to clear the variables.

Ensuring variable existence
ColdFusion generates an error if you try to use a variable value that does not exist. Therefore, before you use any
variable whose value is assigned dynamically, you must ensure that a variable value exists. For example, if your application has a form, it must use some combination of requiring users to submit data in fields, providing default values
for fields, and checking for the existence of field variable values before they are used.
There are several ways to ensure that a variable exists before you use it, including the following:

•

You can use the IsDefined function to test for the variable’s existence.

•

You can use the cfparam tag to test for a variable and set it to a default value if it does not exist.

• You can use a cfform input tag with a hidden attribute to tell ColdFusion to display a helpful message to any
user who does not enter data in a required field. For more information on this technique, see “Requiring users to
enter values in form fields” on page 517.

ADOBE COLDFUSION 8 47
ColdFusion Developer’s Guide

Testing for a variable’s existence
Before relying on a variable’s existence in an application page, you can test to see if it exists by using the IsDefined
function. To check whether a specific key exists in a structure, use the StructKeyExists function.
For example, if you submit a form with an unsettled check box, the action page does not get a variable for the check
box. The following example from a form action page makes sure the Contractor check box Form variable exists
before using it:

Contractor: #Form.Contractor#


You must always enclose the argument passed to the IsDefined function in double-quotation marks. For more
information on the IsDefined function, see the CFML Reference.
If you attempt to evaluate a variable that you did not define, ColdFusion cannot process the page and displays an
error message. To help diagnose such problems, turn on debugging in the ColdFusion Administrator or use the
debugger in your editor. The Administrator debugging information shows which variables are being passed to your
application pages.
Variable existence considerations

If a variable is part of a scope that is available as a structure, you might get a minor performance increase by testing
the variable’s existence using the StructKeyExists function instead of the IsDefined function.
You can also determine which Form variables exist by inspecting the contents of the Form.fieldnames built-in
variable. This variable contains a list of all the fields submitted by the form. Remember, however, that form text fields
are always submitted to the action page, and might contain an empty string if the user did not enter data.
The IsDefined function always returns False if you specify an array or structure element using bracket notation.
For example, IsDefined("myArray[3]") always returns False, even if the array element myArray[3] has a value.
To check for the existence of an array element, use cftry, as in the following example:






< cfoutput>Items[1][2] does not exist



Using the cfparam tag
You can ensure that a variable exists by using the cfparam tag, which tests for the variable’s existence and optionally
supplies a default value if the variable does not exist. The cfparam tag has the following syntax:


Note: For information on using the type attribute to validate the parameter data type, see the CFML Reference.
There are two ways to use the cfparam tag to test for variable existence, depending on how you want the validation
test to proceed:

• With only the name attribute to test that a required variable exists. If it does not exist, the ColdFusion server stops
processing the page and displays an error message.

ADOBE COLDFUSION 8 48
ColdFusion Developer’s Guide

• With the name and default attributes to test for the existence of an optional variable. If the variable exists,
processing continues and the value is not changed. If the variable does not exist, it is created and set to the value of
the default attribute, and processing continues.
The following example shows how to use the cfparam tag to check for the existence of an optional variable and to
set a default value if the variable does not already exist:


Example: testing for variables

Using the cfparam tag with the name attribute is one way to clearly define the variables that a page or a custom tag
expects to receive before processing can proceed. This can make your code more readable, as well as easier to
maintain and debug.
For example, the following cfparam tags indicate that this page expects two form variables named StartRow and
RowsToFetch:



If the page with these tags is called without either one of the form variables, an error occurs and the page stops
processing. By default, ColdFusion displays an error message; you can also handle the error as described in
“Handling Errors” on page 246.
Example: setting default values

The following example uses the cfparam tag to see if optional variables exist. If they do exist, processing continues.
If they do not exist, the ColdFusion server creates them and sets them to the default values.




You can use the cfparam tag to set default values for URL and Form variables, instead of using conditional logic. For
example, you could include the following code on the action page to ensure that a SelectedDepts variable exists:


Validating data
It is often not sufficient that input data merely exists; it must also have the right format. For example, a date field must
have data in a date format. A salary field must have data in a numeric or currency format. There are many ways to
ensure the validity of data, including the following methods:

•

Use the cfparam tag with the type attribute to validate a variable.

•

Use the IsValid function to validate a variable.

•

Use the cfqueryparam tag in a SQL WHERE clause to validate query parameters.

•

Use cfform controls that have validation attributes.

•

Use a form input tag with a hidden attribute to validate the contents of a form input field.

Note: Data validation using the cfparam, cfqueryparam, and form tags is done by the server. Validation using
cfform tags and hidden fields is done using JavaScript in the user’s browser, before any data is sent to the server.

ADOBE COLDFUSION 8 49
ColdFusion Developer’s Guide

For detailed information on validating data in forms and variables, see “Validating Data” on page 553 For detailed
information on validating query parameters, see “Using cfqueryparam” on page 399.

Passing variables to custom tags and UDFs
The following sections describe rules for how data gets passed to custom tags and user-defined functions that are
written in CFML, and to CFX custom tags that are written in Java or C++.

Passing variables to CFML tags and UDFs
When you pass a variable to a CFML custom tag as an attribute, or to a user-defined function as an argument, the
following rules determine whether the custom tag or function receives its own private copy of the variable or only
gets a reference to the calling page’s variable:

• Simple variables and arrays are passed as copies of the data. If your argument is an expression that contains
multiple simple variables, the result of the expression evaluation is copied to the function or tag.
•

Structures, queries, and cfobject objects are passed as references to the object.

If the tag or function gets a copy of the calling page’s data, changes to the variable in the custom tag or function do
not change the value of the variable on the calling page. If the variable is passed by reference, changes to the variable
in the custom tag or function also change the value of the variable in the calling page.
To pass a variable to a custom tag, you must enclose the variable name in number signs. To pass a variable to a
function, do not enclose the variable name in number signs. For example, the following code calls a user-defined
function using three Form variables:

TOTAL INTEREST: #TotalInterest(Form.Principal, Form.AnnualPercent,Form.Months)#



The following example calls a custom tag using two variables, MyString and MyArray:


Passing variables to CFX tags
You cannot pass arrays, structures, or cfobject objects to CFX tags. You can pass a query to a CFX tag by using the
query attribute when calling the tag. ColdFusion normally converts simple data types to strings when passing them
to CFX tags; however, the Java Request Interface getIntAttribute method lets you get a passed integer value.

50

Chapter 4: Using Expressions and
Number Signs
In CFML, you create expressions by using number signs to indicate expressions in Adobe ColdFusion tags such as
cfoutput, in strings, and in expressions. You also use variables in variable names and strings to create dynamic
expressions, and dynamic variables.
Contents

Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Using number signs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Dynamic expressions and dynamic variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Expressions
ColdFusion expressions consist of operands and operators. Operands are comprised of constants and variables.
Operators, such as the multiplication symbol, are the verbs that act on the operands; functions are a form of operator.
The simplest expression consists of a single operand with no operators. Complex expressions have multiple operators
and operands. The following are all ColdFusion expressions:
12
MyVariable
a++
(1 + 1)/2
"father" & "Mother"
Form.divisor/Form.dividend
Round(3.14159)

Operators act on the operands. Some operators, such as functions with a single argument, take a single operand.
Many operators, including most arithmetic and logical operators, take two operands. The following is the general
form of a two-operand expression:
Expression Operator Expression

Note that the operator is surrounded by expressions. Each expression can be a simple operand (variable or constant)
or a subexpression consisting of more operators and expressions. Complex expressions are built up using subexpressions. For example, in the expression (1 + 1)/2, 1 + 1 is a subexpression consisting of an operator and two operands.

Operator types
ColdFusion has four types of operators:

•

Arithmetic

•

Boolean

•

Decision (or comparison)

•

String

Functions also can be viewed as operators because they act on operands.

ADOBE COLDFUSION 8 51
ColdFusion Developer’s Guide

Arithmetic operators

The following table describes the arithmetic operators:
Operator

Description

+ - * /

Basic arithmetic: Addition, subtraction, multiplication, and division.
In division, the right operand cannot be zero.

++ --

Increment and decrement. Increase or decrease the variable by one.
These operators can be used for pre-incrementing or decrementing (as in x = + i), where the variable is changed
before it is used in the expression, or post-incrementing or decrementing (as in x = i++), where the value is
changed after it is used in the expression. If the value of the variable i is initially 7, for example, the value of x in x =
++i is 8 after expression evaluation, but in x=i++, the value of x is 7. In both cases, the value of i becomes 8.
These operators cannot be used with expressions that involve functions, as in f().a++. Also, you can use an expression such as -++x, but ---x and +++x cause errors, because their meanings are ambiguous. You can use parentheses to group the operators, as in -(--x) or +(++x), however.

+= -= *= /= %=

Compound assignment operators. The variable on the right is used as both an element in the expression and the
result variable. Thus, the expression a += b is equivalent to a = a +b.
An expression can have only one compound assignment operator.

+ -

Unary arithmetic: Set the sign of a number.

MOD

Modulus: Return the remainder after a number is divided by a divisor. The result has the same sign as the divisor. The
value to the right of the operator should be an integer; using a non-numeric value causes an error, and if you specify
a real number, ColdFusion ignores the fractional part (for example, 11 MOD 4.7 is 3).

or %
\

Integer division: Divide an integer by another integer. The result is also an integer; for example, 9\4 is 2. The right
operand cannot be zero.

^

Exponentiation: Return the result of a number raised to a power (exponent). Use the caret character (^) to separate
the number from the power; for example, 2^3 is 8. Real and negative numbers are allowed for both the base and the
exponent. However, any expression that equates to an imaginary number, such -1^.5 results in the string "-1.#IND.
ColdFusion does not support imaginary or complex numbers.

Boolean operators

Boolean, or logical, operators perform logical connective and negation operations. The operands of Boolean
operators are Boolean (True/False) values. The following table describes the Boolean operators:
Operator

Description

NOT

Reverse the value of an argument. For example, NOT True is False and vice versa.

or !
AND
or &&
OR
or ||

Return True if both arguments are True; return False otherwise. For example, True AND True is True, but True AND
False is False.
Return True if any of the arguments is True; return False otherwise. For example, True OR False is True, but False OR
False is False.

XOR

Exclusive or: Return True if one of the values is True and the other is False. Return False if both arguments are True or
both are False. For example, True XOR True is False, but True XOR False is True.

EQV

Equivalence: Return True if both operands are True or both are False. The EQV operator is the opposite of the XOR
operator. For example, True EQV True is True, but True EQV False is False.

IMP

Implication: The statement A IMP B is the equivalent of the logical statement “If A Then B.” A IMP B is False only if A is
True and B is False. It is True in all other cases.

ADOBE COLDFUSION 8 52
ColdFusion Developer’s Guide

Decision operators

The ColdFusion decision, or comparison, operators produce a Boolean True/False result. Many types of operation
have multiple equivalent operator forms. For example, IS and EQ perform the same operation. The following table
describes the decision operators:
Operator

Description

IS

Perform a case-insensitive comparison of two values. Return True if the values are identical.

EQUAL
EQ
IS NOT
NOT EQUAL

Opposite of IS. Perform a case-insensitive comparison of two values. Return True if the values
are not identical.

NEQ
CONTAINS

Return True if the value on the left contains the value on the right.

DOES NOT CONTAIN

Opposite of CONTAINS. Return True if the value on the left does not contain the value on the
right.

GREATER THAN

Return True if the value on the left is greater than the value on the right.

GT
LESS THAN
LT
GREATER THAN OR EQUAL TO

Opposite of GREATER THAN. Return True if the value on the left is smaller than the value on
the right.
Return True if the value on the left is greater than or equal to the value on the right.

GTE
GE
LESS THAN OR EQUAL TO

Return True if the value on the left is less than or equal to the value on the right.

LTE
LE

Note: In CFScript expressions only, you can also use the following decision operators. You cannot use them in expressions
in tags. == (EQ), != (NEQ), > (GT), < (LT), >= (GTE), and <= (LTE).
Decision operator rules

The following rules apply to decision operators:

• When ColdFusion evaluates an expression that contains a decision operator other than CONTAINS or DOES
NOT CONTAIN, it first determines if the data can be converted to numeric values. If they can be converted, it
performs a numeric comparison on the data. If they cannot be converted, it performs a string comparison. This can
sometimes result in unexpected results. For more information on this behavior, see “Evaluation and type conversion
issues” on page 39.
• When ColdFusion evaluates an expression with CONTAINS or DOES NOT CONTAIN it does a string
comparison. The expression A CONTAINS B evaluates to True if B is a substring of A. Therefore an expression such
as the following evaluates as True:
123.45 CONTAINS 3.4

1 When a ColdFusion decision operator compares strings, it ignores the case. As a result, the following expression
is True:

ADOBE COLDFUSION 8 53
ColdFusion Developer’s Guide

"a" IS "A"

2 When a ColdFusion decision operator compares strings, it evaluates the strings from left to right, comparing the
characters in each position according to their sorting order. The first position where the characters differ determines
the relative values of the strings. As a result, the following expressions are True:
"ab" LT "aba"
"abde" LT "ac"

String operators

String operators manipulate strings of characters. The following table describes the operators:
Operator

Description

&

Concatenates strings.

&=

Compound concatenation. The variable on the right is used as both an element in the concatenation operation and
the result variable. Thus, the expression a &= b is equivalent to a = a & b.
An expression can have only one compound assignment operator.

Note: In a Query of Queries, you use || as the concatenation operator.

Operator precedence and evaluation ordering
The order of precedence controls the order in which operators in an expression are evaluated. The order of precedence is as follows. (Some alternative names for operators, such as EQUALS and GREATER THAN OR EQUAL TO
are omitted for brevity.)
Unary +, Unary ^
*, /
\
MOD
+, &
EQ, NEQ, LT, LTE, GT, GTE, CONTAINS, DOES NOT CONTAIN, ==, !=, >, >=, <, <=
NOT, !
AND, &&
OR
XOR, ||
EQV
IMP

To enforce a nonstandard order of evaluation, you must parenthesize expressions. For example:

•

6 - 3 * 2 is equal to 0

•

(6 - 3) * 2 is equal to 6

You can nest parenthesized expressions. When in doubt about the order in which operators in an expression will be
evaluated, use parentheses to force the order of evaluation.

Using functions as operators
Functions are a form of operator. Because ColdFusion functions return values, you can use function results as
operands. Function arguments are expressions. For example, the following are valid expressions:

•
•

Rand()
UCase("This is a text: ") & ToString(123 + 456)

ADOBE COLDFUSION 8 54
ColdFusion Developer’s Guide

Function syntax

The following table shows function syntax and usage guidelines:
Usage

Example

No arguments

Function()

Basic format

Function(Data)

Nested functions

Function1(Function2(Data))

Multiple arguments

Function(Data1, Data2, Data3)

String arguments

Function('This is a demo')
Function("This is a demo")

Arguments that are expressions

Function1(X*Y, Function2("Text"))

All functions return values. In the following example, the cfset tag sets a variable to the value returned by the Now
function:


You can use the values returned by functions directly to create more complex expressions, as in the following
example:
Abs(Myvar)/Round(3.14159)

For more information on how to insert functions in expressions, see “Using number signs” on page 55.
Optional function arguments

Some functions take optional arguments after their required arguments. If omitted, all optional arguments default
to a predefined value. For example:

•

Replace("Eat and Eat", "Eat", "Drink") returns "Drink and Eat"

•

Replace("Eat and Eat", "Eat", "Drink", "All") returns "Drink and Drink"

The difference in the results is because the Replace function takes an optional fourth argument that specifies the
scope of replacement. The default value is “One,” which explains why only the first occurrence of “Eat” was replaced
with “Drink” in the first example. In the second example, a fourth argument causes the function to replace all occurrences of “Eat” with “Drink”.
Expression evaluation and functions

It is important to remember that ColdFusion evaluates function attributes as expressions before it executes the
function. As a result, you can use any ColdFusion expression as a function attribute. For example, consider the
following lines:



When ColdFusion server executes the second line, it does the following:
1

Determines that there is an expression with a string concatenation.

2

Evaluates the firstVariable variable as the string "we all need".

3

Concatenates "we all need" with the string " more sleep!" to get "we all need more sleep!".

4

Passes the string "we all need more sleep!" to the UCase function.

ADOBE COLDFUSION 8 55
ColdFusion Developer’s Guide

Executes the UCase function on the string argument "we all need more sleep!" to get "WE ALL NEED MORE
SLEEP!".

5
6

Assigns the string value "WE ALL NEED MORE SLEEP!" to the variable myStringVar.

ColdFusion completes steps 1-3 before invoking the function.

Using number signs
Number signs (#) have a special meaning in CFML. When the ColdFusion server encounters number signs in CFML
text, such as the text in a cfoutput tag body, it checks to see if the text between the number signs is either a variable
or a function.
Number signs are also called pound signs.
Is so, it replaces the text and surrounding number signs with the variable value or the result of the function.
Otherwise, ColdFusion generates an error.
For example, to output the current value of a variable named Form.MyFormVariable, you delimit (surround) the
variable name with number signs:
Value is #Form.MyFormVariable#

In this example, the variable Form.MyFormVariable is replaced with the value assigned to it.
Follow these guidelines when using number signs:

•

Use number signs to distinguish variables or functions from plain text.

• Surround only a single variable or function in number signs; for example, #Variables.myVar# or #Left(myString,
position)#. (However, a function in number signs can contain nested functions, such as #Left(trim(myString),
position)#.
• Do not put complex expressions, such as 1 + 2 in number signs. Although this is allowed in a cfoutput block,
such as One plus one is #1 + 1#, doing so mixes logic and presentation.
•

Use number signs only where necessary, because unneeded number signs slow processing.

The following sections provide more details on how to use number signs in CFML. For a description of using
number signs to create variable names, see “Using number signs to construct a variable name in assignments” on
page 59.

Using number signs in ColdFusion tag attribute values
You can put variables, functions, or expressions inside tag attributes by enclosing the variable or expression with
number signs. For example, if the variable CookieValue has the value "MyCookie", the following line sets the
cfcookie value attribute to "The value is MyCookie":


You can optionally omit quotation marks around variables used as attribute values as shown in the following
example:


However, surrounding all attribute values in quotation marks is more consistent with HTML coding style.

ADOBE COLDFUSION 8 56
ColdFusion Developer’s Guide

If you use string expressions to construct an attribute value, as shown in the following example, the strings inside the
expression use single quotation marks (') to differentiate the quotation marks from the quotation marks that
surround the attribute value.


Note: You do not need to use number signs when you use the cfset tag to assign one variable’s value to another value.
For example, the following tag assigns the value of the oldVar variable to the new variable, newVar: .

Using number signs in tag bodies
You can put variables or functions freely inside the bodies of the following tags by enclosing each variable or
expression with number signs:

•

cfoutput

•

cfquery

•

cfmail

For example:

Value is #Form.MyTextField#


The name is #FirstName# #LastName#.


The value of Cos(0) is #Cos(0)#


If you omit the number signs, the text, rather than the value, appears in the output generated by the cfoutput
statement.
Two expressions inside number signs can be adjacent to one another, as in the following example:

"Mo" and "nk" is #Left("Moon", 2)##Mid("Monkey", 3, 2)#


This code displays the following text:
"Mo" and "nk" is Monk
ColdFusion does not interpret the double number sign as an escaped # character.

Using number signs in strings
You can put variables or functions freely inside strings by enclosing each variable or expression with number signs;
for example:




ColdFusion automatically replaces the text with the value of the variable or the value returned by the function. For
example, the following pairs of cfset statements produce the same result:

ADOBE COLDFUSION 8 57
ColdFusion Developer’s Guide




If number signs are omitted inside the string, the text, rather than the value, appears in the string. For example, the
following pairs of cfset statements produce the same result:



As with the cfoutput statement, two expressions can be adjacent to each other in strings, as in the following
example:


The double-quotation marks around "Moon" and "Monkey" do not need to be escaped (as in ""Moon"" and
""Monkey""). This is because the text between the number signs is treated as an expression; it is evaluated before its
value is inserted inside the string.

Nested number signs
In a few cases, you can nest number signs in an expression. The following example uses nested number signs:


In this example, number signs are nested so that the values of the variables FirstName and LastName are inserted in
the string whose length the Len function calculates.
Nested number signs imply a complex expression that can typically be written more clearly and efficiently without
the nesting. For example, you can rewrite the preceding code example without the nested number signs, as follows:


The following achieves the same results and can further improve readability:



A common mistake is to put number signs around the arguments of functions, as in:




These statements result in errors. As a general rule, never put number signs around function arguments.

Using number signs in expressions
Use number signs in expressions only when necessary, because unneeded number signs reduce clarity and can
increase processing time. The following example shows the preferred method for referencing variables:


In contrast, the following example uses number signs unnecessarily and is less efficient than the previous statement:


ADOBE COLDFUSION 8 58
ColdFusion Developer’s Guide

Dynamic expressions and dynamic variables
This section discusses the advanced topics of dynamic expressions, dynamic evaluation, and dynamic variable
naming. Many ColdFusion programmers never encounter or need to use dynamic expressions. However, dynamic
variable naming is important in situations where the variable names are not known in advance, such as in shopping
cart applications.
This section also discusses the use of the IIf function, which is most often used without dynamic expressions. This
function dynamically evaluates its arguments, and you must often use the DE function to prevent the evaluation. For
more information on using the IIF function, see “Using the IIF function” on page 63.
Note: This section uses several tools and techniques that are documented in later chapters. If you are unfamiliar with
using ColdFusion forms, structures, and arrays, you should learn about these tools before reading this section.

About dynamic variables
Dynamic variables are variables that are named dynamically, typically by creating a variable name from a static part
and a variable part. For example, the following example dynamically constructs the variable name from a variable
prefix and a static suffix:


Using dynamic variables in this manner does not require dynamic evaluation.

About dynamic expressions and dynamic evaluation
In a dynamic expression, the actual expression, not just its variable values, is determined at execution time. In other
words, in a dynamic expression the structure of the expression, such as the names of the variables, not just the values
of the variables, gets built at runtime.
You create dynamic expressions using string expressions, which are expressions contained in strings, (that is,
surrounded with quotation marks). Dynamic evaluation is the process of evaluating a string expression. The
Evaluate and IIf functions, and only these functions, perform dynamic evaluation.
When ColdFusion performs dynamic evaluation it does the following:
1

Takes a string expression and treats it as a standard expression, as if the expression was not a string.

2

Parses the expression to determine the elements of the expression and validate the expression syntax.

3 Evaluates the expression, looking up any variables and replacing them with their values, calling any functions,
and performing any required operations.

This process enables ColdFusion to interpret dynamic expressions with variable parts. However, it incurs a
substantial processing overhead.
Dynamic expressions were important in early versions of ColdFusion, before it supported arrays and structures, and
they still can be useful in limited circumstances. However, the ability to use structures and the ability to use
associative array notation to access structure elements provide more efficient and easier methods for dynamically
managing data. For information on using arrays and structures, see “Using Arrays and Structures” on page 68.
Selecting how to create variable names

The following two examples describes cases when you need dynamic variable names:

ADOBE COLDFUSION 8 59
ColdFusion Developer’s Guide

• Form applications where the number and names of fields on the form vary dynamically. In this case, the form
posts only the names and values of its fields to the action page. The action page does not know all the names of the
fields, although it does know how the field names (that is, the variable names) are constructed.
•

If the following are true:

•

ColdFusion calls a custom tag multiple times.

•

The custom tag result must be returned to different variables each time.

•

The calling code can specify the variable in which to return the custom tag result.

In this case, the custom tag does not know the return variable name in advance, and gets it as an attribute value.
In both cases, it might appear that dynamic expressions using the Evaluate function are needed to construct the
variable names. However, you can achieve the same ends more efficiently by using dynamic variable naming, as
shown in “Example: a dynamic shopping cart” on page 64.
This does not mean that you must always avoid dynamic evaluation. However, given the substantial performance
costs of dynamic evaluation, you should first ensure that one of the following techniques cannot serve your purpose:

•

An array (using index variables)

•

Associative array references containing expressions to access structure elements

•

Dynamically generated variable names

Dynamic variable naming without dynamic evaluation
While ColdFusion does not always allow you to construct a variable name in-line from variable pieces, it does let you
to do so in the most common uses, as described in the following sections.
Using number signs to construct a variable name in assignments

You can combine text and variable names to construct a variable name on the left side of a cfset assignment. For
example, the following code sets the value of the variable Product12 to the string "Widget":



To construct a variable name this way, all the text on the left side of the equal sign must be in quotation marks.
This usage is less efficient than using arrays. The following example has the same purpose as the previous one, but
requires less processing:



Dynamic variable limitation

When you use a dynamic variable name in quotation marks on the left side of an assignment, the name must be
either a simple variable name or a complex name that uses object.property notation (such as MyStruct.#KeyName#).
You cannot use an array as part of a dynamic variable name. For example, the following code generates an error:

productClassNo = 1>
productItemNo = 9>
"myArray[#productClassNo##productItemNo#]" = "Widget">

ADOBE COLDFUSION 8 60
ColdFusion Developer’s Guide

However, you can construct an array index value dynamically from variables without using quotation marks on the
left side of an assignment. For example, the preceding sample code works if you replace the final line with the
following line:

Dynamically constructing structure references

The ability to use associative array notation to reference structures provides a way for you to use variables to dynamically create structure references. (For a description of associative array notation, see “Structure notation” on
page 79.) Associative array structure notation allows you to use a ColdFusion expression inside the index brackets.
For example, if you have a productName structure with keys of the form product_1, product_2 and so on, you can
use the following code to display the value of productName.product_3:


Product_3 Name: #ProductName["product_" & prodNo]#


For an example of using this format to manage a shopping cart, see “Example: a dynamic shopping cart” on page 64.

Using dynamic evaluation
The following sections describe how to use dynamic evaluation and create dynamic expressions.
ColdFusion dynamic evaluation functions

The following table describes the functions that perform dynamic evaluation and are useful in evaluating dynamic
expressions:
Function

Purpose

DE

Escapes any double-quotation marks in the argument and wraps the result in double-quotation
marks. The DE function is particularly useful with the IIF function, to prevent the function from
evaluating a string to be output.
For an example of using the DE function with the IIF function, see “Using the IIF function” on
page 63.

Evaluate

Takes one or more string expressions and dynamically evaluates their contents as expressions
from left to right. (The results of an evaluation to the left can have meaning in an expression to the
right.) Returns the result of evaluating the rightmost argument.
For more information on this function see “About the Evaluate function” on page 61.

IIf

Evaluates a boolean condition expression. Depending on whether this expression is True or False,
dynamically evaluates one of two string expressions and returns the result of the evaluation. The
IIF function is convenient for incorporating a cfif tag in-line in HTML.
For an example of using this function, see “Using the IIF function” on page 63.

PrecisionEvaluate

Operates identically to the Evaluate function, except that it can calculate arbitrary precision
decimal arithmetic. If one or more operands in an arithmetic expression are decimal numbers,
such as 12947834.986532, and are too long to be represented exactly by a ColdFusion numeric
data type, the function uses arbitrary-precision arithmetic to calculate the result, and return the
result as an arbitrarily long string of numbers. For more information about this function, see
PrecisionEvaluate in the CFML Reference.

SetVariable

Sets a variable identified by the first argument to the value specified by the second argument. This
function is no longer required in well-formed ColdFusion pages; see “SetVariable function considerations” on page 63.

ADOBE COLDFUSION 8 61
ColdFusion Developer’s Guide

Function argument evaluation considerations

It is important to remember that ColdFusion always evaluates function arguments before the argument values are
passed to a function:
For example, consider the following DE function:
#DE("1" & "2")#

You might expect this line to display """1"" & ""2""". Instead, it displays “12”, because ColdFusion processes the line
as follows:
1

Evaluates the expression "1" & "2" as the string “12”.

2

Passes the string "12" (without the quotation marks) to the DE function.

3

Calls the DE function, which adds literal quotation marks around the 12.

Similarly, if you use the expression DE(1 + 2), ColdFusion evaluates 1 + 2 as the integer 3 and passes it to the
function. The function converts it to a string and surrounds the string in literal quotation marks: “3”.
About the Evaluate function

The Evaluate function takes one or more string expressions, dynamically evaluates their contents as expressions
from left to right, and returns the result of evaluating the rightmost argument.
The following example shows the Evaluate function and how it works with ColdFusion variable processing:



#myVar2#

#myVar#

#Evaluate("myVar2")#

#Evaluate("myVar")#

#Evaluate(myVar2)#

#Evaluate(myVar)#


Reviewing the code

The following table describes how ColdFusion processes this code:
Code

Description




Sets the two variables to the following strings:
myVar
27/9


#myVar2#

#myVar#


Displays the values assigned to the variables, myVar and 27/9, respectively.

#Evaluate("myVar2")#


Passes the string "myvar2" (without the quotation marks) to the Evaluate function, which does the
following:
1 Evaluates it as the variable myVar2.
2 Returns the value of the myVar2 variable, the string "myvar" (without the quotation marks).

ADOBE COLDFUSION 8 62
ColdFusion Developer’s Guide

Code

Description

#Evaluate("myVar")#


Passes the string "myvar" (without the quotation marks) to the Evaluate function, which does the
following:
1

Evaluates it as the variable myVar.

2 Returns the value of the myVar variable, the string "27/9" (without the quotation marks).
#Evaluate(myVar2)#


Evaluates the variable myVar2 as the string "myVar" and passes the string (without the quotation
marks) to the Evaluate function. The rest of the processing is the same as in the previous line.

#Evaluate(myVar)#



Evaluates the variable myVar as the string "27/9" (without the quotation marks), and passes it to
the Evaluate function, which does the following:
1

Evaluates the string as the expression 27/9

2 Performs the division.
3 Returns the resulting value, 3

As you can see, using dynamic expressions can result in substantial expression evaluation overhead, and the code
can be confusing. Therefore, you should avoid using dynamic expressions wherever a simpler technique, such as
using indexed arrays or structures can serve your purposes.
Avoiding the Evaluate function

Using the Evaluate function increases processing overhead, and in most cases it is not necessary. The following
sections provide examples of cases where you might consider using the Evaluate function.
Example 1

You might be inclined to use the Evaluate function in code such as the following:
1 + 1 is #Evaluate(1 + 1)#

Although this code works, it is not as efficient as the following code:

1 + 1 is #Result#
Example 2

This example shows how you can use an associative array reference in place of an Evaluate function. This technique
is powerful because:

•

Most ColdFusion scopes are accessible as structures.

• You can use ColdFusion expressions in the indexes of associative array structure references. For more information on using associative array references for structures, see “Structure notation” on page 79.
The following example uses the Evaluate function to construct a variable name:

Product Name: #Evaluate("Form.product_#i#")#


This code comes from an example where a form has entries for an indeterminate number of items in a shopping cart.
For each item in the shopping cart there is a product name field. The field name is of the form product_1, product_2,
and so on, where the number corresponds to the product’s entry in the shopping cart. In this example, ColdFusion
does the following:
1

Replaces the variable i with its value, for example 1.

ADOBE COLDFUSION 8 63
ColdFusion Developer’s Guide

2

concatenates the variable value with "Form.product_", and passes the result (for Form.product_1) to the

Evaluate function, which does the remaining steps.

Parses the variable product_1 and generates an executable representation of the variable. Because ColdFusion
must invoke its parser, this step requires substantial processing, even for a simple variable.
3
4

Evaluates the representation of the variable, for example as "Air popper".

5

Returns the value of the variable.

The following example has the same result as the preceding example and is more efficient:

ProductName: #Form["product_" & i]#


In this code, ColdFusion does the following:
6 Evaluates the expression in the associative array index brackets as the string "product_" concatenated with the
value of the variable i.
7

Determines the value of the variable i; 1.

8

Concatenates the string and the variable value to get product_1.

Uses the result as the key value in the Form structure to get Form[product_1]. This associative array reference
accesses the same value as the object.attribute format reference Form.product_1; in this case, Air popper.
9

This code format does not use any dynamic evaluation, but it achieves the same effect, of dynamically creating a
structure reference by using a string and a variable.
SetVariable function considerations

You can avoid using the SetVariable function by using a format such as the following to set a dynamically named
variable. For example, the following lines are equivalent:



In the second line, enclosing the myVar#i# variable name in quotation marks tells ColdFusion to evaluate the name
and process any text in number signs as a variable or function. ColdFusion replaces the #i# with the value of the
variable i, so that if the value of i is 12, this code is equivalent to the line


For more information on this usage, see “Using number signs to construct a variable name in assignments” on
page 59.

Using the IIF function
The IIf function is a shorthand for the following code:






The function returns the value of the result variable. It is comparable to the use of the JavaScript and Java ? : operator,
and can result in more compact code. As a result, the IIF function can be convenient even if you are not using
dynamic expressions.

ADOBE COLDFUSION 8 64
ColdFusion Developer’s Guide

The IIF function requires the DE function to prevent ColdFusion from evaluating literal strings, as the following
example shows:

#IIf(IsDefined("LocalVar"), "LocalVar", DE("The variable is not defined."))#


If you do not enclose the string "The variable is not defined." in a DE function, the IIF function tries to evaluate the
contents of the string as an expression and generates an error (in this case, an invalid parser construct error).
The IIF function is useful for incorporating ColdFusion logic in-line in HTML code, but it entails a processing time
penalty in cases where you do not otherwise need dynamic expression evaluation.
The following example shows using IIF to alternate table row background color between white and gray. It also
shows the use of the DE function to prevent ColdFusion from evaluating the color strings.





hello #i#






This code is more compact than the following example, which does not use IIF or DE:










hello #i#






Example: a dynamic shopping cart
The following example dynamically creates and manipulates variable names without using dynamic expression
evaluation by using associative array notation.
You need to dynamically generate variable names in applications such as shopping carts, where the required output
is dynamically generated and variable. In a shopping cart, you do not know in advance the number of cart entries or
their contents. Also, because you are using a form, the action page only receives Form variables with the names and
values of the form fields.

ADOBE COLDFUSION 8 65
ColdFusion Developer’s Guide

The following example shows the shopping cart contents and lets you edit your order and submit it. To simplify
things, the example automatically generates the shopping cart contents using CFScript instead of having the user fill
the cart. A more complete example would populate a shopping cart as the user selected items. Similarly, the example
omits all business logic for committing and making the order.
Create the form
1 Create a file in your editor.





CartItems=4;
Cart = ArrayNew(1);
for ( i=1; i LE cartItems; i=i+1)
{
Cart[i]=StructNew();
Cart[i].ID=i;
Cart[i].Name="Product " & i;
Cart[i].SKU=i*100+(2*i*10)+(3*i);
Cart[i].Qty=3*i-2;
}


Your shopping cart has the following items.

You can change your order quantities.

If you don't want any item, clear the item's check box.

When you are ready to order, click submit.










Order?
Product
Code
Quantity
















ADOBE COLDFUSION 8 66
ColdFusion Developer’s Guide

2

Save the file as ShoppingCartForm.cfm.

Reviewing the code

The following table describes the code:
Code

Description


CartItems=4;
Cart = ArrayNew(1);
for ( i=1; i LE #cartItems#; i=i+1)
{
Cart[i]=StructNew();
Cart[i].ID=i;
Cart[i].Name="Product " & i;
Cart[i].SKU=i*100+(2*i*10)+(3*i);
Cart[i].Qty=3*i-2;
}


Create a shopping cart as an array of structures, with each structure containing
the cart item ID, product name, SKU number, and quantity ordered for one item
in the cart. Populate the shopping cart by looping CartItems times and setting
the structure variables to arbitrary values based on the loop counter. A real application would set the Name, SKU, and Quantity values on other pages.




Start the form and its embedded table. When the user clicks the submit button,
post the form data to the ShoppingCartAction.cfm page.







Order?
Product
Code
Quantity













Loop through the shopping cart entries to generate the cart form dynamically.
For each loop, generate variables used for the form field name attributes by
appending the cart item ID (Cart[i].ID) to a field type identifier, such as "sku_".




Create the Submit button and end the form.

Create the Action page
1 Create a file in your editor.

The table formats the form neatly. The first table row contains the column
headers. Each following row has the data for one cart item.

Use a single name, "itemID", for all check boxes. This way, the itemID value posted
to the action page is a list of all the check box field values. The check box field
value for each item is the cart item ID.
Each column in a row contains a field for a cart item structure entry. The
passthrough attribute sets the product name and SKU fields to read-only; note
the use of single-quotation marks. (For more information on the cfinput tag
passthrough attribute, see the CFML Reference.) The check boxes are selected
by default.

ADOBE COLDFUSION 8 67
ColdFusion Developer’s Guide

2

Enter the following text:








You have ordered the following items:




ProductName: #Form["product_" & i]#

Product Code: #Form["sku_" & i]#

Quantity: #Form["qty_" & i]#









3

Save the file as ShoppingCartAction.cfm

4

Open ShoppingCartform.cfm in your browser, change the check box and quantity values, and click Submit.

Reviewing the code

The following table describes the code:
Code

Description



Run the CFML on this page only if it is called by submitting a form. This is not needed if there
are separate form and action pages, but is required if the form and action page were one
ColdFusion page.



Set the default Form.itemID to the empty string. This prevents ColdFusion from displaying an
error if the user clears all check boxes before submitting the form (so no product IDs are
submitted).


You have ordered the following
items:




ProductName:
#Form["product_" &
i]#

Product Code:
#Form["sku_" & i]#

Quantity:
#Form["qty_" & i]#







Display the name, SKU number, and quantity for each ordered item.
The form page posts Form.itemID as a list containing the value attributes of all the check
boxes. These attributes contain the shopping cart item IDs for the selected cart items. Use the
list values to index a loop that outputs each ordered item.
Use associative array notation to access the Form scope as a structure and use expressions in
the array indexes to construct the form variable names. The expressions consist of a string
containing the field name’s field type prefix (for example, "sku_"), concatenated with the variable i, which contains the shopping cart ItemID number (which is also the loop index variable).

68

Chapter 5: Using Arrays and Structures
Adobe ColdFusion supports dynamic multidimensional arrays. Using arrays can enhance your ColdFusion application code.
ColdFusion also supports structures for managing lists of key-value pairs. Because structures can contain other
structures or complex data types as it values, they provide a flexible and powerful tool for managing complex data.
Contents

About arrays. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Basic array techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Populating arrays with data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Array functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
About structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Creating and using structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Structure examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Structure functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

About arrays
Traditionally, an array is a tabular structure used to hold data, much like a spreadsheet table with clearly defined
limits and dimensions.
In ColdFusion, you typically use arrays to temporarily store data. For example, if your site lets users order goods
online, you can store their shopping cart contents in an array. This lets you make changes easily without committing
the information, which the user can change before completing the transaction, to a database.

Basic array concepts
Subsequent discussions of ColdFusion arrays are based on the following terms:
Array dimension: The relative complexity of the array structure.
Index: The position of an element in a dimension, ordinarily surrounded by square brackets: my1Darray[1],
my2Darray[1][1], my3Darray[1][1][1].
Array element: Data stored at an array index.
The simplest array is a one-dimensional array, similar to a row in a table. A one-dimensional array has a name (the
variable name) and a numerical index. The index number references a single entry, or cell, in the array, as the
following figure shows:

ADOBE COLDFUSION 8 69
ColdFusion Developer’s Guide

Thus, the following statement sets the value of the fifth entry in the one-dimensional array MyArray to “Robert”:


A basic two-dimensional (2D) array is like a simple table. A three-dimensional (3D) array is like a cube of data, and
so on. ColdFusion lets you directly create arrays with up to three dimensions. You can use multiple statements to
create arrays with more than three dimensions.
The syntax my2darray[1][3]="Paul" is the same as saying “My2dArray is a two-dimensional array and the value
of the array element index [1][3] is ‘Paul’”.

About ColdFusion arrays
ColdFusion arrays differ from traditional arrays, because they are dynamic. For example, in a conventional array,
array size is constant and symmetrical, whereas in a ColdFusion array, you can have rows of differing lengths based
on the data that is added or removed.
The following figures show the differences between traditional arrays and ColdFusion arrays using 2D arrays. The
differences between traditional and ColdFusion 3D arrays are similar, but much harder to show on a page.
A conventional 2D array is like a fixed-size table made up of individual cells, as the following figure shows:

The following figure represents a ColdFusion 2D array:

ADOBE COLDFUSION 8 70
ColdFusion Developer’s Guide

A ColdFusion 2D array is actually a one-dimensional array that contains a series of additional 1D arrays. Each of the
arrays that make up a row can expand and contract independently of any other column. Similarly, a ColdFusion 3D
array is essentially three nested sets of 1D arrays.
Dynamic arrays expand to accept data that you add to them and contract as you remove data from them.

Basic array techniques
Referencing array elements
You reference array elements by enclosing the index with brackets: arrayName[x] where x is the index that you want
to reference. In ColdFusion, array indexes are counted starting with position 1, which means that position 1 in the
firstname array is referenced as firstname[1]. For 2D arrays, you reference an index by specifying two coordinates:
myarray[1][1].
You can use ColdFusion variables and expressions inside the square brackets to reference an index, as the following
example shows:









Note: The IsDefined function does not test the existence of array elements. Instead, put any code that might try to
access an undefined array element in a try block and use a catch block to handle exceptions that arise if elements do not
exist.

ADOBE COLDFUSION 8 71
ColdFusion Developer’s Guide

Creating arrays
In ColdFusion, you can create arrays explicitly, by using a function to declare the array and then assigning it data, or
implicitly by using an assignment statement. You can create simple or complex, multidimensional arrays.
Creating arrays using functions

To create an array explicitly, you use the arrayNew function and specify the array dimensions, as in the following
example:


This line creates a two-dimensional array named myNewArray. You use this method to create an array with up to
three dimensions.
After you create an array, you add array elements, which you can then reference by using the element indexes.
For example, suppose you create a one-dimensional array called firstname:


The array firstname holds no data and is of an unspecified length. Next you add data to the array:




After you add these names to the array, it has a length of 3.
Creating arrays implicitly

To create an array implicitly, you do not use the ArrayNew function. Instead, you use a new variable name on the left
side of an assignment statement, and array notation on the right side of the statement, as in the following example:


This single statement is equivalent to the four statements used to create the firstname array in Creating arrays using
functions.
When you create an array implicitly, the right side of the assignment statement has square brackets ([]) surrounding
the array contents and commas separating the individual array elements. The elements can be literal values, such as
the strings in the example, variables, or expressions. If you specify variables, do not put the variable names in
quotation marks.
You can create an empty array implicitly, as in the following example:


You can also create an array implicitly by assigning a single entry, as the following example shows:



ColdFusion does not allow nested implicit creation of arrays, structures, or arrays and structures. Therefore, you
cannot create a multidimensional array in a single implicit statement. For example, neither of the following statements is valid:




ADOBE COLDFUSION 8 72
ColdFusion Developer’s Guide




You cannot use a dynamic variable when you create an array implicitly. For example, the following expression
generates an error:


Creating complex multidimensional arrays

ColdFusion supports dynamic multidimensional arrays. When you declare an array with the ArrayNew function,
you specify the number of dimensions. You can create an asymmetrical array or increase an existing array’s dimensions by nesting arrays as array elements.
It is important to know that when you assign one array (array1) to an element of another array (array2), array1 is
copied into array2. The original copy of array1 still exists, independent of array2. You can then change the contents
of the two arrays independently.
The best way to understand an asymmetrical array is by looking at it. The following example creates an asymmetric,
multidimensional array and the cfdump tag displays the resulting array structure. Several array elements do not yet
contain data.




biggerarray[1][1][1][10]=3>
biggerarray[2][1][1]=myotherarray>
biggerarray[2][1][1][4][2]="five deep">


biggestarray[3][1][1]=biggerarray>
biggestarray[3][1][1][2][3][1]="This is complex">
myarray[3]="Can you see me">





Note: The cfdump tag displays the entire contents of an array. It is an excellent tool for debugging arrays and arrayhandling code.
Reviewing the code

The following table describes the code:

ADOBE COLDFUSION 8 73
ColdFusion Developer’s Guide

Code

Description





Create three empty arrays, a 1D array, a 2D array, and a 3D array.




Make element [1][1][1] of the 3D biggerarray array be a
copy of the 1D array. Assign 3 to the [1][1][1][10] element of the
resulting array.
The biggerarray array is now asymmetric. For example, it does
not have a [1][1][2][1] element.




Make element [2][1][1] of the 3D array be the 2D array, and
assign the [2][1][1][4][2] element the value "five deep".
The biggerarray array is now even more asymmetric.





Create a second 3D array. Make the [3][1][1] element of this
array a copy of the biggerarray array, and assign element
[3][1][1][2][3][1].
The resulting array is very complex and asymmetric.






Assign a value to element [3] of myarray.
Use cfdump to view the structure of biggestarray and myarray.
Notice that the "Can you see me" entry appears in myarray, but
not in biggestarray, because biggestarray has a copy of the
original myarray values and is not affected by the change to
myarray.

Adding elements to an array
You can add an element to an array by assigning the element a value or by using a ColdFusion function.
Adding an array element by assignment

You can add elements to an array by defining the value of an array element, as shown in the following cfset tag:


If an element does not exist at the specified index, ColdFusion creates it. If an element already exists at the specified
index, ColdFusion replaces it with the new value. To prevent existing data from being overwritten, use the
ArrayInsertAt function, as described in the next section.
If elements with lower-number indexes do not exist, they remain undefined. You must assign values to undefined
array elements before you can use them. For example, the following code creates an array and an element at index 4.
It outputs the contents of element 4, but generates an error when it tries to output the (nonexistent) element 3.



myarray4: #myarray[4]#

myarray3: #myarray[3]#


Adding an array element with a function

You can use the following array functions to add data to an array:

ADOBE COLDFUSION 8 74
ColdFusion Developer’s Guide

Function

Description

ArrayAppend

Creates a new array element at the end of the array.

ArrayPrepend

Creates a new array element at the beginning of the array.

ArrayInsertAt

Inserts an array element at the specified index position.

Because ColdFusion arrays are dynamic, if you add or delete an element from the array, any higher-numbered index
values all change. For example, the following code creates a two element array and displays the array contents. It then
uses ArrayPrepend to insert a new element at the beginning of the array and displays the result. The data that was
originally in indexes 1 and 2 is now in indexes 2 and 3.










ArrayPrepend(myarray, "New First Element");




For more information about these array functions, see the CFML Reference.

Deleting elements from an array
Use the ArrayDeleteAt function to delete data from the array at a particular index, instead of setting the data value
to zero or an empty string. If you remove data from an array, the array resizes dynamically, as the following example
shows:









The array now has #ArrayLen(firstname)# indexes

The first entry is #firstname[1]#

The second entry is #firstname[2]#



The ArrayDeleteAt function removed the original second element and resized the array so that it has two entries,
with the second element now being the original third element.

ADOBE COLDFUSION 8 75
ColdFusion Developer’s Guide

Copying arrays
You can copy arrays of simple variables (numbers, strings, Boolean values, and date-time values) by assigning the
original array to a new variable name. You do not have to use ArrayNew to create the new array first. When you
assign the existing array to a new variable, ColdFusion creates a new array and copies the old array’s contents to the
new array. The following example creates and populates a two-element array. It then copies the original array,
changes one element of the copied array and dumps both arrays. As you can see, the original array is unchanged and
the copy has a new second element.









If your array contains complex variables (structures, query objects, or external objects such as COM objects)
assigning the original array to a new variable does not make a complete copy of the original array. The array structure
is copied; however, the new array does not get its own copy of the complex data, only references to it. To demonstrate
this behavior, run the following code:
Create an array that contains a structure.











Copy the array and dump it.






Change the values in the new array.





Contents of the original array after the changes:



Contents of the new array after the changes:



The change to the new array also changes the contents of the structure in the original array.
To make a complete copy of an array that contains complex variables, use the Duplicate function.

Populating arrays with data
Array elements can store any values, including queries, structures, and other arrays. You can use a number of
functions to populate an array with data, including ArraySet, ArrayAppend, ArrayInsertAt, and ArrayPrepend.
These functions are useful for adding data to an existing array.
In particular, you should master the following basic techniques:

•

Populating an array with the ArraySet function

ADOBE COLDFUSION 8 76
ColdFusion Developer’s Guide

•

Populating an array with the cfloop tag

•

Populating an array from a query

Populating an array with the ArraySet function
You can use the ArraySet function to populate a 1D array, or one dimension of a multidimensional array, with some
initial value, such as an empty string or zero. This can be useful if you need to create an array of a certain size, but
do not need to add data to it right away. One reason to do this is so that you can refer to all the array indexes. If you
refer to an array index that does not contain some value, such as an empty string, you get an error.
The ArraySet function has the following form:
ArraySet (arrayname, startrow, endrow, value)

The following example initializes the array myarray, indexes 1 to 100, with an empty string:
ArraySet (myarray, 1, 100, "")

Populating an array with the cfloop tag
The cfloop tag provides a common and very efficient method for populating an array. The following example uses
a cfloop tag and the MonthAsString function to populate a simple 1D array with the names of the months. A
second cfloop outputs data in the array to the browser.






#months[loopcount]#



Using nested loops for 2D and 3D arrays

To output values from 2D and 3D arrays, you must employ nested loops to return array data. With a one-dimensional
(1D) array, a single cfloop is sufficient to output data, as in the previous example. With arrays of dimension greater
than one, you need to maintain separate loop counters for each array level.
Nesting cfloop tags for a 2D array

The following example shows how to handle nested cfloop tags to output data from a 2D array. It also uses nested
cfloop tags to populate the array:






The values in my2darray are currently:



[#OuterCounter#][#InnerCounter#]:

ADOBE COLDFUSION 8 77
ColdFusion Developer’s Guide

#my2darray[OuterCounter][InnerCounter]#




Nesting cfloop tags for a 3D array

For 3D arrays, you simply nest an additional cfloop tag. (This example does not set the array values first to keep the
code short.)




[#Dim1#][#Dim2#][#Dim3#]:
#my3darray[Dim1][Dim2][Dim3]#






Populating an array from a query
When populating an array from a query, keep the following things in mind:

• You cannot add query data to an array all at once. A looping structure is generally required to populate an array
from a query.
• You can reference query column data using array-like syntax. For example, myquery.col_name[1] references
data in the first row in the col_name column of the myquery query.
•

Inside a cfloop query= loop, you do not have to specify the query name to reference the query’s variables.

You can use a cfset tag with the following syntax to define values for array indexes:


In the following example, a cfloop tag places four columns of data from a sample data source into an array, myarray.


SELECT Emp_ID, LastName, FirstName, Email
FROM Employees














ID: #MyArray[Counter][1]#,
LASTNAME: #MyArray[Counter][2]#,

ADOBE COLDFUSION 8 78
ColdFusion Developer’s Guide

FIRSTNAME: #MyArray[Counter][3]#,
EMAIL: #MyArray[Counter][4]# 




This example uses the query object built-in variable CurrentRow to index the first dimension of the array.

Array functions
The following functions are available for creating, editing, and handling arrays:
Function

Description

ArrayAppend

Appends an array element to the end of a specified array.

ArrayAvg

Returns the average of the values in the specified array.

ArrayClear

Deletes all data in a specified array.

ArrayDeleteAt

Deletes an element from a specified array at the specified index and resizes the array.

ArrayInsertAt

Inserts an element (with data) in a specified array at the specified index and resizes the array.

ArrayIsDefined

Returns True if the specified array is defined.

ArrayIsEmpty

Returns True if the specified array is empty of data.

ArrayLen

Returns the length of the specified array.

ArrayMax

Returns the largest numeric value in the specified array.

ArrayMin

Returns the smallest numeric value in the specified array.

ArrayNew

Creates an array of specified dimension.

ArrayPrepend

Adds an array element to the beginning of the specified array.

ArrayResize

Resets an array to a specified minimum number of elements.

ArraySet

Sets the elements in a 1D array in a specified range to a specified value.

ArraySort

Returns the specified array with elements sorted numerically or alphanumerically.

ArraySum

Returns the sum of values in the specified array.

ArraySwap

Swaps array values in the specified indexes.

ArrayToList

Converts the specified 1D array to a list, delimited with the character you specify.

IsArray

Returns True if the value is an array.

ListToArray

Converts the specified list, delimited with the character you specify, to an array.

For more information about each of these functions, see the CFML Reference.

About structures
ColdFusion structures consist of key-value pairs. Structures let you build a collection of related variables that are
grouped under a single name. You can define ColdFusion structures dynamically.

ADOBE COLDFUSION 8 79
ColdFusion Developer’s Guide

You can use structures to refer to related values as a unit, rather than individually. To maintain employee lists, for
example, you can create a structure that holds personnel information such as name, address, phone number, ID
numbers, and so on. Then you can refer to this collection of information as a structure called employee rather than
as a collection of individual variables.
A structure’s key must be a string. The values associated with the key can be any valid ColdFusion value or object. It
can be a string or integer, or a complex object such as an array or another structure. Because structures can contain
any kind of data they provide a very powerful and flexible mechanism for representing complex data.

Structure notation
ColdFusion supports three types of notation for referencing structure contents. The notation that you use depends
on your requirements.
Notation

Description

Object.property

You can refer to a property, prop, of an object, obj, as obj.prop. This notation, also called dot notation, is useful
for simple assignments, as in this example:
depts.John="Sales"

Use this notation only when you know the property names (keys) in advance and they are strings, with no
special characters, numbers, or spaces. You cannot use the dot notation when the property, or key, is dynamic.
Associative arrays

If you do not know the key name in advance, or it contains spaces, numbers, or special characters, you can use
associative array notation. This notation uses structures as arrays with string indexes; for example:
depts["John"]="Sales"
depts[employeeName]="Sales"

You can use a variable (such as employeeName) as an associative array index. Therefore, you must enclose any
literal key names in quotation marks.
For information on using associative array references containing variables, see “Dynamically constructing
structure references” on page 60.
Structure

You use structure notation only when you create structures and set their initial values, not when you are
accessing or updating structure data, and only on the right side of an assignment expression. This notation has
the following format:
{keyName=value[,keyName=value]...}

where the square braces ([]) and ellipses (...) indicate optional contents that can be repeated.
The following example creates a structure that uses structure notation:


ADOBE COLDFUSION 8 80
ColdFusion Developer’s Guide













key2Var="key2">
key3Var="key3">
var2="2">


Value of the first key

#mystruct.key1#

#mystruct["key1"]#

#mystruct[key1Var]#



Value of the second entry in the key2 array

#myStruct.key2[2]#

#myStruct["key2"][2]#

#myStruct[key2Var][2]#

#myStruct[key2Var][var2]#



Value of the struct2key2 entry in the key3 structure

#myStruct.key3.struct2key2#

#myStruct["key3"]["struct2key2"]#

#myStruct[key3Var]["struct2key2"]#

#myStruct.key3["struct2key2"]#

#myStruct["key3"].struct2key2#




Reviewing the code

The following table describes the code:
Code

myArray[1]="2">
myArray[2]="3">
myStruct2=StructNew()>
myStruct2.struct2key1="4">
myStruct2.struct2key2="5">
myStruct=StructNew()>
myStruct.key1="1">
myStruct.key2=myArray>
myStruct.key3=myStruct2>

Create a structure with three entries: a string, an array, and an embedded structure.




Display the complete structure.


key2Var="key2">
key3Var="key3">
var2="2">

ADOBE COLDFUSION 8 81
ColdFusion Developer’s Guide

Code

Description


Value of the first key

#mystruct.key1#

#mystruct["key1"]#

#mystruct[key1Var]#




Output the value of the structure’s key1 (string) entry using the following notation:

Value of the second entry in the
key2 array

#myStruct.key2[2]#

#myStruct["key2"][2]#

#myStruct[key2Var][2]#

#myStruct[key2Var][var2]#




•

object.property notation

•

associative array notation with a constant

•

associative array notation with a variable

Output the value of the second entry in the structure’s key2 array using the
following notation:

•

object.property notation

•

associative array notation with a constant

•

associative array notation with a variable

•

associative array notation with variables for both the array and the array
index
Value of the struct2key2 entry in
the key3 structure

#myStruct.key3.struct2key2#

#myStruct["key3"]["struct2key2"]#

#myStruct[key3Var]["struct2key2"]#

#myStruct.key3["struct2key2"]#

#myStruct["key3"].struct2key2#





Output the value of second entry in the structure’s key3 embedded structure
using the following notation:

•

object.property notation

•

associative array notation with two constants

•

associative array notation with a variable and a constant

•

object.property notation followed by associative array notation

•

associative array notation followed by object.property notation

Creating and using structures
This section explains how to create and use structures in ColdFusion. The sample code in this section uses a
structure called employee, which is used to add new employees to a corporate information system.

Creating structures
In ColdFusion, you can create structures explicitly by using a function, and then populate the structure using
assignment statements or functions, or you can create the structure implicitly by using an assignment statement.
Creating structures using functions

You can create structures by assigning a variable name to the structure with the StructNew function as follows:


For example, to create a structure named departments, use the following syntax:


This creates an empty structure to which you can add data.
Creating structures implicitly

You can create an empty structure implicitly, as in the following example:


ADOBE COLDFUSION 8 82
ColdFusion Developer’s Guide

You can also create a structure by assigning data to a variable. For example, each of the following lines creates a
structure named myStruct with one element, name, that has the value Adobe Systems Incorporated.




When you use structure notation to create a structure, as shown in the third example, you can populate multiple
structure fields. The following example shows this use:


Similarly, you cannot use object.property notation on the left side of assignments inside structure notation. The
following statement, for example, causes an error:


Instead of using these formats, you must use multiple statements, such as the following:


You cannot use a dynamic variable when you create a structure implicitly. For example, the following expression
generates an error:



Adding and updating structure elements
You add or update a structure element to a structure by assigning the element a value or by using a ColdFusion
function. It is simpler and more efficient to use direct assignment.
You can add structure key-value pairs by defining the value of the structure key, as the following example shows:





The following code uses cfset and object.property notation to create a structure element called departments.John,
and changes John’s department from Sales to Marketing. It then uses associative array notation to change his
department to Facilities. Each time the department changes, it displays the results:



Before the first change, John was in the #departments.John# Department




After the first change, John is in the #departments.John# Department




After the second change, John is in the #departments.John# Department



ADOBE COLDFUSION 8 83
ColdFusion Developer’s Guide

Getting information about structures and keys
You use ColdFusion functions to find information about structures and their keys.
Getting information about structures

To find out if a given value represents a structure, use the IsStruct function, as follows:
IsStruct(variable)

This function returns True if variable is a ColdFusion structure. (It also returns True if variable is a Java object that
implements the java.util.Map interface.)
Structures are not indexed numerically, so to find out how many name-value pairs exist in a structure, use the
StructCount function, as in the following example:
StructCount(employee)

To discover whether a specific Structure contains data, use the StructIsEmpty function, as follows:
StructIsEmpty(structure_name)

This function returns True if the structure is empty, and False if it contains data.
Finding a specific key and its value

To determine whether a specific key exists in a structure, use the StructKeyExists function, as follows:
StructKeyExists(structure_name, "key_name")

Do not put the name of the structure in quotation marks, but you do put the key name in quotation marks. For
example, the following code displays the value of the MyStruct.MyKey only if it exists:

 #mystruct.myKey#



You can use the StructKeyExists function to dynamically test for keys by using a variable to represent the key
name. In this case, you do not put the variable in quotation marks. For example, the following code loops through
the records of the GetEmployees query and tests the myStruct structure for a key that matches the query’s LastName
field. If ColdFusion finds a matching key, it displays the Last Name from the query and the corresponding entry in
the structure.


#LastName#: #mystruct[LastName]#




If the name of the key is known in advance, you can also use the ColdFusion IsDefined function, as follows:
IsDefined("structure_name.key")>

However, if the key is dynamic, or contains special characters, you must use the StructKeyExists function.
Note: Using StructKeyExists to test for the existence of a structure entry is more efficient than using IsDefined.
ColdFusion scopes are available as structures and you can improve efficiency by using StructKeyExists to test for the
existence of variables.
Getting a list of keys in a structure

To get a list of the keys in a CFML structure, you use the StructKeyList function, as follows:


ADOBE COLDFUSION 8 84
ColdFusion Developer’s Guide

You can specify any character as the delimiter; the default is a comma.
Use the StructKeyArray function to returns an array of keys in a structure, as follows:


Note: The StructKeyList and StructKeyArray functions do not return keys in any particular order. Use the
ListSort or ArraySort functions to sort the results.

Copying structures
ColdFusion provides several ways to copy structures and create structure references. The following table lists these
methods and describes their uses:
Technique

Use

Duplicate function Makes a complete copy of the structure. All data is copied from the original structure to the new structure, including

the contents of structures, queries, and other objects. As a result changes to one copy of the structure have no effect
on the other structure.
This function is useful when you want to move a structure completely into a new scope. In particular, if a structure is
created in a scope that requires locking (for example, Application), you can duplicate it into a scope that does not
require locking (for example, Request), and then delete it in the scope that requires locking.
StructCopy func-

tion

Makes a shallow copy of a structure. It creates a new structure and copies all simple variable and array values at the
top level of the original structure to the new structure. However, it does not make copies of any structures, queries,
or other objects that the original structure contains, or of any data inside these objects. Instead, it creates a reference
in the new structure to the objects in the original structure. As a result, any change to these objects in one structure
also changes the corresponding objects in the copied structure.
The Duplicate function replaces this function for most, if not all, purposes.

Variable assignment

Creates an additional reference, or alias, to the structure. Any change to the data using one variable name changes
the structure that you access using the other variable name.
This technique is useful when you want to add a local variable to another scope or otherwise change a variable’s
scope without deleting the variable from the original scope.

The following example shows the different effects of copying, duplicating, and assigning structure variables:
Create a new structure
















A StructCopy copied structure






A Duplicated structure







ADOBE COLDFUSION 8 85
ColdFusion Developer’s Guide

A new reference to a structure






Change a string, array element, and structure value in the StructCopy copy.






Original structure



Copied structure



Duplicated structure



Structure reference




Change a string, array element, and structure value in the Duplicate.






Original structure



Copied structure



Duplicated structure



Structure reference




Change a string, array element, and structure value in the reference.






Original structure



Copied structure



Duplicated structure



Structure reference




Clear the original structure


Original structure:



Copied structure



Duplicated structure



Structure reference:




ADOBE COLDFUSION 8 86
ColdFusion Developer’s Guide

Deleting structure elements and structures
To delete a key and its value from a structure, use the StructDelete function, as follows:
StructDelete(structure_name, key [, indicateNotExisting ])

The indicateNotExisting argument tells the function what to do if the specified key does not exist. By default, the
function always returns True. However, if you specify True for the indicateNotExisting argument, the function
returns True if the key exists and False if it does not.
You can also use the StructClear function to delete all the data in a structure but keep the structure instance itself,
as follows:
StructClear(structure_name)

If you use StructClear to delete a structure that you have copied using the StructCopy function, the specified
structure is deleted, but the copy is unaffected.
If you use StructClear to delete a structure that has a multiple references, the function deletes the contents of the
structure and all references point to the empty structure, as the following example shows:

Structure before StructClear




After Clear:

myStruct: 

myCopy: 

Looping through structures
You can loop through a structure to output its contents, as the following example shows:










Employee
Department



#person#
#Departments[person]#





ADOBE COLDFUSION 8 87
ColdFusion Developer’s Guide

Structure examples
Structures are particularly useful for grouping together a set of variables under a single name. The example in this
section uses structures to collect information from a form, and to submit that information to a custom tag, named
cf_addemployee. For information on creating and using custom tags, see “Creating and Using Custom CFML Tags”
on page 190.
Example file newemployee.cfm

The following ColdFusion page shows how to create structures and use them to add data to a database. It calls the
cf_addemployee custom tag, which is defined in the addemployee.cfm file.





Add New Employees









Please fill out the form.



employee=StructNew();
employee.firstname = Form.firstname;
employee.lastname = Form.lastname;
employee.email = Form.email;
employee.phone = Form.phone;
employee.department = Form.department;


First name is #StructFind(employee, "firstname")#

Last name is #StructFind(employee, "lastname")#

EMail is #StructFind(employee, "email")#

Phone is #StructFind(employee, "phone")#

Department is #StructFind(employee, "department")#








First Name: 



ADOBE COLDFUSION 8 88
ColdFusion Developer’s Guide

Last Name: 


EMail: 


Phone: 


Department: 








Reviewing the code

The following table describes the code:
Code

name="Form.lastname" default="">
name="Form.email" default="">
name="Form.phone" default="">
name="Form.department" default="">


Please fill out the form.


Set default values of all form fields so that they exist the first time this page
is displayed and can be tested.

Test the value of the form’s firstname field. This field is required. The test is
False the first time the page displays.
If there is no data in the Form.firstname variable, display a message
requesting the user to fill the form.

ADOBE COLDFUSION 8 89
ColdFusion Developer’s Guide

Code

Description




employee=StructNew();
employee.firstname = Form.firstname;
employee.lastname = Form.lastname;
employee.email = Form.email;
employee.phone = Form.phone;
employee.department = Form.department;


If Form.firstname contains text, the user submitted the form.
Use CFScript to create a new structure named employee and fill it with the
form field data.
Then display the contents of the structure.

First name is #employee.firstname#

Last name is #employee.lastname#

EMail is #employee.email#

Phone is #employee.phone#

Department is #employee.department#





Call the cf_addemployee custom tag and pass it a copy of the employee
structure in the empinfo attribute.
The duplicate function ensures that the custom tag gets a copy of the
employee structure, not the original. Although this is not necessary in this
example, it is good practice because it prevents the custom tag from modifying the calling page’s structure contents.

 The data form. When the user clicks Submit, the form posts the data to this
First Name: 
ColdFusion page.


Last Name: 


EMail: 


Phone: 


Department: 







Example file addemployee.cfm

The following file is an example of a custom tag used to add employees. Employee information is passed through the
employee structure (the empinfo attribute). For databases that do not support automatic key generation, you must
also add the Emp_ID.


Error. No employee data was passed.






INSERT INTO Employees
(FirstName, LastName, Email, Phone, Department)
VALUES (
'#attributes.empinfo.firstname#' ,
'#attributes.empinfo.lastname#' ,

ADOBE COLDFUSION 8 90
ColdFusion Developer’s Guide

'#attributes.empinfo.email#' ,
'#attributes.empinfo.phone#' ,
'#attributes.empinfo.department#' )



Employee Add Complete

Reviewing the code

The following table describes the code:
Code

Description



Error. No employee data was passed.



If the custom tag was called without an empinfo attribute, displays an
error message and exit the tag.



INSERT INTO Employees
(FirstName, LastName, Email, Phone,
Department)
VALUES (
'#attributes.empinfo.firstname#' ,
'#attributes.empinfo.lastname#' ,
'#attributes.empinfo.email#' ,
'#attributes.empinfo.phone#' ,
'#attributes.empinfo.department#' )



Add the employee data passed in the empinfo structure to the Employees
table of the cfdocexamples database.


Employee Add Complete


Use direct references to the structure entries, not StructFind functions.
If the database does not support automatic generation of the Emp_ID key,
you must add an Emp_ID entry to the form and add it to the query.

Display a completion message. This code does not have to be inside the
cfelse block because the cfexit tag prevents it from being run if the
empinfo structure is empty.

Structure functions
You can use the following functions to create and manage structures in ColdFusion applications. The table describes
each function’s purpose and provides specific, but limited, information that can assist you in determining whether
to use the function instead of other technique.
All functions except StructDelete throw an exception if a referenced key or structure does not exist.
For more information on these functions, see the CFML Reference.
Function

Description

Duplicate

Returns a complete copy of the structure.

IsStruct

Returns True if the specified variable is a ColdFusion structure or a Java object that implements the
java.util.Map interface.

StructAppend

Appends one structure to another.

StructClear

Removes all data from the specified structure.

StructCopy

Returns a "shallow" copy of the structure. All embedded objects are references to the objects in the original
structure. The Duplicate function has replaced this function for most purposes.

ADOBE COLDFUSION 8 91
ColdFusion Developer’s Guide

Function

Description

StructCount

Returns the number of keys in the specified structure.

StructDelete

Removes the specified item from the specified structure.

StructFind

Returns the value associated with the specified key in the specified structure. This function is redundant with
accessing structure elements using associative array notation.

StructFindKey

Searches through a structure for the specified key name and returns an array containing data on the found key
or keys.

StructFindValue

Searches through a structure for the specified simple data value (for example, a string or number) and returns
an array containing information on the value location in the structure.

StructGet

Returns a reference to a substructure contained in a structure at the specified path. This function is redundant
with using direct reference to a structure. If you accidentally use this function on a variable that is not a structure, it replaces the value with an empty structure.

StructInsert

Inserts the specified key-value pair into the specified structure. Unlike a direct assignment statement, this
function generates an error by default if the specified key exists in the structure.

StructIsEmpty

Indicates whether the specified structure contains data. Returns True if the structure contains no data, and
False if it does contain data.

StructKeyArray

Returns an array of keys in the specified structure.

StructKeyExists

Returns True if the specified key is in the specified structure. You can use this function in place of the
IsDefined function to check for the existence of variables in scopes that are available as structures.

StructKeyList

Returns a list of keys in the specified structure.

StructNew

Returns a new structure.

StructSort

Returns an array containing the key names of a structure in the order determined by the sort criteria.

StructUpdate

Updates the specified key with the specified value. Unlike a direct assignment statement, this function generates an error if the structure or key does not exist.

92

Chapter 6: Extending ColdFusion Pages
with CFML Scripting
Adobe ColdFusion offers a server-side scripting language, CFScript, that provides ColdFusion functionality in script
syntax. This JavaScript-like language gives developers the same control flow as ColdFusion, but without tags. You
can also use CFScript to write user-defined functions that you can use anywhere that a ColdFusion expression is
allowed.
Contents

About CFScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
The CFScript language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Using CFScript statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Handling exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
CFScript example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

About CFScript
CFScript is a language within a language. It is a scripting language that is similar to JavaScript but is simpler to use.
Also, unlike JavaScript, CFScript only runs on the ColdFusion server; it does not run on the client system. CFScript
code can use all the ColdFusion functions and expressions, and has access to all ColdFusion variables that are
available in the script’s scope.
CFScript provides a compact and efficient way to write ColdFusion logic. Typical uses of CFScript include the
following:

•

Simplifying and speeding variable setting

•

Building compact JavaScript-like flow control structures

•

Creating user-defined functions

Because you use functions and expressions directly in CFScript, you do not have to surround each assignment or
function in a cfset tag. Also, CFScript assignments are often faster than cfset tags.
CFScript provides a set of decision and flow-control structures that are more familiar than ColdFusion tags to most
programmers.
In addition to variable setting, other operations tend to be slightly faster in CFScript than in tags.
ColdFusion 5 and later releases let you use CFScript to create user-defined functions, or UDFs (also known as
custom functions). You call UDFs in the same manner that you call standard ColdFusion functions. UDFs are to
ColdFusion built-in functions what custom tags are to ColdFusion built-in tags. Typical uses of UDFs include data
manipulation and mathematical calculation routines.
You cannot include ColdFusion tags in CFScript. However, a number of functions and CFScript statements are
equivalent to commonly used tags. For more information, see “CFScript functional equivalents to ColdFusion tags”
on page 96.

ADOBE COLDFUSION 8 93
ColdFusion Developer’s Guide

Comparing tags and CFScript
The following examples show how you can use CFML tags and CFScript to do the same thing. Each example takes
data submitted from a form and puts it in a structure; if the form does not have a last name and department field, it
displays a message.
Using CFML tags









Adding #Form.firstname# #Form.lastname#




You must enter a Last Name and Department.





Using CFScript

if (IsDefined("Form.submit")) {
if ((Form.lastname NEQ "") AND (Form.department NEQ "")) {
employee=StructNew();
employee.firstname=Form.firstname;
employee.lastname=Form.lastname;
employee.email=Form.email;
employee.phone=Form.phone;
employee.department=Form.department;
WriteOutput("Adding #Form.firstname# #Form.lastname# 
");
}
else
WriteOutput("You must enter a Last Name and Department.
");
}


The CFScript language
This section explains the syntax of the CFScript language.

Identifying CFScript
You enclose CFScript regions inside  and  tags. No other CFML tags are allowed inside a
cfscript region. The following lines show a minimal script:

a = 2;


ADOBE COLDFUSION 8 94
ColdFusion Developer’s Guide

Variables
CFScript variables can be of any ColdFusion type, such as numbers, strings, arrays, queries, and objects. The
CFScript code can read and write any variables that are available in the page that contains the script. This includes
all common scope variables, such as session, application, and server variables.

Expressions and operators
CFScript supports all CFML expressions. CFML expressions include operators (such as +, -, EQ, and so on), as well
as all CFML functions.
You can use several comparison operators in CFScript only, not in CFML tags. (You can also use the corresponding
CFML operators in CFScript.) The following table lists the CFScript-only operators and the equivalent operator that
you can use in CFML tags or CFScript:
CFScript operator

CFML operator

CFScript operator

CFML operator

==

EQ

!=

NEQ

<

LT

<=

LTE

>

GT

>=

GTE

For information about CFML expressions, operators, and functions, see “Using Expressions and Number Signs” on
page 50.

Statements
CFScript supports the following statements:
assignment

for-in

try-catch

function call

while

function (function definition)

if-else

do-while

var (in custom functions only)

switch-case-default

break

return (in custom functions only)

for

continue

The following rules apply to statements:

•

You must put a semicolon at the end of a statement.

•

Line breaks are ignored. A single statement can cross multiple lines.

•

White space is ignored. For example, it does not matter whether you precede a semicolon with a space character.

•

Use curly braces to group multiple statements together into one logical statement unit.

•

Unless otherwise indicated, you can use any ColdFusion expression in the body of a statement.

Note: This chapter documents all statements except function, var, and return. For information on these statements,
see “Defining functions in CFScript” on page 135.

Statement blocks
Curly brace characters ({ and }) group multiple CFScript statements together so that they are treated as a single unit
or statement. This enables you to create code blocks in conditional statements, such as the following:

ADOBE COLDFUSION 8 95
ColdFusion Developer’s Guide

if(score GT 0) {
result = "positive";
Positives = Positives + 1;
}

In this example, both assignment statements are executed if the score is greater than 0. If they were not in the code
block, only the first line would execute.
You do not have to put brace characters on their own lines in the code. For example, you could put the open brace
in the preceding example on the same line as the if statement, and some programmers use this style. However,
putting at least the ending brace on its own line makes it easier to read the code and separate out code blocks.

Comments
CFScript has two forms of comments: single line and multiline.
A single line comment begins with two forward slashes (//) and ends at the line end; for example:
//This is a single-line comment.
//This is a second single-line comment.

A multiline comment starts with a /* marker and continues until it reaches a */ marker; for example:
/*This is a multiline comment.
You do not need to start each line with a comment indicator.
This is the last line in the comment. */

The following rules apply to comments:
1 Comments do not have to start at the beginning of a line. They can follow active code on a line. For example, the
following line is valid:
MyVariable = 12; // Set MyVariable to the default value.

The end of a multiline comment can be followed on the same line by active code. For example, the following line
is valid, although it is poor coding practice:
2

End of my long comment */ foo = "bar";

3

You can use multiline format for a comment on a single line, for example:
/*This is a single line comment using multiline format. */

•

You cannot nest /* and */ markers inside other comment lines.

•

CFML comments () do not work in CFScript.

Reserved words
In addition to the names of ColdFusion functions and words reserved by ColdFusion expressions (such as NOT,
AND, IS, and so on), the following words are reserved in CFScript. Do not use these words as variables or identifiers
in your scripting code:
break

default

function

switch

case

do

if

try

catch

else

in

var

continue

for

return

while

ADOBE COLDFUSION 8 96
ColdFusion Developer’s Guide

Differences from JavaScript
Although CFScript and JavaScript are similar, they have several key differences. The following list identifies CFScript
features that differ from JavaScript:

• CFScript uses ColdFusion expressions, which are neither a superset nor a subset of JavaScript expressions. In
particular, ColdFusion expressions do not support bitwise operators, and the ColdFusion MOD or % operator
operates differently from the corresponding JavaScript % operator: In ColdFusion, the operator does integer arithmetic and ignores fractional parts. ColdFusion expressions also support the EQV, IMP, CONTAINS, and DOES
NOT CONTAIN operators that are not supported in JavaScript.
•

Variable declarations (var keyword) are only used in user-defined functions and threads.

•

CFScript is case-insensitive.

•

All statements end with a semicolon, and line breaks in the code are ignored.

• Assignments are statements, not expressions, and therefore cannot be used in situations that require the
assignment operation to be evaluated.
•

JavaScript objects, such as Window and Document, are not available.

•

Only the ColdFusion server processes CFScript. There is no client-side CFScript.

CFScript limitation
You cannot include ColdFusion tags in CFScript. However, you can include cfscript blocks inside other
ColdFusion tags, such as cfoutput.

CFScript functional equivalents to ColdFusion tags
Tag

CFScript equivalent

cfset

Direct assignment, such as Myvar=1;

cfoutput

WriteOutput function

cfif, cfelseif, cfelse

if and else statements

cfswitch, cfcase,
cfdefaultcase

switch, case, and default statements

Indexed cfloop

for loops

Conditional cfloop

while loops and do while loops

Structure cfloop

for in loop. (There is no equivalent for queries, lists, or objects.)

cfbreak

break statement. CFScript also has a continue statement that has no equivalent CFML tag.

cftry, cfcatch

try and catch statements

cfcookie

Direct assignment of Cookie scope memory-only variables. You cannot use direct assignment to set
persistent cookies that are stored on the user’s system.

cfobject

CreateObject function

For example, the following example loops through a query in CFScript:
...

// Loop through the qGetEmails RecordSet

ADOBE COLDFUSION 8 97
ColdFusion Developer’s Guide

for (x = 1; x LTE qGetEmails.RecordCount; x=x+1) {
This_id = qGetEmails.Emails_id[x];
This_Subject = qGetEmails.Subject[x];
This_RecFrom = qGetEmails.RecFrom[x];
This_SentTo = qGetEmails.SentTo[x];
This_dReceived = qGetEmails.dReceived[x];
This_Body = qGetEmails.Body[x];
... // More code goes here.
}


Using CFScript statements
The following sections describe how to use these CFScript statements:

•

Using assignment statements and functions

•

Using conditional processing statements

•

Using looping statements

Using assignment statements and functions
CFScript assignment statements are the equivalent of the cfset tag. These statements have the following form:
lval = expression;

lval is any ColdFusion variable reference; for example:
x = "positive";
y = x;
a[3]=5;
structure.member=10;
ArrayCopy=myArray;

You can use ColdFusion function calls, including UDFs, directly in CFScript. For example, the following line is a
valid CFScript statement:
StructInsert(employee,"lastname",FORM.lastname);

Using conditional processing statements
CFScript includes the following conditional processing statements:

•

if and else statements, which serve the same purpose as the cfif, cfelseif, and cfelse tags

•

switch, case, and default statements, which are the equivalents of the cfswitch, cfcase, and

cfdefaultcase tags
Using if and else statements

The if and else statements have the following syntax:
if(expr) statement [else statement]

In its simplest form, an if statement looks like this:
if(value EQ 2700)
message = "You’ve reached the maximum";

A simple if-else statement looks like the following:

ADOBE COLDFUSION 8 98
ColdFusion Developer’s Guide

if(score GT 1)
result = "positive";
else
result = "negative";

CFScript does not include an elseif statement. However, you can use an if statement immediately after an else
statement to create the equivalent of a cfelseif tag, as the following example shows:
if(score GT 1)
result = "positive";
else if(score EQ 0)
result = "zero";
else
result = "negative";

As with all conditional processing statements, you can use curly braces to enclose multiple statements for each
condition, as follows:
if(score GT 1) {
result = "positive";
message = "The result was positive.";
}
else {
result = "negative";
message = "The result was negative.";
}

Note: Often, you can make your code clearer by using braces even where they are not required.
Using switch and case statements

The switch statement and its dependent case and default statements have the following syntax:
switch (expression) {
case constant: [case constant:]... statement(s) break;
[case constant: [case constant:]... statement(s) break;]...
[default: statement(s)] }

Use the following rules and recommendations for switch statements:

•

You cannot mix Boolean and numeric constant values in a switch statement.

•

Each constant value must be a constant (that is, not a variable, a function, or other expression).

• Multiple case constant: statements can precede the statement or statements to execute if any of the cases are true.
This lets you specify several matches for one code block.
•

No two constant values can be the same.

• The statements following the colon in a case statement block do not have to be in braces. If a constant value
equals the switch expression, ColdFusion executes all statements through the break statement.
• The break statement at the end of the case statement tells ColdFusion to exit the switch statement. ColdFusion
does not generate an error message if you omit a break statement. However, if you omit it, ColdFusion executes all
the statements in the following case statement, even if that case is false. In nearly all circumstances, this is not what
you want to do.
• You can have only one default statement in a switch statement block. ColdFusion executes the statements in
the default block if none of the case statement constants equals the expression value.
• The default statement does not have to follow all switch statements, but it is good programming practice to
do so. If any switch statements follow the default statement you must end the default block code with a break
statement.

ADOBE COLDFUSION 8 99
ColdFusion Developer’s Guide

• The default statement is not required. However, you should use one if the case constants do not include all
possible values of the expression.
• The default statement does not have to follow all the case statements; however, it is good programming
practice to put it there.
The following switch statement takes the value of a name variable:
1

If the name is John or Robert, it sets both the male variable and the found variable to True.

2

If the name is Mary, it sets the male variable to False and the found variable to True.

3

Otherwise, it sets the found variable to False.

switch(name) {
case "John": case "Robert":
male=True;
found=True;
break;
case "Mary":
male=False;
found=True;
break;
default:
found=False;
} //end switch

Using looping statements
CFScript provides a richer selection of looping constructs than those supplied by CFML tags. It enables you to create
efficient looping constructs similar to those in most programming and scripting languages. CFScript provides the
following looping constructs:

•

For

•

While

•

Do-while

•

For-in

CFScript also includes the continue and break statements that control loop processing.
The following sections describe these types of loops and their uses.
Using for loops

The for loop has the following format:
for (initial-expression; test-expression; final-expression) statement

The initial-expression and final-expression can be one of the following:

•

A single assignment expression; for example, x=5 or loop=loop+1

•

Any ColdFusion expression; for example, SetVariable("a",a+1)

•

Empty

The test-expression can be one of the following:

•

Any ColdFusion expression; for example:
A LT 5
index LE x

ADOBE COLDFUSION 8 100
ColdFusion Developer’s Guide

status EQ "not found" AND index LT end

•

Empty

Note: The test expression is re-evaluated before each repeat of the loop. If code inside the loop changes any part of the
test expression, it can affect the number of iterations in the loop.
The statement can be a single semicolon terminated statement or a statement block in curly braces.
When ColdFusion executes a for loop, it does the following:
1

Evaluates the initial expression.

2

Evaluates the test-expression.

3

If the test-expression is False, exits the loop and processing continues following the statement.
If the test-expression is True:
a

Executes the statement (or statement block).

b

Evaluates the final-expression.

c

Returns to Step 2.

For loops are most commonly used for processing in which an index variable is incremented each time through the
loop, but it is not limited to this use.
The following simple for loop sets each element in a 10-element array with its index number.
for(index=1;
index LTE 10;
index = index + 1)
a[index]=index;

The following, more complex, example demonstrates two features:

•

The use of curly braces to group multiple statements into a single block.

•

An empty condition statement. All loop control logic is in the statement block.


strings=ArrayNew(1);
ArraySet(strings, 1, 10, "lock");
strings[5]="key";
indx=0;
for( ; ; ) {
indx=indx+1;
if(Find("key",strings[indx],1)) {
WriteOutput("Found key at " & indx & ".
");
break;
}
else if (indx IS ArrayLen(strings)) {
WriteOutput("Exited at " & indx & ".
");
break;
}
}


This example shows one important issue that you must remember when creating loops: you must always ensure that
the loop ends. If this example lacked the else if statement, and there was no “key” in the array, ColdFusion would
loop forever or until a system error occurred; you would have to stop the server to end the loop.

ADOBE COLDFUSION 8 101
ColdFusion Developer’s Guide

The example also shows two issues with index arithmetic: in this form of loop you must make sure to initialize the
index, and you must keep track of where the index is incremented. In this case, because the index is incremented at
the top of the loop, you must initialize it to 0 so it becomes 1 in the first loop.
Using while loops

The while loop has the following format:
while (expression) statement

The while statement does the following:
1

Evaluates the expression.

2

If the expression is True, it does the following:
a Executes the statement, which can be a single semicolon-terminated statement or a statement block in curly
braces.
b

Returns to step 1.

If the expression is False, processing continues with the next statement.
The following example uses a while loop to populate a 10-element array with multiples of five.
a = ArrayNew(1);
loop = 1;
while (loop LE 10) {
a[loop] = loop * 5;
loop = loop + 1;
}

As with other loops, you must make sure that at some point the while expression is False and you must be careful
to check your index arithmetic.
Using do-while loops

The do-while loop is like a while loop, except that it tests the loop condition after executing the loop statement block.
The do-while loop has the following format:
do statement while (expression);

The do while statement does the following:
1 Executes the statement, which can be a single semicolon-terminated statement or a statement block in curly
braces.
2

Evaluates the expression.

3

If the expression is true, it returns to step 1.

If the expression is False, processing continues with the next statement.
The following example, like the while loop example, populates a 10-element array with multiples of 5:
a = ArrayNew(1);
loop = 1;
do {
a[loop] = loop * 5;
loop = loop + 1;
}
while (loop LE 10);

ADOBE COLDFUSION 8 102
ColdFusion Developer’s Guide

Because the loop index increment follows the array value assignment, the example initializes the loop variable to 1
and tests to make sure that it is less than or equal to 10.
The following example generates the same results as the previous two examples, but it increments the index before
assigning the array value. As a result, it initializes the index to 0, and the end condition tests that the index is less
than 10.
a = ArrayNew(1);
loop = 0;
do {
loop = loop + 1;
a[loop] = loop * 5;
}
while (loop LT 10);

The following example loops through a query:

... sql goes here...


if (myQuery.RecordCount gt 0) {
currRow=1;
do {
theValue=myQuery.myField[CurrRow];
currRow=currRow+1;
} while (currRow LTE myQuery.RecordCount);
}


Using for-in loops

The for-in loop loops over the elements in a ColdFusion structure. It has the following format:
for (variable in structure) statement

The variable can be any ColdFusion identifier; it holds each structure key name as ColdFusion loops through the
structure. The structure must be the name of an existing ColdFusion structure. The statement can be a single
semicolon terminated statement or a statement block in curly braces.
The following example creates a structure with three elements. It then loops through the structure and displays the
name and value of each key. Although the curly braces are not required here, they make it easier to determine the
contents of the relatively long WriteOutput function. In general, you can make structured control flow, especially
loops, clearer by using curly braces.
myStruct=StructNew();
myStruct.productName="kumquat";
mystruct.quality="fine";
myStruct.quantity=25;
for (keyName in myStruct) {
WriteOutput("myStruct." & Keyname & " has the value: " &
myStruct[keyName] &"
");
}

Note: Unlike the cfloop tag, CFScript for-in loops do not provide built-in support for looping over queries and lists.
Using continue and break statements

The continue and break statements enable you to control the processing inside loops:

•

The continue statement tells ColdFusion to skip to the beginning of the next loop iteration.

ADOBE COLDFUSION 8 103
ColdFusion Developer’s Guide

•

The break statement exits the current loop or case statement.

Using continue

The continue statement ends the current loop iteration, skips any code following it in the loop, and jumps to the
beginning of the next loop iteration. For example, the following code loops through an array and display’s each value
that is not an empty string:
for ( loop=1; loop LE 10; loop = loop+1) {
if(a[loop] EQ "") continue;
WriteOutput(loop);
}

(To test this code snippet, you must first create an array, a, with 10 or more elements, some of which are not empty
strings.)
In general, the continue statement is particularly useful if you loop over arrays or structures and you want to skip
processing for array elements or structure members with specific values, such as the empty string.
Using break

The break statement exits the current loop or case statement. Processing continues at the next CFScript statement.
You end case statement processing blocks with a break statement. You can also use a test case with a break
statement to prevent infinite loops, as shown in the following example. This script loops through an array and prints
out the array indexes that contain the value key. It uses a conditional test and a break statement to make sure that
the loop ends when at the end of the array.
strings=ArrayNew(1);
ArraySet(strings, 1, 10, "lock");
strings[5]="key";
strings[9]="key";
indx=0;
for( ; ; ) {
indx=indx+1;
if(Find("key",strings[indx],1)) {
WriteOutput("Found a key at " & indx & ".
");
}
else if (indx IS ArrayLen(strings)) {
WriteOutput("Array ends at index " & indx & ".
");
break;
}
}

Handling exceptions
ColdFusion provides two statements for exception handling in CFScript: try and catch. These statements are
equivalent to the CFML cftry and cfcatch tags.
Note: This section does not explain exception-handling concepts. For a discussion of exception handling in ColdFusion,
see “Handling Errors” on page 246.

Exception handling syntax and rules
Exception-handling code in CFScript has the following format:
try {
Code where exceptions will be caught

ADOBE COLDFUSION 8 104
ColdFusion Developer’s Guide

}
catch(exceptionType exceptionVariable) {
Code to handle exceptions of type exceptionType
that occur in the try block
}
...
catch(exceptionTypeN exceptionVariableN) {
Code to handle exceptions of type
exceptionTypeN that occur in the try block
}

Note: In CFScript, catch statements follow the try block; you do not put them inside the try block. This structure
differs from that of the cftry tag, which must include the cfcatch tags in its body.
When you have a try statement, you must have a catch statement. In the catch block, the exceptionVariable
variable contains the exception type. This variable is the equivalent of the cfcatch tag cfcatch.Type built-in
variable.

Exception handling example
The following code shows exception handling in CFScript. It uses a CreateObject function to create a Java object.
The catch statement executes only if the CreateObject function generates an exception. The displayed information
includes the exception message; the except.Message variable is the equivalent of calling the Java getMessage method
on the returned Java exception object.

try {
emp = CreateObject("Java", "Employees");
}
catch(Any excpt) {
WriteOutput("The application was unable to perform a required operation.

Please try again later.
If this problem persists, contact
Customer Service and include the following information:

#excpt.Message#
");
}


CFScript example
The example in this section uses the following CFScript features:

•

Variable assignment

•

Function calls

•

For loops

•

If-else statements

•

WriteOutput functions

•

Switch statements

The example uses CFScript without any other ColdFusion tags. It creates a structure of course applicants. This
structure contains two arrays; the first has accepted students, the second has rejected students. The script also creates
a structure with rejection reasons for some (but not all) rejected students. It then displays the accepted applicants
followed by the rejected students and their rejection reasons.

ADOBE COLDFUSION 8 105
ColdFusion Developer’s Guide







//Set the variables
acceptedApplicants[1] = "Cora Cardozo";
acceptedApplicants[2] = "Betty Bethone";
acceptedApplicants[3] = "Albert Albertson";
rejectedApplicants[1] = "Erma Erp";
rejectedApplicants[2] = "David Dalhousie";
rejectedApplicants[3] = "Franny Farkle";
applicants.accepted=acceptedApplicants;
applicants.rejected=rejectedApplicants;
rejectCode=StructNew();
rejectCode["David Dalhousie"] = "score";
rejectCode["Franny Farkle"] = "too late";
//Sort and display accepted applicants
ArraySort(applicants.accepted,"text","asc");
WriteOutput("The following applicants were accepted:
");
for (j=1;j lte ArrayLen(applicants.accepted);j=j+1) {
WriteOutput(applicants.accepted[j] & "
");
}
WriteOutput("
");
//sort and display rejected applicants with reasons information
ArraySort(applicants.rejected,"text","asc");
WriteOutput("The following applicants were rejected:
");
for (j=1;j lte ArrayLen(applicants.rejected);j=j+1) {
applicant=applicants.rejected[j];
WriteOutput(applicant & "
");
if (StructKeyExists(rejectCode,applicant)) {
switch(rejectCode[applicant]) {
case "score":
WriteOutput("Reject reason: Score was too low.
");
break;
case "late":
WriteOutput("Reject reason: Application was late.
");
break;
default:
WriteOutput("Rejected with invalid reason code.
");
} //end switch
} //end if
else {
WriteOutput("Reject reason was not defined.
");
} //end else
WriteOutput("
");
} //end for

Reviewing the code

The following table describes the code:

ADOBE COLDFUSION 8 106
ColdFusion Developer’s Guide

Code

Description


acceptedApplicants[1] = "Cora Cardozo";
acceptedApplicants[2] = "Betty Bethone";
acceptedApplicants[3] = "Albert Albertson";
rejectedApplicants[1] = "Erma Erp";
rejectedApplicants[2] = "David Dalhousie";
rejectedApplicants[3] = "Franny Farkle";
applicants.accepted=acceptedApplicants;
applicants.rejected=rejectedApplicants;

Creates two one-dimensional arrays, one with the accepted applicants and another with the rejected applicants. The entries in each
array are in random order.

rejectCode=StructNew();
rejectCode["David Dalhousie"] = "score";
rejectCode["Franny Farkle"] = "too late";
ArraySort(applicants.accepted,"text","asc");
WriteOutput("The following applicants were
accepted:
");
for (j=1;j lte
ArrayLen(applicants.accepted);j=j+1) {
WriteOutput(applicants.accepted[j] & "
");
}
WriteOutput("
");

Creates a structure and assign each array to an element of the structure.
Creates a structure with rejection codes for rejected applicants. The
rejectedCode structure does not have entries for all rejected applicants, and one of its values does not match a valid code. The structure
element references use associative array notation in order to use key
names that contain spaces.
Sorts the accepted applicants alphabetically.
Displays a heading.
Loops through the accepted applicants and writes their names.
Braces enhance clarity, although they are not needed for a single
statement loop.
Writes an additional line break at the end of the list of accepted applicants.

ArraySort(applicants.rejected,"text","asc");
WriteOutput("The following applicants were
rejected:
");

Sorts rejectedApplicants array alphabetically and writes a
heading.

for (j=1;j lte
ArrayLen(applicants.rejected);j=j+1) {
applicant=applicants.rejected[j];
WriteOutput(applicant & "
");

Loops through the rejected applicants.
Sets the applicant variable to the applicant name. This makes the
code clearer and enables you to easily reference the rejectCode
array later in the block.
Writes the applicant name.

if (StructKeyExists(rejectCode,applicant)) {
switch(rejectcode[applicant]) {
case "score":
WriteOutput("Reject reason: Score was too
low.
");
break;
case "late":
WriteOutput("Reject reason: Application was
late.
");
break;
default:
WriteOutput("Rejected with invalid reason
code.
");
} //end switch
} //end if

Checks the rejectCode structure for a rejection code for the applicant.

else {
WriteOutput("Reject reason was not defined.

");
{

If there is no entry for the applicant in the rejectCode structure,
displays a message indicating that the reason was not defined.

WriteOutput("
");
} //end for


Displays a blank line after each rejected applicant.

If a code exists, enters a switch statement that examines the rejection
code value.
If the rejection code value matches one of the known codes, displays
an expanded explanation of the meaning. Otherwise (the default
case), displays an indication that the rejection code is not valid.
Comments at the end of blocks help clarify the control flow.

Ends the for loop that handles each rejected applicant.
Ends the CFScript.

107

Chapter 7: Using Regular Expressions in
Functions
Regular expressions let you perform string matching operations using ColdFusion functions; in particular. regular
expressions work with the following functions:

•

REFind

•

REFindNoCase

•

REReplace

•

REReplaceNoCase

Regular expressions used in the cfinput and cftextinput tags are JavaScript regular expressions, which have a
slightly different syntax than ColdFusion regular expressions. For information on JavaScript regular expressions, see
“Building Dynamic Forms with cfform Tags” on page 530.
Contents

About regular expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Regular expression syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Using backreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Returning matched subexpressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Regular expression examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Types of regular expression technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

About regular expressions
In traditional string matching, as used by the ColdFusion Find and Replace functions, you provide the string
pattern to search for and the string to search. The following example searches a string for the pattern " BIG " and
returns a string index if found. The string index is the location in the search string where the string pattern begins.



You must provide the exact string pattern to match. If the exact pattern is not found, Find returns an index of 0.
Because you must specify the exact string pattern to match, matches for dynamic data can be very difficult, if not
impossible, to construct.
The next example uses a regular expression to perform the same search. This example searches for the first occurrence in the search string of any string pattern that consists entirely of uppercase letters enclosed by spaces:



The regular expression " [A-Z]+ " matches any string pattern consisting of a leading space, followed by any number
of uppercase letters, followed by a trailing space. Therefore, this regular expression matches the string " BIG " and
any string of uppercase letters enclosed in spaces.

ADOBE COLDFUSION 8 108
ColdFusion Developer’s Guide

By default, the matching of regular expressions is case-sensitive. You can use the case-insensitive functions,
REFindNoCase and REReplaceNoCase, for case-insensitive matching.
Because you often process large amounts of dynamic textual data, regular expressions are invaluable in writing
complex ColdFusion applications.

Using ColdFusion regular expression functions
ColdFusion supplies four functions that work with regular expressions:

•
•
•
•

REFind
REFindNoCase
REReplace
REReplaceNoCase

REFind and REFindNoCase use a regular expression to search a string for a pattern and return the string index where

it finds the pattern. For example, the following function returns the index of the first instance of the string " BIG ":



To find the next occurrence of the string " BIG ", you must call the REFind function a second time. For an example
of iterating over a search string to find all occurrences of the regular expression, see “Returning matched subexpressions” on page 117.
REReplace and REReplaceNoCase use regular expressions to search through a string and replace the string pattern

that matches the regular expression with another string. You can use these functions to replace the first match, or to
replace all matches.
For detailed descriptions of the ColdFusion functions that use regular expressions, see the CFML Reference.

Basic regular expression syntax
The simplest regular expression contains only a literal characters. The literal characters must match exactly the text
being searched. For example, you can use the regular expression function REFind to find the string pattern " BIG ",
just as you can with the Find function:



In this example, REFind must match the exact string pattern " BIG ".
To use the full power of regular expressions, combine literal characters with character sets and special characters, as
in the following example:



The literal characters of the regular expression consists of the space characters at the beginning and end of the regular
expression. The character set consists of that part of the regular expression in square brackets. This character set
specifies to find a single uppercase letter from A to Z, inclusive. The plus sign (+) after the square brackets is a special
character specifying to find one or more occurrences of the character set.
If you removed the + from the regular expression in the previous example, " [A-Z] " matches a literal space, followed
by any single uppercase letter, followed by a single space. This regular expression matches " B " but not " BIG ". The
REFind function returns 0 for the regular expression, meaning that it did not find a match.

ADOBE COLDFUSION 8 109
ColdFusion Developer’s Guide

You can construct very complicated regular expressions containing literal characters, character sets, and special
characters. Like any programming language, the more you work with regular expressions, the more you can accomplish with them. The examples in this section are fairly basic. For more examples, see “Regular expression examples”
on page 121.

Regular expression syntax
This section describes the basic rules for creating regular expressions.

Using character sets
The pattern within the square brackets of a regular expression defines a character set that is used to match a single
character. For example, the regular expression " [A-Za-z] " specifies to match any single uppercase or lowercase letter
enclosed by spaces. In the character set, a hyphen indicates a range of characters.
The regular expression " B[IAU]G " matches the strings “ BIG “, “ BAG “, and “ BUG “, but does not match the string
" BOG ".
If you specified the regular expression as " B[IA][GN] ", the concatenation of character sets creates a regular
expression that matches the corresponding concatenation of characters in the search string. This regular expression
matches a space, followed by “B”, followed by an “I” or “A”, followed by a “G” or “N”, followed by a trailing space. The
regular expression matches “ BIG ”, “ BAG ”, “BIN ”, and “BAN ”.
The regular expression [A-Z][a-z]* matches any word that starts with an uppercase letter and is followed by zero or
more lowercase letters. The special character * after the closing square bracket specifies to match zero or more occurrences of the character set.
Note: The * only applies to the character set that immediately precedes it, not to the entire regular expression.
A + after the closing square bracket specifies to find one or more occurrences of the character set. You interpret the
regular expression " [A-Z]+ " as matching one or more uppercase letters enclosed by spaces. Therefore, this
regular expression matches " BIG " and also matches “ LARGE ”, “ HUGE ”, “ ENORMOUS ”, and any other string of
uppercase letters surrounded by spaces.
Considerations when using special characters

Since a regular expression followed by an * can match zero instances of the regular expression, it can also match the
empty string. For example,

REReplace("Hello","[T]*","7","ALL") - #REReplace("Hello","[T]*","7","ALL")#



results in the following output:
REReplace("Hello","[T]*","7","ALL") - 7H7e7l7l7o

The regular expression [T]* can match empty strings. It first matches the empty string before “H” in “Hello”. The
“ALL” argument tells REReplace to replace all instances of an expression. The empty string before “e” is matched and
so on until the empty string before “o” is matched.
This result might be unexpected. The workarounds for these types of problems are specific to each case. In some
cases you can use [T]+, which requires at least one “T”, instead of [T]*. Alternatively, you can specify an additional
pattern after [T]*.

ADOBE COLDFUSION 8 110
ColdFusion Developer’s Guide

In the following examples the regular expression has a “W” at the end:

REReplace("Hello World","[T]*W","7","ALL") –
#REReplace("Hello World","[T]*W","7","ALL")#



This expression results in the following more predictable output:
REReplace("Hello World","[T]*W","7","ALL") - Hello 7orld

Finding repeating characters
In some cases, you might want to find a repeating pattern of characters in a search string. For example, the regular
expression "a{2,4}" specifies to match two to four occurrences of “a”. Therefore, it would match: "aa", "aaa", "aaaa", but
not "a" or "aaaaa". In the following example, the REFind function returns an index of 6:



The regular expression "[0-9]{3,}" specifies to match any integer number containing three or more digits: “123”,
“45678”, etc. However, this regular expression does not match a one-digit or two-digit number.
You use the following syntax to find repeating characters:
1

{m,n}

Where m is 0 or greater and n is greater than or equal to m. Match m through n (inclusive) occurrences.
The expression {0,1} is equivalent to the special character ?.
2

{m,}

Where m is 0 or greater. Match at least m occurrences. The syntax {,n} is not allowed.
The expression {1,} is equivalent to the special character +, and {0,} is equivalent to *.
3

{m}

Where m is 0 or greater. Match exactly m occurrences.

Case sensitivity in regular expressions
ColdFusion supplies case-sensitive and case-insensitive functions for working with regular expressions. REFind and
REReplace perform case-sensitive matching and REFindNoCase and REReplaceNoCase perform case-insensitive
matching.
You can build a regular expression that models case-insensitive behavior, even when used with a case-sensitive
function. To make a regular expression case insensitive, substitute individual characters with character sets. For
example, the regular expression [Jj][Aa][Vv][Aa], when used with the case-sensitive functions REFind or
REReplace, matches all of the following string patterns:

•

JAVA

•

java

•

Java

•

jAva

•

All other combinations of case

ADOBE COLDFUSION 8 111
ColdFusion Developer’s Guide

Using subexpressions
Parentheses group parts of regular expressions together into grouped subexpressions that you can treat as a single
unit. For example, the regular expression "ha" specifies to match a single occurrence of the string. The regular
expression "(ha)+" matches one or more instances of “ha”.
In the following example, you use the regular expression "B(ha)+" to match the letter "B" followed by one or more
occurrences of the string "ha":



You can use the special character | in a subexpression to create a logical "OR". You can use the following regular
expression to search for the word "jelly" or "jellies":



Using special characters
Regular expressions define the following list of special characters:
+ * ? . [ ^ $ ( ) { | \

In some cases, you use a special character as a literal character. For example, if you want to search for the plus sign
in a string, you have to escape the plus sign by preceding it with a backslash:
"\+"

The following table describes the special characters for regular expressions:
Special Character

Description

\

A backslash followed by any special character matches the literal character itself, that is, the backslash escapes the
special character.
For example, "\+" matches the plus sign, and "\\" matches a backslash.

.

A period matches any character, including newline.
To match any character except a newline, use [^#chr(13)##chr(10)#], which excludes the ASCII carriage return and
line feed codes. The corresponding escape codes are \r and \n.

[]

A one-character character set that matches any of the characters in that set.
For example, "[akm]" matches an “a”, “k”, or “m”. A hyphen in a character set indicates a range of characters; for
example, [a-z] matches any single lowercase letter.
If the first character of a character set is the caret (^), the regular expression matches any character except those in
the set. It does not match the empty string.
For example, [^akm] matches any character except “a”, “k”, or “m”. The caret loses its special meaning if it is not the
first character of the set.

^

If the caret is at the beginning of a regular expression, the matched string must be at the beginning of the string
being searched.
For example, the regular expression "^ColdFusion" matches the string "ColdFusion lets you use regular expressions"
but not the string "In ColdFusion, you can use regular expressions."

$

If the dollar sign is at the end of a regular expression, the matched string must be at the end of the string being
searched.
For example, the regular expression "ColdFusion$" matches the string "I like ColdFusion" but not the string "ColdFusion is fun."

ADOBE COLDFUSION 8 112
ColdFusion Developer’s Guide

Special Character

Description

?

A character set or subexpression followed by a question mark matches zero or one occurrences of the character set
or subexpression.
For example, xy?z matches either “xyz” or “xz”.

|

The OR character allows a choice between two regular expressions.
For example, jell(y|ies) matches either “jelly” or “jellies”.

+

A character set or subexpression followed by a plus sign matches one or more occurrences of the character set or
subexpression.
For example, [a-z]+ matches one or more lowercase characters.

*

A character set or subexpression followed by an asterisk matches zero or more occurrences of the character set or
subexpression.
For example, [a-z]* matches zero or more lowercase characters.

()

Parentheses group parts of a regular expression into subexpressions that you can treat as a single unit.
For example, (ha)+ matches one or more instances of “ha”.

(?x)

If at the beginning of a regular expression, it specifies to ignore whitespace in the regular expression and lets you
use ## for end-of-line comments. You can match a space by escaping it with a backslash.
For example, the following regular expression includes comments, preceded by ##, that are ignored by ColdFusion:
reFind("(?x)
one
##first option
|two
##second option
|three\ point\ five ## note escaped spaces
", "three point five")

(?m)

If at the beginning of a regular expression, it specifies the multiline mode for the special characters ^ and $.
When used with ^, the matched string can be at the start of the of entire search string or at the start of new lines,
denoted by a linefeed character or chr(10), within the search string. For $, the matched string can be at the end the
search string or at the end of new lines.
Multiline mode does not recognize a carriage return, or chr(13), as a new line character.
The following example searches for the string “two” across multiple lines:
#reFind("(?m)^two", "one#chr(10)#two")#

This example returns 4 to indicate that it matched “two” after the chr(10) linefeed. Without (?m), the regular expression would not match anything, because ^ only matches the start of the string.
The character (?m) does not affect \A or \Z, which always match the start or end of the string, respectively. For information on \A and \Z, see “Using escape sequences” on page 113.
(?i)

If at the beginning of a regular expression for REFind(), it specifies to perform a case-insensitive compare.
For example, the following line would return an index of 1:
#reFind("(?i)hi", "HI")#

If you omit the (?i), the line would return an index of zero to signify that it did not find the regular expression.

ADOBE COLDFUSION 8 113
ColdFusion Developer’s Guide

Special Character

Description

(?=...)

If at the beginning of a regular expression, it specifies to use positive lookahead when searching for the regular
expression.
Positive lookahead tests for the parenthesized subexpression like regular parenthesis, but does not include the
contents in the match - it merely tests to see if it is there in proximity to the rest of the expression.
For example, consider the expression to extract the protocol from a URL:



mid(string, result.pos[1], result.len[1])

This example results in the string "http". The lookahead parentheses ensure that the "://" is there, but does not
include it in the result. If you did not use lookahead, the result would include the extraneous "://".
Lookahead parentheses do not capture text, so backreference numbering will skip over these groups. For more information on backreferencing, see “Using backreferences” on page 115.
(?!...)

If at the beginning of a regular expression, it specifies to use negative lookahead. Negative is just like positive lookahead, as specified by (?=...), except that it tests for the absence of a match.
Lookahead parentheses do not capture text, so backreference numbering will skip over these groups. For more information on backreferencing, see “Using backreferences” on page 115.

(?:...)

If you prefix a subexpression with "?:", ColdFusion performs all operations on the subexpression except that it will not
capture the corresponding text for use with a back reference.

You must be aware of the following considerations when using special characters in character sets, such as [a-z]:

• To include a hyphen (-) in the square brackets of a character set as a literal character, you cannot escape it as you
can other special characters because ColdFusion always interprets a hyphen as a range indicator. Therefore, if you
use a literal hyphen in a character set, make it the last character in the set.
• To include a closing square bracket (]) in the character set, escape it with a backslash, as in [1-3\]A-z]. You do
not have to escape the ] character outside of the character set designator.

Using escape sequences
Escape sequences are special characters in regular expressions preceded by a backslash (\). You typically use escape
sequences to represent special characters within a regular expression. For example, the escape sequence \t represents
a tab character within the regular expression, and the \d escape sequence specifies any digit, similar to [0-9]. In
ColdFusion the escape sequences are case-sensitive.
The following table lists the escape sequences that ColdFusion supports:

ADOBE COLDFUSION 8 114
ColdFusion Developer’s Guide

Escape Sequence

Description

\b

Specifies a boundary defined by a transition from an alphanumeric character to a nonalphanumeric character, or
from a nonalphanumeric character to an alphanumeric character.
For example, the string " Big" contains boundary defined by the space (nonalphanumeric character) and the "B"
(alphanumeric character).
The following example uses the \b escape sequence in a regular expression to locate the string "Big" at the end of
the search string and not the fragment "big" inside the word "ambiguous".
reFindNoCase("\bBig\b", "Don’t be ambiguous about Big.")


When used inside of a character set (e.g. [\b]), it specifies a backspace
\B

Specifies a boundary defined by no transition of character type. For example, two alphanumeric character in a row
or two nonalphanumeric character in a row; opposite of \b.

\A

Specifies a beginning of string anchor, much like the ^ special character.
However, unlike ^, you cannot combine \A with (?m) to specify the start of newlines in the search string.

\Z

Specifies an end of string anchor, much like the $ special character.
However, unlike $, you cannot combine \Z with (?m) to specify the end of newlines in the search string.

\n

Newline character

\r

Carriage return

\t

Tab

\f

Form feed

\d

Any digit, similar to [0-9]

\D

Any nondigit character, similar to [^0-9]

\w

Any alphanumeric character, similar to [[:alnum:]]

\W

Any nonalphanumeric character, similar to [^[:alnum:]]

\s

Any whitespace character including tab, space, newline, carriage return, and form feed. Similar to [ \t\n\r\f].

\S

Any nonwhitespace character, similar to [^ \t\n\r\f]

\xdd

A hexadecimal representation of character, where d is a hexadecimal digit

\ddd

An octal representation of a character, where d is an octal digit, in the form \000 to \377

Using character classes
In character sets within regular expressions, you can include a character class. You enclose the character class inside
square brackets, as the following example shows:
REReplace ("Adobe Web Site","[[:space:]]","*","ALL")

This code replaces all the spaces with *, producing this string:
Adobe*Web*Site

You can combine character classes with other expressions within a character set. For example, the regular expression
[[:space:]123] searches for a space, 1, 2, or 3. The following example also uses a character class in a regular expression:


ADOBE COLDFUSION 8 115
ColdFusion Developer’s Guide



The following table shows the character classes that ColdFusion supports. Regular expressions using these classes
match any Unicode character in the class, not just ASCII or ISO-8859 characters.
Character class

Matches

:alpha:

Any alphabetic character.

:upper:

Any uppercase alphabetic character.

:lower:

Any lowercase alphabetic character

:digit:

Any digit. Same as \d.

:alnum:

Any alphanumeric character. Same as \w.

:xdigit:

Any hexadecimal digit. Same as [0-9A-Fa-f].

:blank:

Space or a tab.

:space:

Any whitespace character. Same as \s.

:print:

Any alphanumeric, punctuation, or space character.

:punct:

Any punctuation character

:graph:

Any alphanumeric or punctuation character.

:cntrl:

Any character not part of the character classes [:upper:], [:lower:], [:alpha:], [:digit:], [:punct:], [:graph:], [:print:], or
[:xdigit:].

:word:

Any alphanumeric character, plus the underscore (_)

:ascii:

The ASCII characters, in the Hexadecimal range 0 - 7F

Using backreferences
You use parenthesis to group components of a regular expression into subexpressions. For example, the regular
expression “(ha)+” matches one or more occurrences of the string “ha”.
ColdFusion performs an additional operation when using subexpressions; it automatically saves the characters in the
search string matched by a subexpression for later use within the regular expression. Referencing the saved subexpression text is called backreferencing.
You can use backreferencing when searching for repeated words in a string, such as “the the” or “is is”. The following
example uses backreferencing to find all repeated words in the search string and replace them with an asterisk:
REReplace("There is is coffee in the the kitchen",
"[ ]+([A-Za-z]+)[ ]+\1"," * ","ALL")

Using this regular expression, ColdFusion detects the two occurrences of “is” as well as the two occurrences of “the”,
replaces them with an asterisk enclosed in spaces, and returns the following string:
There * coffee in * kitchen

You interpret the regular expression [ ]+([A-Za-z]+)[ ]+\1 as follows:
Use the subexpression ([A-Za-z]+) to search for character strings consisting of one or more letters, enclosed by one
or more spaces, [ ]+, followed by the same character string that matched the first subexpression, \1.

ADOBE COLDFUSION 8 116
ColdFusion Developer’s Guide

You reference the matched characters of a subexpression using a slash followed by a digit n (\n) where the first subexpression in a regular expression is referenced as \1, the second as \2, etc. The next section includes an example using
multiple backreferences.

Using backreferences in replacement strings
You can use backreferences in the replacement string of both the REReplace and REReplaceNoCase functions. For
example, to replace the first repeated word in a text string with a single word, use the following syntax:
REReplace("There is is a cat in in the kitchen",
"([A-Za-z ]+)\1","\1")

This results in the sentence:
"There is a cat in in the kitchen"

You can use the optional fourth parameter to REReplace, scope, to replace all repeated words, as in the following
code:
REReplace("There is is a cat in in the kitchen",
"([A-Za-z ]+)\1","\1","ALL")

This results in the following string:
“There is a cat in the kitchen”

The next example uses two backreferences to reverse the order of the words "apples" and "pears" in a sentence:



In this example, you reference the subexpression (apples) as \1 and the subexpression (pears) as \2. The REReplace
function returns the string:
"pears and apples, pears and apples, pears and apples"

Note: To use backreferences in either the search string or the replace string, you must use parentheses within the regular
expression to create the corresponding subexpression. Otherwise, ColdFusion throws an exception.
Using backreferences to perform case conversions in replacement strings

The REReplace and REReplaceNoCase functions support special characters in replacement strings to convert
replacement characters to uppercase or lowercase. The following table describes these special characters:
Special character

Description

\u

Converts the next character to uppercase.

\l

Converts the next character to lowercase.

\U

Converts all characters to uppercase until encountering \E.

\L

Converts all characters to lowercase until encountering \E.

\E

End \U or \L.

To include a literal \u, or other code, in a replacement string, escape it with another backslash; for example \\u .
For example, the following statement replaces the uppercase string "HELLO" with a lowercase "hello". This example
uses backreferences to perform the replacement. For more information on using backreferences, see “Using backreferences in replacement strings” on page 116.

ADOBE COLDFUSION 8 117
ColdFusion Developer’s Guide

reReplace("HELLO", "([[:upper:]]*)", "Don't shout\scream \L\1")

The result of this example is the string "Don't shout\scream hello".
Escaping special characters in replacement strings

You use the backslash character, \, to escape backreference and case-conversion characters in replacement strings.
For example, to include a literal "\u" in a replacement string, escape it, as in "\\u".

Omitting subexpressions from backreferences
By default, a set of parentheses will both group the subexpression and capture its matched text for later referral by
backreferences. However, if you insert "?:" as the first characters of the subexpression, ColdFusion performs all
operations on the subexpression except that it will not capture the corresponding text for use with a back reference.
This is useful when alternating over subexpressions containing differing numbers of groups would complicate
backreference numbering. For example, consider an expression to insert a "Mr." in between Bonjour|Hi|Hello and
Bond, using a nested group for alternating between Hi & Hello:



#reReplace(string, regex, replaceString)#

This example returns "Hello Mr. Bond". If you did not prohibit the capturing of the Hi/Hello group, the \2 backreference would end up referring to that group instead of " Bond", and the result would be "Hello Mr.ello".

Returning matched subexpressions
The REFind and REFindNoCase functions return the location in the search string of the first match of the regular
expression. Even though the search string in the next example contains two matches of the regular expression, the
function only returns the index of the first:



To find all instances of the regular expression, you must call the REFind and REFindNoCase functions multiple
times.
Both the REFind and REFindNoCase functions take an optional third parameter that specifies the starting index in
the search string for the search. By default, the starting location is index 1, the beginning of the string.
To find the second instance of the regular expression in this example, you call REFind with a starting index of 8:



In this case, the function returns an index of 9, the starting index of the second string " BIG ".
To find the second occurrence of the string, you must know that the first string occurred at index 5 and that the
string’s length was 5. However, REFind only returns starting index of the string, not its length. So, you either must
know the length of the matched string to call REFind the second time, or you must use subexpressions in the regular
expression.

ADOBE COLDFUSION 8 118
ColdFusion Developer’s Guide

The REFind and REFindNoCase functions let you get information about matched subexpressions. If you set these
functions’ fourth parameter, ReturnSubExpression, to True, the functions return a CFML structure with two
arrays, pos and len, containing the positions and lengths of text strings that match the subexpressions of a regular
expression, as the following example shows:






The following image shows the output of the cfdump tag:

Element one of the pos array contains the starting index in the search string of the string that matched the regular
expression. Element one of the len array contains length of the matched string. For this example, the index of the
first " BIG " string is 5 and its length is also 5. If there are no occurrences of the regular expression, the pos and len
arrays each contain one element with a value of 0.
You can use the returned information with other string functions, such as mid. The following example returns that
part of the search string matching the regular expression:



#mid(myString, sLenPos.pos[1], sLenPos.len[1])#


Each additional element in the pos array contains the position of the first match of each subexpression in the search
string. Each additional element in len contains the length of the subexpression’s match.
In the previous example, the regular expression " BIG " contained no subexpressions. Therefore, each array in the
structure returned by REFind contains a single element.
After executing the previous example, you can call REFind a second time to find the second occurrence of the regular
expression. This time, you use the information returned by the first call to make the second:








The following image shows the output of the cfdump tag:

ADOBE COLDFUSION 8 119
ColdFusion Developer’s Guide

If you include subexpressions in your regular expression, each element of pos and len after element one contains
the position and length of the first occurrence of each subexpression in the search string.
In the following example, the expression [A-Za-z]+ is a subexpression of a regular expression. The first match for the
expression ([A-Za-z]+)[ ]+, is “is is”.






The following image shows the output of the cfdump tag:

The entries sLenPos.pos[1] and sLenPos.len[1] contain information about the match of the entire regular expression.
The array elements sLenPos.pos[2] and sLenPos.len[2] contain information about the first subexpression (“is”).
Because REFind returns information on the first regular expression match only, the sLenPos structure does not
contain information about the second match to the regular expression, "in in".
The regular expression in the following example uses two subexpressions. Therefore, each array in the output
structure contains the position and length of the first match of the entire regular expression, the first match of the
first subexpression, and the first match of the second subexpression.









The following image shows the output of the cfdump tag:

ADOBE COLDFUSION 8 120
ColdFusion Developer’s Guide

For a full discussion of subexpression usage, see the sections on REFind and REFindNoCase in the ColdFusion
functions chapter in the CFML Reference.

Specifying minimal matching
The regular expression quantifiers ?, *, +, {min,} and {min,max} specify a minimum and/or maximum number of
instances of a given expression to match. By default, ColdFusion locates the greatest number characters in the search
string that match the regular expression. This behavior is called maximal matching.
For example, you use the regular expression "(.*)" to search the string "one two". The
regular expression "(.*)", matches both of the following:

•

one

•

one two

By default, ColdFusion always tries to match the regular expression to the largest string in the search string. The
following code shows the results of this example:
(.*)", "one two", 1, "True")>





The following image shows the output of the cfdump tag:

Thus, the starting position of the string is 1 and its length is 21, which corresponds to the largest of the two possible
matches.

ADOBE COLDFUSION 8 121
ColdFusion Developer’s Guide

However, sometimes you might want to override this default behavior to find the shortest string that matches the
regular expression. ColdFusion includes minimal-matching quantifiers that let you specify to match on the smallest
string. The following table describes these expressions:
Expression

Description

*?

minimal-matching version of *

+?

minimal-matching version of +

??

minimal-matching version of ?

{min,}?

minimal-matching version of {min,}

{min,max}?

minimal-matching version of {min,max}

{n}?

(no different from {n}, supported for notational consistency)

If you modify the previous example to use the minimal-matching syntax, the code is as follows:
(.*?)", "one two", 1, "True")>





The following image shows the output of the cfdump tag:

Thus, the length of the string found by the regular expression is 10, corresponding to the string "one".

Regular expression examples
The following examples show some regular expressions and describe what they match:
Expression

Description

[\?&]value=

A URL parameter value in a URL.

[A-Z]:(\\[A-Z0-9_]+)+

An uppercase DOS/Windows path in which (a) is not the root of a
drive, and (b) has only letters, numbers, and underscores in its text.

^[A-Za-z][A-Za-z0-9_]*

A ColdFusion variable with no qualifier.

([A-Za-z][A-Za-z0-9_]*)(\.[A-Za-z][A-Za-z0-9_]*)?

A ColdFusion variable with no more than one qualifier; for example,
Form.VarName, but not Form.Image.VarName.

ADOBE COLDFUSION 8 122
ColdFusion Developer’s Guide

Expression

Description

(\+|-)?[1-9][0-9]*

An integer that does not begin with a zero and has an optional sign.

(\+|-)?[0-9]+(\.[0-9]*)?

A real number.

(\+|-)?[1-9]\.[0-9]*E(\+|-)?[0-9]+

A real number in engineering notation.

a{2,4}

Two to four occurrences of “a”: aa, aaa, aaaa.

(ba){3,}

At least three “ba” pairs: bababa, babababa, and so on.

Regular expressions in CFML
The following examples of CFML show some common uses of regular expression functions:
Expression

Returns

REReplace (CGI.Query_String, "CFID=[0-9]+[&]*", "")

The query string with parameter CFID
and its numeric value stripped out.

REReplace(“I Love Jellies”, ”[[:lower:]]”,”x”,”ALL”

I Lxxx Jxxxxxx

REReplaceNoCase(“cabaret”,”[A-Z]”, ”G”,”ALL”)

GGGGGGG

REReplace (Report,"\$[0-9,]*\.[0-9]*","$***.**")", "")

The string value of the variable Report
with all positive numbers in the dollar
format changed to "$***.**".

REFind ("[Uu]\.?[Ss]\.?[Aa}\.?", Report )

The position in the variable Report of
the first occurrence of the abbreviation
USA. The letters can be in either case
and the abbreviation can have a
period after any letter.

REFindNoCase("a+c","ABCAACCDD")

4

REReplace("There is is coffee in the the kitchen","([A-Za-z]+)[
]+\1","*","ALL")

There * coffee in * kitchen

REReplace(report, "<[^>]*>", "", "All")

Removes all HTML tags from a string
value of the report variable.

Types of regular expression technologies
Many types of regular expression technologies are available to programmers. JavaScript, Perl, and POSIX are all
examples of different regular expression technologies. Each technology has its own syntax specifications and is not
necessarily compatible with other technologies.
ColdFusion supports regular expressions that are Perl compliant with a few exceptions:

•

A period, ., always matches newlines.

• In replacement strings, use \n instead of $n for backreference variables. ColdFusion escapes all $ in the
replacement string.
• You do not have to escape backslashes in replacement strings. ColdFusion escapes them, with the exception of
case conversion sequences or escaped versions (e.g. \u or \\u).
•

Embedded modifiers ( (?i), etc. ) always affect the entire expression, even if they are inside a group.

ADOBE COLDFUSION 8 123
ColdFusion Developer’s Guide

•

\Q and the combinations \u\L and \l\U are not supported in replacement strings.

The following Perl statements are not supported:

•

Lookbehind (?<=) (

Note: You cannot break CFML code blocks across pages. For example, if you open a cfoutput block in a ColdFusion
page, you must close the block on the same page; you cannot include the closing portion of the block in an included page.
ColdFusion searches for included files as follows:

•

The template attribute specifies a path relative to the directory of the calling page.

• If the template value is prefixed with a forward slash (/), ColdFusion searches for the included file in directories
that you specify on the Mappings page of the ColdFusion Administrator.
Important: A page must not include itself. Doing so causes an infinite processing loop, and you must stop the ColdFusion
server to resolve the problem.
Include code in a calling page
1 Create a ColdFusion page named header.cfm that displays your company’s logo. Your page can consist of just the

following lines, or it can include many lines to define an entire header:

ADOBE COLDFUSION 8 128
ColdFusion Developer’s Guide





(For this example to work, you must also put your company’s logo as a GIF file in the same directory as the
header.cfm file.)
2

Create a ColdFusion page with the following content:









3

Save the file as includeheader.cfm and view it in a browser.

The header should appear along with the logo.

Recommended uses
Consider using the cfinclude tag in the following cases:

•

For page headers and footers

•

To divide a large page into multiple logical chunks that are easier to understand and manage

• For large “snippets” of code that are used in many places but do not require parameters or fit into the model of
a function or tag

About user-defined functions
User-defined functions (UDFs) let you create application elements in a format in which you pass in arguments and
get a return a value. You can define UDFs using CFScript or the cffunction tag. The two techniques have several
differences, of which the following are the most important:

•

If you use the cffunction tag, your function can include CFML tags.

•

If you write your function using CFScript, you cannot include CFML tags.

You can use UDFs in your application pages just as you use standard ColdFusion functions. When you create a
function for an algorithm or procedure that you use frequently, you can then use the function wherever you need
the procedure, just as you would use a ColdFusion built-in function. For example, the following line calls the
function MyFunct and passes it two arguments:


You can group related functions in a ColdFusion component. For more information, see “Using ColdFusion components” on page 129.
As with custom tags, you can easily distribute UDFs to others. For example, the Common Function Library Project
at www.cflib.org is an open-source collection of CFML user-defined functions.

Recommended uses
Typical uses of UDFs include, but are not limited to, the following:

ADOBE COLDFUSION 8 129
ColdFusion Developer’s Guide

•

Data manipulation routines, such as a function to reverse an array

•

String and date and time routines, such as a function to determine whether a string is a valid IP address

• Mathematical calculation routines, including standard trigonometric and statistical operations or calculating
loan amortization
• Routines that call functions externally, for example using COM or CORBA, such as routines to determine the
space available on a Windows file system drive
Consider using UDFs in the following circumstances:

• You must pass in a number of arguments, process the results, and return a value. UDFs can return complex
values, including structures that contain multiple simple values.
•

You want to provide logical units, such as data manipulation functions.

•

Your code must be recursive.

•

You distribute your code to others.

If you can create either a UDF or a custom CFML tag for a particular purpose, first consider creating a UDF because
invoking it requires less system overhead than using a custom tag.

For more information
For more information on user-defined functions, see “Writing and Calling User-Defined Functions” on page 134.

Using ColdFusion components
ColdFusion components (CFCs) are ColdFusion templates that contain related functions and arguments that each
function accepts. The CFC contains the CFML tags necessary to define its functions and arguments and return a
value. ColdFusion components are saved with a .cfc extension.
CFCs combine the power of objects with the simplicity of CFML. By packaging related functionality into a single
unit, they provide an object or class shell from which functions can be called.
ColdFusion components can make their data private, so that it is available to all functions (also called methods) in
the component, but not to any application that uses the component.
ColdFusion components have the following features:

•

They are designed to provide related services in a single unit.

•

They can provide web services and make them available over the Internet.

•

They can provide ColdFusion services that Flash clients can call directly.

• They have several features that are familiar to object-oriented programmers, including data hiding, inheritance,
packages, and introspection.

Recommended uses
Consider using ColdFusion components when doing the following:

•

Creating web services. (To create web services in ColdFusion, you must use components.)

•

Creating services that are callable by Flash clients.

ADOBE COLDFUSION 8 130
ColdFusion Developer’s Guide

•

Creating libraries of related functions, particularly if they must share data.

•

Using integrated application security mechanisms based on roles and the requestor location.

• Developing code in an object-oriented manner, in which you use methods on objects and can create objects that
extend the features of existing objects.

For more information
For more information on using ColdFusion components, see “Building and Using ColdFusion Components” on
page 158

Using custom CFML tags
Custom tags written in CFML behave like ColdFusion tags. They can do all of the following:

•

Take arguments.

•

Have tag bodies with beginning and ending tags.

•

Do specific processing when ColdFusion encounters the beginning tag.

•

Do processing that is different from the beginning tag processing when ColdFusion encounters the ending tag.

• Have any valid ColdFusion page content in their bodies, including both ColdFusion built-in tags and custom
tags (referred to as nested tags), or even JSP tags or JavaScript.
•

Be called recursively; that is, a custom tag can, if designed properly, call itself in the tag body.

• Return values to the calling page in a common scope or the calling page’s Variables scope, but custom tags do not
return values directly, the way functions do.
Although a custom tag and a ColdFusion page that you include using the cfinclude tag are both ColdFusion pages,
they differ in how they are processed. When a page calls a custom tag, it hands processing off to the custom tag page
and waits until the custom tag page completes. When the custom tag finishes, it returns processing (and possibly
data) to the calling page; the calling page can then complete its processing. The following image shows how this
works. The arrows indicate the flow of ColdFusion processing the pages.

Calling custom CFML tags
Unlike built-in tags, you can invoke custom CFML tags in the following three ways:

ADOBE COLDFUSION 8 131
ColdFusion Developer’s Guide

•

Call a tag directly.

•

Call a tag using the cfmodule tag.

•

Use the cfimport tag to import a custom tag library directory.

To call a CFML custom tag directly, precede the filename with cf_, omit the .cfm extension, and put the name in
angle brackets (<>). For example, use the following line to call the custom tag defined by the file mytag.cfm:


If your tag takes a body, end it with the same tag name preceded with a forward slash (/), as follows:


For information on using the cfmodule and cfimport tags to call custom CFML tags, see “Creating and Using
Custom CFML Tags” on page 190.

Recommended uses
ColdFusion custom tags let you abstract complex code and programming logic into simple units. These tags let you
maintain a CFML-like design scheme for your code. You can easily distribute your custom tags and share tags with
others. For example, the ColdFusion Developer’s Exchange includes a library of custom tags that perform a wide
variety of often-complex jobs; see http://www.adobe.com/cfusion/exchange/index.cfm?view=sn130.
Consider using CFML custom tags in the following circumstances:

• You need a tag-like structure, which has a body and an end tag, with the body contents changing from invocation
to invocation.
•

You want to associate specific processing with the beginning tag, the ending tag, or both tags.

•

To use a logical structure in which the tag body uses “child” tags or subtags. This structure is similar to the

cfform tag, which uses subtags for the individual form fields.

•

You do not need a function format in which the calling code uses a direct return value.

•

Your code must be recursive.

•

Your functionality is complex.

•

To distribute your code in a convenient form to others.

If you can create either a UDF or a custom CFML tag for a purpose, first consider creating a UDF because invoking
it requires less system overhead than using a custom tag.

For more information
For more information on custom CFML tags, see “Creating and Using Custom CFML Tags” on page 190

Using CFX tags
ColdFusion Extension (CFX) tags are custom tags that you write in Java or C++. Generally, you create a CFX tag to
do something that is not possible in CFML. CFX tags also let you use existing Java or C++ code in your ColdFusion
application. Unlike CFML custom tags, CFX tags cannot have bodies or ending tags.
CFX tags can return information to the calling page in a page variable or by writing text to the calling page.
CFX tags can do the following:

ADOBE COLDFUSION 8 132
ColdFusion Developer’s Guide

•

Have any number of custom attributes.

•

Create and manipulate ColdFusion queries.

•

Dynamically generate HTML to be returned to the client.

•

Set variables within the ColdFusion page from which they are called.

•

Throw exceptions that result in standard ColdFusion error messages.

Calling CFX tags
To use a CFX tag, precede the class name with cfx_ and put the name in angle brackets. For example, use the
following line to call the CFX tag defined by the MyCFXClass class and pass it one attribute.


Recommended uses
CFX tags provide one way of using C++ or Java code. However, you can also create Java classes and COM objects
and access them using the cfobject tag. CFX tags, however, provide some built-in features that the cfobject tag
does not have:

• CFX tags are easier to call in CFML code. You use CFX tags directly in CFML code as you would any other tag,
and you can pass arguments using a standard tag format.
• ColdFusion provides predefined classes for use in your Java or C++ code that facilitate CFX tag development.
These classes include support for request handling, error reporting, and query management.
You should consider using CFX tags in the following circumstances:

• You already have existing application functionality written in C++ or Java that you want to incorporate into your
ColdFusion application.
•

You cannot build the functionality you need using ColdFusion elements.

• You want to provide the new functionality in a tag format, as opposed to using the cfobject tag to import native
Java or COM objects.
•

You want use the Java and C++ classes provided by ColdFusion for developing your CFX code.

For more information
For more information on CFX tags, see “Building Custom CFXAPI Tags” on page 205.

Selecting among ColdFusion code reuse methods
The following table lists common reasons to employ code reuse methods and indicates the techniques to consider
for each purpose. The letter P indicates that the method is preferred. (There can be more than one preferred
method.) The letter A means that the method provides an alternative that might be useful in some circumstances.
This table does not include CFX tags. You use CFX tags only when you should code your functionality in C++ or
Java. For more information about using CFX tags, see “Using CFX tags” on page 131.

ADOBE COLDFUSION 8 133
ColdFusion Developer’s Guide

Purpose

cfinclude tag

Custom tag

UDF

Provide code, including CFML, HTML,
and static text, that must be used in
multiple pages.

P

Deploy headers and footers.

P

Include one page in another page.

P

Divide pages into smaller units.

P

Use variables from a calling page.

A

P

P

Implement code that uses recursion.

P

P

P

Distribute your code to others.

P

P

P

Operate on a body of HTML or CFML
text.

P

Use subtags.

P

Provide a computation, data manipulation, or other procedure.

A

P

Provide a single functional element that
takes any number of input values and
returns a (possibly complex) result.

A

P

Use variables, whose variable names
might change from use to use.

A

P

P

Provide accessibility from Flash clients.

A

A

P

A

P

Use built-in user security features.

Component

Encapsulate multiple related functions
and properties.

P

Create web services.

P

Implement object-oriented coding
methodologies.

P

134

Chapter 9: Writing and Calling UserDefined Functions
Creating custom functions for algorithms or procedures that you call frequently lets you organize and reuse the
functions in your ColdFusion application pages.
Contents

About user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Creating user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Calling user-defined functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Working with arguments and variables in functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Handling errors in UDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
A user-defined function example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Using UDFs effectively . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

About user-defined functions
You can create your own custom functions, known as user-defined functions, or UDFs. You then use them in your
application pages the same way you use standard ColdFusion functions. You can also organize functions you create
by grouping related functions into ColdFusion components. For more information, see “Building and Using
ColdFusion Components” on page 158.
When you create a function for an algorithm or procedure that you use frequently, you can then use the function
wherever you require the procedure. If you must change the procedure, you change only one piece of code. You can
use your function anywhere that you can use a ColdFusion expression: in tag attributes, between number (#) signs
in output, and in CFScript code. Typical uses of UDFs include, but are not limited to the following:

•

Data manipulation routines, such as a function to reverse an array

•

String and date/time routines, such as a function to determine whether a string is a valid IP address

• Mathematical calculation routines, including standard trigonometric and statistical operations or calculating
loan amortization
• Routines that call functions externally, for example using COM or CORBA, including routines to determine the
space available on a Windows file system drive
For information about selecting among user-defined functions, ColdFusion components, and custom tags, see
“Creating ColdFusion Elements” on page 126.
Note: The Common Function Library Project at www.cflib.org is an open source collection of CFML user-defined
functions.

ADOBE COLDFUSION 8 135
ColdFusion Developer’s Guide

Creating user-defined functions
Before you create a UDF, you must determine where you want to define it, and whether you want to use CFML or
CFScript to create it.

Determining where to create a user-defined function
You can define a function in the following places:

• In a ColdFusion component. If you organize your functions in ColdFusion components, you use the functions
as described in “Using ColdFusion components” on page 170.
• On the page where it is called. You can even define it below the place on the page where it is called, but this poor
coding practice can result in confusing code.
• On a page that you include using a cfinclude tag. The cfinclude tag must be executed before the function
gets called. For example, you can define all your application’s functions on a single page and place a cfinclude tag
at the top of pages that use the functions.
• On any page that puts the function name in a scope common with the page on which you call the function. For
more information on UDF scoping, see “Specifying the scope of a function” on page 153.
• On the Application.cfc or Application.cfm page. For more information, see “Designing and Optimizing a
ColdFusion Application” on page 218.
For recommendations on selecting where you define functions, see the sections “Using Application.cfm and
function include files” on page 153 and “Specifying the scope of a function” on page 153.

About creating functions using CFScript
You use the function statement to define the function in CFScript. CFScript function definitions have the following
features and limitations:

•

The function definition syntax is familiar to anyone who uses JavaScript or most programming languages.

•

CFScript is efficient for writing business logic, such as expressions and conditional operations.

•

CFScript function definitions cannot include CFML tags.

The following is a CFScript definition for a function that returns a power of 2:

function twoPower(exponent) {
return 2^exponent;
}


For more information on how to use CFScript to define a function, see “Defining functions in CFScript” on page 135.

Defining functions in CFScript
You define functions using CFScript in a manner similar to defining JavaScript functions. You can define multiple
functions in a single CFScript block.
Note: For more information on using CFScript, see “Extending ColdFusion Pages with CFML Scripting” on page 92.
CFScript function definition syntax

A CFScript function definition has the following syntax:

ADOBE COLDFUSION 8 136
ColdFusion Developer’s Guide

function functionName( [argName1[, argName2...]] )
{
CFScript Statements
}

The following table describes the function variables:
Function variable

Description

functionName

The name of the function. You cannot use the name of a standard ColdFusion function or any name that starts
with “cf”. You cannot use the same name for two different function definitions. Function names cannot include
periods.

argName1...

Names of the arguments required by the function. The number of arguments passed into the function must
equal or exceed the number of arguments in the parentheses at the start of the function definition. If the
calling page omits any of the required arguments, ColdFusion generates a mismatched argument count error.

The body of the function definition must be in curly braces, even if it is a empty.
The following two statements are allowed only in function definitions:
Statement

Description

var variableName = expression;

Creates and initializes a variable that is local to the function (function variable). This variable has
meaning only inside the function and is not saved between calls to the function. It has precedence
in the function body over any variables with the same name that exist in any other scopes. You
never prefix a function variable with a scope identifier, and the name cannot include periods. The
initial value of the variable is the result of evaluating the expression. The expression can be any
valid ColdFusion expression, including a constant or even another UDF.
All var statements must be at the top of the function declaration, before any other statements.
You must initialize all variables when you declare them. You cannot use the same name for a function variable and an argument.
Each var statement can initialize only one variable.
You should use the var statement to initialize all function-only variables, including loop counters
and temporary variables.

return expression;

Evaluates expression (which can be a variable), returns its value to the page that called the function, and exits the function. You can return any ColdFusion variable type.

A simple CFScript example

The following example function adds the two arguments and returns the result:

function Sum(a,b) {
var sum = a + b;
return sum;
}


In this example, a single line declares the function variable and uses an expression to set it to the value to be returned.
This function can be simplified so that it does not use a function variable, as follows:
function MySum(a,b) {Return a + b;}

You must always use curly braces around the function definition body, even if it is a single statement.

ADOBE COLDFUSION 8 137
ColdFusion Developer’s Guide

About creating functions by using tags
You use the cffunction tag to define a UDF in CFML. The cffunction tag syntax has the following features and
limitations:

• Developers who have a background in CFML or HTML, but no scripting or programming experience will be
more familiar with the syntax.
• You can include any ColdFusion tag in your function definition. Therefore, you can create a function, for
example, that accesses a database.
•

You can embed CFScript code inside the function definition.

• The cffunction tag provides attributes that enable you to easily limit the execution of the tag to authorized
users or specify how the function can be accessed.
The following code uses the cffunction tag to define the exponentiation function:





For more information on how to use the cffunction tag to define a function, see “Defining functions by using the
cffunction tag” on page 137.

Defining functions by using the cffunction tag
The cffunction and cfargument tags let you define functions in CFML without using CFScript.
For information on ColdFusion components, see “Building and Using ColdFusion Components” on page 158. For
more information on the cffunction tag, see the CFML Reference.
The cffunction tag function definition format

A cffunction tag function definition has the following format:

]




where square brackets ([]) indicate optional arguments. You can have any number of cfargument tags.
The cffunction tag specifies the name you use when you call the function. You can optionally specify other
function characteristics, as the following table describes:

ADOBE COLDFUSION 8 138
ColdFusion Developer’s Guide

Attribute

Description

name

The function name.

returnType

(Optional) The type of data that the function returns. The valid standard type names are: any, array, binary, boolean,
date, guid, numeric, query, string, struct, uuid, variableName, xml, and void. If you specify any other name,
ColdFusion requires the argument to be a ColdFusion component with that name.
ColdFusion throws an error if you specify this attribute and the function tries to return data with a type that
ColdFusion cannot automatically convert to the one you specified. For example, if the function returns the result of
a numeric calculation, a returnType attribute of string or numeric is valid, but array is not.

roles

(Optional) A comma-delimited list of security roles that can invoke this method. If you omit this attribute, ColdFusion
does not restrict user access to the function.
If you use this attribute, the function executes only if the current user is logged in using the cfloginuser tag and
is a member of one or more of the roles specified in the attribute. Otherwise, ColdFusion throws an unauthorized
access exception. For more information on user security, see “Securing Applications” on page 311.

output

(Optional) Determines how ColdFusion processes displayable output in the function body.
If you do not specify this option, ColdFusion treats the body of the function as normal CFML. As a result, text and the
result of any cfoutput tags in the function definition body are displayed each time the function executes.
If you specify true or yes, the body of the function is processed as if it were in a cfoutput tag. ColdFusion displays
variable values and expression results if you surround the variables and expressions with number signs (#).
If you specify false or no., the function is processed as if it were in a cfsilent tag. The function does not display
any output. The code that calls the function is responsible for displaying any function results.

You must use cfargument tags for required function arguments. All cfargument tags must precede any other
CFML code in a cffunction tag body. Therefore, put the cfargument tags immediately following the cffunction
opening tag. The cfargument tag takes the following attributes:
Attribute

Description

name

The argument name.

type

(Optional) The data type of the argument. The type of data that is passed to the function. The valid standard type
names are any, array, binary, boolean, date, guid, numeric, query, string, struct, uuid, and variableName. If you specify
any other name, ColdFusion requires the argument to be a ColdFusion component with that name.
ColdFusion throws an error if you specify this attribute and the function is called with data of a type that ColdFusion
cannot automatically convert to the one you specified. For example, if the argument type attribute is numeric, you
cannot call the function with an array.

required

(Optional) A Boolean value that specifies whether the argument is required. If set to true and the argument is
omitted from the function call, ColdFusion throws an error. The default value is false. The required attribute is not
required if you specify a default attribute.
Because you do not identify arguments when you call a function, all cfargument tags that specify required arguments must precede any cfargument tags that specify optional arguments in the cffunction definition.

default

(Optional) The default value for an optional argument if no argument value is passed. If you specify this attribute,
ColdFusion ignores the required attribute.

Note: The cfargument tag is not required for optional arguments. This feature is useful if a function can take an
indeterminate number of arguments. If you do not use the cfargument tag for an optional argument, reference it by
using its position in the Arguments scope array. For more information see “Using the Arguments scope as an array” on
page 143.

ADOBE COLDFUSION 8 139
ColdFusion Developer’s Guide

Using a CFML tag in a user-defined function

The most important advantage of using the cffunction tag over defining a function in CFScript is that you can
include CFML tags in the function. Thus, UDFs can encapsulate activities, such as database lookups, that require
ColdFusion tags. Also, you can use the cfoutput tag to display output on the calling page with minimal coding.
Note: To improve performance, avoid using the cfparam tag in ColdFusion functions. Instead, use the cfset tag.
The following example function looks up and returns an employee’s department ID. It takes one argument, the
employee ID, and looks up the corresponding department ID in the cfdocexamples Employee table:




SELECT Dept_ID
FROM Employee
WHERE Emp_ID = #empID#




Rules for function definitions
The following rules apply to functions that you define using CFScript or the cffunction tag:

• The function name must be unique. It must be different from any existing variable, UDF, or built-in function
name, except you can use the ColdFusion advanced security function names.
• The function name must not start with the letters cf in any form. (For example, CF_MyFunction, cfmyFunction,
and cfxMyFunction are not valid UDF names.)
• You cannot redefine or overload a function. If a function definition is active, ColdFusion generates an error if
you define a second function with the same name.
•

You cannot nest function definitions; that is, you cannot define one function inside another function definition.

•

The function can be recursive, that is, the function definition body can call the function.

•

The function does not have to return a value.

You can use tags or CFScript to create a UDF. Each technique has advantages and disadvantages.

Calling user-defined functions
You can call a function anywhere that you can use an expression, including in number signs (#) in a cfoutput tag,
in a CFScript, or in a tag attribute value. One function can call another function, and you can use a function as an
argument to another function.
You can call a UDF in two ways:

•

With unnamed, positional arguments, as you would call a built-in function

•

With named arguments, as you would use attributes in a tag

You can use either technique for any function. However, if you use named arguments, you must use the same
argument names to call the function as you use to define the function. You cannot call a function with a mixture of
named and unnamed arguments.

ADOBE COLDFUSION 8 140
ColdFusion Developer’s Guide

One example of a user-defined function is a TotalInterest function that calculates loan payments based on a principal
amount, annual percentage, and loan duration in months. (For this function’s definition, see “A user-defined
function example” on page 152). You might call the function without argument names on a form’s action page, as
follows:

Interest: #TotalInterest(Form.Principal, Form.Percent, Form.Months)#


You might call the function with argument names, as follows:

Interest: #TotalInterest(principal=Form.Principal, annualPercent=Form.Percent,
months=Form.Months)#


Working with arguments and variables in functions
Good argument naming practice
An argument’s name should represent its use. For example, the following code is unlikely to result in confusion:

function SumN(Addend1,Addend2)
{ return Addend1 + Addend2; }



#SumN(x,y)#

The following, similar code is more likely to result in programming errors:

function SumN(x,y)
{ return x + y; }



#SumN(x,y)#

Passing arguments
ColdFusion passes the following data types to the function by value:

•

Integers

•

Real numbers

•

Strings (including lists)

•

Date-time objects

•

Arrays

As a result, any changes that you make in the function to these arguments do not affect the variable that was used to
call the function, even if the calling code is on the same ColdFusion page as the function definition.
ColdFusion passes queries, structures, and external objects such as COM objects into the function by reference. As
a result, any changes to these arguments in the function also change the value of the variable in the calling code.

ADOBE COLDFUSION 8 141
ColdFusion Developer’s Guide

For an example of the effects of passing arguments, see “Passing complex data” on page 141.

Passing complex data
Structures, queries, and complex objects such as COM objects are passed to UDFs by reference, so the function uses
the same copy of the data as the caller. Arrays are passed to user-defined functions by value, so the function gets a
new copy of the array data and the array in the calling page is unchanged by the function. As a result, you must
handle arrays differently from all other complex data types.
Passing structures, queries, and objects

For your function to modify the caller’s copy of a structure, query, or object, you must pass the variable as an
argument. Because the function gets a reference to the caller’s structure, the caller variable reflects all changes in the
function. You do not have to return the structure to the caller. After the function returns, the calling page accesses
the changed data by using the structure variable that it passed to the function.
If you do not want a function to modify the caller’s copy of a structure, query, or object, use the Duplicate function
to make a copy and pass the copy to the function.
Passing arrays

If you want your function to modify the caller’s copy of the array, the simplest solution is to pass the array to the
function and return the changed array to the caller in the function return statement. In the caller, use the same
variable name in the function argument and return variable.
The following example shows how to directly pass and return arrays. In this example, the doubleOneDArray
function doubles the value of each element in a one-dimensional array.

//Initialize some variables
//This creates a simple array.
a=ArrayNew(1);
a[1]=2;
a[2]=22;
//Define the function.
function doubleOneDArray(OneDArray) {
var i = 0;
for ( i = 1; i LE arrayLen(OneDArray); i = i + 1)
{ OneDArray[i] = OneDArray[i] * 2; }
return OneDArray;
}
//Call the function.
a = doubleOneDArray(a);



This solution is simple, but it is not always optimal:

• This technique requires ColdFusion to copy the entire array twice, once when you call the function and once
when the function returns. This is inefficient for large arrays and can reduce performance, particularly if the
function is called frequently.
•

You can use the return value for other purposes, such as a status variable.

If you do not use the return statement to return the array to the caller, you can pass the array as an element in a
structure and change the array values inside the structure. Then the calling page can access the changed data by using
the structure variable it passed to the UDF.

ADOBE COLDFUSION 8 142
ColdFusion Developer’s Guide

The following code shows how to rewrite the previous example using an array in a structure. It returns True as a
status indicator to the calling page and uses the structure to pass the array data back to the calling page.

//Initialize some variables.
//This creates an simple array as an element in a structure.
arrayStruct=StructNew();
arrayStruct.Array=ArrayNew(1);
arrayStruct.Array[1]=2;
arrayStruct.Array[2]=22;
//Define the function.
function doubleOneDArrayS(OneDArrayStruct) {
var i = 0;
for ( i = 1; i LE arrayLen(OneDArrayStruct.Array); i = i + 1)
{ OneDArrayStruct.Array[i] = OneDArrayStruct.Array[i] * 2; }
return True;
}
//Call the function.
Status = doubleOneDArrayS(arrayStruct);
WriteOutput("Status: " & Status);





You must use the same structure element name for the array (in this case Array) in the calling page and the function.

About the Arguments scope
All function arguments exist in their own scope, the Arguments scope.
The Arguments scope exists for the life of a function call. When the function returns, the scope and its variables are
destroyed.
However, destroying the Argument scope does not destroy variables, such as structures or query objects, that
ColdFusion passes to the function by reference. The variables on the calling page that you use as function arguments
continue to exist; if the function changes the argument value, the variable in the calling page reflects the changed
value.
The Arguments scope is special, in that you can treat the scope as either an array or a structure. This dual nature of
the Arguments scope is useful because it makes it easy to use arguments in any of the following circumstances:

•

You define the function using CFScript.

•

You define the function using the cffunction tag.

•

You pass arguments using argument name=value format.

•

You pass arguments as values only.

•

The function takes optional, undeclared arguments.

The following sections describe the general rules for using the Arguments scope as an array and a structure. For more
information on using the Arguments scope in functions defined using CFScript, see “Using the Arguments scope in
CFScript” on page 145. For more information on using the Arguments scope in functions defined using the
cffunction tag, see “Using the Arguments scope in cffunction definitions” on page 145.
The contents of the Arguments scope

The following rules apply to the Arguments scope and its contents:

•

The scope contains all the arguments passed into a function.

ADOBE COLDFUSION 8 143
ColdFusion Developer’s Guide

• If you use cffunction to define the function, the scope always contains an entry “slot” for each declared
argument, even if you do not pass the argument to the function when you call it. If you do not pass a declared
(optional) argument, the scope entry for that argument is empty.
When you call a function that you defined using CFScript, you must pass the function a value for each argument
declared in the function definition. Therefore, the Arguments scope for a CFScript call does not have empty
slots.
The following example shows these rules. Assume that you have a function declared, as follows:





You can call this function with a single argument, as in the following line:


The resulting Arguments scope looks like the following:
As an array

As a structure

Entry

Value

Entry

Value

1

1

Arg1

1

2

undefined

Arg2

undefined

In this example, the following functions return the value 2 because there are two defined arguments:
ArrayLen(Arguments)
StructCount(Arguments)

However, the following tests return the value false, because the contents of the second element in the Arguments
scope is undefined.
Isdefined("Arguments.Arg2")
testArg2 = Arguments[2]>
Isdefined("testArg2")

Note: The IsDefined function does not test the existence of array elements. Instead, put any code that might try to
access an undefined array element in a try block and use a catch block to handle exceptions that arise if elements do not
exist.
Using the Arguments scope as an array

The following rules apply to referencing Arguments scope as an array:

• If you call the function using unnamed arguments, the array index is the position of the argument in the function
call.
• If you use names to pass the arguments, the array indexes correspond to the order in which the arguments are
declared in the function definition.
• If you use names to pass arguments, and do not pass all the arguments defined in the function, the Arguments
array has an empty entry at the index corresponding to the argument that was not passed. This rule applies only to
functions created using the cffunction tag.
• If you use a name to pass an optional argument that is not declared in the function definition, the array index of
the argument is the sum of the following:

ADOBE COLDFUSION 8 144
ColdFusion Developer’s Guide

a

The number of arguments defined with names in the function.

b The position of the optional argument among the arguments passed in that do not have names defined in
the function.

However, using argument names in this manner is not good programming practice because you cannot ensure
that you always use the same optional argument names when calling the function.
To demonstrate these rules, define a simple function that displays the contents of its Arguments array and call the
function with various argument combinations, as the following example shows:




Argument #i#: #Arguments[i]#



One Unnamed argument


Two Unnamed arguments


Three Unnamed arguments


Arg1:


Arg2:


Arg1=8, Arg2=9:


Arg2=6, Arg1=7


Arg1=8, Arg2=9, Arg3=10:


Arg2=6, Arg3=99, Arg1=7



Note: Although you can use the Arguments scope as an array, the IsArray(Arguments) function always returns
false and the cfdump tag displays the scope as a structure.
Using the Arguments scope as a structure

The following rule applies when referencing Arguments scope as a structure:

• Use the argument names as structure keys. For example, if your function definition includes a Principal
argument, refer to the argument as Arguments.Principal.
The following rules are also true, but avoid writing code that uses them. To ensure program clarity, only use the
Arguments structure for arguments that you name in the function definition. Use the Arguments scope as an array
for optional arguments that you do not declare in the function definition.

• If the function can take unnamed optional arguments, use array notation to reference the unnamed arguments.
For example, if the function declaration includes two named arguments and you call the function with three
arguments, refer to the third argument as Arguments[3]. To determine if an unnamed optional argument exists, use
the StructKeyExists function; for example, structKeyExists(Arguments,"3").

ADOBE COLDFUSION 8 145
ColdFusion Developer’s Guide

• If you do not name an optional argument in the function definition, but do use a name for it in the function call,
use the name specified in the function call For example, if you have an unnamed optional argument and call the
function using the name myOptArg for the argument, you can refer to the argument as Arguments.myOptArg in the
function body. This usage, however, is poor programming practice, as it makes the function definition contents
depend on variable names in the code that calls the function.
Using the Arguments scope in CFScript

A function can have optional arguments that you do not have to specify when you call the function. To determine
the number of arguments passed to the function, use the following function:
ArrayLen(Arguments)

When you define a function using CFScript, the function must use the Arguments scope to retrieve the optional
arguments. For example, the following SumN function adds two or more numbers together. It requires two
arguments and supports any number of additional optional arguments. You can refer to the first two, required,
arguments as Arg1 and Arg2 or as Arguments[1] and Arguments[2]. You must refer to the third, fourth, and any
additional optional arguments as Arguments[3], Arguments[4], and so on.
function SumN(Arg1,Arg2) {
var arg_count = ArrayLen(Arguments);
var sum = 0;
var i = 0;
for( i = 1 ; i LTE arg_count; i = i + 1 )
{
sum = sum + Arguments[i];
}
return sum;
}

With this function, any of the following function calls are valid:
SumN(Value1, Value2)
SumN(Value1, Value2, Value3)
SumN(Value1, Value2, Value3, Value4)

and so on.
The code never uses the Arg1 and Arg2 argument variables directly, because their values are always the first two
elements in the Arguments array and it is simpler to step through the array. Specifying Arg1 and Arg2 in the function
definition ensures that ColdFusion generates an error if you pass the function one or no arguments.
Note: Avoid referring to a required argument in the body of a function by both the argument name and its place in the
Arguments scope array or structure, as this can be confusing and makes it easier to introduce errors.
For more information on the Arguments scope, see “About the Arguments scope” on page 142.
Using the Arguments scope in cffunction definitions

When you define a function using the cffunction tag, you generally refer to the arguments directly by name if all
arguments are named in the cfargument tags. If you do use the Arguments scope identifier, follow the rules listed
in “About the Arguments scope” on page 142.

Function-only variables
In addition to the Arguments scope, each function can have a number of variables that exist only inside the function,
and are not saved between times the function gets called. As soon as the function exits, all the variables in this scope
are removed.

ADOBE COLDFUSION 8 146
ColdFusion Developer’s Guide

In CFScript, you create function-only variables with the var statement. Unlike other variables, you never prefix
function-only variables with a scope name.
Using function-only variables

Make sure to use the var statement in CFScript UDFs to declare all function-specific variables, such as loop indexes
and temporary variables that are required only for the duration of the function call. Doing this ensures that these
variables are available inside the function only, and makes sure that the variable names do not conflict with the
names of variables in other scopes. If the calling page has variables of the same name, the two variables are
independent and do not affect each other.
For example, if a ColdFusion page has a cfloop tag with an index variable i, and the tag body calls a CFScript UDF
that also has a loop with a function-only index variable i, the UDF does not change the value of the calling page loop
index, and the calling page does not change the UDF index. So you can safely call the function inside the cfloop tag
body.
In general, use the var statement to declare all UDF variables, other than the function arguments or shared-scope
variables, that you use only inside CFScript functions. Use another scope, however, if the value of the variable must
persist between function calls; for example, for a counter that the function increments each time it is called.

Referencing caller variables
A function can use and change any variable that is available in the calling page, including variables in the caller’s
Variables (local) scope, as if the function was part of the calling page. For example, if you know that the calling page
has a local variable called Customer_name (and there is no function scope variable named Customer_name) the
function can read and change the variable by referring to it as Customer_name or (using better coding practice)
Variables.Customer_name. Similarly, you can create a local variable inside a function and then refer to it anywhere
in the calling page after the function call. You cannot refer to the variable before you call the function.
However, you should generally avoid using the caller’s variables directly inside a function. Using the caller’s variables
creates a dependency on the caller. You must always ensure that the code outside the function uses the same variable
names as the function. This can become difficult if you call the function from many pages.
You can avoid these problems by using only the function arguments and the return value to pass data between the
caller and the function. Do not reference calling page variables directly in the function. As a result, you can use the
function anywhere in an application (or even in multiple applications), without concern for the calling code’s
variables.
As with many programming practice, there are valid exceptions to this recommendation. For example you might do
any of the following:

•

Use a shared scope variable, such as an Application or Session scope counter variable.

• Use the Request scope to store variables used in the function. For more information, see “Using the Request
scope for static variables and constants” on page 154.
•

Create context-specific functions that work directly with caller data if you always synchronize variable names.

Note: If your function must directly change a simple variable in the caller (one that is not passed to the function by
reference), you can place the variable inside a structure argument.

Using arguments
Function arguments can have the same names, but different values, as variables in the caller. Avoid such uses for
clarity, however.

ADOBE COLDFUSION 8 147
ColdFusion Developer’s Guide

The following rules apply to argument persistence:

• Because simple variable and array arguments are passed by value, their names and values exist only while the
function executes.
• Because structures, queries, and objects such as COM objects are passed by reference, the argument name exists
only while the function executes, but the underlying data persists after the function returns and can be accessed by
using the caller’s variable name. The caller’s variable name and the argument name can, and should, be different.
Note: If a function must use a variable from another scope that has the same name as a function-only variable, prefix
the external variable with its scope identifier, such as Variables or Form. (However, remember that using variables from
other scopes directly in your code is often poor practice.)

Handling errors in UDFs
This section discusses the following topics:

•

Displaying error messages directly in the function

•

Returning function status information to the calling page

• Using try/catch or cftry/cfcatch blocks and the cfthrow and cfrethrow tags to handle and generate exceptions
The technique you use depends on the circumstances of your function and application and on your preferred
programming style. However, most functions should use the second or third technique, or a combination of the two.
The following sections discuss the uses, advantages, and disadvantages of each technique, and provide examples of
their use.

Displaying error messages
Your function can test for errors and use the WriteOutput function to display an error message directly to the user.
This method is particularly useful for providing immediate feedback to users for simple input errors. You can use it
independently or in conjunction with either of the other two error-handling methods.
For example, the following variation on a “Hello world” function displays an error message if you do not enter a name
in the form:

Enter your Name: 




function HelloFriend(Name) {
if (Name is "") WriteOutput("You forgot your name!");
else WriteOutput("Hello " & name &"!");
return "";
}
if (IsDefined("Form.submit")) HelloFriend(Form.name);

Reviewing the code

The following table describes the code:

ADOBE COLDFUSION 8 148
ColdFusion Developer’s Guide

Code

Description


Enter your Name: 




Creates a simple form requesting you to enter your name.


function HelloFriend(Name) {
if (Name is "") WriteOutput("You forgot your
name!");
else WriteOutput("Hello " & name &"!");
return "";
}
if (IsDefined("Form.submit"))
HelloFriend(Form.name);


Defines a function to display "Hello name!" First, checks
whether the argument is an empty string. If so, displays an
error message.

Uses the script_name CGI variable to post to this page
without specifying a URL.
If you do not enter a name, the form posts an empty string
as the name field.

Otherwise displays the hello message.
Returns the empty string. (The caller does not use the return
value). It is not necessary to use curly braces around the if or
else statement bodies because they are single statements.
If this page has been called by submitting the form, calls the
HelloFriend function. Otherwise, the page just displays the
form.

Providing status information
In some cases, such as those where the function cannot provide a corrective action, the function cannot, or should
not, handle the error directly. In these cases, your function can return information to the calling page. The calling
page must handle the error information and act appropriately.
Consider the following mechanisms for providing status information:

• Use the return value to indicate the function status only. The return value can be a Boolean success/failure
indicator. The return value can also be a status code, for example where 1 indicates success, and various failure types
are assigned known numbers. With this method, the function must set a variable in the caller to the value of a
successful result.
• Set a status variable that is available to the caller (not the return variable) to indicate success or failure and any
information about the failure. With this method, the function can return the result directly to the caller. In this
method, the function should use only the return value and structure arguments to pass the status back to the caller.
Each of these methods can have variants, and each has advantages and disadvantages. The technique that you use
should depend on the type of function, the application in which you use it, and your coding style.
The following example, which modifies the function used in “A user-defined function example” on page 152, uses
one version of the status variable method. It provides two forms of error information:

• It returns -1, instead of an interest value, if it encounters an error. This value can serve as an error indicator
because you never pay negative interest on a loan.
• It also writes an error message to a structure that contains an error description variable. Because the message is
in a structure, it is available to both the calling page and the function.
The TotalInterest function

After changes to handle errors, the TotalInterest function looks like the following. Code that is changed from the
example in “A user-defined function example” on page 152 is in bold.

function TotalInterest(principal, annualPercent, months, status) {
Var years = 0;
Var interestRate = 0;

ADOBE COLDFUSION 8 149
ColdFusion Developer’s Guide

Var totalInterest = 0;
principal = trim(principal);
principal = REReplace(principal,"[\$,]","","ALL");
annualPercent = Replace(annualPercent,"%","","ALL");
if ((principal LE 0) OR (annualPercent LE 0) OR (months LE 0)) {
Status.errorMsg = "All values must be greater than 0";
Return -1;
}
interestRate = annualPercent / 100;
years = months / 12;
totalInterest = principal*(((1+ interestRate)^years)-1);
Return DollarFormat(totalInterest);
}

Reviewing the code

The following table describes the code that has been changed or added to the previous version of this example. For
a description of the initial code, see “A user-defined function example” on page 152.
Code

Description

function TotalInterest(principal, annualPercent, months,
status)

The function now takes an additional argument, a status
structure. Uses a structure for the status variable so that
changes that the function makes affect the status structure in the caller.

if ((principal LE 0) OR
Checks to make sure the principal, percent rate, and dura(annualPercent LE 0) OR
tion are all greater than zero.
(months LE 0)) {
Status.errorMsg = "All values must be greater than 0"; If any is not, sets the errorMsg key (the only key) in the
Return -1;
Status structure to a descriptive string. Also, returns -1 to
}

the caller and exits the function without processing
further.

Calling the function

The code that calls the function now looks like the following. Code that is changed from the example in “A userdefined function example” on page 152 is in bold.




ERROR: #status.errorMsg#




Loan amount: #Form.Principal#

Annual percentage rate:
#Form.AnnualPercent#

Loan duration: #Form.Months# months

TOTAL INTEREST: #myInterest#



Reviewing the code

The following table describes the code that has been changed or added:

ADOBE COLDFUSION 8 150
ColdFusion Developer’s Guide

Code

Description



Creates a structure to hold the function status.



Calls the function. This time, the function requires four arguments,
including the status variable.



ERROR: #status.errorMsg#



If the function returns -1, there must be an error. Displays the
message that the function placed in the status.errorMsg structure
key.



Loan amount: #Form.Principal#

Annual percentage rate:
#Form.AnnualPercent#

Loan duration: #Form.Months# months

TOTAL INTEREST: #myInterst#




If the function does not return -1, it returns an interest value. Displays
the input values and the function return value.

Using exceptions
UDFs written in CFScript can handle exceptions using the try and catch statements. UDFs written using the
cffunction tag can use the cftry, cfcatch, cfthrow, and cfrethrow tags. Using exceptions corresponds to the
way many functions in other programming languages handle errors, and can be an effective way to handle errors. In
particular, it separates the functional code from the error-handling code, and it can be more efficient than other
methods at runtime, because it does not require testing and branching.
Exceptions in UDFs have the following two dimensions:

•

Handling exceptions generated by running the UDF code

• Generating exceptions when the UDF identifies invalid data or other conditions that would cause errors if
processing continued
Handling exceptions in UDFs

A UDF should use try/catch blocks to handle exceptions in the same conditions that any other ColdFusion application uses try/catch blocks. These are typically circumstances where the function uses an external resource, such as
a Java, COM, or CORBA object, a database, or a file. When possible, your application should prevent, rather than
catch, exceptions caused by invalid application data. For example, the application should prevent users from entering
a zero value for a form field that is used to divide another number, rather than handling exceptions generated by
dividing by zero.
When ColdFusion catches an exception, the function can use any of the following methods to handle the exception:

• If the error is recoverable (for example, if the problem is a database time-out where a retry might resolve the
issue), try to recover from the problem.
•

Display a message, as described in “Displaying error messages” on page 147.

•

Return an error status, as described in “Providing status information” on page 148.

• If the UDF is defined using the cffunction tag, throw a custom exception, or rethrow the exception so that it
will be caught by the calling ColdFusion page. For more information on throwing and rethrowing exceptions, see
“Handling runtime exceptions with ColdFusion tags” on page 258.

ADOBE COLDFUSION 8 151
ColdFusion Developer’s Guide

Generating exceptions in UDFs

If you define your function using the cffunction tag, you can use the cfthrow and cfrethrow tags to throw errors
to the page that called the function. You can use this technique whenever your UDF identifies an error, instead of
displaying a message or returning an error status. For example, the following code rewrites the example from
“Providing status information” on page 148 to use the cffunction tag and CFML, and to throw and handle an
exception if any of the form values are not positive numbers.
The lines that identify invalid data and throw the exception are in bold. The remaining lines are equivalent to the
CFScript code in the previous example. However, the code that removes unwanted characters must precede the error
checking code.



















The code that calls the function and handles the exception looks like the following. The changed lines are in bold.




Loan amount: #Form.Principal#

Annual percentage rate: #Form.AnnualPercent#

Loan duration: #Form.Months# months

TOTAL INTEREST: #myInterest#




#cfcatch.message#





ADOBE COLDFUSION 8 152
ColdFusion Developer’s Guide

A user-defined function example
The following simple function takes a principal amount, an annual percentage rate, and a loan duration in months
and returns the total amount of interest to be paid over the period. You can optionally use the percent sign for the
percentage rate, and include the dollar sign and comma separators for the principal amount.
You could use the TotalInterest function in a cfoutput tag of a form’s action page, as follows:

Loan amount: #Form.Principal#

Annual percentage rate: #Form.AnnualPercent#

Loan duration: #Form.Months# months

TOTAL INTEREST: #TotalInterest(Form.Principal, Form.AnnualPercent, Form.Months)#



Defining the function using CFScript

function TotalInterest(principal, annualPercent, months) {
Var years = 0;
Var interestRate = 0;
Var totalInterest = 0;
principal = trim(principal);
principal = REReplace(principal,"[\$,]","","ALL");
annualPercent = Replace(annualPercent,"%","","ALL");
interestRate = annualPercent / 100;
years = months / 12;
totalInterest = principal*(((1+ interestRate)^years)-1);
Return DollarFormat(totalInterest);
}

Reviewing the code

The following table describes the code:
Code

Description

function TotalInterest(principal, annualPercent,
months) {

Starts the TotalInterest function definition. Requires three variables: the principal amount, the annual percentage rate, and the
loan duration in months.

Var years = 0;
Var interestRate = 0;
Var totalInterest = 0;

Declares intermediate variables used in the function and initializes
them to 0. All var statements must precede the rest of the function
code.

principal = trim(principal);
principal = REReplace(principal,"[\$,]","","ALL");
annualPercent =
Replace(annualPercent,"%","","ALL");
interestRate = annualPercent / 100;
years = months / 12;

Removes any leading or trailing spaces from the principal argument.
Removes any dollar sign ($) and comma (,) characters from the principal argument to get a numeric value.
Removes any percent (%) character from the annualPercent argument to get a numeric value, then divides the percentage value by
100 to get the interest rate.
Converts the loan from months to years.

totalInterest = principal*
(((1+ interestRate)^years)-1);
Return DollarFormat(totalInterest);
}

Calculates the total amount of interest due. It is possible to calculate
the value in the Return statement, but this example uses an intermediate totalInterest variable to make the code easier to read.
Returns the result formatted as a US currency string.
Ends the function definition.

ADOBE COLDFUSION 8 153
ColdFusion Developer’s Guide

Defining the function using the cffunction tag
The following code replaces CFScript statements with their equivalent CFML tags.
















Using UDFs effectively
This section provides information that will help you use user-defined functions more effectively.

Using functions in ColdFusion component
In many cases, the most effective use of UDFs is within a CFC. For more information on CFCs, see “Building and
Using ColdFusion Components” on page 158.

Using Application.cfm and function include files
Consider the following techniques for making your functions available to your ColdFusion pages:

•

If you consistently call a small number of UDFs, consider putting their definitions on the Application.cfm page.

•

If you call UDFs in only a few of your application pages, do not include their definitions in Application.cfm.

• If you use many UDFs, put their definitions on one or more ColdFusion pages that contain only UDFs. You can
include the UDF definition page in any page that calls the UDFs.
The next section describes other techniques for making UDFs available to your ColdFusion pages.

Specifying the scope of a function
User-defined function names are essentially ColdFusion variables. ColdFusion variables are names for data.
Function names are names (references) for segments of CFML code. Therefore, like variables, functions belong to
scopes.
About functions and scopes

Like ColdFusion variables, UDFs exist in a scope:

•

When you define a UDF, ColdFusion puts it in the Variables scope.

• You can assign a UDF to a scope the same way you assign a variable to a scope, by assigning the function to a
name in the new scope. For example, the following line assigns the MyFunc UDF to the Request scope:

ADOBE COLDFUSION 8 154
ColdFusion Developer’s Guide



You can now use the function from any page in the Request scope by calling Request.MyFunc.
Selecting a function scope

The following table describes the advantages and disadvantages of scopes that you might considering using for your
functions:
Scope

Considerations

Application

Makes the function available across all invocations of the application. Access to UDFs in Application scope is multithreaded and you can execute multiple copies of the UDF at one time.

Request

Makes the function available for the life of the current HTTP request, including in all custom tags and nested custom
tags. This scope is useful if a function is used in a page and in the custom tags it calls, or in nested custom tags.

Server

Makes the function available to all pages on a single server. In most cases, this scope is not a good choice because
in clustered systems, it only makes the function available on a single server, and all code that uses the function must
be inside a cflock block.

Session

Makes the function available to all pages during the current user session. This scope has no significant advantages
over the Application scope.

Using the Request scope

You can effectively manage functions that are used in application pages and custom tags by doing the following:
1

Define the functions on a function definitions page.

2

On the functions page, assign the functions to the request scope.

3 Use a cfinclude tag to include the function definition page on the application page, but do not include it on
any custom tag pages.
4

Always call the functions using the request scope.

This way you only need to include the functions once per request and they are available throughout the life of the
request. For example, create a myFuncs.cfm page that defines your functions and assigns them to the Request scope
using syntax such as the following:
function MyFunc1(Argument1, Argument2)
{ Function definition goes here }
Request.MyFunc1 = MyFunc1

The application page includes the myFuncs.cfm page:


The application page and all custom tags (and nested custom tags) call the functions as follows:
Request.MyFunc1(Value1, Value2)
Using the Request scope for static variables and constants

This section describes how to partially break the rule described in the section “Referencing caller variables” on
page 146. Here, the function defines variables in the Request scope. However, it is a specific solution to a specific
issue, where the following circumstances exist:

•

Your function initializes a large number of variables.

•

The variables have either of the following characteristics:

• They must be static: they are used only in the function, the function can change their values, and their values
must persist from one invocation of the function to the next.

ADOBE COLDFUSION 8 155
ColdFusion Developer’s Guide

•

They are named constants; that is the variable value never changes.

•

Your application page (and any custom tags) calls the function multiple times.

•

You can assure that the variable names are used only by the function.

In these circumstances, you can improve efficiency and save processing time by defining your function’s variables in
the Request scope, rather than the Function scope. The function tests for the Request scope variables and initializes
them if they do not exist. In subsequent calls, the variables exist and the function does not reset them.
The NumberAsString function, written by Ben Forta and available from www.cflib.org, takes advantage of this
technique.

Using function names as function arguments
Because function names are ColdFusion variables, you can pass a function’s name as an argument to another
function. This technique allows a function to use another function as a component. For example, a calling page can
call a calculation function, and pass it the name of a function that does some subroutine of the overall function.
This way, the calling page could use a single function for different specific calculations, such as calculating different
forms of interest. The initial function provides the framework, while the function whose name is passed to it can
implement a specific algorithm that is required by the calling page.
The following simple example shows this use. The binop function is a generalized function that takes the name of a
function that performs a specific binary operation and two operands. The binop function simply calls the specified
function and passes it the operands. This code defines a single operation function, the sum function. A more
complete implementation would define multiple binary operations.

function binop(operation, operand1, operand2)
{ return (operation(operand1, operand2)); }
function sum(addend1, addend2)
{ return addend1 + addend2;}
x = binop(sum, 3, 5);
writeoutput(x);


Handling query results using UDFs
When you call a UDF in the body of a tag that has a query attribute, such as a cfloop query=... tag, any function
argument that is a query column name passes a single element of the column, not the entire column. Therefore, the
function must manipulate a single query element.
For example, the following code defines a function to combine a single first name and last name to make a full name.
It queries the cfdocexamples database to get the first and last names of all employees, and then it uses a cfoutput
tag to loop through the query and call the function on each row in the query.

function FullName(aFirstName, aLastName)
{ return aFirstName & " " & aLastName; }


SELECT FirstName, LastName
FROM Employee



ADOBE COLDFUSION 8 156
ColdFusion Developer’s Guide

#FullName(FirstName, LastName)#



You generally use functions that manipulate many rows of a query outside tags that loop over queries. Pass the query
to the function and loop over it inside the function. For example, the following function changes text in a query
column to uppercase. It takes a query name as an argument.
function UCaseColumn(myquery, colName) {
var currentRow = 1;
for (; currentRow lte myquery.RecordCount; currentRow = currentRow + 1)
{
myquery[colName][currentRow] = UCase(myquery[colName][currentRow]);
}
Return "";
}

The following code uses a script that calls the UCaseColumn function to convert all the last names in the GetEmployees query to uppercase. It then uses cfoutput to loop over the query and display the contents of the column.

UCaseColumn(GetEmployees, "LastName");


#LastName#



Identifying and checking for UDFs
You can use the IsCustomFunction function to determine whether a name represents a UDF. The
IsCustomFunction function generates an error if its argument does not exist. As a result, you must ensure that the
name exists before calling the function, for example, by calling the IsDefined function. The following code shows
this use:

if(IsDefined("MyFunc"))
if(IsCustomFunction(MyFunc))
WriteOutput("MyFunc is a user-defined function");
else
WriteOutput("Myfunc is defined but is NOT a user-defined function");
else
WriteOutput("MyFunc is not defined");


You do not surround the argument to IsCustomFunction in quotation marks, so you can use this function to
determine if function arguments are themselves functions.

Using the Evaluate function
If your user-defined function uses the Evaluate function on arguments that contain strings, you must make sure
that all variable names you use as arguments include the scope identifier. Doing so avoids conflicts with functiononly variables.
The following example returns the result of evaluating its argument. It produces the expected results, the value of the
argument, if you pass the argument using its fully scoped name, Variables.myname. However, the function returns
the value of the function local variable if you pass the argument as myname, without the Variables scope identifier.

myname = "globalName";
function readname(name) {

ADOBE COLDFUSION 8 157
ColdFusion Developer’s Guide

var myname = "localName";
return (Evaluate(name));
}



The result of calling readname with myname is:
#readname("myname")# 


The result of calling readname with Variables.myname is:
#readname("Variables.myname")#


Using recursion
A recursive function is a function that calls itself. Recursive functions are useful when a problem can be solved by an
algorithm that repeats the same operation multiple times using the results of the preceding repetition. Factorial
calculation, used in the following example, is one case where recursion is useful. The Towers of Hanoi game is also
solved using a recursive algorithm.
A recursive function, like looping code, must have an end condition that always stops the function. Otherwise, the
function will continue until a system error occurs or you stop the ColdFusion server.
The following example calculates the factorial of a number, that is, the product of all the integers from 1 through the
number; for example, 4 factorial is 4 X 3 X 2 X 1 = 24.
function Factorial(factor) {
If (factor LTE 1)
return 1;
else
return factor * Factorial(factor -1);
}

If the function is called with a number greater than 1, it calls itself using an argument one less than it received. It
multiplies that result by the original argument, and returns the result. Therefore, the function keeps calling itself
until the factor is reduced to 1. The final recursive call returns 1, and the preceding call returns 2 * 1, and so on until
all the initial call returns the end result.
Important: If a recursive function calls itself too many times, it causes a stack overflow. Always test any recursive
functions under conditions that are likely to cause the maximum number of recursions to ensure that they do not cause
a stack overflow.

158

Chapter 10: Building and Using
ColdFusion Components
A ColdFusion component (CFC) file contains data and functions that you define in related, multiple methods. You
use CFC pages to organize related actions in one file, which provide can simplify your programming. For more information on creating applications that use CFCs, see the Adobe website: www.adobe.com.
Contents

About ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Creating ColdFusion components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Using ColdFusion components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Passing parameters to methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Using CFCs effectively . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
ColdFusion component example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

About ColdFusion components
A ColdFusion component (CFC) is a file saved with the extension .cfc. A CFC can contain data and functions.
Within a CFC, data is referred to as properties. Although you use the cffunction tag to define functions within a
CFC, they are typically referred to as methods instead of functions.
The page on which you define a CFC is also known as a component page. Component pages use the same tags and
functions that regular CFML pages do, plus a small number of special tags (in particular, the cfcomponent tag) and
tag attributes.
You define related methods in a CFC. Unlike ColdFusion custom tags, a single CFC can perform many related
actions, defined in multiple methods. The methods may share a data context, such as metadata and scoping, or
manage a particular database or set of tables. For example, you can define the methods to insert, update, delete, and
retrieve records from a particular database or table in one CFC.

CFCs and object-oriented programming
CFCs are building blocks that let you develop ColdFusion code in an object-oriented manner, although CFCs do not
require you to do object-oriented programming. Some of the object-oriented features of CFCs include encapsulation, inheritance, and introspection. CFC object-oriented features are similar to the object-oriented elements in
other languages, like JavaScript.
The technique of incorporating both code and data into one object such as a CFC is known as encapsulation. Encapsulation lets users pass data to and get a result from your CFC without having to understand the underlying code.
When you use encapsulation, you can validate data that is passed to the CFC. CFCs can also enforce data types, check
for required parameters, and optionally assign default values.
One CFC can inherit the methods and properties of another CFC. Inheritance lets you build multiple specific
components without rewriting the code for the basic building blocks of the components. For more information, see
“Using the Super keyword” on page 183.

ADOBE COLDFUSION 8 159
ColdFusion Developer’s Guide

CFCs support introspection; that is, they can provide information about themselves. If you display a component page
directly in an HTML browser, inspect it in the ColdFusion and Adobe Dreamweaver CS3 component browsers, or
use the CFML GetMetadata function, you see information about the component. This information includes its
path, property, methods, and additional information that you can specify using special documentation attributes and
tags. For more information, see “Using introspection to get information about components” on page 186.
When you use a ColdFusion component, you can simply invoke a method in the CFC. However, typically, you create
an instance of the CFC, and then invoke methods and refer to properties of the CFC.

When to use CFCs
You can use CFCs in the following ways:

•

Developing structured, reusable code

•

Creating web services

•

Creating Flash Remoting elements

•

Using asynchronous CFCs

Developing structured, reusable code

CFCs provide an excellent method for developing structured applications that separate display elements from logical
elements and encapsulate database queries. You can use CFCs to create application functionality that you (and
others) can reuse wherever needed, similar to user-defined functions (UDFs) and custom tags. If you want to modify,
add, or remove component functionality, you make changes in only one component file.
CFCs have several advantages over UDFs and custom tags. These advantages, which CFCs automatically provide,
include all of the following:

•

The ability to group related methods into a single component, and to group related components into a package

•

Properties that multiple methods can share

•

The This scope, a component-specific scope

• Inheritance of component methods and properties from a base component, including the use of the Super
keyword
•

Access control

•

Introspection for CFC methods, properties, and metadata

CFCs have one characteristic that prevents them from being the automatic choice for all code reuse. It takes relatively
more processing time to instantiate a CFC than to process a custom tag. In turn, it takes substantially more time to
process a custom tag than to execute a user-defined function (UDF). However, after a CFC is instantiated, calling a
CFC method has about the same processing overhead as an equivalent UDF. As a result, you should not use CFCs in
place of independent, single-purpose custom tags or UDFs. Instead, you should use CFCs to create bodies of related
methods, particularly methods that share properties.
For more information about UDFs, custom tags, and other ColdFusion code reuse techniques, see “Creating
ColdFusion Elements” on page 126.
Creating web services

ColdFusion can automatically publish CFC methods as web services. To publish a CFC method as a web service, you
specify the access="remote" attribute in the method’s cffunction tag. ColdFusion generates all the required Web
Services Description Language (WSDL) code and exports the CFC methods. For more information on creating web
services in ColdFusion, see “Using Web Services” on page 900.

ADOBE COLDFUSION 8 160
ColdFusion Developer’s Guide

Creating Flash Remoting elements

Adobe® Flash® applications that use Flash Remoting can easily take advantage of ColdFusion components for
business logic. In a CFC, the cffunction tag names the function and contains the application logic, and the
cfreturn tag returns the result to Flash.
Note: For ColdFusion component methods to communicate with Flash applications, you must set the access attribute
of the cffunction tag to remote.
For more information on creating CFCs for Flash Remoting, see “Using Flash with CFCs” on page 684.
Using asynchronous CFCs

ColdFusion provides an event gateway that lets you send a message to a CFC asynchronously. This gateway lets you
initialize processing by a CFC without waiting for the CFC to complete or return a value. You can use asynchronous
CFCs that use this gateway for the following:

•

Reindexing a Verity collection

•

Logging information

•

Running batch processes

For more information on using asynchronous CFCs, see “About event gateways” on page 1060.

Creating ColdFusion components
When you create CFCs, you create methods, which are ColdFusion user-defined functions, in the component page.
You pass data to a method by using parameters. The method then performs the function and, if specified in the
cfreturn tag, returns data.
You can also define variables in a CFC. Within a CFC, these variables are known as properties.

Tags for creating CFCs
You use the following tags to create a CFC. You include these tags on the CFML page that defines the CFC.
Tag

Description

cfcomponent

Contains a component definition; includes attributes for introspection. For more information, see “Building ColdFusion components” on page 161.

cffunction

Defines a component method (function); includes attributes for introspection. For more information, see “Defining
component methods” on page 161.

cfargument

Defines a parameter (argument) to a method; includes attributes for introspection. For more information, see
“Defining and using method parameters” on page 164.

cfproperty

Defines variables for CFCs that provide web services; also use to document component properties. For more information, see “The cfproperty tag” on page 169.

Elements of a CFC
A CFC has the following characteristics:

• It is a single CFML page with a .cfc filename extension. The component name is the same as the filename. For
example, if the file is myComponent.cfc, the component name is myComponent.

ADOBE COLDFUSION 8 161
ColdFusion Developer’s Guide

•

The page is surrounded by a cfcomponent tag. No code can be outside this tag.

• The component page defines methods (functions), properties (data), or both. Most CFCs have methods, or
methods and properties, but you can also have a CFC that contains only properties.
• You use the cffunction tag to define CFC methods. The CFScript function statement can create simple
methods, but it does not provide options to control access to the method, provide metadata, specify a return type, or
control generated output.
• You can write code on the component page that is outside of cffunction definitions. This code executes when
the CFC is instantiated or whenever you invoke a method of the CFC.

Building ColdFusion components
You use the cfcomponent and cffunction tags to create ColdFusion components. By itself, the cffunction tag
does not provide functionality. The cfcomponent tag provides an envelope that describes the functionality that you
build in CFML and enclose in cffunction tags. The following example shows the skeleton of a component with two
methods:









Defining component methods

You define component methods using cffunction tags. The following example defines a CFC that contains two
methods, getall and getsalary :




SELECT * FROM EMPLOYEE






SELECT FirstName, LastName, Salary FROM EMPLOYEE





Because component methods are ColdFusion functions, most of their features and coding techniques are identical
to those of user-defined functions. For more information on using the cffunction tag to create functions, see
“Writing and Calling User-Defined Functions” on page 134. Like other ColdFusion functions, CFC methods can
display information directly by generating output, or can return a value to the code or client that invoked the
method.
You use the following cffunction tag attributes only for CFCs:

ADOBE COLDFUSION 8 162
ColdFusion Developer’s Guide

• The displayname and hint attributes, which document the CFC; for more information, see “Documenting
CFCs” on page 168.
• The access attribute, which controls access to the CFC; for more information, see “Using access security” on
page 185.
For detailed reference information on the cffunction tag, see the CFML Reference.
Defining CFCs with related methods

When defining CFCs, it is good programming practice to organize related methods in one CFC. For example, you
could put all methods that perform operations related to a user, such as addUser, editUser, and
storeUserPreferences, in one CFC. You can group related mathematical functions into one CFC. A CFC can also
contain all the methods and properties necessary for a shopping cart. The following CFC contains two cffunction
tags that define two component methods, getEmp and getDept. When invoked, the component methods query the
ExampleApps database. The cfreturn tag returns the query results to the client, or page, where the method was
invoked.




SELECT FIRSTNAME, LASTNAME, EMAIL
FROM tblEmployees






SELECT *
FROM tblDepartments





Putting executable code in a separate file

You can put executable code in a separate file from the main component definition page. By placing the method
execution code in a separate file, you can separate property initialization code, meta information, and the method
definition shell from the executable method definition code. This technique lets you modularize your code and helps
prevent CFML pages from getting too long and complex.
To separate the component method code, use a cfinclude tag on the component definition page to call the page
that contains the component method code.
Note: If your method takes arguments or returns data to the page that invokes it, the cfargument tag and the cfreturn
tag must be on the component definition page, not on the included page.
Create a component method by using the cfinclude tag
1 Create a tellTime.cfc file with the following code:






ADOBE COLDFUSION 8 163
ColdFusion Developer’s Guide



2 Create a ColdFusion page with the following code, and save it as getUTCTime.cfm in the same directory as
tellTime.cfc:

serverTime=now();
utcTime=GetTimeZoneInfo();
utcStruct=structNew();
utcStruct.Hour=DatePart("h", serverTime);
utcStruct.Minute=DatePart("n", serverTime);
utcStruct.Hour=utcStruct.Hour + utcTime.utcHourOffSet;
utcStruct.Minute=utcStruct.Minute + utcTime.utcMinuteOffSet;
if (utcStruct.Minute LT 10) utcStruct.Minute = "0" & utcStruct.Minute;


In the example, the getUTCTime method definition calls the getUTCTime.cfm file with the cfinclude tag. The
getUTCTime.cfm code calculates the UTC time representation of the current time and populates a structure
with hour and minute values. The method in tellTime.cfc then uses the information in the structure to return
the current UTC time as a string to the calling page. The included page must not include a cfreturn statement.
Initializing instance data

Some components have instance data, which is data that persists as long as the component instance exists. For
example, a shopping cart component might have instance data that includes the IDs and quantities of items that the
user puts in the shopping cart. Instance data is often shared by several methods that can create, delete, or modify the
data.
You can refer to instance data of a CFC only if you create an instance of the CFC. From inside the CFC, you refer to
instance data of the CFC using the this prefix, for example this.firstvariable. From the calling page, you refer
to instance data using dot notation, including the name of the instance of the component and the name of the
instance data, as in objectname.ivarname. Components whose methods you invoke without first instantiating the
component do not typically have instance data.
You initialize instance data at the top of the component definition, before the method definitions. ColdFusion
executes this code when it instantiates the component; for example, when a cfobject tag creates the component
instance. Because this code executes only when the instance is created and it typically “constructs” properties of the
component, instance data initialization code is sometimes called constructor code.
You can use any CFML tag or function in constructor code, and the code can perform any ColdFusion processing,
such as querying a database or data validation and manipulation. If one component extends another, the parent
component’s constructor code executes before the child component’s constructor code.
Note: ColdFusion does not require you to put the initialization code at the top of the component definition; however, it
is good programming practice to do so.
The following example shows constructor code for a shopping cart CFC:






For information on scopes, see “The This scope” on page 179 and “The Variables scope” on page 179.

ADOBE COLDFUSION 8 164
ColdFusion Developer’s Guide

A useful technique is to define a method named init(), which initializes an instance of a CFC, acting as a
constructor. The init() method can initialize constants and return an instance of the component to the calling
page. The following code illustrates an example of an init() method:









In this example, the init() method uses the variables scope to make the shopping cart ID available anywhere in the
CFC. For more information about scope, see “CFC variables and scope” on page 179.
Defining and using method parameters

You pass data to a method by using parameters. To define a component method parameter, use the cfargument tag
in the cffunction tag body. To define multiple parameters, use multiple cfargument tags. The tag names a
parameter and lets you specify the following:

•

Whether the parameter is required

•

The type of data that is required

•

A default argument value

•

Display name and hint metadata for CFC introspection

Note: You can create CFC methods that do not use cfargument tags, for example, if you use positional parameters in
your methods. However, most CFC methods use the cfargument tag.
Example: convertTemp.cfc

The convertTemp.cfc file consists of the following:












Reviewing the code

The convertTemp CFC contains two methods that convert temperature. The following table describes the code and
its function:

ADOBE COLDFUSION 8 165
ColdFusion Developer’s Guide

Code

Description



Defines the component.



Defines the ctof method.
Indicates that this method does not display output.



Creates the temp parameter of the ctof method. Indicates
that it is required and that the expected value is numeric.



Defines the value that the method returns.



Ends the method definition.



Defines the ftoc method.
Indicates that this method does not display output.



Creates the temp parameter of the ftoc method. Indicates
that it is required and that the expected value is numeric.



Defines the value that the method returns.



Ends the method definition.



Ends the component definition.

Example: tempConversion.cfm

The ColdFusion page tempConversion.cfm is an HTML form in which the user enters the temperature to convert,
and selects the type of conversion to perform. When the user clicks the Submit button, ColdFusion performs the
actions on the processForm.cfm page. The file tempConversion.cfm, which should be in the same directory as
convertTemp.cfc, consists of the following:

Enter the temperature:



Select the type of conversion:


Celsius to Farenheit
Farenheit to Celsius





Example: processForm.cfm

The ColdFusion page processForm.cfm calls the appropriate component method, based on what the user entered in
the form on the tempConversion.cfm page. It should be in the same directory as convertTemp.cfc.


#form.temperature# degrees Celsius is #newtemp# degrees
Farenheit.


#form.temperature# degrees Fahrenheit is #newtemp# degrees
Celsius.


ADOBE COLDFUSION 8 166
ColdFusion Developer’s Guide

Reviewing the code

The file processForm.cfm invokes the appropriate component method. The following table describes the code and
its function:
Code

Description



Executes the code in the cfif block if the user
selected Celsius to Fahrenheit as the conversion type
in the form on the tempConversion.cfm page.



Invokes the ctof method of the convertTemp
component, without creating an instance of the
convertTemp component. Specifies newtemp as
the result variable for the method. Assigns the
temperature value that the user entered in the form
to the variable temp, which is specified in the
cfargument tag of the ctof method. When
invoking the ctof method, the temp variable is
assigned to the Arguments scope. For more information about variables and scope, see “CFC variables
and scope” on page 179.

#form.temperature# degrees Celsius is #newtemp#
degrees Fahrenheit.

Displays the temperature that the user entered in the
form, the text "degrees Celsius is," the new temperature value that results from the ctof method, and
the text "degrees Fahrenheit."



Executes the code in the cfelseif block if the user
selected Fahrenheit to Celsius as the conversion type
in the form on the tempConversion.cfm page.



Invokes the ftoc method of the convertTemp
component, without creating an instance of the
convertTemp component. Specifies newtemp as
the result variable for the method. Assigns the
temperature value that the user entered in the form
to the variable temp, which is specified in the
cfargument tag of the ftoc method. When
invoking the ftoc method, the temp variable is
assigned to the Arguments scope. For more information about variables and scope, see “CFC variables
and scope” on page 179.

#form.temperature# degrees Fahrenheit is #newtemp#
degrees Celsius.

Displays the temperature that the user entered in the
form, the text "degrees Fahrenheit is," the new
temperature value that results from the ftoc
method, and the text "degrees Celsius."



Closes the cfif block.

To run the example, display the tempConversion.cfm page in your browser. When you enter a value in the text box
of the form, the value is stored in the form.temperature variable. Processing is then performed on the
processForm.cfm page, which refers to the value as form.temperature. When you invoke either method, the
cfinvoke tag assigns the value form.temperature to temp; temp is the argument specified in the cfargument tag
of the appropriate method. The appropriate method in the convertTemp component performs the necessary calculations and returns the new value as newtemp.
For detailed reference information on the cfargument tag, see the CFML Reference.

ADOBE COLDFUSION 8 167
ColdFusion Developer’s Guide

To access the parameter values in the component method definition, use structure- or array-like notation with the
Arguments scope. The following example refers to the lastName argument as Arguments.lastname; it could also
refer to it as Arguments[1]. In addition, you can access arguments directly using number (#) signs, such as
#lastname#; however, it is better programming practice to identify the scope (for example,
#Arguments.lastname#). Also, you can use Array- or structure-like notation, which lets you loop over multiple
parameters.
For more information on the Arguments scope, see “The Arguments scope” on page 181.
Define parameters in the component method definition
1 Create a new component with the following contents, and save it as corpQuery.cfc in a directory under your web

root directory:





SELECT LASTNAME, FIRSTNAME, EMAIL
FROM tblEmployees
WHERE LASTNAME LIKE '#Arguments.lastName#'








SELECT ItemName, ItemDescription, ItemCost
FROM tblItems
WHERE ItemCost <= #Arguments.cost#






In the example, the cfargument attributes specify the following:

•

The name attributes define the parameter names.

• The type attribute for the lastName argument specifies that the parameter must be a text string. The type
attribute for the cost argument specifies that the parameter must be a numeric value. These attributes validate the
data before it is submitted to the database.
•

The required attributes indicate that the parameters are required or an exception will be thrown.

•

The Arguments scope provides access to the parameter values.

Providing results
ColdFusion components can provide information in the following ways:

•

They can generate output that is displayed on the calling page.

•

They can return a variable.

ADOBE COLDFUSION 8 168
ColdFusion Developer’s Guide

You can use either technique, or a combination of both, in your applications. The technique that you use should
depend on your application’s needs and your coding methodologies. For example, many CFC methods that perform
business logic return the results as a variable, and many CFC methods that display output directly are designed as
modular units for generating output, and do not do business logic.
Displaying output

If you do not specifically suppress output, any text, HTML code, or output that CFML tags generate inside your
method gets returned as generated output to the client that calls the component method. If the client is a web
browser, it displays these results. For example, the following getLocalTime1 component method shows the local
time directly on the page that invokes the method:


#TimeFormat(now())#



Component methods that are called by using Flash Remoting or as web services cannot use this method to provide
results.
Returning a results variable

In the component method definition, you use the cfreturn tag to return the results to the client as variable data.
For example, the following getLocalTime2 component method returns the local time as a variable to the
ColdFusion page or other client that invokes the method:






The ColdFusion page or other client, such as a Flash application, that receives the result then uses the variable data
as appropriate.
Note: If a CFC is invoked using a URL or by submitting a form, ColdFusion returns the variable as a WDDX packet. A
CFC that is invoked by Flash Remoting, or any other instance of a CFC, must not return the This scope.
You can return values of all data types, including strings, integers, arrays, structures, and instances of CFCs. The
cfreturn tag returns a single variable, as does the return CFScript statement. Therefore, if you want to return more
than one result value at a time, use a structure. If you do not want to display output in a method, use
output="false" in the cffunction tag.
For more information on using the cfreturn tag, see the CFML Reference.
Documenting CFCs

ColdFusion provides several ways to include documentation about your CFCs in your component definitions. The
documentation is available when you use introspection to display information about the CFC or call the
GetMetadata or GetComponentMetaData function to get the component’s metadata. You can use the following
tools for documenting CFCs:

•

The displayname and hint attributes

•

User-defined metadata attributes

•

The cfproperty tag

ADOBE COLDFUSION 8 169
ColdFusion Developer’s Guide

The following sections describe these tools. For information on displaying the information, see “Using introspection
to get information about components” on page 186.
The displayname and hint attributes

The cfcomponent, cffunction, cfargument, and cfproperty tags have displayname and hint attributes.
The displayname attribute lets you provide a more descriptive name for a component, attribute, method, or
property. When you use introspection, this attribute appears in parentheses next to the component or method name,
or on the parameter information line.
You use the hint attribute for longer descriptions of the component, method, or argument. In the introspection
display, this attribute appears on a separate line or on several lines of the component or method description, and at
the end of the argument description.
Metadata attributes

You can include arbitrary metadata information as attributes of the cfcomponent, cffunction, cfargument, and
cfproperty tags. To create a metadata attribute, specify the metadata attribute name and its value. For example, in
the following cfcomponent tag, the Author attribute is a metadata attribute. This attribute is not used as a function
parameter; instead, it indicates who wrote this CFC.


Metadata attributes are not used by ColdFusion for processing; they also do not appear in standard ColdFusion
introspection displays; however, you can access and display them by using the GetMetaData or
GetComponentMetaData function to get the metadata. Each attribute name is a key in the metadata structure of the
CFC element.
Metadata attributes are used for more than documentation. Your application can use the GetMetadata function to
get the metadata attributes for a component instance, or the GetComponentMetaData function to get the metadata
for an interface or component that you have not yet instantiated. You can then act based on the values. For example,
a mathCFC component might have the following cfcomponent tag:


In this case, a ColdFusion page with the following code sets the MetaTypeInfo variable to Float:



Note: All metadata values are replaced by strings in the metadata structure returned from the GetMetadata function.
Because of this, you should not use expressions in custom metadata attributes.
The cfproperty tag

The cfproperty tag is used to create complex data types with WSDL descriptors and for component property
documentation, as follows:

• It can create complex data types with WSDL descriptions for ColdFusion web services. For more information,
see “Using ColdFusion components to define data types for web services” on page 915.
• It can provide documentation of component properties in the ColdFusion introspection output. The introspection information includes the values of the standard cfproperty tag attributes.
Note: The cfproperty tag does not create a variable or assign it a value. It is used for information purposes only. You
use a cfset tag, or CFScript assignment statement, to create the property and set its value.

ADOBE COLDFUSION 8 170
ColdFusion Developer’s Guide

Saving and naming ColdFusion components

The following table lists the locations in which you can save component files and how they can be accessed from each
location:
URL

Form

Flash Remoting

Web services

ColdFusion page

Current directory

N/A

Yes

N/A

N/A

Yes

Web root

Yes

Yes

Yes

Yes

Yes

ColdFusion mappings

No

No

No

No

Yes

Custom tag roots

No

No

No

No

Yes

Note: ColdFusion mappings and custom tag roots can exist within the web root. If so, they are accessible to remote
requests, including URL, form, Flash Remoting, and web services invocation.
When you store components in the same directory, they are members of a component package. You can group related
CFCs into packages. Your application can refer to any component in a directory specifically by using a qualified
component name that starts with a subdirectory of one of the accessible directories and uses a period to delimit each
directory in the path to the directory that contains the component. For example, the following example is a qualified
name of a component named price:
catalog.product.price

In this example, the price.cfc file must be in the catalog\product subdirectory of a directory that ColdFusion searches
for components, as listed in the preceding table. When you refer to a component using the qualified name,
ColdFusion looks for the component in the order described in “Specifying the CFC location” on page 176.
Establishing a descriptive naming convention is a good practice, especially if you plan to install the components as
part of a packaged application.

Using ColdFusion components
There are two ways to use a CFC:
1 You can instantiate a CFC object, which creates a CFC instance. You then invoke the methods of the instance.
You can access the CFC methods and data as instance elements. You can also use the instance in the cfinvoke tag
to invoke the CFC methods. When you instantiate a CFC, data in the CFC is preserved as long as the CFC instance
exists, and ColdFusion does not incur the overhead of creating the instance each time you call a method.

Instantiate CFCs to preserve data in the CFC. To ensure processing efficiency if you use the CFC more than once
on a page, instantiate the CFC before you invoke its methods.
Methods that are executed remotely through Flash Remoting and web services always create a new instance of
the CFC before executing the method.
2 You can invoke (call) a method of the CFC without creating an instance of the CFC, which is referred to as
transiently invoking a method. In this case, ColdFusion creates an instance of the CFC that exists only from the time
you invoke the method until the method returns a result. No data is preserved between invocations and there is no
instance of the CFC that you can reuse elsewhere in your CFML. It is considered a best practice to create an instance
of a CFC before invoking any of its methods, unless your CFML request uses the CFC only once. If you transiently
invoke a method frequently, consider creating a user-defined function to replace the CFC method.

ADOBE COLDFUSION 8 171
ColdFusion Developer’s Guide

You can create persistent CFCs by assigning the CFC instance to a persistent scope, such as the Session or Application scope. This way, you can create CFCs for objects, such as shopping carts or logged-in users, that must persist
for sessions. You can also create CFCs that provide application-specific data and methods.

Tags for using CFCs
The following table lists the tags that you use to instantiate or invoke a CFC. You use these tags on the CFML page
on which you instantiate or invoke the CFC.
Tag

Description

cfinvoke

Invokes a method of a CFC.

cfinvokeargument

Passes the name and value of a parameter to a component method.

cfobject

Creates a CFC instance.

CreateObject

Creates a CFC instance.

CFC invocation techniques
ColdFusion provides many ways to instantiate CFCs and invoke CFC methods. The following table lists the
techniques, including the ColdFusion tags and functions that you use:
Invocation

Description

For more information

cfinvoke tag

Invokes a component method. Can invoke
methods of a CFC instance or invoke the
methods transiently.

See “Invoking CFC methods with the cfinvoke tag” on
page 172.

cfset tag and assignment state- Invoke methods and access properties of a

See “Using components directly in CFScript and CFML”
on page 174.

ments

component instance.

URL (HTTP GET)

Transiently invokes a component method by
specifying the component and method names
in the URL string.

Form control(HTTP POST)

Transiently invokes a component method using See “Invoking component methods by using a form”
on page 175.
the HTML form and input tags and their
attributes.

Flash Remoting

ActionScript can transiently invoke component See “Using the Flash Remoting Service” on page 674.
methods.

Web services

The cfinvoke tag and CFScript consume web
services in ColdFusion. External applications
can also consume CFC methods as web
services.

See “Invoking component methods by using a URL” on
page 175.

See “Using Web Services” on page 900.

Instantiating CFCs
If you use a CFC multiple times in a ColdFusion request, or if you use a CFC with persistent properties, use the
cfobject tag or CreateObject function to instantiate the CFC before you call its methods.
The following example uses the cfobject tag to create an instance of the tellTime CFC.


The following example uses the CreateObject function to instantiate the same component in CFScript:
tellTimeObj = CreateObject("component", "tellTime");

ADOBE COLDFUSION 8 172
ColdFusion Developer’s Guide

Invoking CFC methods with the cfinvoke tag
The cfinvoke tag can invoke methods on a CFC instance or invoke CFC methods transiently. You can also use the
cfinvoke tag to invoke CFC methods from within a CFC.
Invoking methods of a CFC instance

To invoke a component method of a CFC instance, use the cfinvoke tag and specify the following:

•

The CFC instance name, enclosed in number signs (#), in the component attribute.

•

The method name, in the method attribute.

• Any parameters. For information on passing parameters, see “Passing parameters to methods by using the
cfinvoke tag” on page 177.
•

If the component method returns a result, the name of the variable that will contain the result in the
returnVariable attribute.
1

Create a file named tellTime2.cfc with the following code:






serverTime=now();
utcTime=GetTimeZoneInfo();
utcStruct=structNew();
utcStruct.Hour=DatePart("h", serverTime);
utcStruct.Minute=DatePart("n", serverTime);
utcStruct.Hour=utcStruct.Hour + utcTime.utcHourOffSet;
utcStruct.Minute=utcStruct.Minute + utcTime.utcMinuteOffSet;
if (utcStruct.Minute LT 10) utcStruct.Minute = "0" & utcStruct.Minute;





The example defines two component methods: getLocalTime and getUTCTime.
2

Create a ColdFusion page, with the following code and save it in the same directory as the tellTime component:






Time Display Page

Server's Local Time: #localTime#

Calculated UTC Time: #UTCTime#


This example uses the cfobject tag to create an instance of the tellTime component and the cfinvoke tag to invoke
the instance’s getLocalTime and getUTCTime methods. In this example, the CFC contains the functional logic in
the methods, which return a result to the calling page, and the calling page displays the results. This structure
separates the logic from the display functions, which usually results in more reusable code.

ADOBE COLDFUSION 8 173
ColdFusion Developer’s Guide

Invoking component methods transiently

In ColdFusion pages or components, the cfinvoke tag can invoke component methods without creating a persistent
CFC instance.
To invoke a component method transiently, use the cfinvoke tag and specify the following:

•

The name or path of the component, in the component attribute.

•

The method name, in the method attribute.

• Any parameters. For information on passing parameters, see “Passing parameters to methods by using the
cfinvoke tag” on page 177.
•

If the component method returns a result, the name of the variable that contains the result, in the

returnVariable attribute.

1

Create the following component and save it as tellTime.cfc:


#TimeFormat(now())#



The example defines a component with one method, getLocalTime, that displays the current time.
2

Create a ColdFusion page, with the following code, and save it in the same directory as the tellTime component:
Time Display Page
Server's Local Time:


Using the cfinvoke tag, the example invokes the getLocalTime component method without creating a
persistent CFC instance.
Using the cfinvoke tag within the CFC definition

You can use the cfinvoke tag to invoke a component method within the component definition; for example, to call
a utility method that provides a service to other methods in the component. To use the cfinvoke tag in this instance,
do not create an instance or specify the component name in the cfinvoke tag, as the following example shows:


At your service...



We're in mymethod.






Note: When you invoke a method from within the component definition in which you define the method, do not use the
This scope, because this resets the access privileges.
Invoking methods by using dynamic method names

The cfinvoke tag is the only way to efficiently invoke different component methods based on variable data (for
example, form input). In this case, you use a variable name, such as Form.method, as the value of the method
attribute. In the following example, the user selects a report from a form:


ADOBE COLDFUSION 8 174
ColdFusion Developer’s Guide

Complete Report
Salary Information


The cfinvoke tag then invokes the appropriate method, based on what the user selected:


Using components directly in CFScript and CFML
You can invoke methods of a component instance directly using CFScript or in CFML tags. To invoke component
methods directly, use the CreateObject function or cfobject tag to instantiate the component. Thereafter, use the
instance name followed by a period and the method that you are calling to invoke an instance of the method. You
must always use parentheses after the method name, even if the method does not take any parameters.
You can use this syntax anywhere that you can use a ColdFusion function, such as in cfset tags or surrounded by
number signs in the body of a cfoutput tag.
Invoking component methods in CFScript

The following example shows how to invoke component methods in CFScript:


tellTimeObj=CreateObject("component","tellTime");
WriteOutput("Server's Local Time: " & tellTimeObj.getLocalTime());
WriteOutput("
 Calculated UTC Time: " & tellTimeObj.getUTCTime());


In the example, the three CFScript statements do the following:
1

The CreateObject function instantiates the tellTime CFC as tellTimeObj.

The first WriteOutput function displays text followed by the results returned by the getLocalTime method of
the tellTimeObj instance.

2

3 The second WriteOutput function displays text followed by the results returned by the getUTCTime method of
the tellTimeObj instance.

In CFScript, you use the method name in standard function syntax, such as methodName().
Invoking component methods in CFML

The following example uses CFML tags to produce the same results as the CFScript example:


Server's Local Time: #tellTimeObj.getLocalTime()#

Calculated UTC Time: #tellTimeObj.getUTCTime()#


Accessing component data directly

You can access data in the component’s This scope directly in CFScript and cfset assignment statements. For
example, if a user data CFC has a This.lastUpdated property, you could have code such as the following:





For more information, see “The This scope” on page 179.

ADOBE COLDFUSION 8 175
ColdFusion Developer’s Guide

Invoking CFC methods with forms and URLs
You can invoke CFC methods directly by specifying the CFC in a URL, or by using HTML and CFML form tags.
Because all HTTP requests are transient, these methods only let you transiently invoke methods. They do not let you
create persistent CFC instances.
Invoking component methods by using a URL

To invoke a component method by using a URL, you must append the method name to the URL in standard URL
query-string, name-value syntax. You can invoke only one component method per URL request, for example:
http://localhost:8500/tellTime.cfc?method=getLocalTime

Note: To use URL invocation, you must set the access attribute of the cffunction tag to remote.
To pass parameters to component methods using a URL, append the parameters to the URL in standard URL querystring, name-value pair syntax; for example:
http://localhost:8500/corpQuery.cfc?method=getEmp&lastName=camden

To pass multiple parameters within a URL, use the ampersand character (&) to delimit the name-value pairs; for
example:
http://localhost:8500/corpQuerySecure.cfc?method=getAuth&store=women&dept=shoes

Note: To ensure data security, Adobe strongly recommends that you not pass sensitive information over the web using
URL strings. Potentially sensitive information includes all personal user information, including passwords, addresses,
telephone numbers, and so on.
If a CFC method that you access using the URL displays output directly, the user’s browser shows the output. You
can suppress output by specifying output="No" in the cffunction tag. If the CFC returns a result using the
cfreturn tag, ColdFusion converts the text to HTML edit format (with special characters replaced by their HTML
escape sequences), puts the result in a WDDX packet, and includes the packet in the HTML that it returns to the
client.
Invoking component methods by using a form

To invoke a method by using a ColdFusion or HTML form, the following must be true:

•

The form or cfform tag action attribute must specify the CFC filename or path followed by

?method=methodname, where methodname is the name of the method, for example:
.

• The form must have an input tag for each component method parameter. The name attribute of the tag must be
the method parameter name and the field value is the parameter value.
•

The cffunction tag that defines the CFC method being invoked must specify the access="remote" attribute.

If the CFC method that you invoke from the form displays output directly, the user’s browser shows the output. (You
can use the cffunction tag output attribute to disable displaying output.) If the CFC returns a result using the
cfreturn tag, ColdFusion converts the text to HTML edit format, puts it in a WDDX packet, and includes the packet
in the HTML that it returns to the client.
1

Create a corpFind.cfm file with the following contents:
Find People

Enter employee's last Name:



ADOBE COLDFUSION 8 176
ColdFusion Developer’s Guide





In the example, the form tag’s action attribute points to the corpQuery component and invokes the getEmp
method.
Create a corpQuery.cfc file, specifying access="remote" for each cffunction tag, as the following example
shows:

2






SELECT LASTNAME, FIRSTNAME, EMAIL
FROM tblEmployees
WHERE LASTNAME LIKE '#arguments.lastName#'

Results filtered by #arguments.lastName#:





3

Open a web browser and enter the following URL:
http://localhost/corpFind.cfm

ColdFusion displays the search form. After you enter values and click the Submit Query button, the browser
displays the results.

Accessing CFCs from outside ColdFusion and basic HTML
Flash applications that use Flash Remoting can easily take advantage of ColdFusion components for business logic.
Similarly, you can export CFCs so that any application can access CFC methods as web services.
For ColdFusion component methods to communicate with Flash Remoting applications, you must set the access
attribute of the cffunction tag to remote.
For more information on creating CFCs for Flash Remoting, see “Using the Flash Remoting Service” on page 674
Any application, whether it is a ColdFusion application, a Java application, JSP page, or a .Net application, can access
well-formed ColdFusion components as web services by referencing the WSDL file that ColdFusion automatically
generates.
To see a component’s WSDL definition, specify the component web address in a URL, followed by ?wsdl; for
example:
http://localhost:8500/MyComponents/arithCFC.cfc?wsdl

For more information on using CFCs as web services, see “Using Web Services” on page 900

Specifying the CFC location
When you instantiate or invoke a component, you can specify the component name only, or you can specify a
qualified path. To specify a qualified path, separate the directory names with periods, not backslashes. For example,
myApp.cfcs.myComponent specifies the component defined in myApp\cfcs\myComponent.cfc. For additional
information, see “Saving and naming ColdFusion components” on page 170.
ColdFusion uses the following rules to find the specified CFC:

ADOBE COLDFUSION 8 177
ColdFusion Developer’s Guide

• If you use a cfinvoke or cfobject tag, or the CreateObject function, to access the CFC from a CFML page,
ColdFusion searches directories in the following order:

•

a

Local directory of the calling CFML page

b

Web root

c

Directories specified on the Custom Tag Paths page of ColdFusion Administrator

If you specify only a component name, ColdFusion searches each of these directories, in turn, for the component.

• If you specify a qualified path, such as myApp.cfcs.myComponent, ColdFusion looks for a directory matching
the first element of the path in each of these directories (in this example, myApp). If ColdFusion finds a matching
directory, it looks for a file in the specified path beneath that directory, such as myApp\cfcs\myComponent.cfc,
relative to each of these directories.
Note: If ColdFusion finds a directory that matches the first path element, but does not find a CFC under that directory,
ColdFusion returns a not found error and does not search for another directory.

• If you invoke a CFC method remotely, using a specific URL, a form field, Flash Remoting, or a web service
invocation, ColdFusion looks in the specified path relative to the web root. For form fields and URLs that are
specified directly on local web pages, ColdFusion also searches relative to the page directory.
Note: On UNIX and Linux systems, ColdFusion attempts to match a CFC name or custom tag name with a filename,
as follows: First, it attempts to find a file with the name that is all lowercase. If it fails, it tries to find a file whose case
matches the CFML case. For example, if you specify ,
ColdFusion first looks for mycomponent.cfc and, if it doesn't find it, ColdFusion looks for myComponent.cfc.

Passing parameters to methods
You pass parameters to a method in a CFC by using the cfinvoke tag, direct method invocations, or by passing
parameters in a URL.

Passing parameters to methods by using the cfinvoke tag
When you use the cfinvoke tag, ColdFusion provides several methods for passing parameters to CFC methods:

•

As cfinvoke tag attributes, in name="value" format

•

In the cfinvoke tag argumentcollection attribute

•

In the cfinvoke tag body, using the cfinvokeargument tag

You can use any combination of these methods in a single invocation. If you use the same name in two or three of
these methods, ColdFusion uses the value based on the following order of precedence:
1

cfinvokeargument tags

2

cfinvoke attribute name-value pairs

3

argumentcollection arguments

Passing parameters by using attribute format

You can pass parameters in the cfinvoke tag as tag attribute name-value pairs, as the following example shows:


ADOBE COLDFUSION 8 178
ColdFusion Developer’s Guide

In the example, the parameters are passed as the lastName and pwd attributes.
Note: The cfinvoke tag attribute names are reserved and cannot be used for parameter names. The reserved attribute
names are: component, method, argumentCollection, and returnVariable. For more information, see the CFML
Reference.
Passing parameters in the argumentCollection attribute

If you save attributes to a structure, you can pass the structure directly using the cfinvoke tag’s
argumentCollection attribute. This technique is useful if an existing structure or scope (such as the Forms scope)
contains values that you want to pass to a CFC as parameters, and for using conditional or looping code to create
parameters.
When you pass an argumentCollection structure, each structure key is the name of a parameter inside the structure.
The following example passes the Form scope to the addUser method of the UserDataCFC component. In the
method, each form field name is a parameter name; the method can use the contents of the form fields to add a user
to a database.

Passing parameters by using the cfinvokeargument tag

To pass parameters in the cfinvoke tag body, use the cfinvokeargument tag. Using the cfinvokeargument tag, for
example, you can build conditional processing that passes a different parameter based on user input.
The following example invokes the corpQuery component:




The cfinvokeargument tag passes the lastName parameter to the component method.
In the following example, a form already let the user select the report to generate. After instantiating the getdata
and reports components, the action page invokes the doquery component instance, which returns the query
results in queryall. The action page then invokes the doreport component instance and uses the
cfinvokeargument tag to pass the query results to the doreport instance, where the output is generated.







Passing parameters in direct method invocations
ColdFusion provides three methods for passing parameters to CFC methods in direct method invocations:
1 You can pass the parameters the form of comma-separated name="value" entries, as in the following CFScript
example:
authorized = securityCFC.getAuth(name="Almonzo", Password="LauRa123");

2 You can pass the parameters in an argumentCollection structure. The following code is equivalent to the
previous example:
argsColl = structNew();
argsColl.username = "Almonzo";
argsColl.password = "LauRa123”;

ADOBE COLDFUSION 8 179
ColdFusion Developer’s Guide

authorized = securityCFC.getAuth(argumentCollection = argsColl);

3 You can pass positional parameters to a method by separating them with commas. The following example calls
the getAuth method, and passes the name and password as positional parameters:
authorized = securityCFC.getAuth("Almonzo", "LauRa123");

Note: For more information on using positional parameters and component methods in ColdFusion functions, see
“Creating user-defined functions” on page 135.

Passing parameters in a URL
ColdFusion lets you pass parameters to CFC methods in a URL. To do so, you append the URL in standard URL
query-string, name-value pair syntax; for example:
http://localhost:8500/CompanyQuery.cfc?method=getEmp&lastName=Adams

CFC variables and scope
CFCs interact with ColdFusion scopes and use local variables.
Note: Components also have a Super keyword that is sometimes called a scope. For information on the Super keyword,
see “Using the Super keyword” on page 183.

The This scope
The This scope is available within the CFC and is shared by all CFC methods. It is also available in the base
component (if the CFC is a child component), on the page that instantiates the CFC, and all CFML pages included
by the CFC.
Inside the CFC, you define and access This scope variables by using the prefix This, as in the following line:


In the calling page, you can define and access CFC This scope variables by using the CFC instance name as the prefix.
For example, if you create a CFC instance named car and, within the car CFC specify , a ColdFusion page that instantiates the CFC could refer to the component’s color property
as #car.color#.
Variable values in the This scope last as long as the CFC instance exists and, therefore, can persist between calls to
methods of a CFC instance.
Note: The This scope identifier works like the This keyword in JavaScript and ActionScript. CFCs do not follow the Java
class model, and the This keyword behaves differently in ColdFusion than in Java. In Java, This is a private scope,
whereas in ColdFusion, it is a public scope.

The Variables scope
The Variables scope in a CFC is private to the CFC. It includes variables defined in the CFC body (initialization or
constructor code) and in the CFC methods. When you set Variables scope variables in the CFC, they cannot be seen
by pages that invoke the CFC.
The CFC Variables scope does not include any of the Variables scope variables that are declared or available in the
page that instantiates or invokes the CFC. However, you can make the Variables scope of the page that invokes a CFC
accessible to the CFC by passing Variables as an argument to the CFC method.

ADOBE COLDFUSION 8 180
ColdFusion Developer’s Guide

You set a Variables scope variable by assigning a value to a name that has the Variables prefix or no prefix.
Values in the Variables scope last as long as the CFC instance exists, and therefore can last between calls to CFC
instance methods.
The Variables scope is available to included pages, and Variables scope variables that are declared in the included
page are available in the component page.
Note: The Variables scope is not the same as the var keyword, which makes variables private within a function. You
should always define function-local variables using the var keyword.
Example: sharing the Variables scope

The following example shows how to make the Variables scope of the page that invokes a CFC accessible to the CFC
by passing Variables as an argument to the CFC method. It also illustrates that the Variables scope is private to the
CFC.
The following code is for the callGreetMe.cfm page:



Before invoking the CFC, Variables.Myname is: #Variables.MyName#.

Passing Variables scope to hello method. It returns:
#myGreetings.hello(Variables.MyName)#.

After invoking the CFC, Variables.Myname is: #Variables.MyName#.




The following code is for the greetMe CFC:








Within the VarScopeInCfc method, Variables.MyName is:
#variables.MyName#




In this example, the callGreetMe.cfm page does the following:
1

Sets the MyName variable in its Variables scope to Wilson.

2

Displays the Variables.MyName value.

3

Calls the greetMe CFC and passes its Variables scope as a parameter.

4

Displays the value returned by the greetMe CFC.

5

Displays the Variables.MyName value.

6

Invokes the VarScopeInCfc method, which displays the value of Variables.MyName within the CFC.

When you browse the callGreetMe.cfm page, the following appears:
Before invoking the CFC, Variables.Myname is: Wilson.
Passing Variables scope to hello method. It returns: Hello Wilson.
After invoking the CFC, Variables.Myname is: Wilson.
Within the VarScopeInCfc method, Variables.MyName is: Tuckerman

ADOBE COLDFUSION 8 181
ColdFusion Developer’s Guide

The Arguments scope
The Arguments scope exists only in a method, and is not available outside the method. The scope contains the
variables that you passed into the method, including variables that you passed in the following ways:

•

As named attributes to the cfinvoke tag

•

In the cfargumentcollection attribute of the cfinvoke tag

•

In cfinvokeargument tags

• As attributes or parameters passed into the method when the method is invoked as a web service, by Flash
Remoting, as a direct URL, or by submitting a form
You can access variables in the Arguments scope using structure notation (Arguments.variablename), or array
notation (Arguments[1] or Arguments["variablename"]).
The Arguments scope does not persist between calls to CFC methods.
Variables in the Arguments scope are available to pages included by the method.

Other variable scopes
A CFC shares the Form, URL, Request, CGI, Cookie, Client, Session, Application, Server, and Flash scopes with the
calling page. Variables in these scopes are also available to all pages that are included by a CFC. These variables do
not have any behavior that is specific to CFCs.

Function local variables
Variables that you declare with the Var keyword inside a cffunction tag or CFScript function definition are
available only in the method in which they are defined, and only last from the time the method is invoked until it
returns the result. You cannot use the Var keyword outside of function definitions.
Note: You should always use the Var keyword on variables that are only used inside of the function in which they are
declared.
You must define all function local variables at the top of the function definition, before any other CFML code; for
example:






Any arguments declared with the cfargument tag must appear before any variables defined with the cfset tag. You
can also put any cfscript tag first and define variables that you declare with the Var keyword in the script.
Use function local variables if you put the CFC in a persistent scope such as the Session scope, and the function has
data that must be freed when the function exits.
Local variables do not persist between calls to CFC methods.
Local variables are available to pages included by the method.

ADOBE COLDFUSION 8 182
ColdFusion Developer’s Guide

Using CFCs effectively
Several techniques let you effectively use CFCs in your applications:

•

Structure and reuse code

•

Build secure CFCs

•

Use introspection to get information about components

Structuring and reusing code
Component inheritance and the Super keyword are two important tools for creating structured, object-oriented
ColdFusion components.
Component inheritance: Lets you create a single base component and reuse this code in multiple subclasses that are
derived from the base component. Typically a base component is more general, and subcomponents are typically
more specific. Each subclass does not have to redefine the code in the base component, but can override it if
necessary.
The Super keyword: Lets a component that overrides a base component method execute the original base
component method. This technique lets your subclassed component override a method without losing the ability to
call the original version of the method.
Using component inheritance

Component inheritance lets you import component methods and properties from one component to another
component. Inherited components share any component methods or properties that they inherit from other components, and ColdFusion initializes instance data in the parent CFC when you instantiate the CFC that extends it.
When using component inheritance, inheritance should define an is a relationship between components. For
example, a component named president.cfc inherits its methods and properties from manager.cfc, which inherits its
methods and properties from employee.cfc. In other words, president.cfc is a manager.cfc; manager.cfc is an
employee.cfc; and president.cfc is an employee.cfc.
In this example, employee.cfc is the base component; it’s the component upon which the others are based. The
manager component extends the employee component; it has all the methods and properties of the employee
component, and some additional ones. The president component extends the manager component. The president
component is called a subcomponent or child component of the manager component, which, in turn, is a child
component of the employee component.
1

Create the employee.cfc file with the following content:




2

Create the manager.cfc file with the following content:




In the example, the cfcomponent tag’s extends attribute points to the employee component.
3

Create the president.cfc file with the following content:



ADOBE COLDFUSION 8 183
ColdFusion Developer’s Guide



In the example, the cfcomponent tag’s extends attribute points to the manager component.
4 Create the inherit.cfm file with the following content, and save it in the same directory as the components you
created in the previous steps:




An employee's salary is #empObj.basesalary# per week.

A manager's salary is #mgrObj.basesalary + mgrObj.mgrBonus# per week.

A president's salalry is #prezObj.basesalary + prezObj.mgrBonus +
prezObj.PrezBonus# per week.


When you browse the inherit.cfm file, the manager component refers to the basesalary defined in employee.cfc,
which is the base component; the president component refers to both the basesalary defined in the employee
component, and the mgrBonus defined in the manager component. The manager component is the parent class of
the president component.
Using the component.cfc file

All CFCs automatically extend the ColdFusion WEB-INF/cftags/component.cfc component. (The WEB-INF
directory is in the cf_root/wwwroot directory on ColdFusion configured with an embedded J2EE server. It is in the
cf_root directory when you deploy ColdFusion on a J2EE server.) This CFC is distributed as a zero-length file. You
can use it for any core methods or properties that you want all CFCs in your ColdFusion application server instance
to inherit.
Note: When you install a newer version of ColdFusion, the installation procedure replaces the existing component.cfc
file with a new version. Therefore, before upgrading, you should save any code that you have added to the component.cfc
file, and then copy the code into the new component.cfc file.
Using the Super keyword

You use the Super keyword only on CFCs that use the Extends attribute to extend another CFC. Unlike ColdFusion
scopes, the Super keyword is not used for variables; it is only used for CFC methods, and it is not available on
ColdFusion pages that invoke CFCs.
The Super keyword lets you refer to versions of methods that are defined in the CFC that the current component
extends. For example, the employee, manager, and president CFCs each contain a getPaid method. The manager
CFC extends the employee CFC. Therefore, the manager CFC can use the original versions of the overridden
getPaid method, as defined in the employee CFC, by prefixing the method name with Super.
1

Create the employee.cfc file with the following content:







2

Create the manager.cfc file with the following content:






ADOBE COLDFUSION 8 184
ColdFusion Developer’s Guide



3

Create the president.cfc file with the following content:







4 Create the payday.cfm file with the following content, and save it in the same directory as the components that
you created in the previous steps:





An employee earns #empObj.getPaid()#.

A manager earns #mgrObj.getPaid()#.

The president earns #prezObj.getPaid()#.



In this example, each getPaid method in a child component invoked the getPaid method of its parent component.
The child’s getPaid method then used the salary returned by the parent’s getPaid method to calculate the appropriate amount.
Included pages can use the Super keyword.
Note: The Super keyword supports only one level of inheritance. If you use multiple levels of inheritance, you can only
use the Super keyword to access the current component’s immediate parent. The example in this section illustrates
handling this limitation by invoking methods in a chain.
Using component packages

Components stored in the same directory are members of a component package. Component packages help prevent
naming conflicts, and facilitate easy component deployment; for example:

• ColdFusion searches the current directory first for a CFC. If you put two components in a single directory as a
package, and one component refers to the other with only the component name, not a qualified path, ColdFusion
always searches the package directory first for the component. As a result, if you structure each application’s components into a package, your applications can use the same component names without sharing the component code.
• If you use the access="package" attribute in a method’s cffunction tag, access to the method is limited to
components in the same package. Components in other packages cannot use this method, even if they specify it with
a fully qualified component name. For more information on access security, see “Using access security” on page 185.
Invoke a packaged component method with the cfinvoke tag
1 In your web root directory, create a directory named appResources.
2

In the appResources directory, create a directory named components.

Copy the tellTime2.cfc file you created in “Invoking methods of a CFC instance” on page 172 and the
getUTCTime.cfm file that you created in “Putting executable code in a separate file” on page 162 to the components
directory.

3

4

Create the timeDisplay.cfm file with the following content and save it in your web root directory:


ADOBE COLDFUSION 8 185
ColdFusion Developer’s Guide






Time Display Page

Server's Local Time: #localTime#

Calculated UTC Time: #UTCTime#


You use dot syntax to navigate directory structures. Place the directory name before the component name.
5

Browse the timeDisplay.cfm file in your browser.

The following example shows a CFScript invocation:

helloCFC = createObject("component", "appResources.components.catQuery");
helloCFC.getSaleItems();


The following example shows a URL invocation:
http://localhost/appResources/components/catQuery.cfc?method=getSalesItems

Using CFCs in persistent scopes

You can put a CFC instance in the Session or Application scope. This way, the component properties continue to
exist while the scope persists. For example, you might want to use a CFC for a shopping cart application, where the
shopping cart contents must persist for the length of the user’s session. If you put the shopping cart CFC in the
Session scope, you can use component properties to store the cart contents. For example, the following line creates
an instance of the shoppingCart component in the Session scope:


Code that manipulates persistent scope CFC properties must be locked, just as all other code that manipulates
persistent scope properties must be locked. Therefore, you must lock both of the following types of application code:

•

Code that directly manipulates properties of a persistent scope CFC instance

•

Code that calls methods of a persistent scope CFC instance that manipulate properties of the instance

If you put multiple CFC instances in a single persistent scope, you can create a named lock for each CFC instance.
For more information on locking, see “Using Persistent Data and Locking” on page 272.
Note: Session scope CFCs cannot be serialized, so you cannot use them with clustered sessions; for example, if you want
to support session failover among servers.

Building secure ColdFusion components
To restrict access to component methods, ColdFusion components use access, role-based, or programmatic security.
Using access security

CFC access security lets you limit the code that can access the components. You specify the access to a CFC method
by specifying the cffunction access attribute, as follows:

ADOBE COLDFUSION 8 186
ColdFusion Developer’s Guide

Type

Description

private

Available only to the component that declares the method and any components that extend the component in
which it is defined. This usage is similar to the Java protected keyword, not the Java private keyword.

package

Available only to the component that declares the method, components that extend the component, or any other
components in the package. A package consists of all components defined in a single directory. For more information on packages, see “Using component packages” on page 184.

public

Available to any locally executing ColdFusion page or component method.

remote

Available to a locally or remotely executing ColdFusion page or component method, or to a local or remote client
through a URL, form submission, Flash Remoting, or as a web service.

Using role-based security

If you specify a roles attribute in a cffunction tag, only users who are logged in with one of the specified roles can
execute the method. When a user tries to invoke a method that he or she is not authorized to invoke, an exception is
returned.
The following example creates a component method that deletes files:







In the example, the cffunction tag includes the roles attribute to specify the user roles allowed to access it. In this
example, only users in the role admin and manager can access the function. Notice that multiple roles are delimited
by a comma.
For information on ColdFusion security, including the cflogin tag and role-based security in ColdFusion, see
“Securing Applications” on page 311.
Using programmatic security

You can implement your own security within a method to protect resources. For example you can use the
ColdFusion function IsUserInAnyRole to determine if a user is in particular role, as the following example shows:


… do stuff allowed for admin

… do stuff allowed for user

unauthorized access




Using introspection to get information about components
ColdFusion provides several ways for you to get information about components:

•

Request a component page from the browser

•

Use the ColdFusion component browser

•

Use the Adobe® Dreamweaver® Components panel

ADOBE COLDFUSION 8 187
ColdFusion Developer’s Guide

•

Use the GetMetaData function

Development teams can use the information about components as up-to-date API reference information.
Note: For information about how to include documentation in CFCs for display by using introspection, see
“Documenting CFCs” on page 168.
Requesting a component page from the browser

When you access a CFC directly with a web browser without specifying a component method, the following chain
of events occurs:
1 The request is redirected to the cfcexplorer.cfc file, which is located in the cf_root/wwwroot/CFIDE/componentutils directory.
2

The cfcexplorer component prompts users for the ColdFusion RDS or Administrator password, if necessary.

3

The cfcexplorer component renders an HTML description and returns it to the browser.

Using the ColdFusion component browser

You can also browse the components available in ColdFusion using the component browser, which is located at
cf_root/wwwroot/CFIDE/componentutils/componentdoc.cfm.
The browser has three panes:

•

The upper-left pane lists all CFC packages that ColdFusion can access, and has all components and refresh links.

• The lower-left pane lists CFC component names. When the browser first appears, or when you click the all
components link in the upper pane, the lower pane lists all available components. If you click a package name in the
upper left pane, the lower pane lists only the components in the package.
• The right pane initially lists the paths of all components. When you click a component name in the lower-left
pane, the right pane shows the ColdFusion introspection page, as described in “Requesting a component page from
the browser” on page 187.
Note: When RDS user names are enabled, the component browser accepts the root administrator user (admin) with
either the administrator or RDS single password.
Using the Dreamweaver Components panel

The Dreamweaver Components panel lists all available components, including their methods, method parameters,
and properties. The panel’s context menu includes options to create a new component, edit the selected component,
insert code to invoke the component, or show detailed information on the component or component element. The
Get description option shows the ColdFusion introspection page, as described in “Requesting a component page
from the browser” on page 187. For more information on viewing and editing CFCs in Dreamweaver, see the Dreamweaver online Help.
Using the GetMetaData function

The CFML GetMetaData function returns a structure that contains all the metadata of a CFC instance. This
structure contains substantially more data about the CFC than the cfdump tag shows, and includes the following
information:

•

All attributes to the component tag, including any metadata-only attributes, plus the component path.

• An array of structures that contains complete information on each method (function) in the component. This
information describes all attributes, including metadata-only function and parameter attributes.

ADOBE COLDFUSION 8 188
ColdFusion Developer’s Guide

•

Within each function structure, a Parameters element that contains an array of parameters specified by

cfargument tags. Information on each parameter includes any metadata-only attributes.

•

Information about any properties that are specified using the cfproperty tag.

Display metadata for a CFC
1 Create the tellAboutCfcs.cfm file in the same directory as the telltime.cfc file, with the following code:








2

View the tellAboutCfcs.cfm file in a browser.

For information on how to specify CFC metadata, including how to use component tags and how to specify
metadata-only attributes, see “Documenting CFCs” on page 168.

ColdFusion component example
A number of code examples in the ColdFusion Developer’s Guide reuse code, particularly queries. To illustrate the
advantages of CFCs, these examples invoke the appropriate method in the CFC that appears in the following
example. Although Adobe recommends using CFCs to create structured, reusable code, some code examples in this
manual contain queries within a CFML page, rather than invoking a CFC, in order to clearly illustrate a particular
element of ColdFusion.




SELECT * FROM Employee





SELECT Firstname, Lastname, Salary, Contract
FROM Employee





SELECT FirstName || ' ' || LastName AS FullName
FROM Employee



ADOBE COLDFUSION 8 189
ColdFusion Developer’s Guide




SELECT Dept_ID, FirstName || ' ' || LastName
AS FullName
FROM Employee
ORDER BY Dept_ID





SELECT * FROM Employee
WHERE Emp_ID = #URL.Emp_ID#





DELETE FROM Employee
WHERE Emp_ID = #Form.Emp_ID#





SELECT DISTINCT Location
FROM Departmt




190

Chapter 11: Creating and Using Custom
CFML Tags
You can extend CFML by creating and using custom CFML tags that encapsulate common code.
Contents

Creating custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Passing data to custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Managing custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Executing custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Nesting custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Creating custom tags
Custom tags let you extend CFML by adding your own tags to the ones supplied with ColdFusion. After you define
a custom tag, you can use it on a ColdFusion page just as you would any of the standard CFML tags, such as cfquery
and cfoutput.
You use custom tags to encapsulate your application logic so that it can be referenced from any ColdFusion page.
Custom tags allow for rapid application development and code reuse while offering off-the-shelf solutions for many
programming chores.
For example, you might create a custom tag, named cf_happybirthday, to generate a birthday message. You could
then use that tag in a ColdFusion page, as follows:


When ColdFusion processes the page containing this tag, it could output the message:
December 5, 1987 is Ted Cantor’s Birthday.
Please wish him well.

A custom tag can also have a body and end tag, for example:

 Happy Birthday Ellen!
 May you have many more!


This tag could output the message:
June 8, 1993 is Ellen Smith’s Birthday.
Happy Birthday Ellen!
May you have many more!

For more information about using end tags, see “Handling end tags” on page 198.

ADOBE COLDFUSION 8 191
ColdFusion Developer’s Guide

Creating and calling custom tags
You implement a custom tag with a single ColdFusion page. You then call the custom tag from a ColdFusion page
by inserting the prefix cf_ before the page’s filename. The page that references the custom tag is referred to as the
calling page.
1

Create a ColdFusion page, the custom tag page, that shows the current date:
#DateFormat(Now())#

2

Save the file as date.cfm.

3

Create a ColdFusion page, the calling page, with the following content:










4

Save the file as callingdate.cfm.

5

View callingdate.cfm in your browser.
This custom tag returns the current date in the format DD-MMM-YY.

As you can see from this example, creating a custom tag in CFML is no different from writing any ColdFusion page.
You can use all CFML constructs, as well as HTML. You are free to use any naming convention that fits your development practice. Unique descriptive names make it easy for you and others to find the right tag.
Note: Although tag names in ColdFusion pages are case-insensitive, custom tag filenames must be lowercase on UNIX.
Storing custom tag pages

You must store custom tag pages in any one of the following:

•

The same directory as the calling page

•

The cfusion\CustomTags directory

•

A subdirectory of the cfusion\CustomTags directory

•

A directory that you specify in the ColdFusion Administrator

To share a custom tag among applications in multiple directories, place it in the cfusion\CustomTags directory. You
can create subdirectories to organize custom tags. ColdFusion searches recursively for the Custom Tags directory,
stepping down through any existing subdirectories until the custom tag is found.
You might have a situation where you have multiple custom tags with the same name. To guarantee which tag
ColdFusion calls, copy it to the same directory as the calling page. Or, use the cfmodule tag with the template
attribute to specify the absolute path to the custom tag. For more information on cfmodule, see the next section.
Calling custom tags with the cfmodule tag

You can also use the cfmodule tag to call custom tags if you want to specify the location of the custom tag page. The
cfmodule tag is useful if you are concerned about possible name conflicts when invoking a custom tag, or if the
application must use a variable to dynamically call a custom tag at runtime.

ADOBE COLDFUSION 8 192
ColdFusion Developer’s Guide

You must use either a template or name attribute in the tag, but you cannot use both. The following table describes
the basic cfmodule attributes:
Attribute

Description

template

Required if the name attribute is not used. Same as the template attribute in cfinclude. This attribute:

•

Specifies a path relative to the directory of the calling page.

•

If the path value is prefixed with "/", ColdFusion searches directories explicitly mapped in the ColdFusion
Administrator for the included file.
Example:  identifies a custom tag file in the parent directory.
name

Required if the template attribute is not used. Use period-separated names to uniquely identify a subdirectory
under the CustomTags root directory.
Example:  identifies the file GetUserOptions.cfm in the CustomTags\MyApp directory under the ColdFusion root directory.

attributes

The custom tag’s attributes.

For example, the following code specifies to execute the custom tag defined by the mytag.cfm page in the parent
directory of the calling page:


For more information on using the cfmodule tag, see the CFML Reference.
Calling custom tags with the cfimport tag

You can use the cfimport tag to import custom tags from a directory as a tag library. The following example imports
the tags from the directory myCustomTags:


Once imported, you call the custom tags using the prefix that you set when importing, as the following example
shows:


where customTagName corresponds to a ColdFusion application page named customTagName.cfm. If the tag takes
attributes, you include them in the call:


You can also include end tags when calling your custom tags, as the following example shows:

...


ColdFusion calls the custom tag page twice for a tag that includes an end tag: once for the start tag and once for the
end tag. For more information on how ColdFusion handles end tags, and how to write your custom tags to handle
them, see “Handling end tags” on page 198.
One of the advantages to using the cfimport tag is that you can define a directory structure for your custom tags to
organize them by category. For example, you can put all security tags in one directory, and all interface tags in
another. You then import the tags from each directory and give them a different prefix:


...


ADOBE COLDFUSION 8 193
ColdFusion Developer’s Guide

...

...

Reading your code becomes easier because you can identify the location of your custom tags from the prefix.

Securing custom tags
The ColdFusion security framework enables you to selectively restrict access to individual tag files and tag directories. This can be an important safeguard in team development. For details, see Configuring and Administering
ColdFusion.

Accessing existing custom tags
Before creating a custom tag in CFML, you should review the free and commercial custom tags available on the
Adobe developer’s exchange (www.www.adobe.com/devnet/coldfusion/index.html).You might find a tag that does
what you want.
Tags are grouped in several broad categories and are downloadable as freeware, shareware, or commercial software.
You can view each tag’s syntax and usage information. The gallery contains a wealth of background information on
custom tags and an online discussion forum for tag topics.
Tag names with the cf_ preface are CFML custom tags; those with the cfx_ preface are ColdFusion extensions
written in C++. For more information about the CFX tags, see “Building Custom CFXAPI Tags” on page 205.
If you do not find a tag that meets your specific needs, you can create your own custom tags in CFML.

Passing data to custom tags
To make your custom tags flexible, you often pass data to them for processing. To do this, you write custom tags that
take tag attributes and other data as input from a calling page.

Passing values to and from custom tags
Because custom tags are individual ColdFusion pages, variables and other data are not automatically shared between
a custom tag and the calling page. To pass data from the calling page to the custom tag, you can specify attribute
name-value pairs in the custom tag, just as you do for normal HTML and CFML tags.
For example, to pass the value of the NameYouEntered variable to the cf_getmd tag, you can call the custom tag as
follows:


To pass multiple attributes to a custom tag, separate them with a space in the tag as follows:


In the custom tag, you use the Attributes scope to access attributes passed to the tag. Therefore, in the getmd.cfm
page, you refer to the passed attribute as Attributes.Name. The mytag.cfm custom tag page refers to the passed
attributes as Attributes.Firstname and Attributes.Lastname.

ADOBE COLDFUSION 8 194
ColdFusion Developer’s Guide

The custom tag page can also access variables set in the calling page by prefixing the calling page’s local variable with
Caller. However, this is not the best way to pass information to a custom tag, because each calling page would be
required to create variables with the names required by the custom tag. You can create more flexible custom tags by
passing parameters using attributes.
Variables created within a custom tag are deleted when the processing of the tag terminates. Therefore, if you want
to pass information back to the calling page, you must write that information back to the Caller scope of the calling
page. You cannot access the custom tag’s variables outside the custom tag itself.
For example, use the following code in the getmd.cfm page to set the variable Doctor on the calling page:


If the variable Doctor does not exist in the calling page, this statement creates it. If the variable exists, the custom tag
overwrites it.
The following image shows the relationship between the variables on the calling page and the custom tag:

One common technique used by custom tags is for the custom tag to take as input an attribute that contains the name
of the variable to use to pass back results. For example, the calling page passes returnHere as the name of the variable
to use to pass back results:


In mytag.cfm, the custom tag passes back its results using the following code:


Be careful not to overwrite variables in the calling page from the custom tag. You should adopt a naming convention
to minimize the chance of overwriting variables. For example, prefix the returned variable with customtagname_,
where customtagname is the name of the custom tag.
Note: Data that pertains to the HTTP request or to the current application is visible in the custom tag page. This includes
the variables in the Form, Url, Cgi, Request, Cookies, Server, Application, Session, and Client scopes.

Using tag attributes summary
Custom tag attribute values are passed from the calling page to the custom tag page as name-value pairs. CFML
custom tags support required and optional attributes. Custom tag attributes conform to the following CFML coding
standards:

•

ColdFusion passes any attributes in the Attributes scope.

• Use the Attributes.attribute_name syntax when referring to passed attributes to distinguish them from
custom tag page local variables.
•

Attributes are case-insensitive.

•

Attributes can be listed in any order within a tag.

•

Attribute name-value pairs for a tag must be separated by a space in the tag invocation.

ADOBE COLDFUSION 8 195
ColdFusion Developer’s Guide

•

Passed values that contain spaces must be enclosed in double-quotation marks.

• Use the cfparam tag with a default attribute at the top of a custom tag to test for and assign defaults for optional
attributes that are passed from a calling page. For example:



Use the cfparam tag or a cfif tag with an IsDefined function at the top of a custom tag to test for required
attributes that must be passed from a calling page; for example, the following code issues an abort if the user does
not specify the Name attribute to the custom tag:

1





Custom tag example with attributes
The following example creates a custom tag that uses an attribute that is passed to it to set the value of a variable
called Doctor on the calling page.
1

Create a ColdFusion page (the calling page) with the following content:










Before you leave this page, you're #Variables.NameYouEntered#.







You are now #Variables.Doctor#.





2

Save the page as callingpage.cfm.

3

Create another page (the custom tag) with the following content:





ADOBE COLDFUSION 8 196
ColdFusion Developer’s Guide

4

Save the page as getmd.cfm.

5

Open the file callingpage.cfm in your browser.

The calling page uses the getmd custom tag and displays the results.
Reviewing the code

The following table describes the code and its function:
Code

Description



In the calling page, create a variable NameYouEntered and
assign it the value Smith.


Before you leave this page, you're
#Variables.NameYouEntered#.



In the calling page, display the value of the NameYouEntered
variable before calling the custom tag.



In the calling page, call the getmd custom tag and pass it the
Name attribute whose value is the value of the local variable
NameYouEntered.



The custom tag page normally gets the Name variable in the
Attributes scope from the calling page. Assign it the value Who if
the calling page did not pass an attribute.



In the custom tag page, create a variable called Doctor in the
Caller scope so it exists in the calling page as a local variable.
Set its value to the concatenation of the string "Doctor" and the
value of the Attributes.Name variable.


You are now #Variables.Doctor#.



In the calling page, display the value of the Doctor variable
returned by the custom tag page. (This example uses the Variables scope prefix to emphasize the fact that the variable is
returned as a local variable.)

Passing custom tag attributes by using CFML structures
You can use the reserved attribute attributeCollection to pass attributes to custom tags using a structure. The
attributeCollection attribute must reference a structure containing the attribute names as the keys and the
attribute values as the values. You can freely mix attributeCollection with other attributes when you call a
custom tag.
The key-value pairs in the structure specified by the attributeCollection attribute get copied into the custom tag
page’s Attributes scope. This has the same effect as specifying the attributeCollection entries as individual
attributes when you call the custom tag. The custom tag page refers to the attributes passed using
attributeCollection the same way as it does other attributes; for example, as Attributes.CustomerName or
Attributes.Department_number.
Note: You can combine tag attributes and the attributeCollection attribute when you use a custom tag directly or
when you use the cfmodule tag to invoke a custom tag. If you pass an attribute with the same name both explicitly and
in the attributeCollection structure, ColdFusion passes only the tag attribute to the custom tag and ignores the
corresponding attribute from the attribute collection. You cannot combine tag attributes and the
attributeCollection attribute when you use standard (built in) ColdFusion tags.
Custom tag processing reserves the attributeCollection attribute to refer to the structure holding a collection of
custom tag attributes. If attributeCollection does not refer to such a collection, ColdFusion generates a template
exception.

ADOBE COLDFUSION 8 197
ColdFusion Developer’s Guide

The following example uses an attributeCollection attribute to pass two of four attributes:





If testtwo.cfm contains the following code:
---custom tag ---

#attributes.a# #attributes.x# #attributes.y#
#attributes.foo#

--- end custom tag ---

its output is the following statement:
---custom tag --blab -X- -Y- 16
--- end custom tag ---

One use for attributeCollection is to pass the entire Attributes scope of one custom tag to another. This often
happens when you have one custom tag that calls a second custom tag and you want to pass all attributes from the
first tag to the second.
For example, you call a custom tag with the following code:


To pass all the attributes of the first custom tag to the second, you include the following statement in first.cfm:


Within the body of second.cfm, you reference the parameters passed to it as follows:
#attributes.attr1#
#attributes.attr2#

Managing custom tags
If you deploy custom tags in a multideveloper environment or distribute your tags publicly, you can use the advanced
security and template encoding capabilities of ColdFusion.
The ColdFusion security framework enables you to selectively restrict access to individual tags or to tag directories.
This can be an important safeguard in team development. For more information, see “Securing Applications” on
page 311.
You can use the command-line utility cfcompile to precompile your custom tag files into Java class files or byte
code. For more information, see “Using the cfcompile utility” on page 77 in Configuring and Administering
ColdFusion..

Executing custom tags
ColdFusion provides techniques for executing custom tags, including handling end tags and processing body text.

ADOBE COLDFUSION 8 198
ColdFusion Developer’s Guide

Accessing tag instance data
When a custom tag page executes, ColdFusion keeps data related to the tag instance in the thisTag structure. You
can access the thisTag structure from within your custom tag to control processing of the tag. The behavior is
similar to the File tag-specific variable (sometimes called the File scope).
ColdFusion generates the variables in the following table and writes them to the thisTag structure:
Variable

Description

ExecutionMode

Contains the execution mode of the custom tag. Valid values are "start", "end", and "inactive".

HasEndTag

Distinguishes between custom tags that are called with and without end tags. Used for code validation. If
the user specifies an end tag, HasEndTag is set to true; otherwise, it is set to false.

GeneratedContent

Specifies the content that is generated by the tag. This includes anything in the body of the tag, including
the results of any active content, such as ColdFusion variables and functions. You can process this content as
a variable.

AssocAttribs

Contains the attributes of all nested tags if you use cfassociate to make them available to the parent tags.
For more information, see “High-level data exchange” on page 202.

The following example accesses the ExecutionMode variable of the thisTag structure from within a custom tag:


Handling end tags
The preceding examples of custom tags in this topic all reference a custom tag by using just a start tag:


In this case, ColdFusion calls the custom tag page date.cfm to process the tag.
However, you can create custom tags that have both a start and an end tag. For example, the following tag has both
a start and an end tag:

...


ColdFusion calls the custom tag page date.cfm twice for a tag that includes an end tag: once for the start tag and once
for the end tag. As part of the date.cfm page, you can determine if the call is for the start or end tag, and perform the
appropriate processing.
ColdFusion also calls the custom tag page twice if you use the shorthand form of an end tag:


You can also call a custom tag using the cfmodule tag, as shown in the following example:

...


If you specify an end tag to cfmodule, then ColdFusion calls your custom tag as if it had both a start and an end tag.
Determining if an end tag is specified

You can write a custom tag that requires users to include an end tag. If a tag must have an end tag provided, you can
use thisTag.HasEndTag in the custom tag page to verify that the user included the end tag.
For example, in date.cfm, you could include the following code to determine whether the end tag is specified:

ADOBE COLDFUSION 8 199
ColdFusion Developer’s Guide





Determining the tag execution mode

The variable thisTag.ExecutionMode contains the mode of invocation of a custom tag page. The variable has one
of the following values:

•

Start: Mode for processing the start tag.

•

End: Mode for processing the end tag.

• Inactive: Mode when the custom tag uses nested tags. For more information, see “Nesting custom tags” on
page 201.
If an end tag is not explicitly provided, ColdFusion invokes the custom tag page only once, in Start mode.
A custom tag page named bold.cfm that makes text bold could be written as follows:








You then use this tag to convert the text to bold:
This is bold text

You can also use cfswitch to determine the execution mode of a custom tag:








Considerations when using end tags

How you code your custom tag to divide processing between the start tag and end tag depends greatly on the
function of the tag. However, use the following rules to help you make your decisions:

• Use the start tag to validate input attributes, set default values, and validate the presence of the end tag if it is
required by the custom tag.
• Use the end tag to perform the actual processing of the tag, including any body text passed to the tag between
the start and end tags. For more information on body text, see “Processing body text” on page 199.
•

Perform output in either the start or end tag; do not divide it between the two tags.

Processing body text
Body text is any text that you include between the start and end tags when you call a custom tag, for example:

 Happy Birthday Ellen!
 May you have many more!

ADOBE COLDFUSION 8 200
ColdFusion Developer’s Guide



In this example, the two lines of code after the start tag are the body text.
You can access the body text within the custom tag using the thisTag.GeneratedContent variable. The variable
contains all body text passed to the tag. You can modify this text during processing of the tag. The contents of the
thisTag.GeneratedContent variable are returned to the browser as part of the tag’s output.
The thisTag.GeneratedContent variable is always empty during the processing of a start tag. Any output
generated during start tag processing is not considered part of the tag’s generated content.
A custom tag can access and modify the generated content of any of its instances using the
thisTag.GeneratedContent variable. In this context, the term generated content means the results of processing
the body of a custom tag. This includes all text and HTML code in the body, the results of evaluating ColdFusion
variables, expressions, and functions, and the results generated by descendant tags. Any changes to the value of this
variable result in changes to the generated content.
As an example, consider a tag that comments out the HTML generated by its descendants. Its implementation could
look like this:




Terminating tag execution
Within a custom tag, you typically perform error checking and parameter validation. As part of those checks, you
can choose to abort the tag, using cfabort, if a required attribute is not specified or other severe error is detected.
The cfexit tag also terminates execution of a custom tag. However, the cfexit tag is designed to give you more
flexibility when coding custom tags than cfabort. The cfexit tag’s method attribute specifies where execution
continues. The cfexit tag can specify that processing continues from the first child of the tag or continues immediately after the end tag marker.
You can also use the method attribute to specify that the tag body executes again. This enables custom tags to act as
high-level iterators, emulating cfloop behavior.
The following table summarizes cfexit behavior:
Method attribute value

Location of cfexit call

Behavior

ExitTag (default)

Base page

Acts like cfabort

ExecutionMode=start

Continue after end tag

ExecutionMode=end

Continue after end tag

Base page

Acts like cfabort

ExecutionMode=start

Continue from first child in body

ExecutionMode=end

Continue after end tag

Base page

Error

ExecutionMode=start

Error

ExecutionMode=end

Continue from first child in body

ExitTemplate

Loop

ADOBE COLDFUSION 8 201
ColdFusion Developer’s Guide

Nesting custom tags
A custom tag can call other custom tags from within its body text, thereby nesting tags. ColdFusion uses nested tags
such as cfgraph and cfgraphdata, cfhttp and cfhttpparam, and cftree and cftreeitem. The ability to nest
tags allows you to provide similar functionality.
The following example shows a cftreeitem tag nested within a cftree tag:




The calling tag is known as an ancestor, parent, or base tag; the tags that ancestor tags call are known as descendant,
child, or sub tags. Together, the ancestor and all descendant tags are called collaborating tags.
In order to nest tags, the parent tag must have a closing tag.
The following table lists the terms that describe the relationships between nested tags:
Calling tag

Tag nested within the calling tag

Description

Ancestor

Descendant

An ancestor is any tag that contains other tags between its start and end
tags. A descendant is any tag called by a tag.

Parent

Child

Parent and child are synonyms for ancestor and descendant.

Base tag

Sub tag

A base tag is an ancestor that you explicitly associate with a descendant,
called a sub tag, with cfassociate.

You can create multiple levels of nested tags. In this case, the sub tag becomes the base tag for its own sub tags. Any
tag with an end tag present can be an ancestor to another tag.
Nested custom tags operate through three modes of processing, which are exposed to the base tags through the
variable thisTag.ExecutionMode.

Passing data between nested custom tags
A key custom tag feature is for collaborating custom tags to exchange complex data without user intervention, while
encapsulating each tag’s implementation so that others cannot see it.
When you use nested tags, you must address the following issues:

•

What data should be accessible?

•

Which tags can communicate to which tags?

•

How are the source and targets of the data exchange identified?

•

What CFML mechanism is used for the data exchange?

What data is accessible?

To enable developers to obtain maximum productivity in an environment with few restrictions, CFML custom tags
can expose all their data to collaborating tags.

ADOBE COLDFUSION 8 202
ColdFusion Developer’s Guide

When you develop custom tags, you should document all variables that collaborating tags can access and/or modify.
When your custom tags collaborate with other custom tags, you should make sure that they do not modify any
undocumented data.
To preserve encapsulation, put all tag data access and modification operations into custom tags. For example, rather
than documenting that the variable MyQueryResults in a tag's implementation holds a query result and expecting
users to manipulate MyQueryResults directly, create a nested custom tag that manipulates MyQueryResult. This
protects the users of the custom tag from changes in the tag's implementation.

Variable scopes and special variables
Use the Request scope for variables in nested tags. The Request scope is available to the base page, all pages it
includes, all custom tag pages it calls, and all custom tag pages called by the included pages and custom tag pages.
Collaborating custom tags that are not nested in a single tag can exchange data using the request structure. The
Request scope is represented as a structure named Request.
Where is data accessible?

Two custom tags can be related in a variety of ways in a page. Ancestor and descendant relationships are important
because they relate to the order of tag nesting.
A tag’s descendants are inactive while the page is executed; that is, the descendent tags have no instance data. A tag,
therefore, can only access data from its ancestors, not its descendants. Ancestor data is available from the current
page and from the whole runtime tag context stack. The tag context stack is the path from the current tag element
up the hierarchy of nested tags, including those in included pages and custom tag references, to the start of the base
page for the request. Both cfinclude tags and custom tags appear on the tag context stack.

High-level data exchange
Although the ability to create nested custom tags is a tremendous productivity gain, keeping track of complex nested
tag hierarchies can become a chore. The cfassociate tag lets the parent know what the children are up to. By
adding this tag to a sub tag, you enable communication of its attributes to the base tag.
In addition, there are many cases in which descendant tags are used only as a means for data validation and exchange
with an ancestor tag, such as cfhttp/cfhttpparam and cftree/cftreeitem. You can use the cfassociate tag to
encapsulate this processing.
The cfassociate tag has the following format:


The baseTag attribute specifies the name of the base tag that gets access to this tag’s attributes. The dataCollection
attribute specifies the name of the structure in which the base tag stores the sub-tag data. Its default value is AssocAttribs. You only need to specify a dataCollection attribute if the base tag can have more than one type of subtag. It
is convenient for keeping separate collections of attributes, one per tag type.
Note: If the custom tag requires an end tag, the code processing the structure referenced by the dataCollection
attribute must be part of end-tag code.
When cfassociate is encountered in a sub tag, the sub tag’s attributes are automatically saved in the base tag. The
attributes are in a structure appended to the end of an array whose name is thisTag.collectionName.
The cfassociate tag performs the following operations:



ADOBE COLDFUSION 8 203
ColdFusion Developer’s Guide










The code accessing sub-tag attributes in the base tag could look like the following:








Ancestor data access

The ancestor’s data is represented by a structure object that contains all the ancestor’s data.
The following functions provide access to ancestral data:

• GetBaseTagList(): Returns a comma-delimited list of uppercase ancestor tag names, as a string. The first list
element is the current tag, the next element is the parent tag name if the current tag is a nested tag. If the function is
called for a top-level tag, it returns an empty string.
• GetBaseTagData(TagName, InstanceNumber=1): Returns an object that contains all the variables (not just the
local variables) of the nth ancestor with a given name. By default, the closest ancestor is returned. If there is no
ancestor by the given name, or if the ancestor does not expose any data (such as cfif), an exception is thrown.
Example: ancestor data access

This example creates two custom tags and a simple page that calls each of the custom tags. The first custom tag calls
the second. The second tag reports on its status and provides information about its ancestors.
Create the calling page
1 Create a ColdFusion page (the calling page) with the following content:
Call cf_nesttag1 which calls cf_nesttag2



Call cf_nesttag2 directly




2

Save the page as nesttest.cfm.

Create the first custom tag page
1 Create a ColdFusion page with the following content:


2

Save the page as nesttag1.cfm.

ADOBE COLDFUSION 8 204
ColdFusion Developer’s Guide

Create the second custom tag page
1 Create a ColdFusion page with the following content:





I'm custom tag #ListGetAt(ancestorlist,1)#


Ancestorlist entry #loopcount# n is #ListGetAt(ancestorlist,loopcount)#















I'm running in the context of a custom tag named #inCustomTag#.





I'm located inside the

custom tag code either because it is in its start or end execution mode.

body of the tag




I'm not nested inside any custom tags. :^( 




2

Save the page as nesttag2.cfm.

3

Open the file nesttest.cfm in your browser.

205

Chapter 12: Building Custom CFXAPI
Tags
Sometimes, the best approach to application development is to develop elements of your application by building
executables to run with ColdFusion. Perhaps the application requirements go beyond what is currently feasible in
CFML. Perhaps you can improve application performance for certain types of processing. Or, you have existing code
that already solves an application problem and you want to incorporate it into your ColdFusion application.
To meet these types of requirements, you can use the ColdFusion Extension Application Programming Interface
(CFX API) to develop custom ColdFusion tags based on Java or C++.
Contents

What are CFX tags? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Before you begin developing CFX tags in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Writing a Java CFX tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
ZipBrowser example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Approaches to debugging Java CFX tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Developing CFX tags in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

What are CFX tags?
ColdFusion Extension (CFX) tags are custom tags written against the ColdFusion Extension Application
Programming Interface. Generally, you create a CFX tag if you want to do something that is not possible in CFML,
or if you want to improve the performance of a repetitive task.
One common use of CFX tags is to incorporate existing application functionality into a ColdFusion application. That
means if you already have the code available, CFX tags make it easy to use it in your application.
CFX tags can do the following:

•

Handle any number of custom attributes.

•

Use and manipulate ColdFusion queries for custom formatting.

•

Generate ColdFusion queries for interfacing with non-ODBC based information sources.

•

Dynamically generate HTML to be returned to the client.

•

Set variables within the ColdFusion application page from which they are called.

•

Throw exceptions that result in standard ColdFusion error messages.

You can build CFX tags using C++ or Java.
Note: ColdFusion provides several different techniques to create reusable code, including custom tags. For information
on all of these techniques, see “Creating ColdFusion Elements” on page 126.

ADOBE COLDFUSION 8 206
ColdFusion Developer’s Guide

Before you begin developing CFX tags in Java
Before you begin developing CFX tags in Java, you must configure your Java development environment. Also, it
might be helpful to review the examples in this topic before you create CFX tags.

Sample Java CFX tags
Before you begin developing a CFX tag in Java, you might want to study sample CFX tags. You can find the Java
source files for the examples for Windows in the cfx\java\distrib\examples subdirectory of the main installation
directory. In UNIX systems, the files are located in the cfx/java/examples directory. The following table describes the
example tags:
Example

Action

Demonstrates

HelloColdFusion

Prints a personalized greeting.

The minimal implementation required to create a CFX tag.

ZipBrowser

Retrieves the contents of a ZIP archive.

How to generate a ColdFusion query and return it to the calling
page.

ServerDateTime

Retrieves the date and time from a
network server.

Attribute validation, using numeric attributes, and setting variables
within the calling page.

OutputQuery

Returns a ColdFusion query in an HTML
table.

How to handle a ColdFusion query as input, throw exceptions, and
generate dynamic output.

HelloWorldGraphic

Generates a “Hello World!” graphic in
JPEG format.

How to dynamically create and return graphics from a Java CFX tag.

Setting up your development environment to develop CFX tags in Java
You can use a wide range of Java development environments, including the Java Development Kit (JDK) from Sun,
to build Java CFX tags. You can download the JDK from Sun http://java.sun.com/j2se.
Adobe recommends that you use one of the commercial Java IDEs, so you have an integrated environment for development, debugging, and project management.
Configuring the classpath

To configure your development environment to build Java CFX tags, you must ensure that the supporting classes are
visible to your Java compiler. These classes are located in the cfx.jar archive, located in one of the following directories:
Server configuration: cf_root/wwwroot/WEB-INF/lib
J2EE configuration: cf_webapp_root/WEB-INF/lib
Consult your Java development tool documentation to determine how to configure the compiler classpath for your
particular environment.
The cfx.jar archive contains the classes in the com.allaire.cfx package, which are required for developing and
deploying Java CFX tags.
When you create new Java CFX tags, you should compile them into the WEB-INF/classes directory. Doing this
simplifies your development, debugging, and testing processes.
After you finish with development and testing, you can deploy your Java CFX tag anywhere on the classpath visible
to ColdFusion.

ADOBE COLDFUSION 8 207
ColdFusion Developer’s Guide

Customizing and configuring Java
Use the ColdFusion Administrator > Server Settings > JVM and Java Settings page to customize your Java development environment by customizing the classpath and Java system properties, or by specifying an alternate JVM.
For more information, see the ColdFusion Administrator online Help.

Writing a Java CFX tag
To create a Java CFX tag, create a class that implements the Custom tag interface. This interface contains one
method, processRequest, which is passed Request and Response objects that are then used to do the work of the
tag.
The example in the following procedure creates a very simple Java CFX tag named cfx_MyHelloColdFusion that
writes a text string back to the calling page.
1

Create a source file in your editor with the following code:
import com.allaire.cfx.* ;
public class MyHelloColdFusion implements CustomTag {
public void processRequest( Request request, Response response )
throws Exception {
String strName = request.getAttribute( "NAME" ) ;
response.write( "Hello, " + strName ) ;
}
}

2

Save the file as MyHelloColdFusion.java in the WEB_INF/classes directory.

3 Compile the java source file into a class file using the Java compiler. If you are using the command-line tools
bundled with the JDK, use the following command line, which you execute from within the classes directory:
javac -classpath cf_root\WEB-INF\lib\cfx.jar MyHelloColdFusion.java

Note: The previous command works only if the Java compiler (javac.exe) is in your path. If it is not in your path,
specify the fully qualified path; for example, c:\jdk1.3.1_01\bin\javac in Windows or /usr/java/bin/javac in UNIX.
If you receive errors during compilation, check the source code to make sure you entered it correctly. If no errors
occur, you successfully wrote your first Java CFX tag.

Calling the CFX tag from a ColdFusion page
You call Java CFX tags from within ColdFusion pages by using the name of the CFX tag that is registered on the
ColdFusion Administrator CFX Tags page. This name should be the prefix cfx_ followed by the class name (without
the .class extension).
Register a Java CFX tag in the ColdFusion Administrator
1 In the ColdFusion Administrator, select Extensions > CFX Tags.
2

Click Register Java CFX.

3

Enter the tag name (for example, cfx_MyHelloColdFusion).

4

Enter the class name without the .class extension (for example, MyHelloColdFusion).

5

(Optional) Enter a description.

6

Click Submit.

ADOBE COLDFUSION 8 208
ColdFusion Developer’s Guide

You can now call the tag from a ColdFusion page.
Call a CFX tag from a ColdFusion page
1 Create a ColdFusion page (.cfm) in your editor with the following content to call the HelloColdFusion custom

tag:






2 Save the file in a directory configured to serve ColdFusion pages. For example, you can save the file as
C:\inetpub\wwwroot\cfdocs\testjavacfx.cfm in Windows or /home/docroot/cfdocs/testjavacfx.cfm in UNIX.
3 If you have not already done so, register the CFX tag in the ColdFusion Administrator (see “Registering CFX
tags” on page 215).
4

Request the page from your browser using the appropriate URL; for example:
http://localhost/cfdocs/testjavacfx.cfm

ColdFusion processes the page and returns a page that displays the text “Hello, Les.” If an error is returned instead,
check the source code to make sure you entered it correctly.
Delete a CFX tag in the ColdFusion Administrator
1 In the ColdFusion Administrator, select Extensions > CFX Tags.
2

For the tag to delete, click the Delete icon in the Controls column of the Registered CFX Tags list.

Processing requests
Implementing a Java CFX tag requires interaction with the Request and Response objects passed to the
processRequest method. In addition, CFX tags that need to work with ColdFusion queries also interface with the
Query object. The com.allaire.cfx package, located in the WEB-INF/lib/cfx.jar archive, contains the Request,
Response, and Query objects.
For a complete description of these object types, see “ColdFusion Java CFX Reference” on page 1436 in the CFML
Reference. For a complete example Java CFX tag that uses Request, Response, and Query objects, see “ZipBrowser
example” on page 210.
Request object

The Request object is passed to the processRequest method of the CustomTag interface. The following table lists
the methods of the Request object for retrieving attributes, including queries, passed to the tag and for reading
global tag settings:
Method

Description

attributeExists

Checks whether the attribute was passed to this tag.

debug

Checks whether the tag contains the debug attribute.

getAttribute

Retrieves the value of the passed attribute.

getAttributeList

Retrieves a list of all attributes passed to the tag.

ADOBE COLDFUSION 8 209
ColdFusion Developer’s Guide

Method

Description

getIntAttribute

Retrieves the value of the passed attribute as an integer.

getQuery

Retrieves the query that was passed to this tag, if any.

getSetting

Retrieves the value of a global custom tag setting.

For detailed reference information on each of these interfaces, see the CFML Reference.
Response object

The Response object is passed to the processRequest method of the CustomTag interface. The following table lists
the methods of the Response object for writing output, generating queries, and setting variables within the calling
page:
Method

Description

write

Outputs text to the calling page.

setVariable

Sets a variable in the calling page.

addQuery

Adds a query to the calling page.

writeDebug

Outputs text to the debug stream.

For detailed reference information on each of these interfaces, see the CFML Reference.
Query object

The Query object provides an interface for working with ColdFusion queries. The following table lists the methods
of the Query object for retrieving name, row count, and column names and methods for getting and setting data
elements:
Method

Description

getName

Retrieves the name of the query.

getRowCount

Retrieves the number of rows in the query.

getColumnIndex

Retrieves the index of a query column.

getColumns

Retrieves the names of the query columns.

getData

Retrieves a data element from the query.

addRow

Adds a new row to the query.

setData

Sets a data element within the query.

For detailed reference information on each of these interfaces, see CFML Reference.

Life cycle of Java CFX tags
A new instance of the Java CFX object is created for each invocation of the Java CFX tag. This means that it is safe to
store per-request instance data within the members of your CustomTag object. To store data and/or objects that are
accessible to all instances of your CustomTag, use static data members. If you do so, you must ensure that all accesses
to the data are thread-safe.

ADOBE COLDFUSION 8 210
ColdFusion Developer’s Guide

ZipBrowser example
The following example shows the use of the Request, Response, and Query objects. The example uses the
java.util.zip package to implement a Java CFX tag called cfx_ZipBrowser, which is a zip file browsing tag.
Note: The Java source file that implements cfx_ZipBrowser, ZipBrowser.java, is included in the
cf_root/cfx/java/distrib/examples (server configuration) or cf_webapp_root/WEBINF/cfusion/cfx/java/distrib/examples (J2EE configuration) directory. Compile ZipBrowser.java to implement the tag.
The tag’s archive attribute specifies the fully qualified path of the zip archive to browse. The tag’s name attribute
must specify the query to return to the calling page. The returned query contains three columns: Name, Size, and
Compressed.
For example, to query an archive at the path C:\logfiles.zip for its contents and output the results, you use the
following CFML code:


#Name#,#Size#, #Compressed# 



The Java implementation of ZipBrowser is as follows:
import
import
import
import

com.allaire.cfx.* ;
java.util.Hashtable ;
java.io.FileInputStream ;
java.util.zip.* ;

public class ZipBrowser implements CustomTag {
public void processRequest( Request request, Response response )
throws Exception {
// Validate that required attributes were passed.
if (!request.attributeExists( "ARCHIVE" ) || !request.attributeExists( "NAME" ) ) {
throw new Exception(
"Missing attribute (ARCHIVE and NAME are both " +
"required attributes for this tag)" ) ;
}
// get attribute values
String strArchive = request.getAttribute( "ARCHIVE" ) ;
String strName = request.getAttribute( "NAME" ) ;
// create a query to use for returning the list of files
String[] columns = { "Name", "Size", "Compressed" } ;
int iName = 1, iSize = 2, iCompressed = 3 ;
Query files = response.addQuery( strName, columns ) ;
// read the zip file and build a query from its contents
ZipInputStream zin = new ZipInputStream( new FileInputStream(strArchive) ) ;
ZipEntry entry ;
while ( ( entry = zin.getNextEntry()) != null ) {
// Add a row to the results.
int iRow = files.addRow() ;
// populate the row with
files.setData( iRow,
files.setData( iRow,
files.setData( iRow,

data
iName, entry.getName() ) ;
iSize, String.valueOf(entry.getSize()) ) ;
iCompressed,

ADOBE COLDFUSION 8 211
ColdFusion Developer’s Guide

String.valueOf(entry.getCompressedSize())) ;
// Finish up with entry.
zin.closeEntry() ;
}
// Close the archive.
zin.close() ;
}
}

Approaches to debugging Java CFX tags
Java CFX tags are not stand-alone applications that run in their own process, like typical Java applications. Rather,
they are created and invoked from an existing process. This makes debugging Java CFX tags more difficult, because
you cannot use an interactive debugger to debug Java classes that have been loaded by another process.
To overcome this limitation, you can use one of the following techniques:

•

Debug the CFX tag while it is running within ColdFusion by outputting the debug information as needed.

• Debug the CFX tag using a Java IDE (Integrated Development Environment) that supports debugging features,
such as setting breakpoints, stepping through your code, and displaying variable values.
• Debug the request in an interactive debugger offline from ColdFusion using the special com.allaire.cfx
debugging classes.

Outputting debugging information
Before using interactive debuggers became the norm, programmers typically debugged their programs by inserting
output statements in their programs to indicate information such as variable values and control paths taken. Often,
when a new platform emerges, this technique comes back into vogue while programmers wait for more sophisticated
debugging technology to develop for the platform.
If you need to debug a Java CFX tag while running against a live production server, this is the technique you must
use. In addition to outputting debugging text using the Response.write method, you can also call your Java CFX
tag with the debug="On" attribute. This attribute flags the CFX tag that the request is running in debug mode and
therefore should output additional extended debugging information. For example, to call the HelloColdFusion
CFX tag in debugging mode, use the following CFML code:


To determine whether a CFX tag is invoked with the debug attribute, use the Request.debug method. To write
debugging output in a special debugging block after the tag finishes executing, use the Response.writeDebug
method. For information on using these methods, see “ColdFusion Java CFX Reference” on page 1436 in CFML
Reference.

Debugging in a Java IDE
You can use a Java IDE to debug your Java CFX tags. This means you can develop your Java CFX tag and debug it in
a single environment.
1

Start your IDE.

ADOBE COLDFUSION 8 212
ColdFusion Developer’s Guide

2 In the project properties (or your IDE's project setting), make sure your CFX class is in the web_root\WEBINF\classes directory or in the system classpath.

Make sure the libraries cf_root/wwwroot/WEB-INF/lib/cfx.jar (cf_webapp_root/WEB-INF/lib/cfx.jar in the
J2EE configuration) and cf_root/runtime/lib/jrun.jar (server configuration only) are included in your classpath.

3
4

In your project settings, set your main class to jrunx.kernel.JRun and application parameters to -start

default.

5 Debug your application by setting breakpoints, single stepping, displaying variables, or by performing other
debugging actions.

Using the debugging classes
To develop and debug Java CFX tags in isolation from the ColdFusion, you use three special debugging classes that
are included in the com.allaire.cfx package. These classes lets you simulate a call to the processRequest
method of your CFX tag within the context of the interactive debugger of a Java development environment. The
three debugging classes are the following:

• DebugRequest: An implementation of the Request interface that lets you initialize the request with custom
attributes, settings, and a query.
•

DebugResponse: An implementation of the Response interface that lets you print the results of a request once

it has completed.

•

DebugQuery: An implementation of the Query interface that lets you initialize a query with a name, columns,

and a data set.
Implement a main method
1 Create a main method for your Java CFX class.

Within the main method, initialize a DebugRequest and DebugResponse, and a DebugQuery. Use the appropriate attributes and data for your test.

2
3

Create an instance of your Java CFX tag and call its processRequest method, passing in the DebugRequest and

DebugResponse objects.

Call the DebugResponse.printResults method to output the results of the request, including content
generated, variables set, queries created, and so on.

4

After you implement a main method as described previously, you can debug your Java CFX tag using an interactive,
single-step debugger. Specify your Java CFX class as the main class, set breakpoints as appropriate, and begin
debugging.
Example:debugging classes

The following example demonstrates how to use the debugging classes:
import java.util.Hashtable ;
import com.allaire.cfx.* ;
public class OutputQuery implements CustomTag {
// debugger testbed for OutputQuery
public static void main(String[] argv) {
try {
// initialize attributes
Hashtable attributes = new Hashtable() ;
attributes.put( "HEADER", "Yes" ) ;
attributes.put( "BORDER", "3" ) ;

ADOBE COLDFUSION 8 213
ColdFusion Developer’s Guide

// initialize query
String[] columns = { "FIRSTNAME", "LASTNAME", "TITLE" } ;
String[][] data = {
{ "Stephen", "Cheng", "Vice President" },
{ "Joe", "Berrey", "Intern" },
{ "Adam", "Lipinski", "Director" },
{ "Lynne", "Teague", "Developer" } };
DebugQuery query = new DebugQuery( "Employees", columns, data ) ;
// create tag, process debugging request, and print results
OutputQuery tag = new OutputQuery() ;
DebugRequest request = new DebugRequest( attributes, query ) ;
DebugResponse response = new DebugResponse() ;
tag.processRequest( request, response ) ;
response.printResults() ;
}
catch( Throwable e ) {
e.printStackTrace() ;
}
}
public void processRequest(Request request, Response response) throws Exception {
// ...code for processing the request...
}
}

Developing CFX tags in C++
You can develop CFX tags in C++.

Sample C++ CFX tags
Before you begin development of a CFX tag in C++, you might want to study the two CFX tags included with
ColdFusion. These examples will help you get started working with the CFXAPI. The two example tags are as
follows:

•

CFX_DIRECTORYLIST: Queries a directory for the list of files it contains.

•

CFX_NTUSERDB (Windows only): Lets you add and delete Windows NT users.

In Windows, these tags are located in the cf_root\cfx\examples directory. In UNIX, these tags are in the
cf_root/coldfusion/cfx/examples directory.

Setting up your C++ development environment
The following compliers generate valid CFX code for UNIX platforms:
Platform

Compiler

Solaris

Sun Workshop C++ compiler, version 5.0 or higher (gcc cannot be used to compile CFX code on Solaris)

Linux

Gnu C++ compiler - gcc

ADOBE COLDFUSION 8 214
ColdFusion Developer’s Guide

Before you can use your C++ compiler to build custom tags, you must enable the compiler to locate the CFX API
header file, cfx.h. In Windows, you do this by adding the CFX API include directory to your list of global include
paths. In Windows, this directory is cf_root\cfx\include. In UNIX, this directory is cf_root/cfx/include. in UNIX, you
will need -I  on your compile line (see the Makefile for the directory list example in the cfx/examples
directory).

Compiling C++ CFX tags
CFX tags built in Windows and in UNIX must be thread-safe. Compile CFX tags for Solaris with the -mt switch on
the Sun compiler.

Locating your C++ library files in UNIX
In UNIX systems, your C++ library files can be in any directory as long as the directory is included in
LD_LIBRARY_PATH or SHLIB_PATH (HP-UX only).

Implementing C++ CFX tags
CFX tags built in C++ use the tag request object, represented by the C++ CCFXRequest class. This object represents a request made from an application page to a custom tag. A pointer to an instance of a request object is passed
to the main procedure of a custom tag. The methods available from the request object let the custom tag accomplish
its work. For information about the CFX API classes and members, see “ColdFusion C++ CFX Reference” on
page 1415 in the CFML Reference.
Note: Calling a nonexistent C++ CFX procedure or entry point causes a JVM crash in UNIX.

Debugging C++ CFX tags
After you configure a debugging session, you run your custom tag from within the debugger, set breakpoints, singlestep, and so on.
Debugging in Windows

You can debug custom tags within the Visual C++ environment.
1

Build your C++ CFX tag using the debug option.

2

Restart ColdFusion.

3

Start Visual C++.

4

Select Build > Start Debug > AttachProcess.

5

Select jrunsvc.exe.
Adobe recommends that you shut down all other Java programs.

6

Execute any ColdFusion page that calls the CFX tag.

7

Select File > Open to open a file in VisualDev in which to set a breakpoint.

8

Set a breakpoint in the CFX project.
The best place is to put it in ProcessRequest(). Next time you execute the page you will hit the breakpoint.

ADOBE COLDFUSION 8 215
ColdFusion Developer’s Guide

Registering CFX tags
To use a CFX tag in your ColdFusion applications, first register it in the Extensions, CFX Tags page in the ColdFusion
Administrator.
1

In the ColdFusion Administrator, select Extensions > CFX Tags.

2

Click Register C++ CFX.

3

Enter the Tag name (for example, cfx_MyNewTag).

4

If the Server Library .dll field is empty, enter the filepath.

5

Accept the default Procedure entry.

6

Clear the Keep library loaded box while developing the tag.
For improved performance, when the tag is ready for production use, you can select this option to keep the DLL
in memory.

7

(Optional) Enter a description.

8

Click Submit.

You can now call the tag from a ColdFusion page.
Delete a CFX tag
1 In the ColdFusion Administrator, select Extensions > CFX Tags.
2

For the tag to delete, click the Delete icon in the Controls column of the Registered CFX Tags list.

216

Part 3: Developing CFML Applications
This part contains the following topics:
Designing and Optimizing a ColdFusion Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .218
Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Using Persistent Data and Locking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Using ColdFusion Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Securing Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Developing Globalized Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Debugging and Troubleshooting Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351
Using the ColdFusion Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

218

Chapter 14: Designing and Optimizing a
ColdFusion Application
Application elements and how you structure an application on your server make your Adobe ColdFusion pages an
effective Internet application. You use the Application.cfc and Application.cfm files and various coding methods to
optimize the efficiency of your application.
Contents

About applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Elements of a ColdFusion application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Structuring an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Defining the application and its event handlers in Application.cfc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Migrating from Application.cfm to Application.cfc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Using an Application.cfm page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Optimizing ColdFusion applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

About applications
The term application can mean many things. An application can be as simple as a guest book or as sophisticated as
a full Internet commerce system with catalog pages, shopping carts, and reporting.
An application, however, has a specific meaning in ColdFusion. A ColdFusion application has the following characteristics:

•

It consists of one or more ColdFusion pages that work together and share a common set of resources.

• All pages in the application share an application name and configuration settings as specified in an Application.cfc file or a cfapplication tag.
•

All pages in the application share variables in the Application scope.

•

You can write application-wide event handlers for specific events, such as request start or session end.

What appears to a user to be a single application (for example, a company’s website), might consist of multiple
ColdFusion applications.
ColdFusion applications are not J2EE applications. However, if you do not specify an application name in your
Application.cfc file or cfapplication tag, the Application scope corresponds to the J2EE application servlet
context.
ColdFusion applications end when the application has been inactive for the application time-out period or the server
stops. When the application times out, ColdFusion releases all Application scope variables. You must, therefore,
select a time-out period that balances the need for clearing Application scope memory and the overhead of recreating the scope. A typical application time-out is two days.
ColdFusion applications and sessions are independent of each other. For example, if an application times out while
a user’s session is active, the session continues and the session context, including the user’s Session scope variables,
is unaffected by the application ending and restarting.

ADOBE COLDFUSION 8 219
ColdFusion Developer’s Guide

Although there are no definite rules about how you represent your web application as a ColdFusion application or
applications, the following guidelines are useful:

• Application pages share a common general purpose. For example, a web storefront is typically a single
ColdFusion application.
• Many, but not necessarily all, pages in a ColdFusion application share data or common code elements, such as a
single login mechanism.
• Application pages share a common look and feel, often enforced by using common code elements, such as the
same header and footer pages, and a common error message template.

Elements of a ColdFusion application
Before you develop a ColdFusion application, you must determine how to structure the application and how to
handle application-wide needs and issues. In particular, you must consider all of the following:

•

The overall application framework

•

Reusable application elements

•

Shared variables

•

Application events and the Application.cfc file

•

Application-level settings and functions

•

Application security and user identification

The application framework
The application framework is the overall structure of the application and how your directory structure and application pages reflect that structure. You can use a single application framework to structure multiple ColdFusion
applications into a single website or Internet application. You can structure a ColdFusion application by using many
methodologies. For example, the Fusebox application development methodology is one popular framework for
developing ColdFusion web applications. (For more information on Fusebox, see www.fusebox.org.)
This chapter does not provide information on how to use or develop a specific application framework. However, it
does discuss the tools that ColdFusion provides for building your framework, including the Application.cfc file, how
an application’s directory structure affects the application, and how you can map the directory structure. For more
information on mapping the application framework, see “Structuring an application” on page 222.
Note: For one example of an application framework, see “ColdFusion Methodologies for Content Management,”
available at www.adobe.com/devnet/server_archive/articles/cf_methodologies_for_content_mgmt.html..

Reusable application elements
ColdFusion provides a variety of reusable elements that you can use to provide commonly used functionality and
extend CFML. These elements include the following:

•

User-defined functions (UDFs)

•

CFML custom tags

•

ColdFusion components (CFCs)

•

CFX (ColdFusion Extension) tags

ADOBE COLDFUSION 8 220
ColdFusion Developer’s Guide

•

Pages that you include using the cfinclude tag

For an overview of these elements, and information about how to choose among them, see “Creating ColdFusion
Elements” on page 126.

Shared variables
The following ColdFusion variable scopes maintain data that lasts beyond the scope of the current HTTP request:
Variable scope

Variables available

Server

To all applications on a server and all clients

Application

To all pages in an application for all clients

Client

For a single client browser over multiple browser sessions in one application

Session

For a single client browser for a single browser session in one application

For more information on using these variables, including how to use locks to ensure that the data they contain
remains accurate, see “Using Persistent Data and Locking” on page 272.

Application events and the Application.cfc file
Application events are specific occurrences during the life cycle of an application. Each time one of these events
occurs, ColdFusion runs the corresponding method in your Application.cfc file (also referred to as the application
CFC). The Application.cfc file defines application settings and implements methods to handle the application events.
You can implement application CFC methods to handle the following events:
.

Event

Trigger

Application start

ColdFusion starts processing the first request for a page in an application that is not running.

Application end

An application time-out setting is reached or the server shuts down.

Session start

A new session is created as a result of a request that is not in an existing session.

Session end

A session time-out setting is reached.

Request start

ColdFusion receives a request, including HTTP requests, messages to the event gateway, SOAP requests, or Flash
Remoting requests.

Request

Immediately after ColdFusion finishes processing the request start event. The handler for this event is intended for
use as a filter for the request contents. For more information on the differences between request start and request
events, see “Managing requests in Application.cfc” on page 229.

Request end

ColdFusion finishes processing all pages and CFCs for the request.

Exceptions

An exception occurs that is not handled in a try/catch block.

The Application.cfc file can also define application-wide settings, including the application name and whether the
application supports Session variables.
For more information on using application events and the Application.cfc file, see “Defining the application and its
event handlers in Application.cfc” on page 224.

ADOBE COLDFUSION 8 221
ColdFusion Developer’s Guide

Other application-level settings and functions
This section describes the techniques used prior to ColdFusion MX 7 to define application-level settings, variables,
and functions. Adobe recommends that you do not use these techniques in new code that you write; instead, you
should use the Application.cfc file and its variables and methods, which provide more features and include logical,
hierarchical structure.
If you do not have an Application.cfc file, ColdFusion processes the following two pages, if they are available, every
time it processes any page in the application:

•

The Application.cfm page is processed before each page in the application.

•

The OnRequestEnd.cfm page is processed after each page in the application.

Note: UNIX systems are case-sensitive. To ensure that your pages work on UNIX, always capitalize the A in Application.cfm and the O, R, and E in OnRequestEnd.cfm.
The Application.cfm page can define the application. It can contain the cfapplication tag that specifies the application name, and code on this page is processed for all pages in the application. This page can define applicationlevel settings, functions, and features.
The OnRequestEnd.cfm page is used in fewer applications than the Application.cfm page. It lets you provide
common clean-up code that gets processed after all application pages, or specify dynamic footer pages.
The OnRequestEnd.cfm page does not execute if the page invokes a cflocation tag.
For more information on the Application.cfm and OnRequestEnd.cfm pages, see “Using an Application.cfm page”
on page 235. For information on placing these pages in the application directory structure, see “Structuring an application” on page 222.
Note: You can create a ColdFusion application without using an Application.cfc, Application.cfm, or OnRequestEnd.cfm
page. However, it is much easier to use the Application.cfm page than to have each page in the application use a
cfapplication tag and define common application elements.

Specifying settings per application
You can set the following on a per-application basis:

•

Mappings

•

Custom tag paths

These settings override the server-side settings in the ColdFusion Administrator for the specified application only.
Specifying per application settings does not change the server-wide settings. To set per-application settings, you
must first enable per-application settings on the Settings page of the ColdFusion Administrator. You then set the
mappings or custom tag paths in the Application.cfc file.
Custom Tags in per-application settings override those defined in the ColdFusion Administrator. For example, if you
have two custom tags of the same name and they are in different locations in the Administrator and per-application
settings, the one in the per-application settings is taken first.
Note: Per-application settings are supported in applications that use an Application.cfc file only, not in applications that
use an Application.cfm file. The per-application settings do not work if you have disabled application variables in the
Memory Variables page of the Administrator.
Set the mappings per application
1 Check the Enable Per App Settings option on the Settings page of the ColdFusion Administrator.

ADOBE COLDFUSION 8 222
ColdFusion Developer’s Guide

2

Include code similar to the following in your Application.cfc file:


or


Set the custom tag paths per application
1 Check the Enable Per App Settings option on the Settings page of the ColdFusion Administrator.
2

Include code similar to the following in your Application.cfc file:




Application security and user identification
All applications must ensure that malicious users cannot make improper use of their resources. Additionally, many
applications require user identification, typically to control the portions of a site that the user can access, to control
the operations that the user can perform, or to provide user-specific content. ColdFusion provides the following
forms of application security to address these issues:
Resource (file and directory-based) security: Limits the ColdFusion resources, such as tags, functions, and data
sources that application pages in particular directories can access. You must consider the resource security needs of
your application when you design the application directory structure.
User (programmatic) security: Provides an authentication (login) mechanism and a role-based authorization
mechanism to ensure that users can only access and use selected features of the application. User security also incorporates a user ID, which you can use to customize page content. To implement user security, you include security
code, such as the cflogin and cfloginuser tags, in your application.
For more on implementing security, see “Securing Applications” on page 311.

Structuring an application
When you design a ColdFusion application, you must structure its contents into directories and files, also known as
mapping the directory structure. This activity is an important step in designing a ColdFusion application. Before you
start building the application, you must establish a root directory for the application. You can store application pages
in subdirectories of the root directory.
The following sections describe how ColdFusion uses application-specific pages and how you can organize your
application pages in a directory structure.

How ColdFusion finds and process application definition pages
ColdFusion uses the following rules to locate and process the Application.cfc, Application.cfm, and
OnRequestEnd.cfm pages that define application-specific elements. The way ColdFusion locates these files helps
determine how you structure an application.
Each time ColdFusion processes a page request it does the following:
1

When ColdFusion starts processing the request, it does the following:

ADOBE COLDFUSION 8 223
ColdFusion Developer’s Guide

• It searches the page’s directory for a file named Application.cfc. If one exists, it creates a new instance of the
CFC, processes the initial events, and stops searching. (ColdFusion creates a new instance of the CFC and
processes its initialization code for each request.)
• If the requested page’s directory does not have an Application.cfc file, it checks the directory for an Application.cfm file. If one exists, ColdFusion logically includes the Application.cfm page at the beginning of the
requested page and stops searching further.
• If the requested page’s directory does not have an Application.cfc or Application.cfm file, ColdFusion
searches up the directory tree and checks each directory first for an Application.cfc file and then, if one is not
found, for an Application.cfm page, until it reaches the root directory (such as C:\). When it finds an Application.cfc or Application.cfm file, it processes the page and stops searching.
2

ColdFusion processes the requested page’s contents.

3

When the request ends, ColdFusion does the following:

• If you have an Application.cfc, ColdFusion processes the CFC’s onRequestEnd method and releases the CFC
instance.
• If you do not have an Application.cfc, but do have an Application.cfm page, ColdFusion looks for an
OnRequestEnd.cfm in the same directory as the Application.cfm page ColdFusion uses for the current page.
ColdFusion does not search beyond that directory, so it does not run an OnRequestEnd.cfm page that resides in
another directory. Also, the OnRequestEnd.cfm page does not run if there is an error or an exception on the
application page, or if the application page executes the cfabort or cfexit tag.
The following rules determine how ColdFusion processes application pages and settings:

• ColdFusion processes only one Application.cfc or Application.cfm page for each request. If a ColdFusion page
has a cfinclude tag pointing to an additional ColdFusion page, ColdFusion does not search for an Application.cfc
or Application.cfm page when it includes the additional page.
• If a ColdFusion page has a cfapplication tag, it first processes any Application.cfc or Application.cfm, and
then processes the cfapplication tag. The tag can override the settings from the application files, including the
application name and the behaviors set by the cfapplication tag attributes.
• You can have multiple Application.cfc files, Application.cfm files, and cfapplication tags that use the same
application name. In this case, all pages that have the same name share the same application settings and Application
scope and can set and get all the variables in this scope. ColdFusion uses the parameter settings of the
cfapplication tag or the most recently processed file, if the settings, such as the session time-out, differ among the
files.
Note: If your application runs on a UNIX platform, which is case-sensitive, you must spell Application.cfc, Application.cfm, and OnRequestEnd.cfm with capital letters.

Defining the directory structure
Defining an application directory structure with an application-specific root directory has the following advantages:
Development: The application is easier to develop and maintain, because the application page files are wellorganized.
Portability: You can easily move the application to another server or another part of a server without changing any
code in the application page files.
Application-level settings: Application pages that are under the same directory can share application-level settings
and functions.

ADOBE COLDFUSION 8 224
ColdFusion Developer’s Guide

Security: Application pages that are under the same directory can share web server security settings.
When you put your application in an application-specific directory hierarchy, you can use a single application
definition (Application.cfc or Application.cfm) page in the application root directory, or put different application
definition pages that govern individual sections of the application in different directories.
You can divide your logical web application into multiple ColdFusion applications by using multiple application
definition pages with different application names. Alternatively, you can use multiple application definition pages
that specify the same application name, but have different code, for different subsections of your application.
The directory trees in the following image show two approaches to implementing an application framework:

• In the example on the left, a company named Web Wonders, Inc. uses a single Application.cfc file installed in the
application root directory to process all application page requests.
• In the example on the right, Bandwidth Associates uses the settings in individual Application.cfc files to create
individual ColdFusion applications at the departmental level. Only the Products application pages are processed
using the settings in the root Application.cfc file. The Consulting, Marketing, and Sales directories each have their
own Application.cfc file.

Web Wonder, Inc.

Bandwith Associates

Application.cfc

Products

Application.cfc

Products
Orders
Consulting

Support
Application.cfc
Services
Marketing
Application.cfc

Sales
Application.cfc

Defining the application and its event handlers in
Application.cfc
The Application.cfc file defines application-wide settings and variables, and application event handlers:

• Application-wide settings and variables include page processing settings, default variables, data sources, style
settings, and other application-level constants.

ADOBE COLDFUSION 8 225
ColdFusion Developer’s Guide

• Application event handlers are CFC methods that ColdFusion automatically executes when specific events occur
during the lifetime of an application: application start and end, session start and end, request start, execution, and
end, and exceptions.

Defining application-level settings and variables
When you create an application, you can set a number of application-wide properties and characteristics, including
the following items:

•

Application name

•

Application properties, including Client-, Application-, and Session-variable management options

•

Page processing options

•

Default variables, data sources, style settings, and other application-level constants

This section describes the following topics:

•

Naming the application

•

Setting application properties

•

Setting page processing options

For information on setting default variables, see “Setting application default variables and constants in onApplicationStart” on page 228.
Naming the application

Define the application and give it a name by setting the This.name variable in the Application.cfc initialization
section, before the method definitions. By using a specific application name, you define a set of pages as part of the
same logical application.
ColdFusion supports unnamed applications, which are useful for ColdFusion applications that must interoperate
with JSP tags and servlets. Consider creating an unnamed application only if your ColdFusion pages must share
Application or Session scope data with existing JSP pages and servlets. You cannot have more than one unnamed
application on a server instance. For more information on using unnamed applications, see “Sharing data between
ColdFusion pages and JSP pages or servlets” on page 932.
Setting application properties

You can specify application properties by setting This scope variables in the Application.cfc initialization code.
(These are the same properties that you can set in the cfapplication tag.) The following table lists the This scope
variable that ColdFusion uses to set application properties and describes their uses.
Variable

Default

Description

applicationTimeout

Administrator value

Life span, as a real number of days, of the application, including all Application scope
variables. Use the createTimeSpan function to generate this variable.

clientManagement

False

Whether the application supports Client scope variables.

clientStorage

Administrator value

Where Client variables are stored; can be cookie, registry, or the name of a data source.

loginStorage

Cookie

Whether to store login information in the Cookie scope or the Session scope.

scriptProtect

Administrator Value

Whether to protect variables from cross-site scripting attacks.

sessionManagement

False

Whether the application supports Session scope variables.

ADOBE COLDFUSION 8 226
ColdFusion Developer’s Guide

Variable

Default

Description

sessionTimeout

Administrator Value

Life span, as a real number of days, of the user session, including all Session variables.
Use the createTimeSpan function to generate this variable.

setClientCookies

True

Whether to send CFID and CFTOKEN cookies to the client browser.

setDomainCookies

False

Whether to use domain cookies for the CFID and CFTOKEN values used for client identification, and for Client scope variables stored using cookies. If False, ColdFusion uses
host-specific cookies. Set to True for applications running on clusters.

The following example code from the top of an Application.cfc sets the application name and properties:








For more information on these settings, see cfapplication in the CFML Reference.
Setting page processing options

The cfsetting tag lets you specify the following page processing attributes that you might want to apply to all pages
in your application:
Attribute

Use

showDebugOutput

Specifies whether to show debugging output. This setting cannot enable debugging if it is disabled in
the ColdFusion Administrator. However, this option can ensure that debugging output is not displayed,
even if the Administrator enables it.

requestTimeout

Specifies the page request time-out. If ColdFusion cannot complete processing a page within the timeout period, it generates an error. This setting overrides the setting in the ColdFusion Administrator. You
can use this setting to increase the page time-out if your application or page frequently accesses
external resources that might be particularly slow, such as external LDAP servers or web services
providers.

enableCFOutputOnly

Disables output of text that is not included inside cfoutput tags. This setting can help ensure that
extraneous text that might be in your ColdFusion pages does not get displayed.

Often, you use the cfsetting tag on individual pages, but you can also use it in your Application.cfc file. For
example, you might use it in multi-application environment to override the ColdFusion Administrator settings in
one application.
You can put an application-wide cfsetting tag in the component initialization code, normally following the This
scope application property settings, as the following example shows:


This.name="MyAppl";
This.clientmanagement="True";
This.loginstorage="Session" ;
This.sessionmanagement="True" ;
This.sessiontimeout=CreateTimeSpan(0,0,1,0);



The cfsetting tag in this example affects all pages in an application. You can override the application-wide settings
in the event methods, such as onRequestStart, or on individual ColdFusion pages.

ADOBE COLDFUSION 8 227
ColdFusion Developer’s Guide

Using application event handlers
The following table briefly describes the application event CFC methods that you can implement, including when
they are triggered. The following sections describe how to use these methods in more detail.
Method

When run

onApplicationStart

The application first starts: when the first request for a page is processed or the first CFC method is
invoked by an event gateway instance, Flash Remoting request, or a web service invocation.
This method is useful for setting application-wide (Application scope) variables, such as the names of
data sources.

onApplicationEnd

The application ends: when the application times out or the server shuts down.

onSessionStart

A new session is created as a result of a request that is not in an existing session, including ColdFusion
event gateway sessions. The application must enable sessions for this event to happen.

onSessionEnd

A session time-out setting is reached. This event is not triggered when the application ends or the server
shuts down.

onRequestStart

ColdFusion receives any of the following: a request, an HTTP request (for example, from a browser), a
message to an event gateway, a SOAP request, or a Flash Remoting request.

onRequest

The onRequestStart event has completed. This method can act as a filter for the requested page
content.

onRequestEnd

All pages and CFCs in the request have been processed: equivalent to the OnRequestEnd.cfm page.

onMissingTemplate

When ColdFusion receives a request for a nonexistent page.

onError

When an exception occurs that is not caught by a try/catch block.

When ColdFusion receives a request, it instantiates the Application CFC and runs the Application.cfc code in the
following order:

•

CFC initialization code at the top of the file

•

onApplicationStart, if not run before for this application

•

onSessionStart, if not run before for this session

•
•

onRequestStart
onRequest, or the requested page if there is no onRequest method

• onRequestEnd
The following methods are triggered by specific events:
• onApplicationEnd
• onSessionEnd
• onMissingTemplate
• onError
The onApplicationEnd and onSessionEnd methods do not execute in the context of a page request, so they cannot
access request variables or display information to the user. The onMissingTemplate method is triggered when a
URL specifies a CFML page that does not exist. The OnError method does not always execute in the context of a
request; you can use its Event argument to determine the context.

ADOBE COLDFUSION 8 228
ColdFusion Developer’s Guide

Managing the application with Application.cfc
You use the onApplicationStart and onApplicationEnd methods to configure and manage the application; that
is, to control resources that are used by multiple pages and requests and must be consistently available to all code in
your application. Such resources can include data sources, application counters such as page hit variables, or style
information for all pages.
The onApplicationStart method executes when ColdFusion gets the first request for a page in the application
after the server starts. The onApplicationEnd method executes when the application server shuts down or if the
application is inactive for the application time-out period.
The following sections describe some of the ways you can use these methods. For more information, see entries for
onApplicationStart and onApplicationEnd in the CFML Reference.
Defining application utility functions

Functions that you define in Application.cfc and do not put in a shared scope are, by default, available only to other
methods in the CFC.
If your Application.cfc implements the onRequest method, any utility functions that you define in Application.cfc
are also directly available in to the target page, because Application.cfc and the target page share the Variables scope.
If your application requires utility functions that are used by multiple pages, not just by the methods in Application.cfc, and you do not use an onRequest method, Adobe recommends that you put them in a separate CFC and
access them by invoking that CFC. As with other ColdFusion pages, Application.cfc can access any CFC in a
directory path that is configured on the ColdFusion Administrator Mappings page. You can, therefore, use this
technique to share utility functions across applications.
If your Application.cfc defines utility functions that you want available on request pages and does not use an
onRequest method, you must explicitly put the functions in a ColdFusion scope, such as the Request scope, as the
following code shows:








On the request page, you would include the following code:


Functions that you define in this manner share the This scope and Variables scope with the Application.cfc file for
the request.
Setting application default variables and constants in onApplicationStart

You can set default variables and application-level constants in Application.cfc. For example, you can do the
following:

•

Specify a data source and ensure that it is available

•

Specify domain name

•

Set styles, such as fonts or colors

•

Set other application-level variables

ADOBE COLDFUSION 8 229
ColdFusion Developer’s Guide

You do not have to lock Application scope variables when you set them in the Application.cfc onApplicationStart
method.
For details on implementing the onApplicationStart method, see onApplicationStart in the CFML Reference.
Using the onApplicationEnd method

Use the onApplicationEnd method for any clean-up activities that your application requires when it shuts down,
such as saving data in memory to a database, or to log the application end. You cannot use this method to display
data on a user page, because it is not associated with any request. The application ends, even if this method throws
an exception. An application that is used often is unlikely to execute this method, except when the server is shut
down.
For details on implementing the onApplicationEnd method, see onApplicationEnd in the CFML Reference.

Managing sessions in Application.cfc
You use the onSessionStart and onSessionEnd methods to configure and manage user sessions; that is, to control
resources that are used by multiple pages while a user is accessing your site from during a single browser session. The
session begins when a user first requests a page in your application, and ends when the session times out. For more
information on Session scope and Session variables, see “Using Persistent Data and Locking” on page 272.
Session resources include variables that store data that is needed throughout the session, such as account numbers,
shopping cart contents, or CFCs that contain methods and data that are used by multiple pages in a session.
Note: Do not put the cflogin tag or basic login processing in the onSessionStart method, as the code executes only at
the start of the session; it cannot handle user logouts, and cannot fully ensure security.
The following sections describe some of the ways you can use the onSessionStart and onSessionEnd methods.
For more information, see the onSessionStart and onSessionEnd entries in the CFML Reference.
Using the onSessionStart method

This method is useful for initializing session data, such as user settings or shopping cart contents, or for tracking the
number of active sessions. You do not need to lock the Session scope when you set session variables in this method.
Using the onSessionEnd method

Use this method for any clean-up activities when the session ends. (For information on ending sessions, see “Ending
a session” on page 286.) You can, for example, save session-related data, such as shopping cart contents or information about whether the user has not completed an order, in a database, or you can log the end of the session to a
file. You cannot use this method to display data on a user page, because it is not associated with a request.
Note: Sessions do not end, and the onSessionEnd method is not called when an application ends. For more information, see the onSessionEnd entry in the CFML Reference.

Managing requests in Application.cfc
ColdFusion provides three methods for managing requests: onRequestStart, onRequest, and onRequestEnd.
ColdFusion processes requests, including these methods, as follows:
1

ColdFusion always processes onRequestStart at the start of the request.

If you implement an onRequest method, ColdFusion processes it; otherwise, it processes the requested page. If
you implement an onRequest method, you must explicitly call the requested page in your onRequest method.

2
3

ColdFusion always processes onRequestEnd at the end of the request.

ADOBE COLDFUSION 8 230
ColdFusion Developer’s Guide

The following sections explain how you can use each of the Application.cfc request methods to manage requests. For
more information, see entries for onRequestStart, onRequest, and onRequestEnd in the CFML Reference.
Using the onRequestStart method

This method runs at the beginning of the request. It is useful for user authorization (login handling), and for requestspecific variable initialization, such as gathering performance statistics.
If you use the onRequestStart method and do not use the onRequest method, ColdFusion automatically processes
the request when it finishes processing the onRequestStart code.
Note: If you do not include an onRequest method in Application.cfm file, the onRequestStart method does not share
a Variables scope with the requested page, but it does share Request scope variables.
User authentication

When an application requires a user to log in, put the authentication code, including the cflogin tag or code that
calls this tag, in the onRequestStart method. Doing so ensures that the user is authenticated at the start of each
request. For detailed information on security and creating logins, see “Securing Applications” on page 311 For an
example that uses authentication code generated by the Adobe Dreamweaver CF Login Wizard, see
onRequestStart in the CFML Reference.
Using the onRequest method

The onRequest method differs from the onRequestStart method in one major way: the onRequest method intercepts the user’s request. This difference has two implications:

• ColdFusion does not process the request unless you explicitly call it, for example, by using a cfinclude tag. This
behavior lets you use the onRequest method to filter requested page content or to implement a switch that determines the pages or page contents to be displayed.
• When you use cfinclude to process request, the CFC instance shares the Variables scope with the requested
page. As a result, any method in the CFC that executes can set the page’s Variables scope variables, and the
onRequestEnd method can access any Variable scope values that the included page has set or changed. Therefore,
for example, the onRequestStart or onRequest method can set variables that are used on the page.
To use this method as a filter, put the cfinclude tag inside a cfsavecontent tag, as the following example shows:






#replace(content, "report", "MyCompany Quarterly Report", "all")#


Using the onRequestEnd method

You use the onRequestEnd method for code that should run at the end of each request. (In ColdFusion versions
through ColdFusion MX 6.1, you would use the OnRequestEnd.cfm page for such code.) Typical uses include
displaying dynamic footer pages. For an example, see onSessionEnd in the CFML Reference.
Note: If you do not include an onRequest method in Application.cfm file, the onRequestEnd method does not share a
Variables scope with the requested page, but it does share Request scope variables.

ADOBE COLDFUSION 8 231
ColdFusion Developer’s Guide

Handling errors in Application.cfc
The following sections briefly describe how you can handle errors in Application.cfc. For more information on error
pages and error handling, see “Handling Errors” on page 246 For details on implementing the onError method, see
onError in the CFML Reference.
Application.cfc error handling techniques

Application.cfc can handle errors in any combination of the following ways:

• You can use try/catch error handling in the event methods, such as onApplicationStart or onRequestStart,
to handle exceptions that happen in the event methods.
• You can implement the onError method. This method receives all exceptions that are not directly handled by
try/catch handlers in CFML code. The method can use the cfthrow tag to pass any errors it does not handle to
ColdFusion for handling.
• You can use cferror tags in the application initialization code following the cfcomponent tag, typically
following the code that sets the application’s This scope variables. These tags specify error processing if you do not
implement an onError method, or if the onError method throws an error. You could implement an applicationspecific validation error handler, for example, by putting the following tag in the CFC initialization code:


1 The ColdFusion default error mechanisms handle any errors that are not handled by the preceding techniques.
These mechanisms include the site-wide error handler that you can specify in the ColdFusion Administrator and the
built-in default error pages.

These techniques let you include application-specific information, such as contact information or application or
version identifiers, in the error message, and let you display all error messages in the application in a consistent
manner. You can use Application.cfc to develop sophisticated application-wide error-handling techniques, including
error-handling methods that provide specific messages, or use structured error-handling techniques.
Note: The onError method can catch errors that occur in the onSessionEnd and onApplicationEnd application
event methods. It will not display messages to the user, however, because there is no request context. The onError
function can log errors that occur when the session or application ends.
Handling server-side validation errors in the onError method

Server-side validation errors are actually ColdFusion exceptions; as a result, if your application uses an onError
method, this method gets the error and must handle it or pass it on to ColdFusion for handling.
To identify a server-side validation error, search the Arguments.Exception.StackTrace field for
coldfusion.filter.FormValidationException. You can then handle the error directly in your onError routine, or
throw the error so that either the ColdFusion default validation error page or a page specified by an cferror tag in
your Application.cfc initialization code handles it.
Example: error Handling with the onError method

The following Application.cfc file has an onError method that handles errors as follows:

• If the error is a server-side validation error, the onError method throws the error for handling by ColdFusion,
which displays its standard validation error message.
• For any other type of exception, the onError method displays the name of the event method in which the error
occurred and dumps the exception information. In this example, because you generate errors on the CFM page only,
and not in a Application.cfc method, the event name is always the empty string.



ADOBE COLDFUSION 8 232
ColdFusion Developer’s Guide











Error Event: #EventName#
Error details:







To test this example, put a CFML page with the following code in the same page as the Application.cfc file, and enter
valid and invalid text in the text input field.

This box does Integer validation:


Check this box to throw an error on the action page:








You entered the following valid data in the field
#form.intinput#



Note: For more information on server-side validation errors, see “Validating Data” on page 553.

Example: a complete Application.cfc
The following example is a simplified Application.cfc file that illustrates the basic use of all application event
handlers:








ADOBE COLDFUSION 8 233
ColdFusion Developer’s Guide



SELECT Emp_ID FROM employee




This application encountered an error.

Please contact support.








Application.availableResources=0;
Application.counter1=1;
Application.sessions=0;













if ((Hour(now()) gt 1) and (Hour(now()) lt 3)) {
WriteOutput("The system is undergoing periodic maintenance.
Please return after 3:00 AM Eastern time.");
return false;
} else {
this.start=now();
}









#replace(content, "report", "MyCompany Quarterly Report", "all")#

ADOBE COLDFUSION 8 234
ColdFusion Developer’s Guide















Session.started = now();
Session.shoppingCart = StructNew();
Session.shoppingCart.items =0;























An unexpected error occurred.
Please provide the following information to technical support:
Error Event: #EventName#
Error details:







ADOBE COLDFUSION 8 235
ColdFusion Developer’s Guide

Migrating from Application.cfm to Application.cfc
To migrate an existing application that uses Application.cfm to one that uses Application.cfc, do the following:

• Replace the cfapplication tag with CFC initialization code that sets the Application.cfc This scope variables
that correspond to the tag attributes.
• Put in the onApplicationStart method any code that initializes Application scope variables, and any other
application-specific code that executes only when the application starts. Often, such code in Application.cfm is
inside a block that tests for the existence of an Application scope switch variable. Remove the variable test and the
Application scope lock that surrounds the code that sets the Application scope variables.
• Put in the onSessionStart method any code that initializes Session scope variables, and any other applicationspecific code that executes only when the session starts. Remove any code that tests for the existence of Session scope
variables to be for initialized and the Session scope lock that surrounds the code that sets the Session scope variables.
•

Put in the onRequestStart method any cflogin tag and related authentication code.

• Put in the onRequest method any code that sets Variables scope variables and add a cfinclude tag that includes
the page specified by the method’s Arguments.Targetpage variable.
•

Put in the onRequestEnd method any code you have in an OnRequestEnd.cfm page.

• Consider replacing cferror tags with an onError event method. If you do not do so, put the cferror tags in
the CFC initialization code.

Using an Application.cfm page
If you do not use an Application.cfc file, you can use the Application.cfm page to define application-level settings
and functions.

Naming the application
Use the cfapplication tag to specify the application name and define a set of pages as part of the same logical application. Although you can create an application by putting a cfapplication tag with the application name on each
page, you normally put the tag in the Application.cfm file; for example:


Note: The value that you set for the name attribute in the cfapplication tag is limited to 64 characters.

Setting the client, application, and session variables options
Use the cfapplication tag to specify client state and persistent variable use, as follows:

•

To use Client scope variables, you must specify clientManagement=True.

•

To use Session scope variables, you must specify sessionManagment=True.

You can also optionally do the following:

• Set application-specific time-outs for Application and Session scope variables. These settings override the
default values set in the ColdFusion Administrator.
• Specify a storage method for Client scope variables. This setting overrides the method set in the ColdFusion
Administrator.

ADOBE COLDFUSION 8 236
ColdFusion Developer’s Guide

•

Specify not to use cookies on the client browser.

For more information on configuring these options, see “Using Persistent Data and Locking” on page 272 and the
CFML Reference.

Defining page processing settings
The cfsetting tag lets you specify page processing attributes that you might want to apply to all pages in your application. For more information, see “Setting page processing options” on page 226.

Setting application default variables and constants
You can set default variables and application-level constants on the Application.cfm page. For example, you can
specify the following values:

•

A data source

•

A domain name

•

Style settings, such as fonts or colors

•

Other important application-level variables

Often, an Application.cfm page uses one or more cfinclude tags to include libraries of commonly used code, such
as user-defined functions, that are required on many of the application’s pages.

Processing logins
When an application requires a user to log in, you typically put the cflogin tag on the Application.cfm page. For
detailed information on security and creating logins, including an Application.cfm page that manages user logins,
see “Securing Applications” on page 311

Handling errors
You can use the cferror tag on your Application.cfm page to specify application-specific error-handling pages for
request, validation, or exception errors, as shown in the example in the following section. This way you can include
application-specific information, such as contact information or application or version identifiers, in the error
message, and you display all error messages in the application in a consistent manner.
For more information on error pages and error handling, see “Handling Errors” on page 246.

Example: an Application.cfm page
The following example shows a sample Application.cfm file that uses several of the techniques typically used in
Application.cfm pages. For the sake of simplicity, it does not show login processing; for a login example, see
“Securing Applications” on page 311.






ADOBE COLDFUSION 8 237
ColdFusion Developer’s Guide






































Reviewing the code

The following table describes the code and its function:

ADOBE COLDFUSION 8 238
ColdFusion Developer’s Guide

Code

Description



Names the application, enables Client and Session scope variables, and sets the
client variable store to the myCompany data source.



Ensures that debugging output is not displayed, if the ColdFusion Administrator
enables it.




Specifies custom error handlers for request and validation errors encountered in
the application. Specifies the mailing address for use in the request error handler.


.
.
.

Sets the Application scope variables, if they are not already set. For a detailed
description of the technique used to set the Application scope variables, see
“Using Persistent Data and Locking” on page 272.









Sets the Session scope pagesHit variable, which counts the number of pages
touched in this session. If the variable does not exist, creates it; otherwise, increments it.





Includes a library of user-defined functions that are used in most pages in the
application.

Optimizing ColdFusion applications
You can optimize your ColdFusion application in many ways. Optimizing ColdFusion mostly involves good development and coding practices. For example, good database design and usage is a prime contributor to efficient
ColdFusion applications.
In several places, this manual documents optimization techniques as part of the discussion of the related ColdFusion
topic. This section provides information about general ColdFusion optimization tools and strategies, and particularly about using CFML caching tags for optimization. This section also contains information on optimizing
database use, an important area for application optimization.
The ColdFusion Administrator provides caching options for ColdFusion pages and SQL queries. For information on
these options, see the ColdFusion Administrator online Help and Configuring and Administering ColdFusion.
For information on debugging techniques that can help you identify slow pages, see “Debugging and Troubleshooting Applications” on page 351.
For additional information on optimizing ColdFusion, see the Adobe ColdFusion support center at
www.adobe.com/go/support/coldfusion.

ADOBE COLDFUSION 8 239
ColdFusion Developer’s Guide

Caching ColdFusion pages that change infrequently
Some ColdFusion pages produce output that changes infrequently. For example, you might have an application that
extracts a vendor list from a database or produces a quarterly results summary. Normally, when ColdFusion gets a
request for a page in the application, it does all the business logic and display processing that are required to produce
the report or generate and display the list. If the results change infrequently, this can be an inefficient use of processor
resources and bandwidth.
The cfcache tag tells ColdFusion to cache the HTML that results from processing a page request in a temporary file
on the server. This HTML does not need to be generated each time the page is requested. When ColdFusion gets a
request for a cached ColdFusion page, it retrieves the pregenerated HTML page without having to process the
ColdFusion page. ColdFusion can also cache the page on the client. If the client browser has its own cached copy of
the page from a previous viewing, ColdFusion instructs the browser to use the client’s page rather than resending the
page.
Note: The cfcache tag caching mechanism considers that each URL is a separate page. Therefore,
http://www.mySite.com/view.cfm?id=1 and http://www.mySite.com/view.cfm?id=2 result in two separate cached pages.
Because ColdFusion caches a separate page for each unique set of URL parameters, the caching mechanism accommodates pages for which different parameters result in different output.
Using the cfcache tag

You tell ColdFusion to cache the page results by putting a cfcache tag on your ColdFusion page before code that
outputs text. The tag lets you specify the following information:

• Whether to cache the page results on the server, the client system, or both. The default is both. The default is
optimal for pages that are identical for all users. If the pages contain client-specific information, or are secured with
ColdFusion user security, set the action attribute in the cfcache tag to ClientCache.
• The directory on the server in which to store the cached pages. The default directory is cf_root/cache. It is a good
practice to create a separate cache directory for each application. Doing so can prevent the cfcache tag flush action
from inappropriately flushing more than one application’s caches at a time.
• The time span that indicates how long the page lasts in the cache from when it is stored until it is automatically
flushed.
You can also specify several attributes for accessing a cached page on the web server, including a user name and
password (if required by the web server), the port, and the protocol (HTTP or HTTPS) to use to access the page.
Place the cfcache tag before any code on your page that generates output, typically at the top of the page body. For
example, the following tag tells ColdFusion to cache the page on both the client and the server. On the server, the
page is cached in the e:/temp/page_cache directory. ColdFusion retains the cached page for one day.


Important: If an Application.cfm or Application.cfc page displays text (for example, if it includes a header page), use the
cfcache tag on the Application.cfm page, in addition to the pages that you cache. Otherwise, ColdFusion displays the
Application.cfm page output twice on each cached page.
Flushing cached pages

ColdFusion automatically flushes any cached page if you change the code on the page. It also automatically flushes
pages after the expiration timespan passes.
You can use the cfcache tag with the action="flush" attribute to immediately flush one or more cached pages.
You can optionally specify the directory that contains the cached pages to be flushed and a URL pattern that
identifies the pages to flush. If you do not specify a URL pattern, all pages in the directory are flushed. The URL
pattern can include asterisk (*) wildcards to specify parts of the URL that can vary.

ADOBE COLDFUSION 8 240
ColdFusion Developer’s Guide

When you use the cfcache tag to flush cached pages, ColdFusion deletes the pages cached on the server. If a flushed
page is cached on the client system, it is deleted, and a new copy gets cached the next time the client tries to access
the ColdFusion page.
The following example flushes all the pages in the e:/temp/page_cache/monthly directory that start with HR:


If you have a ColdFusion page that updates data that you use in cached pages, the page that does the updating
includes a cfcache tag that flushes all pages that use the data.
For more information on the cfcache tag, see the CFML Reference.

Caching parts of ColdFusion pages
In some cases, your ColdFusion page might contain a combination of dynamic information that ColdFusion must
generate each time it displays the page, and information that it generates dynamically, but that change less frequently.
In this case, you cannot use the cfcache tag to cache the entire page. Instead, use the cfsavecontent tag to cache
the infrequently changed content.
The cfsavecontent tag saves the results of processing the tag body in a variable. For example, if the body of the
cfsavecontent tag contains a cfexecute tag that runs an executable program that displays data, the variable saves

the output.
You can use the cfsavecontent tag to cache infrequently changing output in a shared scope variable. If the information is used throughout the application, save the output in the Application scope. If the information is clientspecific, use the Session scope. Because of the overhead of locking shared scope variables, use this technique only if
the processing overhead of generating the output is substantial.
Before you use this technique, also consider whether other techniques are more appropriate. For example, query
caching eliminates the need to repeat a common query. However, if the effort of processing the data or formatting
the output is substantial, using the cfsavecontent tag can save processing time.
Using this technique, if the variable exists, the page uses the cached output. If the variable does not exist, the page
gets the data, generates the output, and saves the results to the shared scope variable.
The following example shows this technique. It has two parts. The first part welcomes the user and prints out a
random lucky number. This part runs and produces a different number each time a user opens the page. The second
part performs a database query to get information that changes infrequently; in this example, a listing of the current
special sale items. It uses the cfsavecontent tag to get the data only when needed.
If you use this technique frequently, consider incorporating it in a custom CFML tag.


Welcome to our home page.

The time is #TimeFormat(Now())#.

Your lucky number is: #RandRange(1,1000)#










ADOBE COLDFUSION 8 241
ColdFusion Developer’s Guide





SELECT ItemName, Item_link, Description, BasePrice
FROM SaleProducts


Check out the following specials




#ItemNAme#
#Item_Link#
#Description#
#salePrice#











#Application.ProductCache#

Reviewing the code

The following table describes the code and its function:
Code

Description


Welcome to our home page.

The time is #TimeFormat(Now())#.

Your lucky number is:
#RandRange(1,1000)#





Displays the part of the page that must change each time.





Inside a read-only lock, tests to see if the part of the page that changes infrequently is already cached in the Application scope, and sets a Boolean flag variable with the result.




If the flag is False, uses a cfsavecontent tag to save output in a Variables scope
variable. Using the Variables scope eliminates the need to do a query (which can
take a long time) in an Application scope lock.


SELECT ItemName, Item_link,
Description, BasePrice
FROM SaleProducts


Queries the database to get the necessary information.

ADOBE COLDFUSION 8 242
ColdFusion Developer’s Guide

Code

Description

Check out the following specials




#ItemNAme#
#Item_Link#
#Description#
#salePrice#




Displays the sale items in a table. Inside a cfoutput tag, calculates each item’s
sale price and displays the item information in a table row.



Ends the cfsavecontent tag block.





Inside an Exclusive cflock tag, saves the contents of the local variable
ProductCache in the Application scope variable Application.productCache.



Ends the code that executes only if the Application.productCache variable does
not exist.



Inside a cflock tag, displays the contents of the Application.productCache variable.

Because this code is inside a cfsavecontent tag, ColdFusion does not display
the results of the cfoutput tag. Instead, it saves the formatted output as HTML
and text in the ProductCache variable.

#Application.ProductCache#


Optimizing database use
Poor database design and incorrect or inefficient use of the database are among the most common causes of inefficient applications. Consider the different methods that are available for using databases and information from
databases when you design your application. For example, if you need to average the price of a number of products
from an SQL query, it is more efficient to use SQL to get the average than to use a loop in ColdFusion.
Two important ColdFusion tools for optimizing your use of databases are the cfstoredproc tag and the cfquery
tag cachedWithin attribute.
Using stored procedures

The cfstoredproc tag lets ColdFusion use stored procedures in your database management system. A stored
procedure is a sequence of SQL statements that is assigned a name, compiled, and stored in the database system.
Stored procedures can encapsulate programming logic in SQL statements, and database systems are optimized to
execute stored procedures efficiently. As a result, stored procedures are faster than cfquery tags.
You use the cfprocparam tag to send parameters to the stored procedure, and the cfprocresult tag to get the
record sets that the stored procedure returns.
The following example executes a Sybase stored procedure that returns three result sets, two of which the example
uses. The stored procedure returns the status code and one output parameter, which the example displays.





ADOBE COLDFUSION 8 243
ColdFusion Developer’s Guide








The output param value: '#foo#'


The Results Information

#name#,#DATE_COL#






Record Count: #RS1.recordCount#

Columns: #RS1.columnList#




#col1#,#col2#,#col3#







Record Count: #RS3.recordCount#

Columns: #RS3.columnList#


The return code for the stored procedure is: '#cfstoredproc.statusCode#'


Reviewing the code

The following table describes the code and its function:
Code

Description



Runs the stored procedure foo_proc on the MY_SYBASE_TEST data
source. Populates the cfstoredproc statusCode variable with
the status code returned by stored procedure.

ADOBE COLDFUSION 8 244
ColdFusion Developer’s Guide

Code

Description




Gets two record sets from the stored procedure: the first and third
result sets it returns.





Specifies two parameters for the stored procedure, an input parameter and an output parameter. Sets the input parameter to 1 and the
ColdFusion variable that gets the output to FOO.


The output param value: '#foo#'



Displays the results of running the stored procedure:

The Results Information

#name#,#DATE_COL#






Record Count: #RS1.recordCount#

Columns: #RS1.columnList#




#col1#,#col2#,#col3#





Ends the cfstoredproc tag body.

•

The output parameter value,

•

The contents of the two columns in the first record set identified
by the name and DATE_COL variables. You set the values of these
variables elsewhere on the page.

•

The number of rows and the names of the columns in the first
record set

•

The contents of the columns in the other record set identified by
the col1, col2, and col3 variables.

•

The number of rows and the names of the columns in the record
set.

•

The status value returned by the stored procedure.




Record Count: #RS3.recordCount#

Columns: #RS3.columnList#


The return code for the stored procedure is:
'#cfstoredproc.statusCode#'



For more information on creating stored procedures, see your database management software documentation. For
more information on using the cfstoredproc tag, see the CFML Reference.
Using the cfquery tag cachedWithin attribute

The cfquery tag cachedWithin attribute tells ColdFusion to save the results of a database query for a specific period
of time. This way, ColdFusion accesses the database on the first page request, and does not query the database on
further requests until the specified time expires. Using the cachedWithin attribute can significantly limit the
overhead of accessing databases that do not change rapidly.
This technique is useful if the database contents only change at specific, known times, or if the database does not
change frequently and the purpose of the query does not require absolutely up- to-date results.
You must use the CreateTimeSpan function to specify the cachedWithin attribute value (in days, hours, minutes,
seconds format). For example, the following code caches the results of getting the contents of the Employees table of
the cfdocexamples data source for one hour.

SELECT * FROM Employees


ADOBE COLDFUSION 8 245
ColdFusion Developer’s Guide

Providing visual feedback to the user
If an application might take a while to process data, it is useful to provide visual feedback to indicate that something
is happening, so the user does not assume that there is a problem and request the page again. Although doing this
does not optimize your application’s processing efficiency, it does make the application appear more responsive.
You can use the cfflush tag to return partial data to a user, as shown in “Introduction to Retrieving and Formatting
Data” on page 511.
You can also use the cfflush tag to create a progress bar. For information on this technique, see the technical article
“Understanding Progress Meters in ColdFusion 5” at
www.adobe.com/v1/handlers/index.cfm?id=21216&method=full. (Although this article was written for ColdFusion
5, it also applies to ColdFusion 8.)

246

Chapter 15: Handling Errors
ColdFusion includes many tools and techniques for responding to errors that your application encounters. These
tools include error handling mechanisms and error logging tools. This chapter describes these tools and how to use
them.
For information on user input validation, see “Introduction to Retrieving and Formatting Data” on page 511 and
“Building Dynamic Forms with cfform Tags” on page 530 For information on debugging, see “Debugging and
Troubleshooting Applications” on page 351
Contents

About error handling in ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Understanding errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Error messages and the standard error format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Determining error-handling strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Specifying custom error messages with the cferror tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Logging errors with the cflog tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Handling runtime exceptions with ColdFusion tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

About error handling in ColdFusion
By default, ColdFusion generates its own error messages when it encounters errors. In addition, it provides a variety
of tools and techniques for you to customize error information and handle errors when they occur. You can use any
of the following error-management techniques.

•

Specify custom pages for ColdFusion to display in each of the following cases:

•

When a ColdFusion page is missing (the Missing Template Handler page)

• When an otherwise-unhandled exception error occurs during the processing of a page (the Site-wide Error
Handler page)
You specify these pages on the Settings page in the Server Settings page in the ColdFusion Administrator; for
more information, see the ColdFusion Administrator Help.

•

Use the cferror tag to specify ColdFusion pages to handle specific types of errors.

• Use the cftry, cfcatch, cfthrow, and cfrethrow tags to catch and handle exception errors directly on the page
where they occur.
•

In CFScript, use the try and catch statements to handle exceptions.

• Use the onError event in Application.cfc to handle exception errors that are not handled by try/catch code on
the application pages.
•

Log errors. ColdFusion logs certain errors by default. You can use the cflog tag to log other errors.

The remaining sections in this chapter provide the following information:

•

The basic building blocks for understating types of ColdFusion errors and how ColdFusion handles them

•

How to use the cferror tag to specify error-handling pages

ADOBE COLDFUSION 8 247
ColdFusion Developer’s Guide

•

How to log errors

•

How to handle ColdFusion exceptions

Note: This chapter discusses using the cftry and cfcatch tags, but not the equivalent CFScript try and catch statements. The general discussion of exception handling in this chapter applies to tags and CFScript statements. However,
the code that you use and the information available in CFScript differs from those in the tags. For more information on
handling exceptions in CFScript, see “Handling errors in UDFs” on page 147.

Understanding errors
There are many ways to look at errors; for example, you can look at errors by their causes. You can also look at them
by their effects, particularly by whether your application can recover from them. You can also look at them the way
ColdFusion does. The following sections discuss these ways of looking at errors.

About error causes and recovery
Errors can have many causes. Depending on the cause, the error might be recoverable. A recoverable error is one for
which your application can identify the error cause and take action on the problem. Some errors, such as time-out
errors, might be recoverable without indicating to the user that an error was encountered. An error for which a
requested application page does not exist is not recoverable, and the application can only display an error message.
Errors such as validation errors, for which the application cannot continue processing the request, but can provide
an error-specific response, can also be considered recoverable. For example, an error that occurs when a user enters
text where a number is required can be considered recoverable, because the application can recognize the error and
redisplay the data field with a message providing information about the error’s cause and telling the user to reenter
the data.
Some types of errors might be recoverable in some, but not all circumstances. For example, your application can retry
a request following a time-out error, but it must also be prepared for the case where the request always times out.
Error causes fall in the broad categories listed in the following table:
Category

Description

Program errors

Can be in the code syntax or the program logic. The ColdFusion compiler identifies and reports program syntax
errors when it compiles CFML into Java classes. Errors in your application logic are harder to locate. For information
on debugging tools and techniques, see “Debugging and Troubleshooting Applications” on page 351.
Unlike ColdFusion syntax errors, SQL syntax errors are only caught at runtime.

Data errors

Are typically user data input errors. You use validation techniques to identify errors in user input data and enable the
user to correct the errors.

System errors

Can come from a variety of causes, including database system problems, time-outs due to excessive demands on
your server, out-of-memory errors in the system, file errors, and disk errors.

Although these categories do not map completely to the way ColdFusion categorizes errors they provide a useful way
of thinking about errors and can help you in preventing and handling errors in your code.

ColdFusion error types
Before you can effectively manage ColdFusion errors, you must understand how ColdFusion classifies and handles
them. ColdFusion categorizes errors as detailed in the following table:

ADOBE COLDFUSION 8 248
ColdFusion Developer’s Guide

Type

Description

Exception

An error that prevents normal processing from continuing. All ColdFusion exceptions are, at their root,
Java exceptions.

Missing template

An HTTP request for a ColdFusion page that cannot be found. Generated if a browser requests a ColdFusion page that does not exist.
Missing template errors are different from missing include exceptions, which result from cfinclude tags
or custom tag calls that cannot find their targets.

Form field data validation

Server-side form field validation errors are a special kind of ColdFusion exception. You specify server-side
form validation by using cfform attributes or hidden HTML form fields. All other types of server-side validation, such as the cfparam tag generate runtime exceptions. For more information on validating form
fields see “Validating Data” on page 553.
ColdFusion includes a built-in error page for server-side form field validation errors, and the cferror tag
includes a type attribute that lets you handle these errors in a custom error page, but if you use onError
processing in Application.cfc, or try/catch error handling, the error appears as an Application exception.
For more information on handling Form field validation in Application.cfc see “Handling server-side validation errors in the onError method” on page 231..

Note: The onSubmit and onBlur form field validation techniques use JavaScript or Flash validation on the client
browser.

About ColdFusion exceptions
Most ColdFusion errors are exceptions. You can categorize ColdFusion exceptions in two ways:

•

When they occur

•

Their type

When exceptions occur

ColdFusion errors can occur at two times, when the CFML is compiled into Java and when the resulting Java
executes, called runtime exceptions.
Compiler exceptions

Compiler exceptions are programming errors that ColdFusion identifies when it compiles CFML into Java. Because
compiler exceptions occur before the ColdFusion page is converted to executable code, you cannot handle them on
the page that causes them. However, other pages can handle these errors. For more information, see “Handling
compiler exceptions” on page 253.
Runtime exception

A runtime exception occurs when the compiled ColdFusion Java code runs. It is an event that disrupts the application’s normal flow of instructions. Exceptions can result from system errors or program logic errors. Runtime
exceptions include:

•

Error responses from external services, such as an ODBC driver or CORBA server

•

CFML errors or the results of cfthrow or cfabort tags

•

Internal errors in ColdFusion

ColdFusion exception types

ColdFusion exceptions have types that you specify in the cferror, cfcatch, and cfthrow error-handling tags. A
cferror or cfcatch tag will handle only exceptions of the specified type. You identify an exception type by using
an identifier from one (or more) of the following type categories:

ADOBE COLDFUSION 8 249
ColdFusion Developer’s Guide

•

Basic

•

Custom

•

Advanced

•

Java class

Note: Use only custom error type names and the Application basic type name in cfthrow tags. All other built-in
exception type names identify specific types of system-identified errors, so you should not use them for errors that you
identify yourself.
Basic exception types

All ColdFusion exceptions except for custom exceptions belong to a basic type category. These types consist of a
broadly-defined categorization of ColdFusion exceptions. The following table describes the basic exception types:
Type

Type name

Description

Database failures

Database

Failed database operations, such as failed SQL statements, ODBC problems, and
so on.

Missing include file errors

MissingInclude

Errors where files specified by the cfinclude, cfmodule, and cferror tags are
missing. (A cferror tag generates a missingInclude error only when an error of
the type specified in the tag occurs.)
The MissingInclude error type is a subcategory of Template error. If you do not
specifically handle the MissingInclude error type, but do handle the Template
error type, the Template error handler catches these errors. MissingInclude
errors are caught at runtime.

Template errors

Template

General application page errors, including invalid tag and attribute names. Most
Template errors are caught at compile time, not runtime.

Object exceptions

Object

Exceptions in ColdFusion code that works with objects.

Security exceptions

Security

Catchable exceptions in ColdFusion code that works with security.

Expression exceptions

Expression

Failed expression evaluations; for example, if you try to add 1 and "a".

Locking exceptions

Lock

Failed locking operations, such as when a cflock critical section times out or
fails at runtime.

Verity Search engine
exception

SearchEngine

Exceptions generated by the Verity search engine when processing cfindex,
cfcollection, or cfsearch tags.

Application-defined
exception events raised by

Application

Custom exceptions generated by a cfthrow tag that do not specify a type, or
specify the type as Application.

Any

Any exceptions. Includes all types in this table and any exceptions that are not
specifically handled in another error handler, including unexpected internal and
external errors.

cfthrow

All exceptions

Note: The Any type includes all error with the Java object type of java.lang.Exception. It does not include
java.lang.Throwable errors. To catch Throwable errors, specify java.lang.Throwable in the cfcatch tag type attribute.
Custom exceptions

You can generate an exception with your own type by specifying a custom exception type name, for example MyCustomErrorType, in a cfthrow tag. You then specify the custom type name in a cfcatch or cferror tag to handle the
exception. Custom type names must be different from any built-in type names, including basic types and Java
exception classes.

ADOBE COLDFUSION 8 250
ColdFusion Developer’s Guide

Advanced exception types

The Advanced exceptions consist of a set of specific, narrow exception types. These types are supported in
ColdFusion for backward-compatibility. For a list of advanced exception types, see “Advanced exception types” on
page 72 in the CFML Reference.
Java exception classes

Every ColdFusion exception belongs to, and can be identified by, a specific Java exception class in addition to its
basic, custom, or advanced type. The first line of the stack trace in the standard error output for an exception
identifies the exception’s Java class.
For example, if you attempt to use an array function such as ArrayIsEmpty on an integer variable, ColdFusion
generates an exception that belongs to the Expression exception basic type and the
coldfusion.runtime.NonArrayException Java class.
In general, most applications do not need to use Java exception classes to identify exceptions. However, you can use
Java class names to catch exceptions in non-CFML Java objects; for example, the following line catches all Java
input/output exceptions:


How ColdFusion handles errors
The following sections describe briefly how ColdFusion handles errors. The rest of this chapter expands on this
information.
Missing template errors

If a user requests a page that the ColdFusion cannot find, and the Administrator Server Settings Missing Template
Handler field specifies a Missing Template Handler page, ColdFusion uses that page to display error information.
Otherwise, it displays a standard error message.
Form field validation errors

When a user enters invalid data in an HTML tag that uses onServer or hidden form field server-side data validation
ColdFusion does the following:
1

If the Application CFC (Application.cfc) has an onError event handler method, ColdFusion calls the method.

2 If the Application.cfc initialization code or the Application.cfm page has a cferror that specifies a Validation
error handler, ColdFusion displays the specified error page.
3 Otherwise, it displays the error information in a standard format that consists of a default header, a bulleted list
describing the errors, and a default footer.

For more information on using hidden form field validation, see “Validating Data” on page 553. For more information on Application.cfc, see “Designing and Optimizing a ColdFusion Application” on page 218.
Compiler exception errors

If ColdFusion encounters a compiler exception, how it handles the exception depends on whether the error occurs
on a requested page or on an included page:

• If the error occurs on a page that is accessed by a cfinclude or cfmodule tag, or on a custom tag page that you
access using the cf_ notation, ColdFusion handles it as a runtime exception in the page that accesses the tag. For a
description of how these errors are handled, see the next section, “Runtime exception errors.”

ADOBE COLDFUSION 8 251
ColdFusion Developer’s Guide

• If the error occurs directly on the requested page, and the Administrator Settings Site-wide Error Handler field
specifies an error handler page, ColdFusion displays the specified error page. Otherwise, ColdFusion reports the
error using the standard error message format described in “Error messages and the standard error format” on
page 251.
Runtime exception errors

If ColdFusion encounters a runtime exception, it does the action for the first matching condition in the following
table:
Condition

Action

The code with the error is inside a cftry tag and the
exception type is specified in a cfcatch tag.

Executes the code in the cfcatch tag.

The ColdFusion application has an Application.cfc with
an onError method

Executes the code in the onError method. For more information on using the
onError method, see “Handling errors in Application.cfc” on page 231.

A cferror tag specifies an exception error handler for
the exception type.

Uses the error page specified by the cferror tag.

The Administrator Settings Site-wide Error Handler field
specifies an error handler page.

Uses the custom error page specified by the Administrator setting.

A cferror tag specifies a Request error handler.

Uses the error page specified by the cferror tag.

The default case.

Uses the standard error message format

If the cftry block does not have a cfcatch tag for this error, tests for an appropriate cferror handler or site-wide error handler.

For example, if an exception occurs in CFML code that is not in a cftry block, and Application.cfc does not have
an onError method, but a cferror tag specifies a page to handle this error type, ColdFusion uses the specified error
page.

Error messages and the standard error format
If your application does not handle an error, ColdFusion displays a diagnostic message in the user’s browser.
Error information is also written to a log file for later review. (For information on error logging, see “Logging errors
with the cflog tag” on page 256.)
The standard error format consists of the information listed in the following table. ColdFusion does not always
display all sections.
Section

Description

Error description

A brief, typically on-line, description of the error.

Error message

A detailed description of the error. The error message diagnostic information displayed depends on the type of error.
For example, if you specify an invalid attribute for a tag, this section includes a list of all valid tag attributes.

Error location

The page and line number where ColdFusion encountered the error, followed by a short section of your CFML that
includes the line. This section does not display for all errors.
In some cases, the cause of an error can be several lines above the place where ColdFusion determines that there is
a problem, so the line that initially causes the error might not be in the display.

ADOBE COLDFUSION 8 252
ColdFusion Developer’s Guide

Section

Description

Resources

Links to documentation, the Knowledge Base, and other resources that can help you resolve the problem.

Error environment
information

Information about the request that caused the error. All error messages include the following:

Stack trace

•

User browser

•

User IP address

•

Date and time of error

The Java stack at the time of the exception, including the specific Java class of the exception. This section can be
helpful if you must contact Adobe Technical Support.
The stack trace is collapsed by default. Click the heading to display the trace.

If you get a message that does not explicitly identify the cause of the error, check the key system parameters, such as
available memory and disk space.

Determining error-handling strategies
ColdFusion provides you with many options for handling errors, particularly exceptions, as described in the section
“How ColdFusion handles errors” on page 250. This section describes considerations for determining which forms
of error handling to use.

Handling missing template errors
Missing template errors occur when ColdFusion receives an HTTP request for a page ending in .cfm that it cannot
find. You can create your own missing template error page to present application-specific information or provide an
application-specific appearance. You specify the missing template error page on the Administrator Settings page.
The missing error page can use CFML tags and variables. In particular, you can use the CGI.script_name variable in
text such as the following to identify the requested page:
The page #Replace(CGI.script_name, "/", "")# is not available.

Make sure that you entered the page correctly.



(In this code, the Replace function removes the leading slash sign from the script name to make the display more
friendly.)

Handling form field validation errors
When you use server-side form field validation, the default validation error message describes the error cause plainly
and clearly. However, you might want to give the error message a custom look or provide additional information such
as service contact phone numbers and addresses. In this case, use the cferror tag with the Validation attribute in
the Application.cfc initialization code or on the Application.cfm page to specify your own validation error handler.
The section “Example of a validation error page” on page 256 provides an example of such a page. You can also put
form field validation error handling code in the Application.cfc onError method.

ADOBE COLDFUSION 8 253
ColdFusion Developer’s Guide

Handling compiler exceptions
You cannot handle compiler exceptions directly on the page where they occur, because the exception is caught before
ColdFusion starts running the page code. You should fix all compiler exceptions as part of the development process.
Use the reported error message and the code debugging techniques discussed in “Debugging and Troubleshooting
Applications” on page 351 to identify and correct the cause of the error.
Compiler exceptions that occur on pages you access by using the cfinclude or cfmodule tags can actually be
handled as runtime errors by surrounding the cfinclude or cfmodule tag in a cftry block. The compiler exception
on the accessed page gets caught as a runtime error on the base page. However, you should avoid this "solution" to
the problem, as the correct method for handling compiler errors is to remove them before you deploy the application.

Handling runtime exceptions
You have many choices for handling exceptions, and the exact path you take depends on your application and its
needs. The following table provides a guide to selecting an appropriate technique:
Technique

Use

cftry

Place cftry blocks around specific code sections where exceptions can be expected and you want to handle those
exceptions in a context-specific manner; for example, if you want to display an error message that is specific to that
code.
Use cftry blocks where you can recover from an exception. For example, you can retry an operation that times out,
or access an alternate resource. You can also use the cftry tag to continue processing where a specific exception
will not harm your application; for example, if a missing resource is not required.
For more information, see “Handling runtime exceptions with ColdFusion tags” on page 258.

Application.cfc
onError method

cferror with

exception- specific
error handler pages

Implement the onError method in your Application.cfc to consistently handle application-specific exceptions
that might be generated by multiple code sections in the application. For more information on error handling using
Application.cfc, see “Handling errors in Application.cfc” on page 231.
Use the cferror tag to specify error pages for specific exception types. These pages cannot recover from errors, but
they can provide the user with information about the error’s cause and steps that they can take to prevent the
problem.
For more information, see “Specifying custom error messages with the cferror tag” on page 254.

cferror with a
Request error page

Use the cferror tag to specify a Request error handler that provides a customized, application-specific message
for unrecoverable exceptions. Put the tag in the Application.cfc initialization code or on the Application.cfm page to
make it apply to all pages in an application.
A Request error page cannot use CFML tags, but it can display error variables. As a result, you can use it to display
common error information, but you cannot provide error-specific instructions. Typically, Request pages display error
variable values and application-specific information, including support contact information.
For example code, see “Example of a request error page” on page 255.

Site-wide error
handler page

Specify a site-wide error handler in the Administrator to provide consistent appearance and contents for all otherwise-unhandled exceptions in all applications on your server.
Like the Request page, the site-wide error handler cannot perform error recovery. However, it can include CFML tags
in addition to the error variables.
Because a site-wide error handler prevents ColdFusion from displaying the default error message, it allows you to
limit the information reported to users. It also lets you provide all users with default contact information or other
instructions.

ADOBE COLDFUSION 8 254
ColdFusion Developer’s Guide

Specifying custom error messages with the cferror tag
Custom error pages let you control the error information that users see. You can specify custom error pages for
different types of errors and handle different types of errors in different ways. For example, you can create specific
pages to handle errors that could be recoverable, such as request time-outs. You can also make your error messages
consistent with the look and feel of your application.
You can specify the following types of custom error message pages:
Type

Description

Validation

Handles server-side form field data validation errors. The validation error page cannot include CFML tags, but it can
display error page variables.
You can use this attribute only in the Application.cfc initialization code or on the Application.cfm page. It has no
effect when used on any other page. Therefore, you can specify only one validation error page per application, and
that page applies to all server-side validation errors.

Exception

Handles specific exception errors. You can specify individual error pages for different types of exceptions.

Request

Handles any exception that is not otherwise-handled. The request error page runs after the CFML language
processor finishes. As a result, the request error page cannot include CFML tags, but can display error page variables.
A request error page is useful as a backup if errors occur in other error handlers.

Specifying a custom error page
You specify the custom error pages with the cferror tag. For Validation errors, the tag must be in the Application.cfc
initialization code or on the Application.cfm page. For Exception and Request errors, you can set the custom error
pages on each application page. However, because custom error pages generally apply to an entire application, it is
more efficient to put these cferror tags in the Application.cfc or Application.cfm file also. For more information on
using these pages, see “Designing and Optimizing a ColdFusion Application” on page 218
The cferror tag has the attributes listed in the following table:
Attribute

Description

Type

The type of error that will cause ColdFusion to display this page: Exception, Request, or Validation.

Exception

Use only for the Exception type. The specific exception or exception category that will cause the page to be
displayed. This attribute can specify any of the types described in “About ColdFusion exceptions” on page 248.

Template

The ColdFusion page to display.

MailTo

(Optional) An e-mail address. The cferror tag sets the error page error.mailTo variable to this value. The error
page can use the error.mailTo value in a message that tells the user to send an error notification. ColdFusion does
not send any message itself.

The following cferror tag specifies a custom error page for exceptions that occur in locking code and informs the
error page of the of an e-mail address it can use to send a notification each time this type of error occurs:


For detailed information on the cferror tag, see the CFML Reference.

ADOBE COLDFUSION 8 255
ColdFusion Developer’s Guide

Creating an error application page
The following table lists the rules and considerations that apply to error application pages:
Type
Validation

Considerations

•

Cannot use CFML tags.

•

Can use HTML tags.

• Can use the Error.InvalidFields, Error.validationHeader, and Error.validationFooter variables by enclosing them with number signs (#).

Request

Exception

•

Cannot use any other CFML variables.

•

Cannot use CFML tags.

•

Can use HTML tags.

•

Can use nine CFML error variables, such as Error.Diagnostics, by enclosing them with number signs.

•

Cannot use other CFML variables.

•

Can use full CFML syntax, including tags, functions, and variables.

•

Can use nine standard CFML Error variables and cfcatch variables. Use either Error or cferror as the prefix for
both types of variables.

•

Can use other application-defined CFML variables.

•

To display any CFML variable, use the cfoutput tag.

The following table describes the variables available on error pages: Exception error pages can also use all of the
exception variables listed in the section “Exception information in cfcatch blocks” on page 260. To use these
variables, replace the cfcatch prefix with cferror or error. For example, to use the exception message in an error
page, refer to it as error.message.
In general, production Exception and Request pages should not display detailed error information, such as that
supplied by the error.diagnostics variable. Typically, Exception pages e-mail detailed error information to an
administrative address or log the information using the cflog tag instead of displaying it to the user. For more information on using the cflog tag, see “Logging errors with the cflog tag” on page 256.
Example of a request error page

The following example shows a custom error page for a request error:





Sorry
An error occurred when you requested this page.
Please send e-mail with the following information to #error.mailTo# to report
this error.

Error Information 

Date and time: #error.DateTime# 

Page: #error.template# 

Remote Address: #error.remoteAddress# 

HTTP Referer: #error.HTTPReferer#



ADOBE COLDFUSION 8 256
ColdFusion Developer’s Guide

We apologize for the inconvenience and will work to correct the problem.


Example of a validation error page

The following example shows a simple custom error page for a validation error:





Data Entry Error
You failed to correctly complete all the fields
in the form. The following problems occurred:
#error.invalidFields#



Logging errors with the cflog tag
ColdFusion provides extensive capabilities for generating, managing, and viewing log files, as described in Configuring and Administering ColdFusion. It also provides the cflog tag which adds entries to ColdFusion logs.
ColdFusion automatically logs errors to the default logs if you use the default error handlers. In all other cases, you
must use the cflog tag in your error handling code to generate log entries.
The cflog tag lets you specify the following information:

•

A custom file or standard ColdFusion log file in which to write the message.

•

Text to write to the log file. This can include the values of all available error and cfcatch variables.

•

Message severity (type): Information Warning, Fatal, or Error.

• Whether to log any of the following: application name, thread ID, system date, or system time. By default, all get
logged.
For example, you could use a cflog tag in an exception error-handling page to log the error information to an application-specific log file, as in the following page:





Sorry
An error occurred when you requested this page.
The error has been logged and we will work to correct the problem.
We apologize for the inconvenience. 



Reviewing the code

The following table describes the highlighted code and its function:
Code

Description



When this page is processed, log an entry in the file myapp_errors.log file in the
ColdFusion log directory. Identify the entry as an error message and include an
error message that includes the exception type, the path of the page that caused
the error, the remote address that called the page, and the error’s diagnostic
message.

A log file entry similar to the following is generated if you try to call a nonexistent custom tag and this page catches
the error (line breaks added for clarity):
"Error","web-13","12/19/01","11:29:07",MYAPP,"Exception error -Exception type: coldfusion.runtime.CfErrorWrapper
Template: /MYStuff/MyDocs/exceptiontest.cfm,
Remote Address: 127.0.0.1,
HTTP Reference:
Diagnostics: Cannot find CFML template for custom tag testCase. Cannot
find CFML template for custom tag testCase. ColdFusion attempted looking
in the tree of installed custom tags but did not find a custom tag with
this name."

The text consists of a comma-delimited list of the following entries:

•

Log entry type, specified by the cflog type attribute

•

ID of the thread that was executing

•

Date the entry was written to the log

•

Time the entry was written to the log

• Application name, as specified in the Application.cfc initialization code (by setting the This.application variable)
or by a cfapplication tag (for example, in an Application.cfm file).
•

The message specified by the cflog text attribute.

ADOBE COLDFUSION 8 258
ColdFusion Developer’s Guide

Handling runtime exceptions with ColdFusion tags
Exceptions include any event that disrupts the normal flow of instructions in a ColdFusion page, such as failed
database operations, missing include files, or developer-specified events. Ordinarily, when ColdFusion encounters
an exception, it stops processing and displays an error message, or an error page specified by a cferror tag or the
Site-wide Error Handler option on the Settings page in the Administrator. However, you can use the ColdFusion
exception handling tags to catch and process runtime exceptions directly in ColdFusion pages.
This ability to handle exceptions directly in your application pages enables your application to do the following:

•

Respond appropriately to specific errors within the context of the current application page

•

Recover from errors whenever possible.

Exception-handling tags
ColdFusion provides the exception-handling tags listed in the following table:
Tag

Description

cftry

If any exceptions occur while processing the tag body, look for a cfcatch tag that handles the exception, and
execute the code in the cfcatch tag body.

cfcatch

Execute code in the body of this tag if the exception caused by the code in the cftry tag body matches the exception type specified in this tag’s attributes.
Used in cftry tag bodies only.

cfthrow

Generate a user-specified exception.

cfrethrow

Exit the current cfcatch block and generates a new exception of the same type.
Used only in cfcatch tag bodies.

Using cftry and cfcatch tags
The cftry tag lets you go beyond reporting error data to the user:

• You can include code that recovers from errors so your application can continue processing without alerting the
user.
•

You can create customized error messages that apply to the specific code that causes the error.

For example, you can use cftry to catch errors in code that enters data from a user registration form to a database.
The cfcatch code could do the following:
1

Retry the query, so the operation succeeds if the resource was only temporarily unavailable.

2

If the retries fail:

•

Display a custom message to the user

• Post the data to an email address so the data could be entered by company staff after the problem has been
solved.
Code that accesses external resources such as databases, files, or LDAP servers where resource availability is not
guaranteed is a good candidate for using try/catch blocks.

ADOBE COLDFUSION 8 259
ColdFusion Developer’s Guide

Try/catch code structure

In order for your code to directly handle an exception, the tags in question must appear within a cftry block. It is a
good idea to enclose an entire application page in a cftry block. You then follow the cftry block with cfcatch
blocks, which respond to potential errors. When an exception occurs within the cftry block, processing is thrown
to the cfcatch block for that type of exception.
Here is an outline for using cftry and cfcatch to handle errors:

Put your application code here ...

Add exception processing code here ...


Add exception processing code here ...

...

Add exception processing code appropriate for all other exceptions here ...


Try/catch code rules and recommendations

Follow these rules and recommendations when you use cftry and cfcatch tags:

•

The cfcatch tags must follow all other code in a cftry tag body.

•

You can nest cftry blocks. For example, the following structure is valid:

code that may cause an exception


First level of exception handling code

Second level of exception handling code




If an exception occurs in the first level of exception-handling code, the inner cfcatch block can catch and
handle it. (An exception in a cfcatch block cannot be handled by cfcatch blocks at the same level as that
block.)

• ColdFusion always responds to the latest exception that gets raised. For example, if code in a cftry block causes
an exception that gets handled by a cfcatch block, and the cfcatch block causes an exception that has no handler,
ColdFusion will display the default error message for the exception in the cfcatch block, and you will not be
notified of the original exception.
• If an exception occurs when the current tag is nested inside other tags, the CFML processor checks the entire
stack of open tags until it finds a suitable cftry/cfcatch combination or reaches the end of the stack.
• Use cftry with cfcatch to handle exceptions based on their point of origin within an application page, or based
on diagnostic information.
•

The entire cftry tag, including all its cfcatch tags, must be on a single ColdFusion page. You cannot put the

 start tag on one page and have the  end tag on another page.

ADOBE COLDFUSION 8 260
ColdFusion Developer’s Guide

• For cases when a cfcatch block is not able to successfully handle an error, consider using the cfrethrow tag,
as described in “Using the cfrethrow tag” on page 267.
•

If an exception can be safely ignored, use a cfcatch tag with no body; for example:


1

In particularly problematic cases, you might enclose an exception-prone tag in a specialized combination of

cftry and cfcatch tags to immediately isolate the tag's exceptions.
Exception information in cfcatch blocks

Within the body of a cfcatch tag, the active exception’s properties are available in a cfcatch object. The following
sections describe the object contents.
Standard cfcatch variables

The following table describes the variables that are available in most cfcatch blocks:
Property variable

Description

cfcatch.Detail

A detailed message from the CFML compiler. This message, which can contain HTML formatting, can help to
determine which tag threw the exception.
The cfcatch.Detail value is available in the CFScript catch statement as the exceptionVariable
parameter.

cfcatch.ErrorCode

The cfthrow tag can supply a value for this code through the errorCode attribute. For Type="Database",
cfcatch.ErrorCode has the same value as cfcatch.SQLState.
Otherwise, the value of cfcatch.ErrorCode is the empty string.

cfcatch.ExtendedInf
o

Custom error message information. This is returned only to cfcatch tags for which the type attribute is
Application or a custom type.
Otherwise, the value of cfcatch.ExtendedInfo is the empty string.

cfcatch.Message

The exception’s default diagnostic message, if one was provided. If no diagnostic message is available, this is
an empty string.
The cfcatch.Message value is included in the value of the CFScript catch statement exceptionVariable
parameter.

cfcatch.RootCause

The Java servlet exception reported by the JVM as the cause of the “root cause” of the exception.

cfcatch.TagContext

An array of structures structure containing information for each tag in the tag stack The tag stack consists of
each tag that is currently open.

cfcatch.Type

The exception’s type, returned as a string.

Note: If you use the cfdump tag to display the cfcatch variable, the display does not include variables that do not have
values.
The cfcatch.TagContext variable contains an array of tag information structures. Each structure represents one
level of the active tag context at the time when ColdFusion detected the exception. That is, there is one structure for
each tag that is open at the time of the exception. For example, if the exception occurs in a tag on a custom tag page,
the tag context displays information about the called custom tag and the tag in which the error occurs.
The structure at position 1 in the array represents the currently executing tag at the time the exception was detected.
The structure at position ArrayLen(cfcatch.tagContext) represents the initial tag in the stack of tags that were
executing when the compiler detected the exception.
The following table lists the tagContext structure attributes:

ADOBE COLDFUSION 8 261
ColdFusion Developer’s Guide

Entry

Description

Column

Obsolete (retained for backwards compatibility). Always 0.

ID

The tag in which the exception occurred. Exceptions in CFScript are indicated by two question
marks (??). All custom tags, including those called directly, are identified as cfmodule.

Line

The line on the page in which the tag is located.

Raw_Trace

The raw Java stack trace for the error.

Template

The pathname of the application page that contains the tag.

Type

The type of page; it is always a ColdFusion page.

Database exceptions

The following additional variables are available whenever the exception type is database:
Property variable

Description

cfcatch.NativeErrorCode

The native error code associated with this exception. Database drivers typically provide error codes
to assist in the diagnosis of failing database operations. The values assumed by
cfcatch.NativeErrorCode are driver-dependent.
If no error code is provided, the value of cfcatch.nativeErrorCode is -1. The value is 0 for
queries of queries.

cfcatch.SQLState

The SQLState code associated with this exception. Database drivers typically provide error codes
to assist in the diagnosis of failing database operations. SQLState codes are more consistent across
database systems than native error codes.
If the driver does not provide an SQLState value, the value of cfcatch.SQLState is -1.

cfcatch.Sql

The SQL statement sent to the data source.

cfcatch.queryError

The error message as reported by the database driver.

cfcatch.where

If the query uses the cfqueryparam tag, query parameter name-value pairs.

Expression exceptions

The following variable is only available for Expression exceptions:
Property variable

Description

cfcatch.ErrNumber

An internal expression error number, valid only when type="Expression".

Locking exceptions

The following additional information is available for exceptions related to errors that occur in cflock tags:
Property variable

Description

cfcatch.lockName

The name of the affected lock. This is set to "anonymous" if the lock name is unknown.

cfcatch.lockOperation

The operation that failed. This is set to "unknown" if the failed operation is unknown.

Missing include exceptions

The following additional variable is available if the error is caused by a missing file specified by a cfinclude tag:

ADOBE COLDFUSION 8 262
ColdFusion Developer’s Guide

Property variable

Description

cfcatch.missingFileName

The name of the missing file.

Using the cftry tag: an example
The following example shows the cftry and cfcatch tags. It uses the cfdocexamples data source, which many of
the examples in this manual use, and a sample included file, includeme.cfm.
If an exception occurs during the cfquery statement's execution, the application page flow switches to the cfcatch
type="Database" exception handler. It then resumes with the next statement after the cftry block, once the
cfcatch type="Database" handler completes. Similarly, the cfcatch type="MissingInclude" block handles
exceptions raised by the cfinclude tag.





SELECT Dept_ID, FirstName, LastName
FROM Employee
WHERE Emp_ID=#EmpID#








Department: #Dept_ID#

Last Name: #LastName#

First Name: #FirstName#





Missing Include File


Message: #cfcatch.Message#
Detail: #cfcatch.Detail#
Filename: #cfcatch.MissingFileName#








Database Error


Message: #cfcatch.Message#

ADOBE COLDFUSION 8 263
ColdFusion Developer’s Guide

Native error code: #cfcatch.NativeErrorCode#
SQLState: #cfcatch.SQLState#
Detail: #cfcatch.Detail#









Other Error: #cfcatch.Type#

Message: #cfcatch.Message#
Detail: #cfcatch.Detail#








Use the following procedure to test the code.
Test the code
1 Make sure there is no includeme.cfm file and display the page. The cfcatch type="MissingInclude" block

displays the error.
2 Create a nonempty includeme.cfm file and display the page. If your database is configured properly, you should
see an employee entry and not get any error.
3

In the cfquery tag, change the line:
FROM Employee

to:
FROM Employer

Display the page. This time the cfcatch type="Database" block displays an error message.
4

Change Employer to Employee.
Change the cfoutput line:
Department: #Dept_ID#


to:
Department: #DepartmentID#


Display the page. This time the cfcatch type="Any" block displays an error message indicating an expression
error.
5

Change DepartmentID back to Dept_ID and redisplay the page. The page displays properly.
Open \CFusion\Log\MyAppPage.log in your text editor. You should see a header line, an initialization line, and
four detail lines, similar to the following:
"Severity","ThreadID","Date","Time","Application","Message"

ADOBE COLDFUSION 8 264
ColdFusion Developer’s Guide

"Information","web-0","11/20/01", "16:27:08",, "cf_root\runtime\servers\default\logs\
MyAppPage.log initialized"
"Information","web-0","11/20/01","16:27:08",,
"Page: web_root/MYStuff/MyDocs/ cftryexample.cfm Error: MissingInclude"
"Information","web-1","11/20/01","16:27:32",,"
Page: web_root/MYStuff/MyDocs/ cftryexample.cfm Error: "
"Information","web-0","11/20/01","16:27:49",,
"Page: web_root/MYStuff/MyDocs/ cftryexample.cfm Error: Database"
"Information","web-1","11/20/01","16:28:21",,
"Page: web_root/MYStuff/MyDocs/ cftryexample.cfm Error: General Exception"
"Information","web-0","11/20/01","16:28:49",,
"Page: web_root/MYStuff/MyDocs/ cftryexample.cfm Error: "
Reviewing the code

The following table describes the code:
Code

Description




Initializes the employee ID to a valid value. An application would get the
value from a form or other source.
Sets the default errorCaught variable value to the empty string (to indicate no error was caught).
There is no need to put these lines in a cftry block.



SELECT Dept_ID, FirstName, LastName
FROM Employee
WHERE Emp_ID=#EmpID#


Starts the cftry block. Exceptions from here to the end of the block can be
caught by cfcatch tags.








Department: #Dept_ID#

Last Name: #LastName#

First Name: #FirstName#


Begins the HTML page. This section contains all the code that displays
information if no errors occur.


Missing Include File


Message:
#cfcatch.Message#
Detail: #cfcatch.Detail#
Filename:
#cfcatch.MissingFilename#





Handles exceptions thrown when a page specified by the cfinclude tag
cannot be found.

Queries the cfdocexamples database to get the data for the employee
identified by the EmpID variable.

Includes the includeme.cfm page.
Displays the user information record from the test query.

Displays cfcatch variables, including the ColdFusion basic error message,
detail message, and the name of the file that could not be found.
Sets the errorCaught variable to indicate the error type.

ADOBE COLDFUSION 8 265
ColdFusion Developer’s Guide

Code

Description


Database Error


Message:
#cfcatch.Message#
Native error code:
#cfcatch.NativeErrorCode#
SQLState:
#cfcatch.SQLState#
Detail: #cfcatch.Detail#





Handles exceptions thrown when accessing a database.




Other Error: #cfcatch.Type#

Message:
#cfcatch.message#
Detail:
#cfcatch.Detail#





Handles any other exceptions generated in the cftry block.





Ends the HTML page, then the cftry block.

Displays cfcatch variables, including the ColdFusion basic error message,
the error code and SQL state reported by the databases system, and the
detailed error message.
Sets the errorCaught variable to indicate the error type.

Since the error can occur after information has displayed (in this case, the
contents of the include file), draws a line before writing the message text.
Displays the ColdFusion basic and detailed error message.
Sets the errorCaught variable to indicate the error type.

Using the cfthrow tag
You can use the cfthrow tag to raise your own, custom exceptions. When you use the cfthrow tag, you specify any
or all of the following information:
Attribute

Meaning

type

The type of error. It can be a custom type that has meaning only to your application, such as InvalidProductCode.
You can also specify Application, the default type. You cannot use any of the predefined ColdFusion error types, such
as Database or MissingTemplate.

message

A brief text message indicating the error.

detail

A more detailed text message describing the error.

errorCode

An error code that is meaningful to the application. This field is useful if the application uses numeric error codes.

extendedInfo

Any additional information of use to the application.

All of these values are optional. You access the attribute values in cfcatch blocks and Exception type error pages by
prefixing the attribute with either cfcatch or error, as in cfcatch.extendedInfo. The default ColdFusion error
handler displays the message and detail values in the Message pane and the remaining values in the Error Diagnostic
Information pane.
Catching and displaying thrown errors

The cfcatch tag catches a custom exception when you use any of the following values for the cfcatch type
attribute:

•

The custom exception type specified in the cfthrow tag.

ADOBE COLDFUSION 8 266
ColdFusion Developer’s Guide

• A custom exception type that hierarchically matches the initial portion of the type specified in the cfthrow tag.
For more information, see the next section, Custom error type name hierarchy.
• Application, which matches an exception that is thrown with the Application type attribute or with no type
attribute.
•

Any, which matches any exception that is not caught by a more specific cfcatch tag.

Similarly, if you specify any of these types in a cferror tag, the specified error page will display information about
the thrown error.
Because the cfthrow tag generates an exception, a Request error handler or the Site-wide error handler can also
display these errors.
Custom error type name hierarchy

You can name custom exception types using a method that is similar to Java class naming conventions: domain name
in reverse order, followed by project identifiers, as in the following example:


This fully qualified naming method is not required; you can use shorter naming rules, for example, just
myApp.Invalid_field.codeValue, or even codeValue.
This naming method is not just a convention; ColdFusion uses the naming hierarchy to select from a possible
hierarchy of error handlers. For example, assume you use the following cfthrow statement:


Any of the following cfcatch error handlers would handle this error:




The handler that most exactly matches handles the error. In this case, the
MyApp.BusinessRuleException.InvalidAccount handler gets invoked. However, if you used the following
cfthrow tag:


Handle it





General Error Handling code



Although this example uses a Database error as an example, you can use any cfcatch type attribute in the innermost
error type.
Follow these rules when you use the cfrethrow tag:

• Nest cftry tags, with one tag for each level of error handling hierarchy. Each level contains the cfcatch tags for
that level of error granularity.
•

Place the most general error catching code in the outermost cftry block.

•

Place the most specific error catching code in the innermost cftry block.

•

Place the code that can cause an exception error at the top of the innermost cftry block.

•

End each cfcatch block except those in the outermost cftry block with a cfrethrow tag.

Example: using nested tags, cfthrow, and cfrethrow
The following example shows many of the techniques discussed in this chapter, including nested cftry blocks and
the cfthrow and cfrethrow tags. The example includes a simple calling page and a custom tag page:

• The calling page does little more than call the custom tag with a single attribute, a name to be looked up in a
database. It does show, however, how a calling page can handle an exception thrown by the custom tag.
• The custom tag finds all records in the cfdocexamples database with a matching last name, and returns the results
in a Caller variable. If it fails to connect with the main database, it tries a backup database.
The calling page

The calling page represents a section from a larger application page. To keep things simple, the example hard-codes
the name to be looked up.




ADOBE COLDFUSION 8 268
ColdFusion Developer’s Guide

Oops
#cfcatch.Message#






Reviewing the code

The following table describes the code:
Code

Description



In a cftry block, calls the cf_getEmps custom tag (getEmps.cfm).



Oops

If the tag throws an exception indicating that it did not receive a valid
attribute, catches the exception and displays a message, including the
message variable set by the cfthrow tag in the custom tag.

#cfcatch.Message#






If the tag returns a result, uses the cfdump tag to display it. (A production
application would not use the cfdump tag.)



The custom tag page

The custom tag page searches for the name in the database and returns any matching records in a getEmpsResult
variable in the calling page. It includes several nested cftry blocks to handle error conditions. For a full description,
see “Reviewing the code” on page 269, following the example:
Save the following code as getEmps.cfm in the same directory as the calling page.












SELECT *
FROM Employee
WHERE LastName = '#attributes.EmpName#'






ADOBE COLDFUSION 8 269
ColdFusion Developer’s Guide





SELECT *
FROM Employee
WHERE LastName = '#attributes.EmpName#'





















Sorry
An unexpected error happened in processing your user inquiry.
Please report the following to technical support:

Type: #cfcatch.Type#
Message: #cfcatch.Message#





Reviewing the code

The following table describes the code:

ADOBE COLDFUSION 8 270
ColdFusion Developer’s Guide

Code

Description


cfthrow Type="myApp.getUser.noEmpName"
message = "Last Name was not supplied to
the cf_getEmps tag.">


Makes sure the calling page specified an EmpName attribute. If not, throws
a custom error that indicates the problem and exits the tag. The calling
page handles the thrown error.




If the tag has an EmpName attribute, does the remaining work inside an
outermost try block. The cfcatch block at its end handles any otherwiseuncaught exceptions.



SELECT *
FROM Employee
WHERE LastName = '#attributes.EmpName#'



Starts a second nested try block. This block catches exceptions in the database query.








If there are no exceptions, sets the calling page’s getEmpsResult variable
with the query results.

If the query threw a Database error, checks to see if the error was caused by
an inability to access the database (indicated by an SQLState variable
value of S100 or IM002).
If the database was not found, starts a third nested try block and tries
accessing the backup database. This try block catches exceptions in this
second database access.
If the database inquiry succeeds, sets the calling page’s getEmpsResult
variable with the query results.
If the second database query failed with a database error, gives up silently.
Because the Database type cfcatch tag does not have a body, the tag
exits. The calling page does not get a getEmpsResult variable. It cannot
tell whether the database had no match or an unrecoverable database
error occurred, but it does know that no match was found.






If the second database query failed for any other reason, throws the error
up to the next try block.






In the second try block, handles the case in which the first database query
failed for a reason other than a failure to find the database.






In the second try block, catches any errors other exceptions and rethrows
them up to the outermost try block.


Sorry
An unexpected error happened in
processing
your user inquiry.
Please report the following to technical
support:

Type: #cfcatch.Type#
Message: #cfcatch.Message#






In the outermost try block, handles any exceptions by displaying an error
message that includes the exception type and the exception’s error
message. Because there was no code to try that is not also in a nested try
block, this cfcatch tag handles only errors that are rethrown from the
nested blocks.

Ends the innermost try block

Rethrows the error up to the next level, the outermost try block.

Ends the second try block.

Exits the custom tag and returns to the calling page.
Ends the catch block, try block, and initial cfif block.

ADOBE COLDFUSION 8 271
ColdFusion Developer’s Guide

Testing the code

To test the various ways errors can occur and be handled in this example, try the following:

•

In the calling page, change the attribute name to any other value; for example, My Attrib. Then change it back.

•

In the first cfquery tag, change the data source name to an invalid data source; for example, NoDatabase.

•

With an invalid first data source name, change the data source in the second cfquery tag to cfdocexamples.

•

Insert cfthrow tags throwing custom exculpations in various places in the code and observe the effects.

272

Chapter 16: Using Persistent Data and
Locking
ColdFusion provides several variable scopes in which data persists past the life of a single request. These are the
Client, Application, Session, and Server scopes. These scopes let you save data over time and share data between
pages and even applications. These scopes as persistent scopes. In particular, you can use the Client and Session
scopes to maintain information about a user across multiple requests.
ColdFusion lets you lock access to sections of code to ensure that ColdFusion does not attempt to run the code, or
access the data that it uses, simultaneously or in an unpredictable order. This locking feature is important for
ensuring the consistency of all shared data, including data in external sources in addition to data in persistent scopes.
You can use persistent scopes to develop an application and use locking to ensure data consistency.
Contents

About persistent scope variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Managing the client state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Configuring and using client variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Configuring and using session variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Configuring and using application variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Using server variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Locking code with cflock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Examples of cflock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

About persistent scope variables
ColdFusion provides four variable scopes, described in the following table, that let you maintain data that must be
available to multiple applications or users or must last beyond the scope of the current request.

ADOBE COLDFUSION 8 273
ColdFusion Developer’s Guide

Variable scope

Description

Client

Contains variables that are available for a single client browser over multiple browser sessions in an application. For
information about browser sessions, see, “What is a session?” on page 282.
Useful for client-specific information, such as client preferences, that you want to store for a significant period of
time.
Data is stored as cookies, database entries, or Registry values. Client variables can time out after an extended period.
Although do not have to use the Client scope prefix in the variable name, code that uses the prefix is more efficient
and easier to maintain.

Session

Contains variables that are available for a single client browser for a single browser session in an application.
Useful for client-specific information, such as shopping cart contents, that you want to persist while the client is
visiting your application.
Data is stored in memory and times out after a period of inactivity or when the server shuts down.
ColdFusion Administrator lets you select between two kinds of session management, Standard ColdFusion Session
management and J2EE session management. For information about types of session management, see “ColdFusion
and J2EE session management” on page 283.
You must use the Session scope prefix in the variable name.

Application

Contains variables that are available to all pages in an application for all clients.
Useful for application-specific information, such as contact information, that can vary over time and should be
stored in a variable.
Data is stored in memory and times out after a period of inactivity or when the server shuts down.
You must use the Application scope prefix in the variable name.

Server

Contains variables that are available to all applications in a server and all clients.
Useful for information that applies to all pages on the server, such as an aggregate page-hit counter.
Data is stored in memory. The variables do not time out, but you can delete variables you create, and all server variables are automatically deleted when the server stops running.
You must use the Server scope prefix in the variable name.

The following sections provide information that is common to all or several of these variables. Later sections
describe how to use the Client, Session, Application, and Server scopes in your applications, and provide detailed
information about locking code.

ColdFusion persistent variables and ColdFusion structures
All persistent scopes are available as ColdFusion structures. As a result, you can use ColdFusion structure functions
to access and manipulate Client, Session, Application, and Server scope contents. This chapter does not cover using
these functions in detail, but does mention features or limitations that apply to specific scopes.
Note: Although you can use the StructClear function to clear your data from the Server scope, the function does not
delete the names of the variables, only their values, and it does not delete the contents of the Server.os and
Server.ColdFusion structures. Using the StructClear function to clear the Session, or Application scope clears the
entire scope, including the built-in variables. Using the StructClear function to clear the Client scope clears the
variables from the server memory, but does not delete the stored copies of the variables.

ColdFusion persistent variable issues
Variables in the Session, Application, and Server scopes are kept in ColdFusion server memory. This storage method
has several implications:

ADOBE COLDFUSION 8 274
ColdFusion Developer’s Guide

•

All variables in these scopes are lost if the server stops running.

•

Variables in these scopes are not shared by servers in a cluster.

• To prevent race conditions and ensure data consistency, lock access to all code that changes variables in these
scopes or reads variables in these scopes with values that can change.
Note: If you use J2EE session management and configure the J2EE server to retain session data between server restarts,
ColdFusion retains session variables between server restarts.
Additionally, you must be careful when using client variables in a server cluster, where an application can run on
multiple servers.
Locking memory variables

Because ColdFusion is a multithreaded system in which multiple requests can share Session, Application, and Server
scope variables, it is possible for two or more requests to try to access and modify data at the same time. ColdFusion
runs in a J2EE environment, which prevents simultaneous data access, so multiple requests do not cause severe
system errors. However, such requests can result in inconsistent data values, particularly when a page might change
more than one variable.
To prevent data errors with session, application, and server variables, lock code that writes and reads data in these
scopes. For more information, see “Locking code with cflock” on page 289.
Using variables in clustered systems

Because memory variables are stored in memory, they are not available to all servers in a cluster. As a result, you
generally do not use Session, Application, or Server scope variables in clustered environment. However, you might
use these scope variables in a clustered system in the following circumstances:

• If the clustering system supports “sticky” sessions, in which the clustering system ensures that each user session
remains on a single server. In this case, you can use session variables as you would on a single server.
• You can use Application and Server scope variables in a cluster for write-once variables that are consistently set,
for example, from a database.
To use client variables on a clustered system, store the variables as cookies or in a database that is available to all
servers. If you use database storage, on one server only, select the Purge Data for Clients that Remain Unvisited
option on the Client Variables, Add/Edit Client Store page in the Server Settings area in the ColdFusion Administrator.
For more information on using client and session variables in clustered systems, see “Managing client identity information in a clustered environment” on page 277.

Managing the client state
Because the web is a stateless system, each connection that a browser makes to a web server is unique to the web
server. However, many applications must keep track of users as they move through the pages within the application.
This is the definition of client state management.
ColdFusion provides tools to maintain the client state by seamlessly tracking variables associated with a browser as
the user moves from page to page within the application. You can use these variables in place of other methods for
tracking client state, such as URL parameters, hidden form fields, and HTTP cookies.

ADOBE COLDFUSION 8 275
ColdFusion Developer’s Guide

About client and session variables
ColdFusion provides two tools for managing the client state: client variables and session variables. Both types of
variables are associated with a specific client, but you manage and use them differently, as described in the following
table:
Variable type

Description

Client

Data is saved as cookies, database entries, or Registry entries. Data is saved between server restarts, but is initially
accessed and saved more slowly than data stored in memory.
Each type of data storage has its own time-out period. You can specify the database and Registry data time-outs in
the ColdFusion Administrator. ColdFusion sets Cookie client variables to expire after approximately 10 years.
Data is stored on a per-user and per-application basis. For example, if you store client variables as cookies, the user
has a separate cookie for each ColdFusion application provided by a server.
Client variables must be simple variables, such as numbers, dates, or strings. They cannot be arrays, structures, query
objects, or other objects.
Client variable names can include periods. For example, My.ClientVar is a valid name for a simple client variable.
Avoid such names, however, to ensure code clarity.
You do not have to prefix client variables with the scope name when you reference them, However, if you do not use
the Client prefix, you might unintentionally refer to a variable with the same name in another scope. Using the prefix
also optimizes performance and increases program clarity.
You do not lock code that uses client variables.
You can use client variables that are stored in cookies or a common database in clustered systems.

Session

Data is stored in memory so it is accessed quickly.
Data is lost when the client browser is inactive for a time-out period. You specify the time-out in the ColdFusion
Administrator, the Application.cfc initialization code, or Application.cfm.
As with client variables, data is available to a single client and application only.
Variables can store any ColdFusion data type.
You must prefix all variable names with the Session scope name.
Lock code that uses session variables to prevent race conditions.
You can use session variables in clustered systems only if the systems support “sticky” sessions, where a session is
limited to a single server.

Session variables are normally better than client variables for values that need to exist for only a single browser
session. You should reserve client variables for client-specific data, such as client preferences that you want available
for multiple browser sessions.

Maintaining client identity
Because the web is a stateless system, client management requires some method for maintaining knowledge of the
client between requests. Normally you do this using cookies, but you can also do it by passing information between
application pages. The following sections describe how ColdFusion maintains client identity in a variety of configurations and environments, and discuss issues that can arise with client state management.
About client identifiers

To use client and session variables, ColdFusion must be able to identify the client. It normally does so by setting the
following two cookie values on the client’s system:

•

CFID: A sequential client identifier

ADOBE COLDFUSION 8 276
ColdFusion Developer’s Guide

•

CFToken: A random-number client security token

These cookies uniquely identify the client to ColdFusion, which also maintains copies of the variables as part of the
Session and Client scopes. You can configure your application so that it does not use client cookies, but in this case,
you must pass these variables to all the pages that your application calls. For more information about maintaining
client and session information without using cookies, see “Using client and session variables without cookies” on
page 276.
You can configure ColdFusion to use J2EE servlet session management instead of ColdFusion session management
for session variables. This method of session management does not use CFID and CFToken values, but does use a
client-side jsessionid session management cookie. For more information on using J2EE session management, see
“ColdFusion and J2EE session management” on page 283.
Using client and session variables without cookies

Often, users disable cookies in their browsers. In this case, ColdFusion cannot maintain the client state automatically.
You can use client or session variables without using cookies, by passing the client identification information
between application pages. However, this technique has significant limitations, as follows:
1 Client variables are effectively the same as session variables, except that they leave unusable data in the client data
store.

Because the client’s system does not retain any identification information, the next time the user logs on,
ColdFusion cannot identify the user with the previous client and must create a new client ID for the user. Any
information about the user from a previous session is not available, but remains in client data storage until
ColdFusion deletes it. If you clear the Purge Data for Clients that Remain Unvisited option in the ColdFusion
Administrator, ColdFusion never deletes this data.
Therefore, do not use client variables, if you allow users to disable cookies. To retain client information without
cookies, require users to login with a unique ID. You can then save user-specific information in a database with
the user’s ID as a key.
2 ColdFusion creates a new session each time the user requests a page directly in the browser, because the new
request contains no state information to indicate the session or client.

Note: You can prevent ColdFusion from sending client information to the browser as cookies by setting This.setClientCookies variable in Application.cfc or the setClientCookies attribute of the cfapplication tag to No.
To use ColdFusion session variables without using cookies, each page must pass the CFID and CFToken values to any
page that it calls as part of the request URL. If a page contains any HTML href a= links, cflocation tags, form tags,
or cfform tags the tags must pass the CFID and CFToken values in the tag URL. To use J2EE session management,
you must pass the jsessionid value in page requests. To use ColdFusion client variables and J2EE session variables,
you must pass the CFID, CFToken, and jsessionid values in URLs.
ColdFusion provides the URLSessionFormat function, which does the following:

• If the client does not accept cookies, automatically appends all required client identification information to a
URL.
•

If the client accepts cookies, does not append the information.

The URLSessionFormat function automatically determines which identifiers are required, and sends only the
required information. It also provides a more secure and robust method for supporting client identification than
manually encoding the information in each URL, because it only sends the information that is required, when it is
required, and it is easier to code.

ADOBE COLDFUSION 8 277
ColdFusion Developer’s Guide

To use the URLSessionFormat function, enclose the request URL in the function. For example, the following
cfform tag posts a request to another page and sends the client identification, if required:


If you use the same page URL in multiple URLSessionFormat functions, you can gain a small performance
improvement and simplify your code if you assign the formatted page URL to a variable, for example:



Client identifiers and security

The following client identifier issues can have security implications:

•

Ensuring the uniqueness and complexity of the CFToken identifier

•

Limiting the availability of Session identifiers

The next sections discuss these issues.
Ensuring CFToken uniqueness and security

By default, ColdFusion uses an eight-digit random number in the CFToken identifier. This CFToken format provides
a unique, secure identifier for users under most circumstances. (In ColdFusion, the method for generating this
number uses a cryptographic-strength random number generator that is seeded only when the server starts.)
However, in the ColdFusion Administrator, you can enable the Settings page to produce a more complex CFToken
identifier. If you enable the Use UUID for cftoken option, ColdFusion creates the CFToken value by prepending a
16-digit random hexadecimal number to a ColdFusion UUID. The resulting CFToken identifier looks similar to the
following:
3ee6c307a7278c7b-5278BEA6-1030-C351-3E33390F2EAD02B9
Providing Session security

ColdFusion uses the same client identifiers for the Client scope and the standard Session scope. Because the CFToken
and CFID values are used to identify a client over a period of time, they are normally saved as cookies on the user’s
browser. These cookies persist until the client’s browser deletes them, which can be a considerable length of time. As
a result, hackers could have more access to these variables than if ColdFusion used different user identifiers for each
session.
A hacker who has the user’s CFToken and CFID cookies could gain access to user data by accessing a web page during
the user’s session using the stolen CFToken and CFID cookies. While this scenario is unlikely, it is theoretically
possible.
You can remove this vulnerability by selecting the Use J2EE Session Variables option on the ColdFusion Administrator Memory Variables page. The J2EE session management mechanism creates a new session identifier for each
session, and does not use either the CFToken or the CFID cookie value.
Managing client identity information in a clustered environment

To maintain your application’s client identity information in a clustered server environment, you must specify
This.setdomaincookies="True" in the Application.cfc initialization code, or use the cfapplication
setdomaincookies attribute in your Application.cfm page.

ADOBE COLDFUSION 8 278
ColdFusion Developer’s Guide

The setdomaincookies attribute specifies that the server-side copies of the CFID and CFToken variables used to
identify the client to ColdFusion are stored at the domain level (for example, .adobe.com). If CFID and CFToken
variable combinations already exist on each host in the cluster, ColdFusion migrates the host-level variables on each
cluster member to the single, common domain-level variable. Following the setting or migration of host-level cookie
variables to domain-level variables, ColdFusion creates a new cookie variable (CFMagic) that tells ColdFusion that
domain-level cookies have been set.
If you use client variables in a clustered system, you must also use a database or cookies to store the variables.

Configuring and using client variables
Use client variables for data that is associated with a particular client and application and that must be saved between
user sessions. Use client variables for long-term information such as user display or content preferences.

Enabling client variables
To enable client variables, you specify This.clientmanagement="True" in the Application.cfc initialization code, or
set the cfapplication tag clientmanagement attribute to Yes in the Application.cfm file. For example, to enable
client variables in an application named SearchApp, you can use the following line in the application’s Application.cfm page:

Choosing a client variable storage method

By default, ColdFusion stores client variables in the Registry. In most cases, however, it is more appropriate to store
the information as client cookies or in a SQL database.
The ColdFusion Administrator Client Variables page controls the default client variable location. You can override
the default location by specifying a This.clientStorage value in Application.cfc or by setting the clientStorage
attribute in the cfapplication tag.
You can specify the following values for the client storage method:

• Registry (default). Client variables are stored under the key HKEY_LOCAL_MACHINE\
SOFTWARE\Macromedia\ColdFusion\CurrentVersion\Clients.
•

Name of a data source configured in ColdFusion Administrator

• Cookie
Generally, it is most efficient to store client variables in a database. Although the Registry option is the default, the
Registry has significant limitations for client data storage. The Registry cannot be used in clustered systems and its
use for client variables on UNIX is not supported in ColdFusion.
Using cookie storage

When you set the client storage method to Cookie, the cookie that ColdFusion creates has the application’s name.
Storing client data in a cookie is scalable to large numbers of clients, but this storage mechanism has some limitations. In particular, if the client turns off cookies in the browser, client variables do not work.
Consider the following additional limitations before implementing cookie storage for client variables:

• Any Client variable that you set after a cfflush tag is not sent to the browser, so the variable value does not get
saved.

ADOBE COLDFUSION 8 279
ColdFusion Developer’s Guide

• Some browsers allow only 20 cookies to be set from a particular host. ColdFusion uses two of these cookies for
the CFID and CFToken identifiers, and also creates a cookie named cfglobals to hold global data about the client,
such as HitCount, TimeCreated, and LastVisit. This limits you to 17 unique applications per client-host pair.
• Some browsers set a size limit of 4K bytes per cookie. ColdFusion encodes nonalphanumeric data in cookies with
a URL encoding scheme that expands at a 3-1 ratio, which means you should not store large amounts of data per
client. ColdFusion throws an error if you try to store more than 4,000 encoded bytes of data for a client.
Configuring database storage

When you specify a database for client variable storage, do not always have to manually create the data tables that
store the client variables.
If ColdFusion can identify that the database you are using supports SQL creation of database tables, you only need
to create the database in advance. When you click the Add button on the Select Data Source to Add as Client Store
box on the Memory Variables page, the Administrator displays a Add/Edit Client Store page which contains a Create
Client Database Tables selection box. Select this option to have ColdFusion create the necessary tables in your
database. (The option does not appear if the database already has the required tables.)
If your database does not support SQL creation of tables, or if you are using the ODBC socket [Macromedia] driver
to access your database, you must use your database tool to create the client variable tables. Create the CDATA and
CGLOBAL tables.
The CDATA table must have the following columns:
Column

Data type

cfid

CHAR(64), TEXT, VARCHAR, or any data type capable of taking variable length strings up to 64 characters

app

CHAR(64), TEXT, VARCHAR, or any data type capable of taking variable length strings up to 64 characters

data

MEMO, LONGTEXT, LONG VARCHAR, CLOB, or any data type capable of taking long, indeterminate-length strings

The CGLOBAL table must have the following columns:
Column

Data type

cfid

CHAR(64), TEXT, VARCHAR, or any data type capable of taking variable length strings up to 64 characters

data

MEMO, LONGTEXT, LONG VARCHAR, CLOB, or any data type capable of taking long, indeterminate-length strings

lvisit

TIMESTAMP, DATETIME, DATE, or any data type that stores date and time values

Note: Different databases use different names for their data types. The names in the preceding tables are common, but
your database might use other names.
To improve performance, you should also create indexes when you create these tables. For the CDATA table, index
these cfid and app columns. For the CGLOBAL table, index the cfid column.
Specifying client variable storage in your application

The override the default client variable storage location, set the This.clientstorage variable in the Application.cfc
initialization code, or use the cfapplication tag clientStorage attribute.
The following lines from an Application.cfc file tell ColdFusion to store the client variables in the mydatasource data
source:

This.name"SearchApp";

ADOBE COLDFUSION 8 280
ColdFusion Developer’s Guide

This.clientManagement="Yes";
This.clientStorage="mydatasource";


The following code from an Application.cfm file does the same thing as the previous example:


Using client variables
When you enable client variables for an application, you can use them to keep track of long-term information that
is associated with a particular client.
Client variables must be simple data types: strings, numbers, lists, Booleans, or date and time values. They cannot be
arrays, record sets, XML objects, query objects, or other objects. If you must store a complex data type as a client
variable, you can use the cfwddx tag to convert the data to WDDX format (which is represented as a string), store
the WDDX data, and use the cfwddx tag to convert the data back when you read it. For more information on using
WDDX, see “Using WDDX” on page 894.
Note: When saving client variable data in WDDX format, in the case of the registry and SQL Server, the limit is about
4K; with ORACLE, the limit is about 2K.
Creating a client variable

To create a client variable and set its value, use the cfset or cfparam tag and use the Client scope identifier as a
variable prefix; for example:


After you set a client variable this way, it is available for use within any page in your application that is accessed by
the client for whom the variable is set.
The following example shows how to use the cfparam tag to check for the existence of a client parameter and set a
default value if the parameter does not already exist:

Accessing and changing client variables

You use the same syntax to access a client variable as for other types of variables. You can use client variables
anywhere you use other ColdFusion variables.
To display the favorite color that has been set for a specific user, for example, use the following code:

Your favorite color is #Client.FavoriteColor#.


To change the client’s favorite color, for example, use code such as the following:

Standard client variables

The Client scope has the following built-in, read-only variables that your application can use:

ADOBE COLDFUSION 8 281
ColdFusion Developer’s Guide

Variable

Description

Client.CFID

The client ID, normally stored on the client system as a cookie.

Client.CFToken

The client security token, normally stored on the client system as a cookie.

Client.URLToken

Value depends on whether J2EE session management is enabled.
No session management or ColdFusion session management: A combination of the CFID and CFToken
values, in the form CFID=IDNum&CFTOKEN=tokenNum. This variable is useful if the client does not support
cookies and you must pass the CFID and CFToken variables from page to page.
J2EE session management: A combination of CFID, CFToken, and session ID values in the form
CFID=IDNum&CFTOKEN=tokenNum&jsessionid=SessionID.

Client.HitCount

The number of page requests made by the client.

Client.LastVisit

The last time the client visited the application.

Client.TimeCreated

The time the CFID and CFToken variables that identify the client to ColdFusion were first created.

Note: ColdFusion lets you delete or change the values of the built-in client variables. As a general rule, avoid doing so.
You use the Client.CFID, Client.CFToken, and Client.URLToken variables if your application supports
browsers that do not allow cookies. For more information on supporting browsers that do not allow cookies, see
“Using client and session variables without cookies” on page 276.
You can use the Client.HitCount and time information variables to customize behavior that depends on how often
users visit your site and when they last visited. For example, the following code shows the date of a user's last visit to
your site:

Welcome back to the Web SuperShop. Your last
visit was on #DateFormat(Client.LastVisit)#.

Getting a list of client variables

To obtain a list of the custom client parameters associated with a particular client, use the
GetClientVariablesList function, as follows:
#GetClientVariablesList()#

The GetClientVariablesList function returns a comma-separated list of the names of the client variables for the
current application. The standard system-provided client variables (CFID, CFToken, URLToken, HitCount,
TimeCreated, and LastVisit) are not returned in the list.
Deleting client variables

To delete a client variable, use the StructDelete function or the DeleteClientVariable function. For example,
the following lines are equivalent:



The Client Variables page in the ColdFusion Administrator lets you set a time-out period of inactivity after which
ColdFusion removes client variables stored in either the Registry or a data source. (The default value is 10 days for
client variables stored in the Registry, and 90 days for client variables stored in a data source.)
Note: You cannot delete the system-provided client variables (CFID, CFToken, URLToken, HitCount, TimeCreated,
and LastVisit).

ADOBE COLDFUSION 8 282
ColdFusion Developer’s Guide

Using client variables with cflocation

If you use the cflocation tag to redirect ColdFusion to a path that ends with .dbm or .cfm, the Client.URLToken
variable is automatically appended to the URL. You can prevent this behavior by adding the attribute
addtoken="No" to the cflocation tag.
Caching client variable

When ColdFusion reads or writes client variables, it caches the variables in memory to help decrease the overhead
of accessing the client data. As a result, ColdFusion only accesses the client data store when you read its value for the
first time or, for values you set, when the request ends. Additional references to the client variable use the cached
value in ColdFusion memory, thereby processing the page more quickly.
Exporting the client variable database

If your client variable database is stored in the Windows system Registry and you need to move it to another
machine, you can export the Registry key that stores your client variables and take it to your new server. The system
Registry lets you export and import Registry entries.
To export your client variable database from the Registry in Windows:
1 Open the Registry editor.
2

Find and select the following key:
HKEY_LOCAL_MACHINE\SOFTWARE\Macromedia\ColdFusion\CurrentVersion\Clients

3

On the Registry menu, click Export Registry File.

4

Enter a name for the Registry file.

After you create a Registry file, you can copy it to a new machine and import it by clicking Import Registry File on
the Registry editor Registry menu.
Note: On UNIX systems, the registry entries are kept in /opt/coldfusion/registry/cf.registry, a text file that you can copy
and edit directly.

Configuring and using session variables
Use session variables when you need the variables for a single site visit or set of requests. For example, you might use
session variables to store a user’s selections in a shopping cart application. (Use client variables if you need a variable
in multiple visits.)
Important: Put code that uses session variables inside cflock tags in circumstances that might result in race conditions
from multiple accesses to the same variable. For information on using cflock tags see “Locking code with cflock” on
page 289.

What is a session?
A session refers to all the connections that a single client might make to a server in the course of viewing any pages
associated with a given application. Sessions are specific to both the individual user and the application. As a result,
every user of an application has a separate session and has access to a separate set of session variables.
This logical view of a session begins with the first connection to an application by a client and ends after that client's
last connection. However, because of the stateless nature of the web, it is not always possible to define a precise point
at which a session ends. A session should end when the user finishes using an application. In most cases, however, a
web application has no way of knowing if a user has finished or is just lingering over a page.

ADOBE COLDFUSION 8 283
ColdFusion Developer’s Guide

Therefore, sessions always terminate after a time-out period of inactivity. If the user does not access a page of the
application within this time-out period, ColdFusion interprets this as the end of the session and clears any variables
associated with that session.
The default time-out for session variables is 20 minutes. You can change the default time-out on the Memory
Variables page in the Server Settings area in the ColdFusion Administrator.
You can also set the time-out period for session variables inside a specific application (thereby overruling the Administrator default setting) by setting the Application.cfc This.sessionTimeout variable or by using the cfapplication
tag sessionTimeout attribute. However, you cannot set a time-out value for that is greater than the maximum
session time-out value set on the Administrator Memory Variables page.
For detailed information on ending sessions and deleting session variables, see “Ending a session” on page 286.
ColdFusion and J2EE session management

The ColdFusion server can use either of the following types of session management:

•

ColdFusion session management

•

J2EE servlet session management

ColdFusion session management uses the same client identification method as ColdFusion client management.
J2EE session management provides the following advantages over ColdFusion session management:

• J2EE session management uses a session-specific session identifier, jsessionid, which is created afresh at the
start of each session.
• You can share session variables between ColdFusion pages and JSP pages or Java servlets that you call from the
ColdFusion pages.
• The Session scope is serializable (convertible into a sequence of bytes that can later be fully restored into the
original object). With ColdFusion session management, the Session scope is not serializable. Only serializable scopes
can be shared across servers.
Therefore, consider using J2EE session management in any of the following cases:

•

You want to maximize session security, particularly if you also use client variables

•

You want to share session variables between ColdFusion pages and JSP pages or servlets in a single application.

• You want to be able to manually terminate a session while maintaining the client identification cookie for use by
the Client scope.
•

You want to support clustered sessions; for example, to support session failover among servers.

Configuring and enabling session variables
To use session variables, you must enable them in two places:

•

ColdFusion Administrator

•

The Application.cfc initialization code This.sessionManagement variable or the active cfapplication tag.

ColdFusion Administrator, Application.cfc, and the cfapplication tag also provide facilities for configuring
session variable behavior, including the variable time-out.
Selecting and enabling session variables in ColdFusion Administrator

To use session variables, they must be enabled on the ColdFusion Administrator Memory Variables page. (They are
enabled by default.) You can also use the Administrator Memory Variables page to do the following:

ADOBE COLDFUSION 8 284
ColdFusion Developer’s Guide

•

Select to use ColdFusion session management (the default) or J2EE session management.

• Change the default session time-out. Application code can override this value. The default value for this timeout is 20 minutes.
• Specify a maximum session time-out. Application code cannot set a time-out greater than this value. The default
value for this time-out is two days.
Enabling session variables in your application

You must also enable session variables in the initialization code of your Application.cfc file or in the cfapplication
tag in your Application.cfm file.
Do the following in the Application.cfc initialization code, below the cfcomponent tag, to enable session variables:

•

Set This.sessionManagement="Yes".

•

Set This.name to specify the application's name.

•

Optionally, set This.sessionTimeout to set an application-specific session time-out value. Use the

CreateTimeSpan function to specify the number of days, hours, minutes, and seconds for the time-out.

Do the following in the Application.cfm file to enable session variables:

•

Set sessionManagement="Yes"

•

Use the name attribute to specify the application's name.

•

Optionally, use the sessionTimeout attribute to set an application-specific session time-out value. Use the

CreateTimeSpan function to specify the number of days, hours, minutes, and seconds for the time-out.

The following sample code enables session management for the GetLeadApp application and sets the session
variables to time out after a 45-minute period of inactivity:


Storing session data in session variables
Session variables are designed to store session-level data. They are a convenient place to store information that all
pages of your application might need during a user session, such as shopping cart contents or score counters.
Using session variables, an application can initialize itself with user-specific data the first time a user accesses one of
the application’s pages. This information can remain available while that user continues to use that application. For
example, you can retrieve information about a specific user’s preferences from a database once, the first time a user
accesses any page of an application. This information remains available throughout that user’s session, thereby
avoiding the overhead of retrieving the preferences repeatedly.

Standard session variables
If you use ColdFusion session variables, the Session scope has four built-in, read-only variables that your application
can use. If you use J2EE session management, the Session scope has two built-in variables. Generally, you use these
variables in your ColdFusion pages only if your application supports browsers that do not allow cookies. For more
information on supporting browsers that do not allow cookies, see “Using client and session variables without
cookies” on page 276. The following table describes the built-in session variables.

ADOBE COLDFUSION 8 285
ColdFusion Developer’s Guide

Variable

Description

Session.CFID

ColdFusion session management only: the client ID, normally stored on the client system as a cookie.

Session.CFToken

ColdFusion session management only: the client security token, normally stored on the client system as a
cookie.

Session.URLToken

ColdFusion session management:

A combination of the CFID and CFToken values in the form
CFID=IDNum&CFTOKEN=tokenNum. Use this variable if the client does not support cookies and you must
pass the CFID and CFToken variables from page to page.

J2EE session management: A combination of the CFID and CFToken cookies and the J2EE session ID, in the
form CFID=IDNum&CFTOKEN=tokenNum&jsessionid=SessionID.
Session.SessionID

A unique identifier for the session.
ColdFusion session management: a combination of the application name and CFID and CFToken values.
J2EE session management: the jsessionid value.

Note: ColdFusion lets you delete or change the values of the built-in session variables. As a general rule, avoid doing so.
If you enable client variables and ColdFusion session management, ColdFusion uses the same values for the Client
and Session scope CFID, CFToken, and URLtoken variables. ColdFusion gets the values for these variables from the
same source, the client’s CFID and CFTOKEN cookies.
If you use J2EE session management, the Session scope does not include the Session.CFID or Session.CFToken
variables, but does include the Session.URLToken and Session.SessionID variables. In this case, the
Session.SessionID is the J2EE session ID and Session.URLToken consists of the string jsessionid= followed
by the J2EE session ID.

Getting a list of session variables
Use the StructKeyList function to get a list of session variables, as follows:

 #StructKeyList(Session)# 


Important: Always put code that accesses session variables inside cflock tags.

Creating and deleting session variables
Use a standard assignment statement to create a new session variable, as follows:




Use the structdelete tag to delete a session variable; for example:




Note: If you set session variables on a CFML template that uses the cflocation tag, ColdFusion might not set the
variables. For more information, see TechNote 22712 at http://www.adobe.com/cfusion/knowledgebase/index.cfm?id=tn_18171.

ADOBE COLDFUSION 8 286
ColdFusion Developer’s Guide

Accessing and changing session variables
You use the same syntax to access a session variable as for other types of variables. However, you must lock any code
that accesses or changes session variables.
For example, to display the number of items in a user’s shopping cart, use the following code:


Your shopping cart has #Session.ShoppingCartItems# items.



To increase the number of items in the shopping cart, use the following code:




Ending a session
The following rules apply to ending a session and deleting Session scope variables:

• If you use ColdFusion session management, ColdFusion automatically ends sessions and deletes all Session
scope variables if the client is inactive for the session time-out period. The session does not end when the user closes
the browser.
• If you use J2EE session management, ColdFusion ends the session and deletes all Session scope variables if the
client is inactive for the session time-out period. However, the browser continues to send the same session ID, and
ColdFusion will reuse this ID for sessions with this browser instance, as long as the browser remains active.
•

Logging a user out does not end the session or delete Session scope variables.

• In many cases, you can effectively end a session by clearing the Session scope, as shown in the following line. The
following list, however, includes important limitations and alternatives:


• Clearing the Session scope does not clear the session ID, and future requests from the browser continue to use
the same session ID until the browser exits. It also does not log the user out, even if you use Session scope storage
for login information. Always use the cflogout tag to log users out.
•

If you use J2EE session management, you can invalidate the session, as follows:


This line creates a pointer to the servlet page context and calls an internal method to reset the session. This clears
all session information, including the session ID Session scope variables, and if you are using session login
storage, the login information, for future request. However, the session information does remain available until
the end of the current request. After you invalidate a session, attempts by the browser to access the application
will generate an invalid session exception until the session times out.
Note: You cannot destroy the session and create a session on the same request, as creating a new session involves sending
session cookies back.
1 If you do not use client cookies, the Session scope and login state is available to your application only as long as
you pass the session’s CFID, CFTOKEN, and, for J2EE sessions, jsessionid values in the URL query string. After you
stop using these values, however, the session data remains in memory until the session time-out period elapses.

ADOBE COLDFUSION 8 287
ColdFusion Developer’s Guide

Configuring and using application variables
Application variables are available to all pages within an application, that is, pages that have the same application
name. Because application variables are persistent, you easily can pass values between pages. You can use application
variables for information including the application name, background color, data source names, or contact information.
You set the application name in the cfapplication tag, normally on your application’s Application.cfm page. The
application name is stored in the Application.applicationName variable.
Unlike client and session variables, application variables do not require that a client name (client ID) be associated
with them. They are available to any clients that use pages in the application.
Important: Put code that uses application variables inside cflock tags in circumstances that might result in race conditions from multiple accesses to the same variable. For information on using cflock tags, see “Locking code with cflock”
on page 289.
The following sections describe how to configure and use application variables.

Configuring and enabling application variables
To use application variables, do the following:

•

Ensure that they are enabled in the ColdFusion Administrator. (They are enabled by default.)

• Specify the application name by setting the This.name variable in the initialization code of the Application.cfc
or by setting the name attribute of the cfapplication tag for the current page.
Note: ColdFusion supports unnamed applications for compatibility with J2EE applications. For more information, see
“Unnamed ColdFusion Application and Session scopes” on page 933
The ColdFusion Administrator also lets you specify the following information:

• A default variable time-out. If all pages in an application are inactive for the time-out period, ColdFusion deletes
all the application variables. The Application.cfc file or cfapplication tag can override this value for a specific
application. The default value for this time-out is two days.
• A maximum time-out. The application code cannot set a time-out greater than this value. The default value for
this time-out is two days.
You can set the time-out period for application variables within a specific application by using the This.applicationTimeout variable of Application.cfc or the applicationTimeout attribute of the cfapplication tag.

Storing application data in application variables
Application variables are a convenient place to store information that all pages of your application might need, no
matter which client is running that application. Using application variables, an application could, for example,
initialize itself when the first user accesses any page of that application. This information can then remain available
indefinitely, thereby avoiding the overhead of repeated initialization.
Because the data stored in application variables is available to all pages of an application, and remains available until
a specific period of inactivity passes or the ColdFusion server shuts down, application variables are convenient for
application-global, persistent data.

ADOBE COLDFUSION 8 288
ColdFusion Developer’s Guide

However, because all clients running an application see the same set of application variables, these variables are not
appropriate for client-specific or session-specific information. To target variables for specific clients, use client or
session variables.

Using application variables
Generally, application variables should hold information that you write infrequently. In most cases, the values of
these variables are set once, most often when an application first starts. Then the values of these variables are referenced many times throughout the life of the application or the course of a session.
In circumstances that might result in race conditions from multiple accesses to the same variable, put code that
writes to Application scope variables or reads Application scope variables with data that can change inside cflock
tags.
Because each Application scope variable is shared in memory by all requests in the application, these variables can
become bottlenecks if used inappropriately. Whenever a request is reading or writing an Application scope variable,
any other requests that use the variable must wait until the code accessing the variable completes. This problem is
increased by the processing time required for locking. If many users access the application simultaneously and you
use Application scope variables extensively, your application performance might degrade. If your application uses
many application variables, consider whether the variables must be in the Application scope or whether they can be
Session or Request scope variables.
The application scope has one built-in variable, Application.applicationName, which contains the application
name you specify in the cfapplication tag.
You access and manipulate application variables the same way you use session variables, except that you use the
variable prefix Application, not Session, and specify Session as the lock scope. For examples of using session variables
see “Creating and deleting session variables” on page 285 and “Accessing and changing session variables” on
page 286.
For information on locking write-once read-many application variables efficiently, see “Locking application
variables efficiently” on page 295

Using server variables
Server variables are associated with a single ColdFusion server. They are available to all applications that run on the
server. Use server variables for data that must be accessed across clients and applications, such as global server hit
counts.
Server variables do not time out, but they are lost when the server shuts down. You can delete server variables.
Server variables are stored on a single server. As a result, you should not use server variables if you use ColdFusion
on a server cluster.
You access and manipulate server variables the same way use Session and application variables, except you use the
variable prefix Server.
Important: Put code that uses server variables inside cflock tags in circumstances that might result in race conditions
from multiple accesses to the same variable. You do not have to lock access to built-in server variables.
ColdFusion provides the following standard built-in read-only server variables:

ADOBE COLDFUSION 8 289
ColdFusion Developer’s Guide

Variable

Description

Server.ColdFusion.AppServer

The name of the J2EE application server ColdFusion is using. For ColdFusion server
editions, which have an integrated application server, the name is JRun4.

Server.ColdFusion.Expiration

The date on which the ColdFusion license expires if it is the trial version.

Server.ColdFusion.ProductLevel

The server product level, such as Enterprise.

Server.ColdFusion.ProductName

The name of the product (ColdFusion).

Server.ColdFusion.ProductVersion

The version number for the server that is running, such as 6,0,0.

Server.ColdFusion.Rootdir

Directory under which ColdFusion is installed, such as C:\cfusion.

Server.ColdFusion.SerialNumber

The serial number assigned to this server installation.

Server.ColdFusion.SupportedLocales

The locales, such as English (US) and Spanish (Standard), supported by the server.

Server.OS.AdditionalInformation

Additional information provided by the operating system, such as the Service Pack
number.

Server.OS.arch

The processor architecture, such as x86 for Intel Pentium processors.

Server.OS.BuildNumber

The specific operating system build, such as 1381

Server.OS.Name

The name of the operating system, such as Windows NT.

Server.OS.Version

The version number of the operating system, such as 4.0.

Locking code with cflock
The cflock tag controls simultaneous access to ColdFusion code. The cflock tag lets you do the following:

• Protect sections of code that access and manipulate shared data in the Session, Application, and Server scopes,
and in the Request and Variables scopes for applications that use ColdFusion threads.
•

Ensure that file updates do not fail because files are open for writing by other applications or ColdFusion tags.

• Ensure that applications do not try to simultaneously access ColdFusion extension tags written using the CFX
API that are not thread-safe. This is particularly important for CFX tags that use shared (global) data structures
without protecting them from simultaneous access (not thread-safe). However, Java CFX tags can also access shared
resources that could become inconsistent if the CFX tag access is not locked.
• Ensure that applications do not try to simultaneously access databases that are not thread-safe. (This is not
necessary for most database systems.)
ColdFusion is a multithreaded web application server that can process multiple page requests at a time. As a result,
the server can attempt to access the same information or resources simultaneously, as the result of two or more
requests.
Although ColdFusion is thread-safe and does not try to modify a variable simultaneously, it does not ensure the
correct order of access to information. If multiple pages, or multiple invocations of a page, attempt to write data
simultaneously, or read and write it at the same time, the resulting data can be inconsistent, as shown in the following
Sample locking scenarios section.
Similarly, ColdFusion cannot automatically ensure that two sections of code do not attempt to access external
resources such as files, databases, or CFX tags that cannot properly handle simultaneous requests. Nor can
ColdFusion ensure that the order of access to these shared resources is consistent and results in valid data.

ADOBE COLDFUSION 8 290
ColdFusion Developer’s Guide

By locking code that accesses such resources so that only one thread can access the resource at a time, you can
prevent race conditions.

Sample locking scenarios
The following examples present scenarios in which you need to lock ColdFusion code. These scenarios show only
two of the circumstances where locking is vital.
Reading and writing a shared variable

If you have an application-wide value, such as a counter of the total number of tickets sold, you might have code such
as the following on a login page:


When ColdFusion executes this code, it performs the following operations:
1

Retrieves the current value of Application.totalTicketsSold from temporary storage.

2

Increments this value.

3

Stores the result back in the Application scope.

Suppose that ColdFusion processes two ticket orders at approximately the same time, and that the value of Application.totalTicketsSold is initially 160. The following sequence might happen:
4

Order 1 reads the total tickets sold as 160.

5

Order 2 reads the total tickets sold as 160.

6

Order 1 adds an order of 5 tickets to 160 to get 165.

7

Order 2 adds an order of 3 tickets to 160 to get 163.

8

Order 1 saves the value 165 to Application.totalTicketsSold

9

Order 2 saves the value 163 to Application.totalTicketsSold

The application now has an inaccurate count of the tickets sold, and is in danger of selling more tickets than the
auditorium can hold.
To prevent this from happening, lock the code that increments the counter, as follows:




The cflock tag ensures that while ColdFusion performs the processing in the tag body, no other threads can access
the Application scope. As a result, the second transaction is not processed until the first one completes. The
processing sequence looks something like the following:
10 Order 1 reaches the lock tag, which gets an Application scope lock.
11 Order 1 reads the total tickets sold as 160.
12 Order 2 reaches the lock tag. Because there is an active Application scope lock, ColdFusion waits for the lock to
free.
13 Order 1 adds an order of 5 tickets to 160 to get 165.
14 Order 1 saves the value 165 to Application.totalTicketsSold.
15 Order 1 exits the lock tag. The Application scope lock is now free.
16 Order 2 gets the Application scope lock and can begin processing.

ADOBE COLDFUSION 8 291
ColdFusion Developer’s Guide

17 Order 2 reads the total tickets sold as 165.
18 Order 2 adds an order of 3 tickets to 165 to get 168.
19 Order 2 saves the value 168 to Application.totalTicketsSold.
20 Order 2 exits the lock tag, which frees the Application scope lock. ColdFusion can process another order.

The resulting Application.totalTickesSold value is now correct.
Ensuring consistency of multiple variables

Often an application sets multiple shared scope variables at one time, such as a number of values submitted by a user
on a form. If the user submits the form, clicks the back button, and then resubmits the form with different data, the
application might end up with a mixture of data from the two submissions, in much the same manner as shown in
the previous section.
For example, an application might store information about order items in a Session scope shopping cart. If the user
submits an item selection page with data specifying sage green size 36 shorts, and then resubmits the item specifying
sea blue size 34 shorts, the application might end up with a mixture of information from the two orders, such as sage
green size 34 shorts.
By putting the code that sets all of the related session variables in a single cflock tag, you ensure that all the variables
get set together. In other words, setting all of the variables becomes an atomic, or single, operation. It is similar to a
database transaction, where everything in the transaction happens, or nothing happens. In this example, the order
details for the first order all get set, and then they are replaced with the details from the second order.
For more examples of using locking in applications, see “Examples of cflock” on page 296.

Using the cflock tag with write-once variables
You do not need to use cflock when you read a variable or call a user-defined function name in the Session, Application, or Server scope if it is set in only one place in the application, and is only read (or called, for a UDF) everywhere else. Such data is called write-once. If you set an Application or Session scope variable in Application.cfm and
never set it on any other pages, you must lock the code that sets the variable, but do not have to lock code on other
pages that reads the variable’s value. If you set the variable in the corresponding start method in Application.cfc (for
example, onApplicationStart for Application scope variables), you do not have to lock the code that sets the
variable.
However, although leaving code that uses write-once data unlocked can improve application performance, it also has
risks. You must ensure that the variables are truly written only once. For example, you must ensure that the variable
is not rewritten if the user refreshes the browser or clicks a back button. Also, it can be difficult to ensure that you,
or future developers, do not later set the variable in more than one place in the application.

Using the cflock tag
The cflock tag ensures that concurrently executing requests do not run the same section of code simultaneously
and thus manipulate shared data structures, files, or CFX tags inconsistently. It is important to remember that
cflock protects code sections that access or set data, not the variables themselves.
You protect access to code by surrounding it in a cflock tag; for example:






ADOBE COLDFUSION 8 292
ColdFusion Developer’s Guide

Lock types

The cflock tag offers two modes of locking, specified by the type attribute:
Exclusive locks (the default lock type): Allow only one request to process the locked code. No other requests can
run code inside the tag while a request has an exclusive lock.
Enclose all code that creates or modifies session, application, or server variables in exclusive cflock tags.
Read-only locks: Allow multiple requests to execute concurrently if no exclusive locks with the same scope or name
are executing. No requests can run code inside the tag while a request has an exclusive lock.
Enclose code that only reads or tests session, application, or server variables in read-only cflock tags. You specify a
read-only lock by setting the type="readOnly" attribute in the cflock tag, for example:


#Application.dailyMessage#




Although ColdFusion does not prevent you from setting shared variables inside read-only lock tag, doing so loses
the advantages of locking. As a result, you must be careful not to set any session, application, or server variables
inside a read-only cflock tag body.
Note: You cannot upgrade or downgrade a lock from one type to another. In other words, do not nest an exclusive lock
in a read-only lock of the same name or scope; the exclusive lock will always time out. Also, do not nest a read-only lock
inside an exclusive lock with the same name or scope; doing so has no effect.
Lock scopes and names

The cflock tag prevents simultaneous access to sections of code, not to variables. If you have two sections of code
that access the same variable, they must be synchronized to prevent them from running simultaneously. You do this
by identifying the locks with the same scope or name attributes.
Note: ColdFusion does not require you to identify exclusive locks. If you omit the identifier, the lock is anonymous and
you cannot synchronize the code in the cflock tag block with any other code. Anonymous locks do not cause errors
when they protect a resource that is used in a single code block, but they are bad programming practice. You must always
identify read-only locks.
Controlling access to data with the scope attribute

When the code that you are locking accesses session, application, or server variables, synchronize access by using the
cflock scope attribute.
You can set the attribute to any of the following values:
Scope

Meaning

Server

All code sections with this attribute on the server share a single lock.

Application

All code sections with this attribute in the same application share a single lock.

Session

All code sections with this attribute that run in the same session of an application share a single lock.

Request

All code sections with this attribute that run in the same request share a single lock. You use this scope only if your
application uses the cfthread tag to create multiple threads in a single request. Locking the Request scope also
locks access to Variables scope data. For more information on locking the Request scrope, see “Locking thread data
and resource access” on page 306.

If multiple code sections share a lock, the following rules apply:

ADOBE COLDFUSION 8 293
ColdFusion Developer’s Guide

• When code is running in a cflock tag block with the type attribute set to Exclusive, code in cflock tag blocks
with the same scope attribute is not allowed to run. They wait until the code with the exclusive lock completes.
• When code in a cflock tag block with the type readOnly is running, code in other cflock tag blocks with the
same scope attribute and the readOnly type attribute can run, but any blocks with the same scope attribute and
an Exclusive type cannot run and must wait until all code with the read-only lock completes. However, if a readonly lock is active and code with an exclusive lock with the same scope or name is waiting to execute, read-only
requests using the same scope or name that are made after the exclusive request is queued must wait until code with
the exclusive lock executes and completes.
Controlling locking access to files and CFX tags with the name attribute

The cflock name attribute provides a second way to identify locks. Use this attribute when you use locks to protect
code that manges file access or calls non-thread-safe CFX code.
When you use the name attribute, specify the same name for each section of code that accesses a specific file or a
specific CFX tag.
Controlling and minimizing lock time-outs

You must include a timeout attribute in your cflock tag. The timeout attribute specifies the maximum time, in
seconds, to wait to obtain the lock if it is not available. By default, if the lock does not become available within the
time-out period, ColdFusion generates a Lock type exception error, which you can handle using cftry and cfcatch
tags.
If you set the cflock throwOnTimeout attribute to No, processing continues after the time-out at the line after the
 end tag. Code in the cflock tag body does not run if the time-out occurs before ColdFusion can acquire
the lock. Therefore, never use the throwOnTimeout attribute for CFML that must run.
Normally, it does not take more than a few seconds to obtain a lock. Very large time-outs can block request threads
for long periods of time and radically decrease throughput. Always use the smallest time-out value that does not
result in a significant number of time-outs.
To prevent unnecessary time-outs, lock the minimum amount of code possible. Whenever possible, lock only code
that sets or reads variables, not business logic or database queries. One useful technique is to do the following:
1

Perform a time-consuming activity outside of a cflock tag

2

Assign the result to a Variables scope variable

3

Assign the Variables scope variable’s value to a shared scope variable inside a cflock block.

For example, if you want to assign the results of a query to a session variable, first get the query results using a
Variables scope variable in unlocked code. Then, assign the query results to a session variable inside a locked code
section. The following code shows this technique:

SELECT FirstName, LastName
FROM Users
WHERE UserID = #request.UserID#





ADOBE COLDFUSION 8 294
ColdFusion Developer’s Guide

Considering lock granularity
When you design your locking strategy, consider whether you should have multiple locks containing small amounts
of code or few locks with larger blocks of code. There is no simple rule for making such a decision, and you might
do performance testing with different options to help make your decision. However, you must consider the following
issues:

• If the code block is larger, ColdFusion will spend more time inside the block, which might increase the number
of times an application waits for the lock to released.
•

Each lock requires processor time. The more locks you have, the more processor time is spent on locking code.

Nesting locks and avoiding deadlocks
Inconsistent nesting of cflock tags and inconsistent naming of locks can cause deadlocks (blocked code). If you are
nesting locks, you must consistently nest cflock tags in the same order and use consistent lock scopes (or names).
A deadlock is a state in which no request can execute the locked section of the page. All requests to the protected
section of the page are blocked until there is a time-out. The following table shows one scenario that would cause a
deadlock:
User 1

User 2

Locks the Session scope.

Locks the Application scope.

Tries to lock the Application scope, but the Application
scope is already locked by User 2.

Tries to lock the Session scope, but the Session scope is already locked by User 1.

Neither user’s request can proceed, because it is waiting for the other to complete. The two are deadlocked.
Once a deadlock occurs, neither of the users can do anything to break the deadlock, because the execution of their
requests is blocked until the deadlock is resolved by a lock time-out.
You can also cause deadlocks if you nest locks of different types. An example of this is nesting an exclusive lock inside
a read-only lock of the same scope or same name.
In order to avoid a deadlock, lock code sections in a well-specified order, and name the locks consistently. In
particular, if you need to lock access to the Server, Application, and Session scopes, you must do so in the following
order:
1

Lock the Session scope. In the cflock tag, specify scope="Session".

2

Lock the Application scope. In the cflock tag, specify scope="Application".

3

Lock the Server scope. In the cflock tag, specify scope="Server".

4

Unlock the Server scope.

5

Unlock the Application scope.

6

Unlock the Session scope.

Note: You can skip any pair of lock and unlock steps in the preceding list if you do not need to lock a particular scope.
For example, you can omit steps 3 and 4 if you do not need to lock the Server scope.
Copying shared variables into the Request scope

You can avoid locking some shared-scope variables multiple times during a request by doing the following:
1

Copy the shared-scope variables into the Request scope in code with an exclusive lock in the Application.cfc

onRequestStart method or the Application.cfm page.

ADOBE COLDFUSION 8 295
ColdFusion Developer’s Guide

2

Use the Request scope variables on your ColdFusion pages for the duration of the request.

3 Copy the variables back to the shared scope in code with an exclusive lock in the Application.cfc onRequestEnd
method on the OnRequestEnd.cfm page.

With this technique the “last request wins.” For example, if two requests run simultaneously, and both requests
change the values of data that was copied from the shared scope, the data from the last request to finish is saved in
the shared scope, and the data from the previous request is not saved.
Locking application variables efficiently

The need to lock application variables can reduce server performance, because all requests that use Application
scope variables must wait on a single lock. This issue is a problem even for write-once read-many variables, because
you still must ensure the variable exists, and possibly set the value before you can read it.
You can minimize this problem by using a technique such as the following to test for the existence of application
variables and set them if they do not exist:
Use an Application scope flag variable to indicate if the variable or variables are initialized. In a read-only lock,
check for the existence of the flag, and assign the result to a local variable.
1
2

Outside the cflock bock, test the value of the local variable

3 If it the local variable indicates that the application variables are not initialized, get an exclusive Application
scope lock.

Inside the lock, again test the Application scope flag, to make sure another page has not set the variables between
step one and step four.
4
5

If the variables are still not set, set them and set the Application scope flag to true.

6

Release the exclusive lock.

The following code shows this technique:















...






ADOBE COLDFUSION 8 296
ColdFusion Developer’s Guide

Examples of cflock
The following examples show how to use cflock blocks in a variety of situations.
Example with application, server, and session variables

This example shows how you can use cflock to guarantee the consistency of data updates to variables in the Application, Server, and Session scopes.
This example does not handle exceptions that arise if a lock times out. As a result, users see the default exception
error page on lock time-outs.
The following sample code might be part of the Application.cfm file:


























E-Turtleneck is proud to say that we have sold
#Application.number# turtlenecks to date.



ADOBE COLDFUSION 8 297
ColdFusion Developer’s Guide

The remaining sample code could appear inside the application page where customers place orders:





cflock Example




Thank you for shopping E-Turtleneck.
Today you have chosen a turtleneck in size
#form.size# and in the color #form.color#.
Your order ID is #Session.sessionID#.







<
!--- Lock the Application scope variable application.number to
update the total number of turtlenecks sold. --->






 Congratulations! You have just selected
the longest-wearing, most comfortable turtleneck
in the world. Please indicate the color and size
you want to buy.


Select a color.

red
white
blue
turquoise
black
forest green


ADOBE COLDFUSION 8 298
ColdFusion Developer’s Guide




Select a size.

small
medium
large
xlarge














Note: In this simple example, the Application.cfm page displays the Application.number variable value. Because the
Application.cfm file is processed before any code on each ColdFusion page, the number that displays after you click the
submit button does not include the new order. One way you can resolve this problem is by using the OnRequestEnd.cfm
page to display the value at the bottom of each page in the application.
Example of synchronizing access to a file system

The following example shows how to use a cflock block to synchronize access to a file system. The cflock tag
protects a cffile tag from attempting to append data to a file already open for writing by the same tag executing on
another request.
If an append operation takes more than 30 seconds, a request waiting to obtain an exclusive lock to this code might
time out. Also, this example uses a dynamic value for the name attribute so that a different lock controls access to
each file. As a result, locking access to one file does not delay access to any other file.




Example of protecting ColdFusion extensions

The following example shows how you can build a custom tag wrapper around a CFX tag that is not thread-safe. The
wrapper forwards attributes to the non-thread-safe CFX tag that is used inside a cflock tag.






ADOBE COLDFUSION 8 299
ColdFusion Developer’s Guide



300

Chapter 17: Using ColdFusion Threads
You can use threads in Adobe ColdFusion to simultaneously run multiple streams of execution in a ColdFusion page
or CFC.
Contents

About ColdFusion threads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Creating and managing ColdFusion threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Using thread data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Working with threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Using ColdFusion tools to control thread use. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Example: getting multiple RSS feeds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

About ColdFusion threads
Threads are independent streams of execution. Multiple threads on a page or CFC can execute simultaneously and
asynchronously, letting you perform asynchronous processing in CFML.
Threads are useful for two broad types of activities:

•

When multiple actions can occur simultaneously

•

When you do not have to wait for one action to complete before starting the next action

Some typical uses for threads include the following examples:

• An application that aggregates information from multiple external sources that might take significant times to
respond has the code that gets information from each source in a separate thread. This way, the application starts all
requests quickly and has to wait only until the last response is received, instead of having to wait for a response to
each request before the next request can start. One example of such usage is an RSS or Atom feed aggregator.
• A page that sends many mail messages runs the code that sends the mail messages in a separate thread and
doesn’t wait for it to complete to continue processing. The thread that sends the mail messages continues processing
after the page-level processing is completed and the application starts processing another page.
• An application might do maintenance of user data, such as using update queries, deleting records, and so on,
whenever a user logs into the site. If the application does the maintenance in a separate thread, the user gets an
immediate response after logging in, without having to wait for the updates to complete.
When ColdFusion processes a page, the page executes in a single thread, called the page thread. The cfthread tag
lets you create additional threads that can process independently of the page thread, and lets you synchronize thread
processing, for example, by having the page thread wait until threads that you create complete their processing.

Creating and managing ColdFusion threads
You use the cfthread tag and the Sleep function to create and manage ColdFusion threads. You manage a thread
by doing the following actions:

ADOBE COLDFUSION 8 301
ColdFusion Developer’s Guide

•

Start the thread running.

• Temporarily suspend the thread’s processing. This action is useful if one thread must wait for another thread to
do processing, but both threads must continue processing without joining.
•

End a thread. You typically end a running thread if there is an error, or if it is still processing after a long time.

• Have the page or a thread wait until one or more other threads have completed processing before proceeding
with its processing, called joining the threads. You typically join threads when one thread requires the results from
another thread. For example, if a page uses multiple threads to get several news feeds for display, it joins all the feed
threads before it displays the results.
Each thread runs the code inside a cfthread tag body and normally exits when the tag body code completes
processing.

Starting a thread
You start a thread by using a cfthread tag with an action attribute value of run. CFML code within the cfthread
tag body executes on a separate thread while the page request thread continues processing. Only the page thread can
create other threads. A thread that you create with a cfthread tag cannot create a child thread, so you cannot have
multiple nested threads.
Optionally, when you start the thread, you can specify a priority level of high, normal (the default), or low to specify
the relative amount of time that the processor should devote to the thread. Page-level code always runs at normal
priority, so you can give your threads more or less processing time than the page.
For more information on using thread attributes, see “The Attributes scope and thread attributes” on page 304.

Suspending a thread
In some cases, one thread must wait until a second thread completes some operations, but should not wait until the
second thread completes all processing, so you cannot just join the threads. For example, one thread might do initialization that is required by multiple threads, and then it might continue with additional processing. The other threads
could suspend themselves until initialization is complete.
The Sleep function and cfthread tag with a sleep action attribute provide two equivalent mechanisms for doing
such synchronization. They suspend the thread processing for a specified period of time. A code loop could test a
condition variable and sleep for a period before retesting the condition. When the condition is true (or a value is
reached, or some other test is valid), the program exits the loop and the thread continues processing.
The following example shows how one thread could use a sleep function to wait for a second thread to perform some
actions.










thread.sleepTimes=0;
thread.initialized=false;

ADOBE COLDFUSION 8 302
ColdFusion Developer’s Guide

while ((threadA.Status != "TERMINATED") && (threadA.j < 400000)) {
sleep(500);
thread.sleeptimes++;
}
// Don’t continue processing if threadA terminated abnormally.
If (threadA.Status != "TERMINATED") {
thread.initialized=true;
// Do additional processing here.
}






current threadA index value: #threadA.j#

threadA status: #threadA.Status#

threadB status: #threadB.Status#

threadB sleepTimes: #threadB.sleepTimes#

Is threadB initialized: #threadB.initialized#



Ending a thread
If a thread never completes processing (is hung), it continues to occupy system resources, so it is good practice to
have your application check for hung threads and end them. You should also consider ending threads that take
excessive time to process and might significantly reduce the responsiveness of your application or server.
To end a thread, use the cfthread tag with an action attribute value of terminate, as the following code snippet
shows.




















ADOBE COLDFUSION 8 303
ColdFusion Developer’s Guide







thread1 index value: #thread1.j#

thread1 status: #thread1.Status#

thread2 index value: #thread2.j#

thread2 status: #thread2.Status#



Note: You can also have the ColdFusion Sever Monitor automatically check for and terminate hung threads.

Joining threads
You use the cfthread tag with an action attribute value of join to join two or more threads. You join threads when
one thread depends on one or more other threads completing before it can do some processing. For example, a page
can start multiple threads to do processing and join them before it processes the thread results. By default, the join
action stops the current thread from doing further processing until all the specified threads complete processing.
You can use a timeout attribute to specify the number of milliseconds that the current thread waits for the thread
or threads being joined to finish. If any thread does not finish by the specified time, the current thread proceeds
without waiting for the remaining thread or threads to complete.
The following code, for example, joins three threads to the current thread (often, the main page thread). The current
thread waits up to six seconds for the other threads to complete, and continues processing if one or more threads do
not complete by then.


If the timeout attribute value is 0, the default value, the current thread continues waiting until all joining threads
finish. In this case, if the current thread is the page thread, the page continues waiting until the threads are joined,
even if you specify a page time-out. As a general rule, you should specify a timeout value to limit hung threads.

Using thread data
Because multiple threads can process simultaneously within a single request, applications must ensure that data from
one thread does not improperly affect data in another thread. ColdFusion provides several scopes that you can use
to manage thread data, and a request-level lock mechanism that you use to prevent problems caused by threads that
access page-level data. ColdFusion also provides metadata variables that contain any thread-specific output and
information about the thread, such as its status and processing time.

Thread scopes
Each thread has three special scopes:

•

The thread-local scope

•

The Thread scope

•

The Attributes scope

ADOBE COLDFUSION 8 304
ColdFusion Developer’s Guide

The thread-local scope

The thread-local scope is an implicit scope that contains variables that are available only to the thread, and exist only
for the life of the thread. Any variable that you define inside the cfthread tag body without specifying a scope name
prefix is in the thread local scope and cannot be accessed or modified by other threads.
To create a thread-local variable, assign the variable in the cfthread tag body without specifying a scope prefix, as
in the following lines:



These two lines are equivalent, with one exception: If you use the var keyword, the assignment code must immediately follow the cfthread tag, before any other CFML tags.
The Thread scope

The Thread scope contains thread-specific variables and metadata about the thread. Only the owning thread can
write data to this scope, but the page thread and all other threads in a request can read the variable values in this
scope. Thread scope data remains available until the page and all threads that started from the page finish, even if
the page finishes before the threads complete processing.
To create a Thread scope variable, in the cfthread tag body, use the keyword Thread or the name of the thread (for
example, myThread) as a prefix. the following examples of creating a Thread scope variable are equivalent:



To access a thread’s Thread scope variables outside the thread, prefix the variable with the thread’s name, as in the
following example:


Thread scope variables are only available to the page that created the thread or to other threads created by that page.
No other page can access the data. If one page must access another page’s Thread scope data, you must put the data
in a database or file and access it from there.
Each thread’s Thread scope is a subscope of a special scope, cfthread, that lasts as long as the request, or until the last
thread that it starts completes, whichever is longer. Thus, if you have two threads, myThread1 and myThread2, you
can access their Thread scopes as cfthread.myThread1 and cfthread.myThread2 until all threads and the request
complete. In most cases, there is no need to use the cfthread scope directly. However, you might use the cfthread
scope name in either of the following situations:
1 If you generate the thread name dynamically, you can avoid using the Evaluate function by using the cfthread
scope with associative array notation, as the following code snippet shows:

...




2 If you have a thread with the same name as a Variables scope variable, you can access that thread’s Thread scope
only by prefacing the Thread name with cfthread. Otherwise, you access the Variables scope variable, or get an
error.
The Attributes scope and thread attributes

The Attributes scope contains attributes that are passed to the thread, either individually or in the
attributeCollection attribute. The Attributes scope is available only within the thread and only for the life of the
thread.

ADOBE COLDFUSION 8 305
ColdFusion Developer’s Guide

ColdFusion makes a complete (deep) copy of all the attribute variables before passing them to the thread; therefore,
the values of the variables inside the thread are independent of the values of any corresponding variables in other
threads, including the page thread. For example, if you pass a CFC instance as an attribute to a thread, the thread
gets a complete new copy of the CFC, including the contents of its This scope at the time that you create the thread.
Any changes made to the original CFC outside the thread, for example, by calling a CFC function, have no effect on
the copy that is in the thread. Similarly, any changes to the CFC instance in the thread have no effect on the original
CFC instance.
Copying the data ensures that the values passed to threads are thread-safe, because the attribute values cannot be
changed by any other thread. If you do not want the data to be duplicated, do not pass it to the thread as an attribute
or in the attributeCollection attribute. Instead, keep the data in a scope that the thread can access. An example
of an object that should not be passed to the thread as an attribute is a singleton CFC that should never be duplicated.
The singleton CFC must be kept in some shared scope and accessed by threads. For more information, see the “Using
other scopes” on page 305.
Because ColdFusion copies all attributes by value, you can have multiple threads, for example, threads created
dynamically in a loop, that use the same attribute names, but where each thread gets a different value, as shown in
the following code excerpt, which creates separate threads to copy each of several files in a directory:







Using other scopes

Threads have access to all the ColdFusion scopes. All the threads run by a page share the same Variables and This
scope. All the threads run in a request share the same Form, URL, Request, CGI, Cookie, Session, Application, Server
and Client scopes. You must be careful to lock access to these scopes if more than one thread could try to modify the
data in the scopes; otherwise you can get deadlocks between threads. For more information, see “Locking thread
data and resource access” on page 306.
Although a thread can access all the scopes, it might not be able to write to scopes like Session, Cookie, or Request
after the request page processing completes.
Scope precedence

If you do not specify a scope prefix on a variable inside a cfthread tag body, ColdFusion checks scopes in the
following order to find the variable:
1

Function-local, in function definitions in the thread only

2

Thread-local

3

Attributes

4

Variables

5

Thread/cfthread

Other scopes are checked in the standard scope checking order.

ADOBE COLDFUSION 8 306
ColdFusion Developer’s Guide

Locking thread data and resource access
When an application uses multiple threads, you must be careful to ensure that the threads do not simultaneously
attempt to use or modify shared resources that are not themselves thread-safe, including the following items:

• If multiple threads modify a Variables or Request scope variable, use a Request scope lock to control access to
the code that uses the variable to prevent deadlocks and race conditions. Similarly, use a Request scope lock around
code that accesses built-in data structures or subscopes of the Variables scope, such as the Forms variable, that you
change in multiple threads.
• Multiple threads should not try to access any other shared resource simultaneously. For example, you should not
use the same FTP connection from multiple threads. To prevent this behavior, place the code that uses the resource
in named cflock tags. Use the same name attribute for all cflock tags around code that uses a specific resource.
For more information on locking code, see cflock and “Locking code with cflock” on page 289 in the
ColdFusion Developer’s Guide.

Metadata variables
The Thread scope contains the following variables that provide information about the thread, called metadata.
Variable

Description

Elapsedtime

The amount of processor time that has been spent handling the thread.

Error

A ColdFusion error structure that contains the keys that you can access in a cfcatch tag. This variable
has a value only if an unhandled error occurred during thread processing. For information on handling thread errors,
see “Handling ColdFusion thread errors” on page 308.

Name

The thread name.

Output

Output text that is generated by the thread. Threads cannot display output directly. For more information see
“Handling thread output” on page 308.

Priority

The thread processing priority, as specified when you created the thread.

Starttime

The time at which the thread began processing.

Status

The current status of the thread. For information on using the Status in an application, see “Using the thread status” on
page 307.

As with other variables in the Thread scope, thread metadata is available to all of a page’s threads by specifying the
thread name as a variable prefix. For example, the page thread can get the current elapsed time of the myThread1
thread from the myThread1.ElapsedTime variable.
The metadata is available from the time that you create the thread until the time when the page and all threads started
on the page complete processing, even if the page finishes before the threads finish. This way, you can get thread
output, error information, and processing information during and after the time when the thread is processing.

Working with threads
Multithreaded applications use several building blocks, including the following:

•

Starting threads in loops

•

Getting information about the thread processing status

•

Displaying thread results

ADOBE COLDFUSION 8 307
ColdFusion Developer’s Guide

•

Handling thread errors

•

Using database transactions with threads

Starting threads inside loops
Because threads run asynchronously, page level variables can change during thread execution. As a result of this
behavior, if you start threads inside a cfloop, and code inside the threads uses the value of the loop iterator (the
index variable, query name, list item, etc.), you must pass the loop iterator to the thread as an attribute.
The following example shows the use of threads inside a loop. It uses an indexed cfloop tag to start five threads.
Each thread gets the current loop index value in a threadIndex attribute. The thread adds an array entry with the
thread’s threadIndex attribute value and the current value of the page cfloop index, pageIndex. After joining the
threads, the page displays the array contents. When you run the example, particularly if you run it multiple times,
you see that at the time the thread saves data to the array, the value of pageIndex has incremented past the
threadIndex value, and multiple threads often have the same pageIndex value; but the multiple threads always
have the correct threadIndex value.







#theOutput[j]# 



Using the thread status
The Thread scope status metadata variable lets the page, or any other thread started by the page, determine the
status of any thread. The page processing code can then take a necessary action, for example, if the thread has terminated abnormally or might be hung. The status variable can have the following values:
Value

Meaning

NOT_STARTED

The thread has been queued but is not processing yet.

RUNNNG

The thread is running normally.

TERMINATED

The thread stopped running as a result of one of the following actions:

•

A cfthread tag with a terminate action stopped the thread.

•

An error occurred in the thread that caused it to terminate.

•

A ColdFusion administrator stopped the thread from the Server Monitor.

COMPLETED

The thread ended normally.

WAITING

The thread has run a cfthread tag with action="join", and one or more of the threads being joined have not
yet completed.

ADOBE COLDFUSION 8 308
ColdFusion Developer’s Guide

Applications can check the thread status to manage processing. For example, an application that requires results from
a thread might specify a time-out when it joins the thread; in this case, it can check for the COMPLETED status to
ensure that the thread has completed processing and the join did not just result from a time-out. Similarly, an application can check the status value of threads that might not start or might not complete normally, and terminate it if
necessary. The example in “Ending a thread” on page 302 checks thread status and terminates any threads with
RUNNING or NOT_STARTED status.

Handling thread output
To prevent conflicts, only the page thread displays output. Therefore, named threads have the following limitations:

• ColdFusion puts all output that you generate inside a thread, such as HTML and plain text, or the generated
output of a cfoutput tag, in the Thread scope output metadata variable. The page-level code can display the
contents of this variable by accessing the threadName.output variable.
• All tags and tag actions that directly send output to the client (instead of generating page text such as HTML
output), do not work inside the thread. For example, to use the cfdocument or cfreport tags in a thread, you must
specify a filename attribute; to use a cfpresentation tag, you must use a directory attribute.

Handling ColdFusion thread errors
If an error occurs in a thread, page-level processing is not affected, and ColdFusion does not generate an error
message. If you do not handle the error by using a try/catch block in the thread code, the thread with the error terminates and the page-level code or other threads can get the error information from the thread metadata Error variable
and handle the error appropriately.
You cannot use page- or application-based error handling techniques to manage errors that occur during thread
execution. For that reason, you cannot use the cferror tag or the onError application event handler for thread
errors. Instead, use either of the following techniques:
Use cftry/cfcatch tags or try/catch CFScript statements in the cfthread body to handle the errors inside
the thread.

1

2 Handle the error outside the thread by using the thread error information that is available to the page and other
threads in the Thread scope threadName.Error variable. Application code can check this variable for error information. For example, after you join to a thread that might have had an error, you could check the
threadname.status variable for a value of terminated, which indicates that the thread terminated abnormally.
You could then check the threadName.Error variable for information on the termination cause.

Handling database transactions
Database transactions cannot span threads. For example, consider a page with the following structure:



...



...




ADOBE COLDFUSION 8 309
ColdFusion Developer’s Guide

In this case, query q1 is not included in the transaction that contains query q2. To include both queries in the transaction, you must put the complete transaction in a single thread, using a structure such as the following:



...


...





Using ColdFusion tools to control thread use
The ColdFusion Administrator and Server Monitor let you control the number of active threads, view information
about active threads, and end slow or hung threads.

Using the Administrator to limit threads
The Tag Limit Settings section of the ColdFusion Administrator Server Settings > Request Tuning page lets you
specify a maximum number of cfthread-started threads that can run at one time. When ColdFusion reaches this
maximum, it queues additional cfthread requests and starts the queued threads when running threads end.

Using the Server Monitor to view and end threads
You can use the Server Monitor to view information about active threads and to end threads that might be impairing
server performance, as follows:

• The Server Monitor displays information about all active ColdFusion threads on the Statistics > Active
ColdFusion Threads page. Displayed information includes the thread names, pages that started the threads, and the
thread processing time. Use this page to manually end any thread.
• If you select the Enabled option on the Server Monitor Alerts > Alerts Configuration page Unresponsive Server
tab, you can specify a threshold based on the number of threads that have been executing longer than a specific time.
If the number of threads that have run longer than the Busy Thread Time exceeds the Hung Thread Count, you can
have ColdFusion take one or more actions, including ending any threads that have run longer than a specified
number of seconds.
• If you select the Enabled option on the Server Monitor Alerts > Alerts Configuration page Slow Server tab, you
can specify an server response time threshold value. If ColdFusion exceeds the threshold, you can have it take one
or more actions, including ending any threads that have run longer than a specified number of seconds.
For more information on using the Server Monitor, see the Server Monitor online Help.

ADOBE COLDFUSION 8 310
ColdFusion Developer’s Guide

Example: getting multiple RSS feeds
The following example uses three threads to get the results of three RSS feeds. The user must submit the form with
all three feeds specified. The application joins the threads with a time-out of 6 seconds, and displays the feed titles
and the individual item titles as links.












This example requires three feeds.

Click the Back button and try again.











#feedResult.myProps.title#

#TITLE#






Enter three RSS Feeds









311

Chapter 18: Securing Applications
Resource security (ColdFusion Standard) or sandbox security (ColdFusion Enterprise) restricts access to specific
resources, such as tags and files. You use the ColdFusion Administrator to configure sandbox or resource security,
and structure an application to take advantage of this security.
User security depends on a user identity. You can implement user security in ColdFusion applications.
For detailed information on using Administrator-controlled security features, see Configuring and Administering
ColdFusion.
Contents

ColdFusion security features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
About resource and sandbox security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
About user security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Using ColdFusion security tags and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Security scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Implementing user security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

ColdFusion security features
ColdFusion provides scalable, granular security for building and deploying your ColdFusion applications.
ColdFusion provides the following types of security resources:
Development: ColdFusion Administrator is protected by a password. Additionally, you can specify a password for
access to data sources from Dreamweaver. For more information on configuring Administrator security passwords,
see the ColdFusion Administrator online Help.
CFML features: The CFML language includes specific features that you can use to enhance application security.
These include the following features:

• The cfqueryparam tag This tag helps prevent users from injecting malicious SQL expressions. For more
information on using this tag for database security, see “Enhancing security with cfqueryparam” on page 398,
• Scriptprotect setting This setting helps protect against cross-site scripting attacks. You can set this value with
the ColdFusion Administrator Enable Global Script Protection setting, in the Application.cfc This.scriptprotect
variable, or in the corresponding cfapplication tag scriptprotect attribute. For more information on this
feature, see cfapplication in the CFML Reference. For information on Application.cfc see “Defining the application and its event handlers in Application.cfc” on page 224.
• Encryption and hashing functions The Encrypt, Decrypt, and Hash functions let you select a secure
algorithm for encrypting and decrypting data or generating a hash “fingerprint.” You can select from among several
secure algorithms that are supported by the underlying Java security mechanisms; for encryption, these include,
AES, Blowfish, DES and Triple DES. For more information, see the Encrypt, Decrypt, and Hash, functions in the
CFML Reference.

ADOBE COLDFUSION 8 312
ColdFusion Developer’s Guide

• Data validation tools ColdFusion includes a variety of tools for validating form input and other data values,
including ways to ensure that users do not submit malicious form data. For information on data validation see
“Validating Data” on page 553; for specific information on security and validation, see “Security considerations” on
page 556.
Resource/Sandbox: The ColdFusion Administrator can limit access to ColdFusion resources, including selected
tags and functions, data sources, files, and host addresses. In the Standard Edition, you configure a single set of
resource limitations that apply to all your ColdFusion applications.
In the Enterprise Edition, you can have multiple sandboxes, based on the location of your ColdFusion pages, each
with its own set of resource limitations. You can confine applications to secure areas, thereby flexibly restricting the
access that the application has to resources.
User: ColdFusion applications can require users to log in to use application pages. You can assign users to roles
(sometimes called groups); ColdFusion pages can determine the logged-in user’s roles or ID and selectively
determine what to do based on this information. User security is also called authentication and authorization
security.
Note: You can also use the cfencode utility, located in the cf_root/bin directory, to obscure ColdFusion pages that you
distribute. Although this technique cannot prevent persistent hackers from determining the contents of your pages, it does
prevent inspection of the pages. The cfencode utility is not available on OS X.

About resource and sandbox security
ColdFusion provides two levels of resource-based security:

• ColdFusion Standard refers to its resource-based security as resource security. It lets you specify a single set of
limitations on access to ColdFusion resources that apply to all ColdFusion applications.
• ColdFusion Enterprise refers to its resource-based security as sandbox security. Sandbox security is a superset
of resource security. Sandbox security lets you create multiple sandboxes, each corresponding to a different directory.
For each sandbox, you specify a set of resource limitations that apply to all ColdFusion pages in the sandbox
directory and its subdirectories. If you create a sandbox that is a subdirectory of a sandbox, the subdirectory’s rules
override the parent directory’s rules.
The ColdFusion Administrator Resource Security page (in Standard) and Sandbox Security page (in Enterprise) let
you enable resource-based security. In ColdFusion Standard, the page lets you configure the resource settings that
apply to all your ColdFusion applications. In ColdFusion Enterprise, the page lets you create sandboxes and
configure the resource limitations for each sandbox individually.

Resource control
ColdFusion lets you control access to the following resources:

ADOBE COLDFUSION 8 313
ColdFusion Developer’s Guide

Resource

Description

Data sources

Enables access to specified data sources.

CF tags

Prevents pages from using CFML tags that access external resources. You can prevent pages in the directory from
using any or all of the following tags:
cfcollection, cfcontent, cfcookie, cfdirectory, cfdocument, cfexecute, cffile, cfftp,
cfgridupdate, cfhttp, cfhttpparam, cfindex, cfinsert, cfinvoke, cfldap, cflog, cfmail, cfobject,
cfobjectcache, cfpop, cfquery, cfregistry, cfreport, cfschedule, cfsearch, cfstoredproc,
cftransaction, cfupdate

CF functions

Prevents pages from using CFML functions that access external resources. You can prevent pages from using any or
all of the following functions:
CreateObject (COM, Java, Web Service), DirectoryExists. ExpandPath, FileExists,
GetBaseTemplatePath, GetDirectoryFromPath, GetFileFromPath, GetGatewayHelper,
GetProfileString, GetTempDirectory, GetTempFile, GetTemplatePath, SendGatewayMessage,
SetProfileString

Files/directories

Sets read, write, execute, and delete access to specified directories, directory trees, or files.

Server/ports

Controls access from ColdFusion to IP addresses and port numbers. You can specify host names or numeric
addresses, and you can specify individual ports and port ranges.

Note: For more information on configuring resource and sandbox security, see Configuring and Administering
ColdFusion and the ColdFusion Administrator online Help.

Sandbox security
In ColdFusion Enterprise, sandbox security lets you apply different sets of rules to different directory structures. You
can use it to partition a shared hosting environment so that a number of applications with different purposes, and
possibly different owners, run securely on a single server. When multiple applications share a host, you set up a
separate directory structure for each application, and apply rules that let each application access only its own data
sources and files.
Sandbox security also lets you structure and partition an application to reflect the access rights that are appropriate
to different functional components. For example, if your application has both employee inquiry functions and HR
functions that include creating, accessing, and modifying sensitive data, you could structure the application as
follows:

•

HR pages go in one directory with access rules that enable most activities.

•

Employee pages go in another directory whose rules limit the files they can modify and the tags they can use.

•

Pages required for both HR and employee functions go in a third directory with appropriate access rules.

About user security
User security lets your application use security rules to determine what it shows. It has two elements:
Authentication: Ensures that a valid user is logged-in, based on an ID and password provided by the user.
ColdFusion (or, in some cases if you use web server authentication, the web server) maintains the user ID information while the user is logged-in.

ADOBE COLDFUSION 8 314
ColdFusion Developer’s Guide

Authorization: Ensures that the logged-in user is allowed to use a page or perform an operation. Authorization is
typically based on one or more roles (sometimes called groups) to which the user belongs. For example, in an
employee database, all users could be members of either the employee role or the contractor role. They could also be
members of roles that identify their department, position in the corporate hierarchy, or job description. For example,
someone could be a member of some or all of the following roles:

•

Employees

•

Human Resources

•

Benefits

•

Managers

Roles enable you to control access in your application resources without requiring the application to maintain
knowledge about individual users. For example, suppose you use ColdFusion for your company’s intranet. The
Human Resources department maintains a page on the intranet on which all employees can access timely information about the company, such as the latest company policies, upcoming events, and job postings. You want
everyone to be able to read the information, but you want only certain authorized Human Resources employees to
be able to add, update, or delete information.
Your application gets the user’s roles from the user information data store when the user logs in, and then enables
access to specific pages or features based on the roles. Typically, you store user information in a database, LDAP
directory, or other secure information store.
You can also use the user ID for authorization. For example, you might want to let employees view customized information about their salaries, job levels, and performance reviews. You certainly would not want one employee to view
sensitive information about another employee, but you would want managers to be able to see, and possibly update,
information about their direct reports. By employing both user IDs and roles, you can ensure that only the appropriate people can access or work with sensitive data.
The following image shows a typical flow of control for user authentication and authorization. Following sections
expand on this diagram to describe how you implement user security in ColdFusion.

ADOBE COLDFUSION 8 315
ColdFusion Developer’s Guide

Authenticating users
You can use either, or both, of the following forms of authentication to secure your ColdFusion application:

• Web server authentication, where the web server authenticates the user and does not allow access to the website
by users without valid login IDs
• Application authentication, where the ColdFusion application authenticates the user and does not allow access
to the application by users without valid login IDs
About web server authentication

All major web servers support basic HTTP authentication. Some web servers also support other authentication
methods, including Digest HTTP authentication and Microsoft NTLM authentication.

ADOBE COLDFUSION 8 316
ColdFusion Developer’s Guide

Note: Dreamweaver and Studio MX do not support NTLM security with RDS. Therefore, you cannot use RDS with these
applications if the ColdFusion RDS servlet (cf_root/CFIDE/main/ide.cfm) is in a directory that is protected using
NTLM security.
In web server authentication, the web server requires the user to log in to access pages in a particular directory, as
follows:
1 When the user first requests a page in the secured directory, the web server notifies the browser that the
requested page requires credentials (a user ID and password).

Basic HTTP authentication sends the user ID and password in a base64-encoded string with each request. Use
SSL (Secure Sockets Layer) for all page transactions, to protect the user ID and password from unauthorized
access. For more information on SSL and the keytool utility, see “About LDAP Server Security” on page 458.
2

The browser prompts the user for the credentials.

3 The user supplies the credentials and the browser send the information back to the web server along with the
original request.
4

The web server checks the user ID and password, using its own user authentication mechanism.

5 If the user logs in successfully, the browser caches the authentication information and sends it in an HTTP
Authorization header with every subsequent page request from the user.
6 The web server processes the requested page and all future page requests from the browser that contain the
HTTP Authorization header, if it is valid for the requested page.

You can use web server authentication without using any ColdFusion security features. In this case, you configure
and manage all user security through the web server’s interfaces.
You can also use web server authentication with ColdFusion application authentication, and thus you can use
ColdFusion security for authorization. If the web server uses basic HTML authentication, the ColdFusion cflogin
tag provides access to the user ID and password that the user entered to log in to the web server. If the web server
uses Digest or NTLM authentication, the cflogin tag normally gets the user ID, but not the password.
As a result, your application can rely on the web server to authenticate the user against its user and password information, and does not have to display a login page. You use the cflogin and cfloginuser tags to log the user into
the ColdFusion user security system, and use the IsUserInAnyRole and GetAuthUser functions to ensure user
authorization. For more information on this form of security, see “A web server authentication security scenario” on
page 322.
Note: If a user has logged in using web server authentication and has not logged in using ColdFusion application authentication, the GetAuthUser tag returns the web server user ID. You could use this feature to combine web server authentication with application authorization based on the user’s ID.
About application authentication

With application authentication, you do not rely on the web server to enforce application security. The application
performs all user authentication and authorization. The application displays a login page, checks the user’s identity
and login against its own authorization store, such as an LDAP directory or database, and logs the user into
ColdFusion using the cfloginuser tag. The application can then use the IsUserInAnyRole and GetAuthUser
functions to check the user’s roles or identity for authorization before running a ColdFusion page or specific code
on a page. For an example of application authentication use, see “An application authentication security scenario” on
page 322.

ADOBE COLDFUSION 8 317
ColdFusion Developer’s Guide

ColdFusion authentication storage and persistence

How ColdFusion application authentication information is maintained by the browser and ColdFusion, and
therefore how long it is available, depends on the following:

•

Whether the user’s browser enables cookies

•

Whether the application supports the Session scope for login storage

Note: For detailed information on Session scope, see “Configuring and using session variables” on page 282. Cookie scope
contains the cookies that are sent by the browser; for more information on using cookies, see cfcookie in the CFML
Reference.
Authentication and cookies

Because HTTP is connectionless, a login can last beyond a single web page viewing only if the browser provides a
unique identifier that software on the server can use to confirm that the current user is authenticated. Normally, this
is done by using memory-only cookies that are automatically destroyed when the user closes all open browser
windows. The specific cookies and how they are used depend on whether the application supports the Session scope
for login storage.
Note: For information on user logins without cookies, see “Using ColdFusion security without cookies” on page 317.
Using the Session scope

If you do the following, ColdFusion maintains login information in the Session scope instead of the Cookie scope:

•

Enable the Session scope in the ColdFusion Administrator and the Application.cfc initialization code or

cfapplication tag.

•

Specify loginStorage="Session" in the Application.cfc initialization code or cfapplication tag.

When ColdFusion maintains login information in the Session scope, it stores the authentication details in a
Session.cfauthorization variable, and ColdFusion uses the session cookie information to identify the user. Sessionbased authentication has the following advantages over less persistent login storage:

•

After the user logs in, the user ID and password are not passed between the server and the browser.

• The login information and the session share a single time-out. There is no need to manually synchronize sessions
and logins.
• If you use server clusters, the Session scope login ID can be available across the cluster. For more information on
server clustering, see Configuring and Administering ColdFusion.
If you do not enable the Session scope, the authentication information is not kept in a persistent scope. Instead, the
detailed login information is put in a memory-only cookie (CFAUTHORIZATION_applicationName) with a
base64-encoded string that contains the user name, password, and application name. The client sends this cookie to
the web server each time it makes a page request while the user is logged-in. Use SSL for all page transactions to
protect the user ID and password from unauthorized access.
Using ColdFusion security without cookies

You can implement a limited-lifetime form of ColdFusion security if the user’s browser does not support cookies. In
this case you do not use the cflogin tag, only the cfloginuser tag. It is the only time you should use the
cfloginuser tag outside a cflogin tag.
Without browser cookies, the effect of the cfloginuser tag is limited to a single HTTP request. You must provide
your own authentication mechanism and call cfloginuser on each page on which you use ColdFusion login identification.

ADOBE COLDFUSION 8 318
ColdFusion Developer’s Guide

Using ColdFusion security tags and functions
ColdFusion provides the following tags and functions for user security:
Tag or function

Purpose

cflogin

A container for user authentication and login code. The body of the tag runs only if the user is not logged in.
When using application-based security, you put code in the body of the cflogin tag to check the userprovided ID and password against a data source, LDAP directory, or other repository of login identification. The
body of the tag includes a cfloginuser tag (or a ColdFusion page that contains a cfloginuser tag) to
establish the authenticated user’s identity in ColdFusion.

cfloginuser

Identifies (logs in) a user to ColdFusion. Specifies the user’s ID, password, and roles. This tag is typically used
inside a cflogin tag.
The cfloginuser tag requires three attributes, name, password, and roles, and does not have a body. The
roles attribute is a comma-delimited list of role identifiers to which the logged-in user belongs. All spaces in
the list are treated as part of the role names, so you should not follow commas with spaces.
While the user is logged-in to ColdFusion, security functions can access the user ID and role information.

cflogout

Logs out the current user. Removes knowledge of the user ID and roles from the server. If you do not use this
tag, the user is automatically logged out as described in “Logging out users” on page 321.
The cflogout tag does not take any attributes, and does not have a body.

cfNTauthenticate

Authenticates a user name and password against the NT domain on which ColdFusion server is running, and
optionally retrieves the user’s groups.

cffunction

If you include a roles attribute, the function executes only when there is a logged-in user who belongs to one
of the specified roles.

IsUserInAnyRole

Returns True if the current user is a member of the specified role.

GetAuthUser

Returns the ID of the currently logged-in user.
This tag first checks for a login made with cfloginuser tag. If none exists, it checks for a web server login
(cgi.remote_user.

Using the cflogin tag
The cflogin tag executes only if there is no currently logged-in user. It has the following three optional arguments
that control the characteristics of a ColdFusion login:
Attribute

Use

idleTimeout

If no page requests occur during the idleTimeout period, ColdFusion logs out the user. The default is 1800
seconds (30 minutes). This is ignored if login information is stored in the Session scope.

applicationToken

Limits the login validity to a specific application as specified by a ColdFusion page’s cfapplication tag. The
default value is the current application name.

cookieDomain

Specifies the domain of the cookie used to mark a user as logged-in. You use cookieDomain if you have a clustered environment (for example, x.acme.com, x2.acme.com, and so on). This lets the cookie work for all the
computers in the cluster.

ADOBE COLDFUSION 8 319
ColdFusion Developer’s Guide

Login identification scope and the applicationToken attribute

The login identification created by the cflogin tag is valid only for pages within the directory that contains the page
that uses the cflogin tag and any of its subdirectories. Therefore, if a user requests a page in another directory tree,
the current login credentials are not valid for accessing those pages. This security limitation lets you use the same
user names and passwords for different sections of your application (for example, a UserFunctions tree and a SecurityFunctions tree) and enforce different roles to the users depending on the section.
ColdFusion uses the applicationToken value to generate a unique identifier that enforces this rule. The default
applicationToken value is the current application name, as specified by a cfapplication tag or Application.cfc

unitization code. In normal use, you do not need to specify an applicationToken value in the cflogin tag.
Specifying the Internet domain

Use the cookieDomain attribute to specify the domain of the cookie used to mark a user as logged-in. You use
cookieDomain if you have a clustered environment (for example, www.acme.com, www2.acme.com, and so on).
This lets the cookie work for all computers in the cluster. For example, to ensure that the cookie works for all servers
in the acme.com domain, specify cookieDomain=".acme.com". To specify a domain name, start the name with a
period.
Important: Before setting the cookie domain, consider the other applications or servers in the broader domain might
have access to the cookie. For example, a clustered payroll application at payroll1.acme.com, payroll2.acme.com, and so
on, might reveal sensitive information to the test computer at test.acme.com, if the cookie domain is broadly set to
.acme.com.

Getting the user ID and password
The cflogin tag has a built-in cflogin structure that contains two variables, cflogin.username and cflogin.password,
if the page is executing in response to any of the following:

•

Submission of a login form that contains input fields with the names j_username and j_password.

• A request that uses HTTP Basic authentication and, therefore, includes an Authorization header with the user
name and password.
•

A message from the Flash Remoting gatewayConnection object that has the setCredentials method set.

• A request that uses NTLM or Digest authentication. In this case, the user name and password are hashed using
a one-way algorithm before they are put in the Authorization header; ColdFusion gets the user name from the web
server and sets the cflogin.password value to the empty string.
You use the first three techniques with application authentication, and the last technique with web server authentication. The cflogin structure provides a consistent interface for determining the user’s login ID and password,
independent of the technique that you use for displaying the login form.
Important: Login forms send the user name and password without encryption. Basic HTTP authentication sends the
user name and password in a base64-encoded string with each request; this format can easily be converted back to plain
text. Use these techniques only with https requests, or when you are not concerned about password security.
The following sections describe how you provide login information to your application for authentication
Using a login form to get user information

When you build an application that gets the User ID and password using a login form, the cflogin tag checks for
the existence of a cflogin structure containing the user’s login information. If the structure does not exist, it displays
a login form, typically using a cfinclude tag on a login page; the following code shows this use.

ADOBE COLDFUSION 8 320
ColdFusion Developer’s Guide

In the Application.cfc onRequestStart method, or a ColdFusion page or CFC method called by the method, you
have the following:











A simple login form looks like the following:



user name:



password:







Using a browser dialog box to get user information

Application authentication does not require you to use a login form; you can rely on the browser to display its
standard login dialog box, instead. To do so, your cflogin tag body returns an HTTP status 401 to the browser if
the user is not logged in or if the login fails; that is, if it does not have a valid cflogin structure. The browser displays
its login dialog box. When the user clicks the login button on the dialog box, the browser returns the login information as an HTTP Authorization header to ColdFusion, which puts the information in the cflogin tag’s cflogin
structure.
This technique has the advantage of simplicity; you do not need a login form and the user gets a familiar-looking
login page. You must be careful of security issues, however. The browser sends the user name and password in a
base64-encoded string, not just when the user logs in, but with each request. Use SSL (Secure Sockets Layer) for all
page transactions to protect the user ID and password from unauthorized access.
Note: You must ensure that your web server is configured correctly to support browser-based login forms for this use.
For example, in IIS 5, you must enable anonymous access and might have to disable Basic authentication and Integrated
Windows authentication.
The following cflogin tag tells the browser to display a login form if the user has not logged in:




ADOBE COLDFUSION 8 321
ColdFusion Developer’s Guide







Logging in a user using Flash Remoting

If you are developing a Rich Internet Application with Flash and Flash Remoting, your ColdFusion application does
not need to be coded specially for a Flash login. The Flash Remoting gateway makes the user ID and password
available to the cflogin tag in the cflogin structure.
In your Flash code, you use the ActionScript SetCredentials method to send login information to ColdFusion.
Your Flash SWF file displays the user ID and password fields, and uses their contents in the setCredentials
method, as follows:
if (inited == null)
{
inited = true;
NetServices.setDefaultGatewayUrl("http://localhost/flashservices/gateway");
gatewayConnection = NetServices.createGatewayConnection();
gatewayConnection.setCredentials(userID, password);
myService = gatewayConnection.getService("securityTest.thecfc", this);
}

For more information on using Flash Remoting, see “Using the Flash Remoting Service” on page 674 and “Using
Flash Remoting Update” on page 688.

Logging out users
After a user logs in, the ColdFusion user authorization and authentication information remains valid until any of the
following happens:

• The application uses a cflogout tag to log out the user, usually in response to the user clicking a log-out link or
button.
•

If your application uses the Session scope for login information, the session ends.

• If your application does not use the Session scope for login information, the user does not request a new page
for the cflogin tag idleTimeout period.
• If your application does not use Session scope for login information, or if you use J2EE-based session identification, the user closes all browser windows.
Logging a user out by using the cflogout tag does not close the user’s session, but if you use session login storage,
it does remove the login information (the Session.cfauthorization variable) from the Session scope. For more information on ending sessions, see “Ending a session” on page 286.
Important: If you use web server–based authentication or any form authentication that uses a Basic HTTP Authorization header, the browser continues to send the authentication information to your application until the user closes the
browser, or in some cases, all open browser windows. As a result, after the user logs out and your application uses the
cflogout tag, until the browser closes, the cflogin structure in the cflogin tag will contain the logged-out user’s UserID
and password. If a user logs out and does not close the browser, another user might access pages with the first user’s login.

ADOBE COLDFUSION 8 322
ColdFusion Developer’s Guide

Security scenarios
The following sections provide two detailed security scenarios. The first scenario uses the web server to perform the
authentication against its user and password database. The second scenario uses ColdFusion for all authentication
and authorization.

A web server authentication security scenario
An application that uses web server authentication might work as follows. The example in “Web server–based
authentication user security example” on page 326 implements this scenario.
1 When the user requests a page from a particular directory on the server for the first time after starting the
browser, the web server displays a login page and logs in the user. The web server handles all user authentication.
2

Because the user requested a ColdFusion page, the web server hands the request to ColdFusion.

3

When ColdFusion receives a request for a ColdFusion page, it instantiates the Application.cfc and runs

onRequestStart method. If you use an Application.cfm page in place of the Application.cfc, it runs the contents of

the Application.cfm page before it runs the requested page. The onRequestStart method or Application.cfm page
contains a cflogin tag. ColdFusion executes the cflogin tag body if the user is not logged into ColdFusion. The
user is logged in if the cfloginuser tag has run successfully for this application and the user has not been logged
out.
Code in the cflogin tag body uses the user ID and password from the browser login, contained in the
cflogin.name and cflogin.password variables, as follows. (With Digest or NTLM web server authentication, the
cflogin.password variable is the empty string.)

4

a It checks the user’s name against information it maintains about users and roles. In a simple case, the application might have two roles, one for users and one for administrators. The CFML assigns the Admin role to any
user logged on with the user ID Admin and assigns the User role to all other users.
b

It calls the cfloginuser tag with the user’s ID, password, and roles, to identify the user to ColdFusion.

5 Application.cfc or the Application.cfm page completes processing, and ColdFusion processes the requested
application page.
6 The application uses the IsUserInAnyRole function to check whether the user belongs to a role before it runs
protected code that must be available only to users in that role.

The application can use the GetAuthUser function to determine the user ID; for example, to display the ID for
personalization. It can also use the ID as a database key to get user-specific data.

7

Important: If you use web server–based authentication or any form authentication that uses a Basic HTTP Authorization header, the browser continues to send the authentication information to your application until the user closes the
browser, or in some cases, all open browser windows. As a result, after the user logs out and your application uses the
cflogout tag, until the browser closes, the cflogin structure in the cflogin tag will contain the logged-out user’s UserID
and password. If a user logs out and does not close the browser, another user might access pages with the first user’s login.

An application authentication security scenario
An application that does its own authentication might work as follows. The example in “Application-based user
security example” on page 328 implements this scenario.

ADOBE COLDFUSION 8 323
ColdFusion Developer’s Guide

1

Whenever ColdFusion receives a request for a ColdFusion page, it instantiates the Application.cfc and runs the

onRequestStart method. If you use an Application.cfm page in place of Application.cfc, ColdFusion runs the

contents of the Application.cfm page before it runs the requested page. The onRequestStart method or Application.cfm page contains the cflogin tag. ColdFusion executes the cflogin tag body if the user is not logged in. A
user is logged in if the cfloginuser tag has run during the current session and the user had not been logged out by
a cflogout tag.
Code in the cflogin tag body checks to see if it has received a user ID and password, normally from a login
form.

2

3 If there is no user ID or password, the code in the cflogin tag body displays a login form that asks for the user’s
ID and password.

The form posts the login information back to the originally requested page, and the cflogin tag in the
onRequestStart method or the Application.cfm page runs again. This time, the cflogin tag body code checks
the user name and password against a database, LDAP directory, or other policy store, to ensure that the user is
valid and get the user’s roles.
If the user name and password are valid, the cflogin tag body code calls the cfloginuser tag with the user’s
ID, password, and roles, to identify the user to ColdFusion.

4

5 When the user is logged in, application pages use the IsUserInAnyRole function to check whether the user
belongs to a role before they run protected code that must be available only to users in that role.

The application can use the GetAuthUser function to determine the user ID; for example, to display the ID for
personalization. It can also use the ID as a database key to get user-specific data.
6 Each application page displays a link to a logout form that uses the cflogout tag to log out the user. Typically,
the logout link is in a page header that appears in all pages. The logout form can also be in the Application.cfc (for
example, in the onRequestStart or onRequestEnd method) or on the Application.cfm page.

Although this scenario shows one method for implementing user security, it is only an example. For example, your
application could require users to log in for only some pages, such as pages in a folder that contains administrative
functions. When you design your user security implementation, remember the following:

•

Code in the cflogin tag body executes only if there is no user logged in.

• With application authentication, you write the code that gets the identification from the user and tests this information against a secure credential store.
•

After you have authenticated the user, you use the cfloginuser tag to log the user into ColdFusion.

The following image shows this flow of control. For simplicity, it omits the log-out option.

ADOBE COLDFUSION 8 324
ColdFusion Developer’s Guide

Implementing user security
The following sections provide several examples of ways to implement security.

Using the Dreamweaver Login Wizard
ColdFusion installs a Login Wizard command in the Dreamweaver Commands menu that generates a skeleton set
of pages for managing user authentication and authorization.
The wizard asks you to you select how to authenticate the login information. You can select one of the following
options:

• Simple You specify a single user ID and password in the wizard. All users must enter this information to log
in. You can use this option for testing, or you can use the generated files as a template where you can replace the
authentication code with more complex code; for example, to verify the ID and password against a database.
•

NT domain

You specify an NT domain in the wizard, and the wizard generates code that queries the domain.

• LDAP You specify the LDAP server and port, the user name and password required to access the login data,
and the distinguished name to use to start the search for the user name. The wizard generates the code to query the
LDAP server with the user ID and password.
The wizard asks you to select one of the following options for displaying the request for login information:

•

Browser Dialog Box

•

ColdFusion Login Form

Structure code generated by the Login Wizard

The wizard generates or modifies the following files in the directory or site that you specify:

ADOBE COLDFUSION 8 325
ColdFusion Developer’s Guide

Application.cfc: If this file does not exist, the wizard creates it with a single onRequestStart method; it does not
specify an application name or any other methods. If the file exists, but does not have an onRequestStart method,
it adds the method. If Application.cfc and the onRequestStart method exist, the wizard inserts the required code
at the beginning of the method. The resulting onRequestStart method has a cfinclude tag that specifies
mm_wizard_application_include.cfm; it also has a simple form with a logout button, which will display at the top of
each page in the application.
Note: If the wizard creates the Application.cfc file, you should, at least, change the file to specify the application name.
For more information on Application.cfc, see “Designing and Optimizing a ColdFusion Application” on page 218.
mm_wizard_application_include.cfm: The Login Wizard uses the information specified in the wizard fields to set
several CFC method arguments. It then uses them to invoke the performlogin method of the master login CFC,
mm_wizard.authenticate.
mm_wizard_authenticate.cfc: This CFC contains all of the user authentication and login logic. The CFC consists
of the following methods:

• The ntauth, ldapauth, and simpleauth authentication methods check the user’s name and ID against the valid
login information, and return information about whether the user is authenticated. For the details of how they
authenticate the user and the specific return values, see the methods.
• The performLogin method is the master login method. It contains the cflogin tag, which displays the login
form and calls the required authentication method. If the authentication method’s return argument indicates a valid
user, the method logs the user in.
• The logout method logs a user out. If you specified Browser Dialog Box as the login page type, it also calls the
closeBrowser method to close the browser window. This behavior is necessary because the browser continues to send
the old login credentials after the user logs out, and the cflogin tag will automatically use them and log the user in
again.
• The closeBrowser method closes the browser window or tells the user to close the browser window to complete
the logout, depending on the browser type.
mm_wizard_login.cfm: This file contains a ColdFusion login form. The wizard generates this file for all options,
but does not use it if you specify Browser Dialog login.
index.cfm or mm_wizard_index.cfm: The wizard generates an index.cfm page if the directory does not have one;
otherwise, creates an mm_wizard_index.cfm page. These pages let you test the generated login code before you
implement your application, or without using any of your standard application pages. To test your login, open the
index.cfm page in your browser.
Modifying the login code for your application

The Login Wizard creates a basic framework for authenticating a user. You must customize this framework to meet
your application’s needs. Typical security-related changes include the following:

•

Providing user-specific role information in the cflogin tag

•

Authenticating users against a database

Providing user-specific role information

The Login Wizard sets all users in a single role. In mm_wizard_authenticate.cfc, the performlogin method is hardcoded to set the role to “user.” The authentication routines handle roles differently. (For the details, see the
mm_wizard_authenticate.cfc code.) If your application uses roles for authorization, you must change the authentication method to get and return valid role information, and change the performlogin method to use the information
in the roles attribute of its cfloginuser tag.

ADOBE COLDFUSION 8 326
ColdFusion Developer’s Guide

Authenticating users against a database

If you use a database to maintain user IDs and passwords, you can create your login framework by specifying simple
authentication, and modify the code to use the database. The following instructions describe a simple way to change
the code to use a database. They do not include all the cleanup work (particularly, removing the hard-coded user
name and password), that you should do for a well-formatted application.
Replace the following code:







With code similar to the following:

SELECT *
FROM Users
WHERE UserName = 









Note: For greater security, consider using a hashed password. Do not store the password directly in the database; instead,
use the hash function to create a secure password fingerprint, and store it in the database. When the user provides a
password, use the Hash function on the submitted string and compare it with the value in the database.

Web server–based authentication user security example
The example in this section shows how you might implement user security using web-server–based basic authentication and two roles, user and administrator.
This example has two ColdFusion pages:
The Application.cfc page logs the user into the ColdFusion security system and assigns the user to specific roles
based on the user’s ID.

1

This page also includes the one-button form and logic for logging out a user, which appears at the top of each
page.
2

The securitytest.cfm page is a sample application page. It displays the logged-in user’s roles.

This simple example does not provide a user log-out interface. You can test the security behavior by adding your own
pages to the same directory as the Application.cfc page.
Example: Application.cfc

The Application.cfc page consists of the following:


ADOBE COLDFUSION 8 327
ColdFusion Developer’s Guide














Authentication data is missing.
Try to reload the page or contact the site administrator.





Reviewing the code

The Application.cfc onRequestStart method executes before the code in each ColdFusion page in an application.
For more information on the Application.cfc page and when it is executed, see “Designing and Optimizing a
ColdFusion Application” on page 218.
The following table describes the CFML code in Application.cfc and its function:
Code

Description






Identifies the application and starts the onRequestStart method that
runs at the starts of each request. The login information on this page only
applies to this application.









Executes if there is no logged-in user.



Logs the user into the ColdFusion security system and specifies the user’s
password, name, and roles. Gets the password and name directly from
the cflogin structure.



Authentication data is missing.
Try to reload the page or contact the
site administrator.


This code should never run, but if the user somehow got to this page
without logging in to the web server, this message would display and
ColdFusion would stop processing the request.






Ends the if/else block.

Makes sure the user is correctly logged in by the web server. (Otherwise,
there would be no cflogin variable.)
Sets a roles variable based on the user’s ID. Assigns users named "admin"
to the admin role. Assigns all other users to the users role.

Ends the cflogin tag body.
Ends the onRequestStart method.
Ends the Application component.

ADOBE COLDFUSION 8 328
ColdFusion Developer’s Guide

Example: securitytest.cfm

The securitytest.cfm page shows how any application page can use ColdFusion user authorization features. The web
server ensures the existence of an authenticated user, and the Application.cfc page ensures that the user is assigned
to roles the page content appears. The securitytest.cfm page uses the IsUserInAnyRole and GetAuthUser functions
to control the information that is displayed.
The securitytest.cfm page consists of the following:







Welcome #GetAuthUser()#!

ALL Logged-in Users see this message.




if (IsUserInRole("admin"))
WriteOutput("Users in the admin role see this message.

");
if (IsUserInRole("user"))
WriteOutput("Everyone in the user role sees this message.

");



Reviewing the code

The following table describes the securitytest.cfm page CFML code and its function:
Code

Description


Welcome #GetAuthUser()#!


User is already logged in by Application.cfc. Displays a welcome
message that includes the user’s login ID.

ALL Logged-in Users see this message.




Displays this message in all cases. The page does not display until a
user is logged in.


if (IsUserInRole("admin"))
WriteOutput("Users in the admin role
see this message.

");
if (IsUserInRole("user"))
WriteOutput("Everyone in the user role
sees this message.

");


Tests whether the user belongs to each of the valid roles. If the user is
in a role, displays a message with the role name.
The user sees one message per role to which the user belongs.

Application-based user security example
The example in this section shows how you might implement user security by authenticating users and then allowing
users to see or use only the resources that they are authorized to access.
This example has three ColdFusion pages:

ADOBE COLDFUSION 8 329
ColdFusion Developer’s Guide

• The Application.cfc page contains the authentication logic that checks whether a user is logged in, requests the
login page if the user is not logged in, and authenticates the data from the login page. If the user is authenticated, it
logs the user in.
This page also includes the one-button form and logic for logging out a user, which appears at the top of each
page.

•

The loginform.cfm page displays the login form. The code on this page could also be included in Application.cfc.

•

The securitytest.cfm page is a sample application page. It displays the logged-in user’s roles.

You can test the security behavior by adding your own pages to the same directory as the Application.cfc page.
The example gets user information from the LoginInfo table of the cfdocexamples database that is installed with
ColdFusion. You can replace this database with any database containing UserID, Password, and Roles fields. The
sample database contains the following data:
UserID

Password

Roles

BobZ

Ads10

Employee,Sales

JaniceF

Qwer12

Contractor,Documentation

RandalQ

ImMe

Employee,Human Resources,Manager

Because spaces are meaningful in roles strings, you should not follow the comma separators in the Roles fields with
spaces.
Example: Application.cfc

The Application.cfc page consists of the following:
















You must enter text in both the User Name and Password fields.






SELECT UserID, Roles
FROM LoginInfo
WHERE
UserID = '#cflogin.name#'

ADOBE COLDFUSION 8 330
ColdFusion Developer’s Guide

AND Password = '#cflogin.password#'





Your login information is not valid.

Please Try again
















Reviewing the code

The Application.cfc page executes before the code in each ColdFusion page in an application. For more information
on the Application.cfc page and when it is executed, see “Designing and Optimizing a ColdFusion Application” on
page 218.
The following table describes the CFML code in Application.cfc and its function:
Code

Description







Identifies the application, enables session management, and enables
storing login information in the Session scope.





If the user just submitted the logout form, logs out the user. The
following cflogin tag runs as a result.






Executes if there is no logged-in user.

Begins the definition of the onRequestStart method that runs at
the starts of each request.

Tests to see if the user has submitted a login form. If not, uses
cfinclude to display the form. The built-in cflogin variable exists
and contains the user name and password only if the login form used
j_username and j_password for the input fields.
The cfabort tag prevents processing of any code that follows on
this page.

ADOBE COLDFUSION 8 331
ColdFusion Developer’s Guide

Code

Description




You must enter text in both the
User Name and Password fields




Executes if the user submitted a login form.
Tests to make sure that both name and password have data. If either
variable is empty, displays a message, followed by the login form.
The cfabort tag prevents processing of any code that follows on
this page.



SELECT UserID, Roles
FROM LoginInfo
WHERE
UserID = '#cflogin.name#'
AND Password = '#cflogin.password#'


Executes if the user submitted a login form and both fields contain
data.




If the query returns data in the Roles field, logs in the user using the
user’s name and password and the Roles field from the database. In
this application, every user must be in some role.



Your login information is not
valid.

Please Try again




Executes if the query did not return a role. If the database is valid, this
means there was no entry matching the user ID and password.
Displays a message, followed by the login form.






Uses the cflogin structure’s name and password entries to find the
user record in the database and get the user’s roles.

The cfabort tag prevents processing of any code that follows on
this page.

Ends the loginquery.Roles test code.
Ends the form entry empty value test.
Ends the form entry existence test.
Ends the cflogin tag body.









If a user is logged-in, displays the Logout button.




Ends the onRequestStart method

If the user clicks the button, posts the form to the application’s (theoretical) entry page, index.cfm.
Application.cfc then logs out the user and displays the login form. If
the user logs in again, ColdFusion displays index.cfm.

Ends the Application component.

Example: loginform.cfm

The loginform.cfm page consists of the following:
Please Log In




ADOBE COLDFUSION 8 332
ColdFusion Developer’s Guide



user name:


password:








Reviewing the code

The following table describes the loginform.cfm page CFML code and its function:
Code

Description

Please Log In




user name:



password:









Example: securitytest.cfm

The securitytest.cfm page shows how any application page can use ColdFusion user authorization features. Application.cfc ensures the existence of an authenticated user before the page content appears. The securitytest.cfm page
uses the IsUserInAnyRole and GetAuthUser functions to control the information that is displayed.
The securitytest.cfm page consists of the following:







Welcome #GetAuthUser()#!

ALL Logged-in Users see this message.




if (IsUserInRole("Human Resources"))
WriteOutput("Human Resources members see this message.

");

ADOBE COLDFUSION 8 333
ColdFusion Developer’s Guide

if (IsUserInRole("Documentation"))
WriteOutput("Documentation members see this message.

");
if (IsUserInRole("Sales"))
WriteOutput("Sales members see this message.

");
if (IsUserInRole("Manager"))
WriteOutput("Managers see this message.

");
if (IsUserInRole("Employee"))
WriteOutput("Employees see this message.

");
if (IsUserInRole("Contractor"))
WriteOutput("Contractors see this message.

");



Reviewing the code

The following table describes the securitytest.cfm page CFML code and its function:
Code

Description


Welcome #GetAuthUser()#!


Displays a welcome message that includes the user’s login ID.

ALL Logged-in Users see this message.




Displays this message in all cases. The page does not display until a
user is logged in.


if (IsUserInRole("Human Resources"))
WriteOutput("Human Resources members
see this message.

");
if (IsUserInRole("Documentation"))
WriteOutput("Documentation members see
this message.

");
if (IsUserInRole("Sales"))
WriteOutput("Sales members see this
message.

");
if (IsUserInRole("Manager"))
WriteOutput("Managers see this
message.

");
if (IsUserInRole("Employee"))
WriteOutput("Employees see this
message.

");
if (IsUserInRole("Contractor"))
WriteOutput("Contractors see this
message.

");


Tests whether the user belongs to each of the valid roles. If the user is
in a role, displays a message with the role name.
The user sees one message per role to which he or she belongs.

Using an LDAP directory for security information
LDAP directories are often used to store security information. The following example of a cflogin tag checks an
LDAP directory to authenticate the user and retrieve the user’s roles.
For more information on using LDAP directories with ColdFusion, see “Managing LDAP Directories” on page 434.










ADOBE COLDFUSION 8 334
ColdFusion Developer’s Guide





























Reviewing the code

The following table describes the code and its function. Comments and some tab characters have been removed for
brevity.

ADOBE COLDFUSION 8 335
ColdFusion Developer’s Guide

Code

Description


Starts the cflogin tag body. Sets several variables to the values used as

attributes in the cfldap tag.







Sets prefix and suffix values used to create a distinquished name (dn) for
binding to the LDAP server.







In a cftry block, uses the user’s concatenated dn to authenticate to the
LDAP server and retrieve the common name (cn) attribute for groups to
which the user is a member. If the authentication fails the LDAP server
returns an error.
















Catches any exceptions.

Note: The LDAP permissions must allow an authenticated user to read and
search groups in order for the query to return results.

Tests to see if the error information includes the string "invalid credentials",
which indicates that either the dn or password is invalid. If so, displays a
dialog box with an error message indicating the problem.

Otherwise, displays a general error message.

If an error is caught, the cfabort tag ends processing of the request after
displaying the error description.
End of cfcatch and cftry blocks.







If the authorization query returns a valid record, logs in the user. Uses the
valueList function to create a comma-separated list of the users
retrieved group memberships, and passes them in the cfloginuser
roles attribute.
Ends the initial isDefined("cflogin") cfif block .
Ends the cflogin tag body

336

Chapter 19: Developing Globalized
Applications
ColdFusion lets you develop dynamic applications for the Internet. Many ColdFusion applications are accessed by
users from different countries and geographical areas. One design detail that you must consider is the globalization
of your application so that you can best serve customers in different areas.
Contents

Introduction to globalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
About character encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Processing a request in ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Tags and functions for globalizing applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Handling data in ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

Introduction to globalization
Globalization lets you create applications for all of your customers in all the languages that you support. In some
cases, globalization can let you accept data input using a different character set than the one you used to implement
your application. For example, you can create a website in English that lets customers submit form data in Japanese.
Or, you can allow a request URL to contain parameter values entered in Korean.
Your application also can process data containing numeric values, dates, currencies, and times. Each of these types
of data can be formatted differently for different countries and regions.
You can also develop applications in languages other than English. For example, you can develop your application in
Japanese so that the default character encoding is Shift-JIS, your ColdFusion pages contain Japanese characters, and
your interface displays in Japanese.
Globalizing your application requires that you perform one or more of the following actions:

•

Accept input in more than one language.

•

Process dates, times, currencies, and numbers formatted for multiple locales.

• Process data from a form, database, HTTP connection, e-mail message, or other input formatted in multiple
character sets.
•

Create ColdFusion pages containing text in languages other than English.

Defining globalization
You will probably find several different definitions for globalization. For this chapter, globalization is defined as an
architectural process where you put as much application functionality as possible into a foundation that can be
shared among multiple languages.
Globalization is composed of the following two parts:

ADOBE COLDFUSION 8 337
ColdFusion Developer’s Guide

Internationalization: Developing language-neutral application functionality that can recognize, process, and
respond to data regardless of its representation. That is, whatever the application can do in one language, it can also
do in another. For example, think of copying and pasting text. A copy and paste operation should not be concerned
with the language of the text it operates on. For a ColdFusion application, you might have processing logic that
performs numeric calculations, queries a database, or performs other operations, independent of language.
Localization: Taking shared, language-neutral functionality, and applying a locale-specific interface to it. Sometimes
this interface is referred to as a skin. For example, you can develop a set of menus, buttons, and dialog boxes for a
specific language, such as Japanese, that represents the language-specific interface. You then combine this interface
with the language-neutral functionality of the underlying application. As part of localization, you create the
functionality to handle input from customers in a language-specific manner and respond with appropriate responses
for that language.

Importance of globalization in ColdFusion applications
The Internet has no country boundaries. Customers can access websites from anywhere in the world, at any time, or
on any date. Unless you want to lock your customers into using a single language, such as English, to access your site,
you should consider globalization issues.
One reason to globalize your applications is to avoid errors and confusion for your customers. For example, a date
in the form 1/2/2003 is interpreted as January 2, 2003 in the United States, but as February 1, 2003 in European
countries.
Another reason to globalize your applications is to display currencies in the correct format. Think of how your
customers would feel when they find out the correct price for an item is 15,000 American dollars, not 15,000 Mexican
pesos (about 1600 American dollars).
Your website can also accept customer feedback or some other form of text input. You might want to support that
feedback in multiple languages using a variety of character sets.

How ColdFusion supports globalization
ColdFusion is implemented in Java. As a Java application, ColdFusion uses Java globalization features. For example,
ColdFusion stores all strings internally using the Unicode character set. Because it uses Unicode, ColdFusion can
represent any text data from any language.
In addition, ColdFusion includes many tags and functions designed to support globalizing your applications. You
can use these tags and functions to set locales, convert date and currency formats, control the output encoding of
ColdFusion pages, and perform other actions.

Character sets, character encodings, and locales
When you discuss globalization issues, two topics that you must consider are the character sets or character
encodings recognized by the application and the locales for which the application must format data.
A character set is a collection of characters. For example, the Latin alphabet is the character set that you use to write
English, and it includes all of the lower- and upper-case letters from A to Z. A character set for French includes the
character set used by English, plus special characters such as “é,” “à,” and “ç.”
The Japanese language uses three alphabets: Hiragana, Katakana, and Kanji. Hiragana and Katakana are phonetic
alphabets that each contain 46 characters plus two accents. Kanji contains Chinese ideographs adapted to the
Japanese language. The Japanese language uses a much larger character set than English because Japanese supports
more than 10,000 different characters.

ADOBE COLDFUSION 8 338
ColdFusion Developer’s Guide

In order for a ColdFusion application to process text, the application must recognize the character set used by the
text. The character encoding maps between a character set definition and the digital codes used to represent the data.
In general use, the terms character set (or charset) and character encoding are often used interchangeably, and most
often a specific character encoding encodes one character set. However, this is not always true; for example, there
are multiple encodings of the Unicode character set. For more information on character encodings, see “About
character encodings” on page 353.
Note: ColdFusion uses the term charset to indicate character encoding in some attribute names, structure field keys, and
function parameter names.
A locale identifies the exact language and cultural settings for a user. The locale controls how dates and currencies
are formatted, how to display time, and how to display numeric data. For example, the locale English (US) determines that a currency value displays as:
$100,000.00
while a locale of Portuguese (Brazilian) displays the currency as:
R$ 100.000
In order to correctly display date, time, currency, and numeric data to your customers, you must know the customer’s
locale. For more information on locales, see “Locales” on page 355.

About character encodings
A character encoding maps each character in a character set to a numeric value that can be represented by a computer.
These numbers can be represented by a single byte or multiple bytes. For example, the ASCII encoding uses seven
bits to represent the Latin alphabet, punctuation, and control characters.
You use Japanese encodings, such as Shift-JIS, EUC-JP, and ISO-2022-JP, to represent Japanese text. These encodings
can vary slightly, but they include a common set of approximately 10,000 characters used in Japanese.
The following terms apply to character encodings:
SBCS: Single-byte character set; a character set encoded in one byte per character, such as ASCII or ISO 8859-1.
DBCS: Double-byte character set; a method of encoding a character set in no more than two bytes, such as Shift-JIS.
Many character encoding schemes that are referred to as double-byte, including Shift-JIS, allow mixing of singlebyte and double-byte encoded characters. Others, such as UCS-2, use two bytes for all characters.
MBCS: Multiple-byte character set; a character set encoded with a variable number of bytes per character, such as
UTF-8.
The following table lists some common character encodings; however, there are many additional character
encodings that browsers and web servers support:

ADOBE COLDFUSION 8 339
ColdFusion Developer’s Guide

Encoding

Type

Description

ASCII

SBCS

7-bit encoding used by English and Indonesian Bahasa languages

Latin-1

SBCS

8-bit encoding used for many Western European languages

DBCS

16-bit Japanese encoding

(ISO 8859-1)
Shift_JIS

Note: You must use an underscore character (_), not a hyphen (-) in the name in CFML
attributes.
EUC-KR

DBCS

16-bit Korean encoding

UCS-2

DBCS

Two-byte Unicode encoding

UTF-8

MBCS

Multibyte Unicode encoding. ASCII is 7-bit; non-ASCII characters used in European and many
Middle Eastern languages are two-byte; and most Asian characters are three-byte

The World Wide Web Consortium maintains a list of all character encodings supported by the Internet. You can find
this information at www.w3.org/International/O-charset.html.
Computers often must convert between character encodings. In particular, the character encodings most commonly
used on the Internet are not used by Java or Windows. Character sets used on the Internet are typically single-byte
or multiple-byte (including DBCS character sets that allow single-byte characters). These character sets are most
efficient for transmitting data, because each character takes up the minimum necessary number of bytes. Currently,
Latin characters are most frequently used on the web, and most character encodings used on the web represent those
characters in a single byte.
Computers, however, process data most efficiently if each character occupies the same number of bytes. Therefore,
Windows and Java both use double-byte encoding for internal processing.

The Java Unicode character encoding
ColdFusion uses the Java Unicode Standard for representing character data internally. This standard corresponds to
UCS-2 encoding of the Unicode character set. The Unicode character set can represent many languages, including
all major European and Asian character sets. Therefore, ColdFusion can receive, store, process, and present text from
all languages supported by Unicode.
The Java Virtual Machine (JVM) that is used to processes ColdFusion pages converts between the character
encoding used on a ColdFusion page or other source of information to UCS-2. The page or data encodings that
ColdFusion supports depend on the specific JVM, but include most encodings used on the web. Similarly, the JVM
converts between its internal UCS-2 representation and the character encoding used to send the response to the
client.
By default, ColdFusion uses UTF-8 to represent text data sent to a browser. UTF-8 represents the Unicode character
set using a variable-length encoding. ASCII characters are sent using a single byte. Most European and Middle
Eastern characters are sent as two bytes, and Japanese, Korean, and Chinese characters are sent as three bytes. One
advantage of UTF-8 is that it sends ASCII character set data in a form that can be recognized by systems designed to
process only single-byte ASCII characters, while it is flexible enough to handle multiple-byte character representations.
While the default format of text data returned by ColdFusion is UTF-8, you can have ColdFusion return a page to
any character set supported by Java. For example, you can return text using the Japanese language Shift-JIS character
set. Similarly, ColdFusion can handle data that is in many different character sets. For more information, see “Determining the page encoding of server output” on page 358.

ADOBE COLDFUSION 8 340
ColdFusion Developer’s Guide

Character encoding conversion issues
Because different character encodings support different character sets, you can encounter errors if your application
gets text in one encoding and presents it in another encoding. For example, the Windows Latin-1 character
encoding, Windows-1252, includes characters with hexadecimal representations in the range 80-9F, while ISO 88591 does not include characters in that range. As a result, under the following circumstances, characters in the range
80-9F, such as the euro symbol (Ä), are not displayed properly:

•

A file encoded in Windows-1252 includes characters in the range 80-9F.

•

ColdFusion reads the file, specifying the Windows-1252 encoding in the cffile tag.

•

ColdFusion displays the file contents, specifying ISO-8859 in the cfcontent tag.

Similar issues can arise if you convert between other character encodings; for example, if you read files encoded in
the Japanese Windows default encoding and display them using Shift-JIS. To prevent these problems, ensure that the
display encoding is the same as the input encoding.

Locales
A locale identifies the exact language and cultural settings to use for a user. The locale controls how to format the
following:

•

Dates

•

Times

•

Numbers

•

Currency amounts

ColdFusion supports all locales supported by the JVM that it uses.
Note: Current JVM versions (through 1.4.2) do not support localized numbers such as Arabic-hindic numbers used in
Arabic locales or hindic digits used in Hindi locales. ColdFusion uses Arabic numbers in all locales.

Locale names
ColdFusion supports two formats for specifying locale names: the standard Java locale names and the ColdFusion
naming convention that was required through ColdFusion 6.1.

•

You can specify all locales using a name consisting of the following:

•

Two lowercase letters to identify the language; for example, en for English, or zh for Chinese.

• Optionally, an underscore and a two uppercase letters to identify the regional variant of the language; for
example, US for the United States, or HK for Hong Kong.
For example, en_US represents United States English and es_MX represents Mexican Spanish. For a list of the
Java locale identifiers supported in the Sun 1.4.2 JVM and their meanings, see
http://java.sun.com/j2se/1.4.2/docs/guide/intl/locale.doc.html.
Prior to ColdFusion MX 7, ColdFusion supported a limited set of locales, and used identifiers that consisted of the
name of the language, followed, for most languages, by a regional identifier in parentheses, such as English (US) or
German (Standard). ColdFusion continues to support these names; for a list, see SetLocale in the CFML Reference.
The Server.coldfusion.supportedlocales variable is a comma-delimited list of the locale names that you can
specify.

ADOBE COLDFUSION 8 341
ColdFusion Developer’s Guide

ColdFusion also includes a GetLocaleDisplayName function that returns a locale name in a format that is
meaningful to users. It lets you display the locale using words in the user’s language; for example, français (France).

Determining the locale
ColdFusion determines the locale value as follows:

• By default, ColdFusion uses the JVM locale, and the default JVM locale is the operating system locale. You can
set the JVM locale value explicitly in ColdFusion in the JVM Arguments field on the Java and JVM Settings page in
the ColdFusion Administrator; for example:
-Duser.language=de -Duser.country=DE.

•

A locale set using the SetLocale function persists for the current request or until it is reset by another

SetLocale function in the request.

• If a request has multiple SetLocale functions, the current locale setting affects how locale-sensitive ColdFusion
tags and functions (such as the functions that start with LS) format data. The last SetLocale function that
ColdFusion processes before sending a response to the requestor (typically the client browser) determines the value
of the response Content-Language HTTP header. The browser that requested the page displays the response
according to the rules for the language specified by the Content-Language header.
•

ColdFusion ignores any SetLocale functions that follow a cfflush tag.

Using the locale
The SetLocale function determines the default formats that ColdFusion uses to output date, time, number, and
currency values. You use the GetLocale function to determine the current locale setting of ColdFusion, or you can
use the GetLocaleDisplayName function to get the locale name in a format that is meaningful to users. If you have
not made a call to SetLocale, GetLocale returns the locale of the JVM.
The current locale has two effects:

• When ColdFusion formats date, time, currency, or numeric output, it determines how to format the output. You
can change the locale multiple times on a ColdFusion page to format information according to different locale
conventions. This enables you to output a page that properly formats different currency values, for example.
• When ColdFusion returns a page to the client, it includes the HTTP Content-Language header. ColdFusion
uses the last locale setting on the page for this information.
Note: In earlier versions of ColdFusion, the default locale was always English, not the operating system’s locale. For the
Japanese version of ColdFusion, the default was Japanese.
The following example uses the LSCurrencyFormat function to output the value 100,000 in monetary units for all
the ColdFusion-supported locales. You can run this code to see how the locale affects the data returned to a browser.
LSCurrencyFormat returns a currency value using the locale convention.



#locale#

Local: #LSCurrencyFormat(100000, "local")#

International: #LSCurrencyFormat(100000, "international")#

None: #LSCurrencyFormat(100000, "none")#





ADOBE COLDFUSION 8 342
ColdFusion Developer’s Guide

This example uses the ColdFusion variable Server.Coldfusion.SupportedLocales, which contains a list of all
supported ColdFusion locales.

Processing a request in ColdFusion
When ColdFusion receives an HTTP request for a ColdFusion page, ColdFusion resolves the request URL to a
physical file path and reads the file contents to parse it. A ColdFusion page can be encoded in any character encoding
supported by the JVM used by ColdFusion, but might need to be specified so that ColdFusion can identify it.
The following image shows an example of a client making a request to ColdFusion:

Client

Request

character set = ?
locale = ??

ColdFusion
character set =

Response

locale = ??

The content of the ColdFusion page on the server can be static data (typically HTML and plain text not processed
by ColdFusion), and dynamic content written in CFML. Static content is written directly to the response to the
browser, and dynamic content is processed by ColdFusion.
The default language of a website might be different from that of the person connecting to it. For example, you could
connect to an English website from a French computer. When ColdFusion generates a response, the response must
be formatted in the way expected by the customer. This includes both the character set of the response and the locale.
The following sections describe how ColdFusion determines the character set of the files that it processes, and how
it determines the character set and locale of its response to the client.

Determining the character encoding of a ColdFusion page
When a request for a ColdFusion page occurs, ColdFusion opens the page, processes the content, and returns the
results back to the browser of the requestor. In order to process the ColdFusion page, though, ColdFusion has to
interpret the page content.
One piece of information used by ColdFusion is the Byte Order Mark (BOM) in a ColdFusion page. The BOM is a
special character at the beginning of a text stream that specifies the order of bytes in multibyte characters used by
the page. The following table lists the common BOM values:
Encoding

BOM signature

UTF-8

EF BB BF

UTF-16 Big Endian

FE FF

UTF-16 Little Endian

FF FE

ADOBE COLDFUSION 8 343
ColdFusion Developer’s Guide

To insert a BOM character in a CFML page easily, your editor must support BOM characters. Many web page development tools support insertion of these characters, including Dreamweaver, which automatically sets the BOM
based on the Page Properties Document Encoding selection.
If your page does not contain a BOM, you can use the cfprocessingdirective tag to set the character encoding
of the page. If you insert the cfprocessingdirective tag on a page that has a BOM, the information specified by
the cfprocessingdirective tag must be the same as for the BOM; otherwise, ColdFusion issues an error.
The following procedure describes how ColdFusion recognizes the encoding format of a ColdFusion page.
Determine the page encoding (performed by ColdFusion)
1 Use the BOM, if specified on the page.

Adobe recommends that you use BOM characters in your files.
Use the pageEncoding attribute of the cfprocessingdirective tag, if specified. For detailed information on
how to use this attribute, see the cfprocessingdirective tag in the CFML Reference.

2

3 Default to the JVM default file character encoding. By default, this is the operating system default character
encoding.

Determining the page encoding of server output
Before ColdFusion can return a response to the client, it must determine the encoding to use for the data in the
response. By default, ColdFusion returns character data using the Unicode UTF-8 format.
ColdFusion pages (.cfm pages) default to using the Unicode UTF-8 format for the response, even if you include the
HTML meta tag in the page. Therefore, the following example will not modify the character set of the response:






...

In this example, the response will still use the UTF-8 character set. Use the cfcontent tag to set the output character
set.
However, within a ColdFusion page you can use the cfcontent tag to override the default character encoding of the
response. Use the type attribute of the cfcontent tag to specify the MIME type of the page output, including the
character set, as follows:


Note: ColdFusion also provides attributes that let you specify the encoding of specific elements, such as HTTP requests,
request headers, files, and mail messages. For more information, see “Tags and functions for controlling character
encoding” on page 359 and “Handling data in ColdFusion” on page 361.
The rest of this chapter describes ColdFusion tags and functions that you use for globalization, and discusses specific
globalization issues.

ADOBE COLDFUSION 8 344
ColdFusion Developer’s Guide

Tags and functions for globalizing applications
ColdFusion supplies many tags and functions that you can use to develop globalized applications.

Tags and functions for controlling character encoding
The following tags and functions let you specify the character encoding of text that ColdFusion generates and interprets:
Tag or function

Attribute or parameter

Use

cfcontent

type

Specifies the encoding in which to return the results to the client
browser. For more information, see “Determining the page encoding of
server output” on page 358.

cffile

charset

Specifies how to encode data written to a file, or the encoding of a file
being read. For more information, see “File data” on page 363.

cfheader

charset

Specifies the character encoding in which to encode the HTTP header
value.

cfhttp

charset

Specifies the character encoding of the HTTP request.

cfhttpparam

mimeType

Specifies the MIME media type of a file; can positionally include the file’s
character encoding.

cfmail

charset

Specifies the character encoding of the mail message, including the
headers.

cfmailpart

charset

Specifies the character encoding of one part of a multipart mail
message.

cfprocessingdirective

pageEncoding

Identifies the character encoding of the contents of a page to be
processed by ColdFusion. For more information, see “Determining the
character encoding of a ColdFusion page” on page 357.

CharsetDecode

encoding

Converts a string in the specified encoding to a binary object.

CharsetEncode

encoding

Converts a binary object to a string in the specified encoding.
Returns the character encoding of text in the Form or URL scope.

GetEncoding
SetEncoding

charset

Specifies the character encoding of text in the Form or URL scope. Used
when the character set of the input to a form, or the character set of a
URL, is not in UTF-8 encoding.

ToBase64

encoding

Specifies the character encoding of the string being converted to Base
64.

ToString

encoding

Returns a string encoded in the specified character encoding.

URLDecode

charset

Specifies the character encoding of the URL being decoded.

URLEncodedFormat

charset

Specifies the character encoding to use for the URL.

Functions for controlling and using locales
ColdFusion provides the following functions that let you specify and identify the locale and format text based on the
locale:

ADOBE COLDFUSION 8 345
ColdFusion Developer’s Guide

Tag or function

Use

GetLocale

Returns the current locale setting.

GetLocaleDisplayName

Returns the name of a locale in the language of a specific locale. The default value is the current locale in
the locale’s language..

LSCurrencyFormat

Converts numbers into a string in a locale-specific currency format. For countries that use the euro, the
result depends on the JVM version.

LSDateFormat

Converts the date part of a date/time value into a string in a locale-specific date format.

LSEuroCurrencyFormat

Converts a number into a string in a locale-specific currency format. Formats using the euro for all countries that use euro as the currency.

LSIsCurrency

Determines whether a string is a valid representation of a currency amount in the current locale.

LSIsDate

Determines whether a string is a valid representation of a date/time value in the current locale.

LSIsNumeric

Determines whether a string is a valid representation of a number in the current locale.

LSNumberFormat

Converts a number into a string in a locale-specific numeric format.

LSParseCurrency

Converts a string that is a currency amount in the current locale into a formatted number. For countries
that use the euro, the result depends on the JVM version.

LSParseDateTime

Converts a string that is a valid date/time representation in the current locale into a date-time object.

LSParseEuroCurrency

Converts a string that is a currency amount in the current locale into a formatted number. Requires euro
as the currency for all countries that use the euro.

LSParseNumber

Converts a string that is a valid numeric representation in the current locale into a formatted number.

LSTimeFormat

Converts the time part of a date/time value into a string in a locale-specific date format.

SetLocale

Specifies the locale setting.

Note: Many functions that have names starting with LS have corresponding functions that do not have this prefix:
DateFormat, IsDate, IsNumeric, NumberFormat, ParseDateTime, and TimeFormat. These function use English
(US) locale rules.
If you do not precede calls to the LS functions with a call to the SetLocale function, they use the locale defined by
the JVM, which typically is the locale of the operating system.
The following example uses the LSDateFormat function to display the current date in the format for each locale
supported by ColdFusion:






LSDateFormat Example
Format the date part of a date/time value using the locale convention.



#locale#

#LSDateFormat(Now(), "mmm-dd-yyyy")#

#LSDateFormat(Now(), "mmmm d, yyyy")#


ADOBE COLDFUSION 8 346
ColdFusion Developer’s Guide

#LSDateFormat(Now(), "mm/dd/yyyy")#

#LSDateFormat(Now(), "d-mmm-yyyy")#

#LSDateFormat(Now(), "ddd, mmmm dd, yyyy")#

#LSDateFormat(Now(), "d/m/yy")#

#LSDateFormat(Now())#







Additional globalization tags and functions
In addition to the tags and functions that are specifically for globalized applications, you might find the following
useful when writing a globalized application:

• All string manipulation functions. For more information, see the String functions list in “ColdFusion Functions”
on page 636 in the CFML Reference.
•

The GetTimeZoneInfo function, which returns the time zone of the operating system.

Handling data in ColdFusion
Many of the issues involved with globalizing applications deal with processing data from the various sources
supported by ColdFusion, including the following:

•

General character encoding issues

•

Locale-specific content

•

Input data from URLs and HTML forms

•

File data

•

Databases

•

E-mail

•

HTTP

•

LDAP

•

WDDX

•

COM

•

CORBA

•

Searching and indexing

General character encoding issues
Applications developed for earlier versions of ColdFusion that assumed that the character length of a string was the
same as the byte length might produce errors in ColdFusion. The byte length of a string depends on the character
encoding.

ADOBE COLDFUSION 8 347
ColdFusion Developer’s Guide

Locale-specific content
The following sections provide information on how to handle locale-specific content in pages that support multiple
locales, and how to handle euro values.
Generating multilocale content

In an application that supports users in multiple locales and produces output that is specific to multiple locales, you
call the SetLocale function in every request to set the locale for that specific request. When processing has
completed, the locale should be set back to its previous value. One useful technique is to save the user’s desired locale
in a Session variable once the user has selected it, and use the Session variable value to set the locale for each user
request during the session.
Supporting the euro

The euro is the currency of many European countries, and ColdFusion supports the reading and writing of correctly
formatted euro values. Unlike other supported currencies, the euro is not tied to any single country (or locale). The
LSCurrencyFormat and LSParseCurrency functions rely on the underlying JVM for their operations, and the rules
used for currencies depend on the JVM. For Sun JVMs, the 1.3 releases did not support euros and used the older
country-specific currencies. The 1.4 releases use euros for all currencies that are in the euro zone as of 2002. If you
are using a JVM that does not support the euro, use the LSEuroCurrencyFormat and LSParseEuroCurrency
functions to format and parse euro values in locales that use euros as their currency.

Input data from URLs and HTML forms
A web application server receives character data from request URL parameters or as form data.
The HTTP 1.1 standard only allows US-ASCII characters (0-127) for the URL specification and for message headers.
This requires a browser to encode the non-ASCII characters in the URL, both address and parameters, by escaping
(URL encoding) the characters using the “%xx” hexadecimal format. URL encoding, however, does not determine
how the URL is used in a web document. It only specifies how to encode the URL.
Form data uses the message headers to specify the encoding used by the request (Content headers) and the encoding
used in the response (Accept headers). Content negotiation between the client and server uses this information.
There are several techniques for handling both URL and form data entered in different character encodings.
Handling URL strings

URL requests to a server often contain name-value pairs as part of the request. For example, the following URL
contains name-value pairs as part of the URL:
http://company.com/prod_page.cfm?name=Stephen;ID=7645
As discussed previously, URL characters entered using any character encoding other than US-ASCII are URLencoded in a hexadecimal format. However, by default, a web server assumes that the characters of a URL string are
single-byte characters.
One common method used to support non-ASCII characters within a URL is to include a name-value pair within
the URL that defines the character encoding of the URL. For example, the following URL uses a parameter called
encoding to define the character encoding of the URL parameters:
http://company.com/prod_page.cfm?name=Stephen;ID=7645;encoding=Latin-1
Within the prod_page.cfm page, you can check the value of the encoding parameter before processing any of the
other name-value pairs. This guarantees that you will handle the parameters correctly.

ADOBE COLDFUSION 8 348
ColdFusion Developer’s Guide

You can also use the SetEncoding function to specify the character encoding of URL parameters. The SetEncoding
function takes two parameters: the first specifies a variable scope and the second specifies the character encoding
used by the scope. Since ColdFusion writes URL parameters to the URL scope, you specify "URL" as the scope
parameter to the function.
For example, if the URL parameters were passed using Shift-JIS, you could access them as follows:

setEncoding("URL", "Shift_JIS");
writeoutput(URL.name);
writeoutput(URL.ID);


Note: To specify the Shift-JIS character encoding, use the Shift_JIS attribute, with an underscore (_), not a hyphen (-).
Handling form data

The HTML form tag and the ColdFusion cfform tag let users enter text on a page, then submit that text to the server.
The form tags are designed to work only with single-byte character data. Since ColdFusion uses two bytes per
character when it stores strings, ColdFusion converts each byte of the form input into a two-byte representation.
However, if a user enters double-byte text into the form, the form interprets each byte as a single character, rather
than recognize that each character is two bytes. This corrupts the input text, as the following example shows:
1

A customer enters three double-byte characters in a form, represented by six bytes.

The form returns the six bytes to ColdFusion as six characters. ColdFusion converts them to a representation
using two bytes per input byte for a total of twelve bytes.
2
3

Outputting these characters results in corrupt information displayed to the user.

To work around this issue, use the SetEncoding function to specify the character encoding of input form text. The
SetEncoding function takes two parameters: the first specifies the variable scope and the second specifies the
character encoding used by the scope. Since ColdFusion writes form parameters to the Form scope, you specify
"Form" as the scope parameter to the function. If the input text is double-byte, ColdFusion preserves the two-byte
representation of the text.
The following example specifies that the form data contains Korean characters:

setEncoding("FORM", "EUC-KR");

 Form Test Result 
Form Values :

#text#

File data
You use the cffile tag to write to and read from text files. By default, the cffile tag assumes that the text that you
are reading, writing, copying, moving, or appending is in the JVM default file character encoding, which is typically
the system default character encoding. For cffile action="Read", ColdFusion also checks for a byte order mark
(BOM) at the start of the file; if there is one, it uses the character encoding that the BOM specifies.
Problems can arise if the file character encoding does not correspond to JVM character encoding, particularly if the
number of bytes used for characters in one encoding does not match the number of bytes used for characters in the
other encoding.

ADOBE COLDFUSION 8 349
ColdFusion Developer’s Guide

For example, assume that the JVM default file character encoding is ISO 8859-1, which uses a single byte for each
character, and the file uses Shift-JIS, which uses a two-byte representation for many characters. When reading the
file, the cffile tag treats each byte as an ISO 8859-1 character, and converts it into its corresponding two-byte
Unicode representation. Because the characters are in Shift-JIS, the conversion corrupts the data, converting each
two-byte Shift-JIS character into two Unicode characters.
To enable the cffile tag to correctly read and write text that is not encoded in the JVM default character encoding,
you can pass the charset attribute to it. Specify as a value the character encoding of the data to read or write, as the
following example shows:


Databases
ColdFusion applications access databases using drivers for each of the supported database types. The conversion of
client native language data types to SQL data types is transparent and is done by the driver managers, database client,
or server. For example, the character data (SQL CHAR, VARCHAR) you use with JDBC API is represented using
Unicode-encoded strings.
Database administrators configure data sources and usually are required to specify the character encodings for
character column data. Many of the major vendors, such as Oracle, Sybase, and Informix, support storing character
data in many character encodings, including Unicode UTF-8 and UTF-16.
The database drivers supplied with ColdFusion correctly handle data conversions from the database native format
to the ColdFusion Unicode format. You should not have to perform any additional processing to access databases.
However, you should always check with your database administrator to determine how your database supports
different character encodings.

E-mail
ColdFusion sends e-mail messages using the cfmail, cfmailparam, and cfmailpart tags.
By default, ColdFusion sends mail in UTF-8 encoding. You can specify a different default encoding on the Mail page
in the ColdFusion Administrator, and you can use the charset attribute of the cfmail and cfmailpart tags to
specify the character encoding for a specific mail message or part of a multipart mail message.

HTTP
ColdFusion supports HTTP communication using the cfhttp and cfhttpparam tags and the
GetHttpRequestData function.
The cfhttp tag supports making HTTP requests. The cfhttp tag uses the Unicode UTF-8 encoding for passing
data by default, and you can use the charset attribute to specify the character encoding. You can also use the
cfhttpparam tag mimeType attribute to specify the MIME type and character set of a file.

LDAP
ColdFusion supports LDAP (Lightweight Directory Access Protocol) through the cfldap tag. LDAP uses the UTF8 encoding format, so you can mix all retrieved data with other data and safely manipulated it. No extra processing
is required to support LDAP.

ADOBE COLDFUSION 8 350
ColdFusion Developer’s Guide

WDDX
ColdFusion supports the cfwddx tag. ColdFusion stores WDDX (Web Distributed Data Exchange) data as UTF-8
encoding, so it automatically supports double-byte character encodings. You do not have to perform any special
processing to handle double-byte characters with WDDX.

COM
ColdFusion supports COM through the cfobject type="com" tag. All string data used in COM interfaces is
constructed using wide characters (wchars), which support double-byte characters. You do not have to perform any
special processing to interface with COM objects.

CORBA
ColdFusion supports CORBA through the cfobject type="corba" tag. The CORBA 2.0 interface definition
language (IDL) basic type “String” used the Latin-1 character encoding, which used the full 8-bits (256) to represent
characters.
As long as you are using CORBA later than version 2.0, which includes support for the IDL types wchar and wstring,
which map to Java types char and string respectively, you do not have to do anything to support double-byte
characters.
However, if you are using a version of CORBA that does not support wchar and wstring, the server uses char and
string data types, which assume a single-byte representation of text.

Searching and indexing
ColdFusion supports Verity search through the cfindex, cfcollection, and cfsearch tags. To support
multlingual searching, the ColdFusion product CD-ROM includes the Verity language packs that you install to
support different languages.

351

Chapter 20: Debugging and
Troubleshooting Applications
ColdFusion provides detailed debugging information to help you resolve problems with your application. You
configure ColdFusion to provide debugging information, and use the cftrace and cftimer tags to provide detailed
information on code execution. You can also use tools for validating your code before you run it and troubleshoot
particular problems.
Note: Adobe Dreamweaver provides integrated tools for displaying and using ColdFusion debugging output. For information on using these tools, see the Dreamweaver online Help.
Contents

Configuring debugging in the ColdFusion Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Using debugging information from browser pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Controlling debugging information in CFML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Using the cftrace tag to trace execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
Using the cftimer tag to time blocks of code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
Using the Code Compatibility Analyzer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
Troubleshooting common problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

Configuring debugging in the ColdFusion
Administrator
ColdFusion can provide important debugging information for every application page requested by a browser. The
ColdFusion Administrator lets you specify which debugging information to make available and how to display it.
The following sections briefly describe the Administrator settings. For more information, see the online Help for the
Debugging pages.

Debugging Settings page
In the Administrator, the following options on the Debugging Settings page determine the information that
ColdFusion displays in debugging output:

ADOBE COLDFUSION 8 352
ColdFusion Developer’s Guide

Option

Description

Enable Robust Exception Information

Enables the display of the following information when ColdFusion displays the exception error
page. (Cleared by default.)

Enable Debugging

•

Path and URL of the page that caused the error

•

Line number and short snippet of the code where the error was identified

•

Any SQL statement and data source

•

Java stack trace

Enables debugging output. When this option is cleared, no debugging information is displayed,
including all output of cftrace and cftimer calls. (Cleared by default.)
You should disable debugging output on production servers. Doing so increases security by
ensuring that users cannot see debugging information. It also improves server response times. You
can also limit debugging output to specific IP addresses; for more information, see “Debugging IP
addresses page” on page 353.

Select Debugging Output Format

Determines how to display debugging output:

•

The classic.cfm template (the default) displays information as plain HTML text at the bottom of
the page.

• The dockable.cfm template uses DHTML to display the debugging information using an
expanding tree format in a separate window. This window can be either a floating pane or docked
to the browser window. For more information on the dockable output format, see “Using the
dockable.cfm output format” on page 360.
Report Execution Times

Lists ColdFusion pages that run as the result of an HTTP request and displays execution times, ColdFusion also highlights in red pages with processing times greater than the specified value, and you
can select between a summary display or a more detailed, tree structured, display.

General Debug Information

Displays general information about the request: ColdFusion Version, Template, Time Stamp, User
Locale, User Agent, User IP, and Host Name.

Database Activity

Displays debugging information about access to SQL data sources and stored procedures. (Selected
by default.)

Exception information

Lists all ColdFusion exceptions raised in processing the request. (Selected by default.)

Tracing information

Displays an entry for each cftrace tag. When this option is cleared, the debugging output does
not include tracing information, but the output page does include information for cftrace tags
that specify inline="Yes". (Selected by default.)
For more information on using the cftrace tag, see“Using the cftrace tag to trace execution” on
page 362.

Variables

Enables the display of ColdFusion variable values. When this option is cleared, disables display of all
ColdFusion variables in the debugging output. (Selected by default.)
When enabled, ColdFusion displays the values of variables in the selected scopes. You can select to
display the contents of any of the ColdFusion scopes except Variables, Attributes, Caller, and
ThisTag. To enhance security, Application, Server, and Request variable display is disabled by
default,

Enable Performance Monitoring

Allows the standard NT Performance Monitor application to display information about a running
ColdFusion application server.

Enable CFSTAT

Enables you to use of the cfstat command line utility to monitor real-time performance. This
utility displays the same information that ColdFusion writes to the NT System Monitor, without
using the System Monitor application. For information on the cfstat utility, see Configuring and
Administering ColdFusion.

The following image shows a sample debugging output using the classic output format:

ADOBE COLDFUSION 8 353
ColdFusion Developer’s Guide

Debugging IP addresses page
By default, when you enable debugging output, the output is visible only to local users (that is, via IP address
127.0.0.1). You can specify additional IP addresses whose users can see debugging output, or even disable output to
local users. In the Administrator, use the Debugging IPs page to specify the addresses that can receive debugging
messages.
Note: If you must enable debugging on a production server, for example to help locate the cause of a difficult problem,
use the Debugging IP Addresses page to limit the output to your development systems and prevent clients from seeing the
debugging information.

Using debugging information from browser pages
The ColdFusion debugging output that you configure in the Administrator displays whenever an HTML request
completes. It represents the server conditions at the end of the request. For information on displaying debugging
information while a request is processed, see “Using the cftrace tag to trace execution” on page 362.
The following image shows a sample collapsed debugging output using the dockable.cfm debugging output format.
The next sections show each of the debugging sections and describe how you can use the information they display.

ADOBE COLDFUSION 8 354
ColdFusion Developer’s Guide

General debugging information
ColdFusion displays general debugging information. In the classic.cfm output format, the information is at the top
of the debugging output. In the dockable.cfm output format, it looks like the following image:

(In the classic.cfm output format, the section is first in the debugging output and has no heading.)
The general debugging information includes the following values. The table lists the names used in the classic output
template view.

ADOBE COLDFUSION 8 355
ColdFusion Developer’s Guide

Name

Description

ColdFusion

The ColdFusion version.

Template

The requested template. (In the dockable.cfm format, this appears in the Page Overview section and is called Page.)

TimeStamp

The time the request was completed. (In the dockable.cfm format, this appears in the Page Overview section and is
called Date.)

Locale

The locality and language that determines how information is processed, particularly the message language.

User Agent

The identity of the browser that made the HTTP request.

Remote IP

The IP address of the client system that made the HTTP request.

Host Name

The name of the host running the ColdFusion server that executed the request.

Execution Time
The Execution Time section displays the time required to process the request. It displays information about the time
required to process all pages required for the request, including the Application.cfc, Application.cfm, and
OnRequestEnd.cfm pages, if used, and any CFML custom tags, pages included by the cfinclude tag, and any
ColdFusion component (CFC) pages.
To display execution time for a specific block of code, use the cftimer tag.
You can display the execution time in two formats:

•

Summary

•

Tree

Note: Execution tine decreases substantially between the first and second time you use a page after creating it or
changing it. The first time ColdFusion uses a page it compiles the page into Java bytecode, which the server saves and
loads into memory. Subsequent uses of unmodified pages do not require recompilation of the code, and therefore are
substantially faster.
Summary execution time format

The summary format displays one entry for each ColdFusion page processed during the request. If a page is
processed multiple times it appears only once in the summary. For example, if a custom tag gets called three time in
a request, it appears only once in the output. In the classic.cfm output format, the summary format looks like the
following image:

The following table describes the display fields:

ADOBE COLDFUSION 8 356
ColdFusion Developer’s Guide

Column

Description

Total Time

The total time required to process all instances of the page and all pages that it uses. For example, if a request causes
a page to be processed two times, and the page includes another page, the total time includes the time required to
process both pages twice.

Avg Time

The average time for processing each instance of this page and the pages that it uses. The Avg Time multiplied by
the Count equals the Total Time.

Count

The number of times the page is processed for the request.

Template

The path name of the page.

The page icon indicates the requested page.
Any page with an average processing time that exceeds the highlight value that you set on the Debugging Settings
page in the ColdFusion Administrator appears in red.
The next to last line of the output displays the time that ColdFusion took to parse, compile, and load pages, and to
start and end page processing. This image is not included in the individual page execution times. The last line shows
the sum of all the time it took to process the request.
Tree execution time format

The tree execution time format is a hierarchical, detailed view of how ColdFusion processes each page. If a page
includes or calls second page, the second page appears below and indented relative to the page that uses it. Each page
appears once for each time it is used. Therefore, if a page gets called three times in processing a request, it appears
three times in the tree. Therefore the tree view displays both processing times and an indication of the order of page
processing.
The tree format looks as follows in the dockable.cfm output format:

As in the summary view, the execution times (in parentheses) show the times to process the listed page and all pages
required to process the page, that is, all pages indented below the page in the tree.
By looking at this output in this image you can determine the following information:

•

ColdFusion took 0 ms to process an Application.cfm page as part of the request.

ADOBE COLDFUSION 8 357
ColdFusion Developer’s Guide

• The requested page was tryinclude.cfm. It took 203 ms to process this page and all pages required to execute it.
The code directly on this page took 71 milliseconds (203 - 93 - 16 - 23) to process.
• The mytag2.cfm page was processed three times. All processing took 93 milliseconds, and the average processing
time was 31 milliseconds. (This page does not call any other pages.)
• The mytag1.cfm page was processed two times. All processing took 78 milliseconds, and the average processing
time was 39 milliseconds. This time included the time to process mytag2.cfm (this tag calls the mytag2 custom tag);
therefore, the code directly on the page took an average of 8 milliseconds and a total of 16 milliseconds to process.
• The includeme.cfm page took about 62 ms to process. This processing time includes the time to process the
mytag1.cfm, and therefore also the time to process mytag2.cfm once. Therefore the code directly on the page took
23 milliseconds (62-39) to process.
•

ColdFusion took 125 ms for processing that was not associated with a specific page.

•

The total processing time was 328 milliseconds, the sum of 125 + 203.

Database Activity
In the Administrator, when Database Activity is selected on the Debugging Settings page, the debugging output
includes information about database access.
SQL Queries

The SQL Queries section provides information about tags that generate SQL queries or result in retrieving a cached
database query: cfquery, cfinsert, cfgridupdate, and cfupdate. The section looks like the following image in
the dockable.cfm output format:

The output displays the following information:

•

Page on which the query is located.

•

The time when the query was made.

•

Query name.

•

An indicator if the result came from a cached query.

ADOBE COLDFUSION 8 358
ColdFusion Developer’s Guide

•

SQL statement, including the results of processing any dynamic elements such as CFML variables and

cfqueryparam tags. This information is particularly useful because it shows the results of all ColdFusion processing

of the SQL statement.

•

Data source name.

•

Number of records returned; 0 indicates no match to the query.

•

Query execution time.

•

Any query parameters values from cfqueryparam tags.

Stored Procedures

The stored procedures section displays information about the results of using the cfstoredproc tag to execute a
stored procedure in a database management system.
The following image shows the Stored Procedures section in the classic.cfm output format:

The output displays the following information:

•

Stored procedure name

•

Data source name

•

Query execution time

•

Page on which the query is located.

•

The time when the query was made.

• A table displaying the procedure parameters sent and received, as specified in the cfprocparam tags, including
the ctype, CFSQLType, value variable, and dbVarName attributes. The variable information for OUT and
INOUT parameters includes the returned value.
•

A table listing the procedure result sets returned, as specified in the cfprocresult tag.

Exceptions
In the Administrator, when Exception Information is selected on the Debugging Settings page, the debugging output
includes a list of all ColdFusion exceptions raised in processing the application page. This section looks like the
following image when displaying information about an exception thrown by the cfthrow tag using the
dockable.cfm output format:

ADOBE COLDFUSION 8 359
ColdFusion Developer’s Guide

The exception information includes information about any application exceptions that are caught and handled by
your application code or by ColdFusion.
Exceptions represent events that disrupt the normal flow of an application. You should catch and, whenever possible,
recover from forseeable exceptions in your application, as described in “Handling Errors” on page 246. However, you
might also want to be alerted to caught exceptions when you are debugging your application. For example, if a file is
missing, your application can catch the cffile exception and use a backup or default file instead. If you enable
exception information in the debugging output, you can immediately see when this happens.

Trace points
In the Administrator, when Tracing Information is selected on the Debugging Settings page, the debugging output
includes the results of all cftrace tags, including all tags that display their results in-line. Therefore, the debugging
output contains a historical record of all trace points encountered in processing the request. The following image
shows this section when you use the classic.cfm output format:

For more information on using the cftrace tag, see “Using the cftrace tag to trace execution” on page 362.

Scope variables
In the Administrator, when the Variables option and one or more variable scopes are selected on the Debugging
Settings page, the debugging output displays the values of all variables in the selected scopes. The debugging output
displays the values that result after all processing of the current page.
By displaying selected scope variables you can determine the effects of processing on persistent scope variables, such
as application variables. This can help you locate problems that do not generate exceptions.
The Form, URL, and CGI scopes are useful for inspecting the state of a request. They let you inspect parameters that
affect page behavior, as follows:
URL variables: Identify the HTTP request parameters.
Form variables: Identify the form fields posted to an action page.
CGI variables: Provide a view of the server environment following the request.

ADOBE COLDFUSION 8 360
ColdFusion Developer’s Guide

Similarly, the Client, Session, Application, and Server scope variables show the global state of the application, and
can be useful in tracing how each page affects the state of the ColdFusion persistent variables.

Using the dockable.cfm output format
The dockable.cfm output format has several features that are not included in the classic.cfm debugging display, as
the following image of a docked debug pane shows:

Application page selections

ColdFusion displays two buttons at the bottom of each page, as described in the following table:
Button

Description

Debug This page

Tells ColdFusion to display the debugging information for the selected frame. Refreshes the debug pane
if you select it for the current frame (or the application does not use frames).

Floating/Docked debug pane

Toggles the display between a floating window and a pane docked to the left of the selected frame.

Debug pane features

The debug pane has the following features:

• You can expand and collapse each debugging information category, such as Exceptions, by clicking on the plus
or minus sign (+ or -) in front of each category heading. You can also expand and collapse each scope data type
display in the Scoped Variables section.
• The top of the debug pane displays the URL of the application page being debugged (as identified by the
cgi.script_name variable). Click this link to refresh the page and display the debugging information that results. (You
can also refresh the page and debugging information by using your browser’s Refresh button or key.)
• The debug pane also displays a box where you can enter a page pathname or URL. When you click the Go button,
ColdFusion processes the page and the debug pane is updated with the debugging information for the new page.

ADOBE COLDFUSION 8 361
ColdFusion Developer’s Guide

Controlling debugging information in CFML
The following sections describe how you can use CFML tags and functions to display or hide debugging and tracing
information.

Generating debugging information for an individual query
In the Administrator, the cfquery tag debug attribute overrides the Database Activity setting on the Debugging
Settings page. The debug attribute has an effect only when debugging output is enabled on the Debugging Settings
page, as follows:

• If Database Activity is selected in the Administrator, specify debug="No" to prevent ColdFusion from displaying
the query’s SQL and statistics in the debugging output.
• If Database Activity is not selected in the Administrator, specify debug="Yes" or debug to have ColdFusion
display the query’s SQL and statistics in the debugging output.
For example, if Database Activity is not selected in the Administrator, you can use the following code to show the
query execution time, number of records returned, ColdFusion page, timestamp, and the SQL statement sent to the
data source for this query only:

SELECT * FROM TestTable


The debug attribute can be useful to disable query debugging information generated by queries in custom tags that
you call frequently, so that you only see the debugging information for queries in pages that call the tags.
You can also view stored procedure-specific debugging information by specifying the debug attribute in the
cfstoredproc tag.

Controlling debugging output with the cfsetting tag
Use the cfsetting tag showDebugOutput attribute to turn off debugging output for a specific page. The attribute
controls debugging output only if the Debugging Settings page in the ColdFusion Administrator enables debugging
output. The attribute’s default value is Yes. The following tag suppresses all debugging output for the current page:


You can put this tag in the initialization code of the Application.cfc file or on your Application.cfm page to suppress
all debugging output for an application, and override it on specific pages by setting showDebugOutput="Yes" in
cfsetting tags on those pages. Conversely, you can leave debugging on for the application, and use the cfsetting
showDebugOutput="No" tag to suppress debugging on individual pages where the output could cause errors or
confusion.
You can also use the showDebugOutput attribute to control debugging output if you do not have access to the
ColdFusion Administrator, but only if the Administrator enables debugging.

Using the IsDebugMode function to run code selectively
The IsDebugMode function returns True if debugging is enabled. You can use this function in a cfif tag condition
to selectively run code only when debugging output is enabled. The IsDebugMode function lets you tell ColdFusion
to run any code in debug mode, so it provides more flexibility than the cftrace tag for processing and displaying
information.

ADOBE COLDFUSION 8 362
ColdFusion Developer’s Guide

You can use the IsDebugMode function to selectively log information only when debugging is enabled. Because you
control the log output, you have the flexibility of silently logging information without displaying trace information
in the browser. For example, the following code logs the application page, the current time, and the values of two
variables to the log file MyAppSilentTrace.log when debugging is enabled:

SELECT *
FROM Employee





If you use cfdump tags frequently for debugging, put them in  tags; for example . This way you ensure that if you leave any cfdump tags in

production code, they are not displayed when you disable debugging output.

Using the cftrace tag to trace execution
The cftrace tag displays and logs debugging data about the state of your application at the time the cftrace tag
executes. You use it to provide “snapshots” of specific information as your application runs.

About the cftrace tag
The cftrace tag provides the following information:

•

A severity identifier specified by the cftrace tag type attribute

•

A timestamp indicating when the cftrace tag executed

•

The time elapsed between the start of processing the request and when the current cftrace tag executes.

• The time between any previous cftrace tag in the request and the current one. If this is the first cftrace tag
processed for the request, the output indicates “1st trace”. ColdFusion does not display this information in inline
trace output, only the log and in the standard debugging output.
•

The name of the page that called the cftrace tag

•

The line on the page where the cftrace call is located

•

A trace category specified by the category attribute

•

A message specified by the text attribute

•

The name and value, at the time the cftrace call executes, of a single variable specified by the var attribute

A typical cftrace tag might look like the following:


You can display the cftrace tag output in either or both of the following ways:

• As a section in the debugging output: To display the trace information in the debugging output, in the Administrator, select Tracing Information on the Debugging Settings page.

ADOBE COLDFUSION 8 363
ColdFusion Developer’s Guide

• In-line in your application page: When you specify the inline attribute in a cftrace tag, ColdFusion displays
the trace output on the page at the cftrace tag location. (An inline cftrace tag does not display any output if it
is inside a cfsilent tag block.)
The cftrace tag executes only if you select Enable Debugging on the ColdFusion Administrator Debugging Settings
page. To display the trace results in the debugging output, you must also specify Tracing Information on the
Debugging Settings page; otherwise, the trace information is logged and inline traces are displayed, but no trace
information appears in the debugging output.
Note: When you use in-line trace tags, ColdFusion sends the page to the browser after all page processing is completed,
but before it displays the debugging output from the debug template. As a result, if an error occurs after a trace tag but
before the end of the page, ColdFusion might not display the trace for that tag.
The following images shows an in-line trace messages:

The following table lists the displayed information:
Entry

Meaning
Trace type (severity) specified in the cftrace call; in this case, Information.

[CFTRACE 13:21:11.011]

Time when the cftrace tag executed.

[501 ms]

Time taken for processing the current request to the point of the cftrace tag.

[C:\CFusion\wwwroot\MYStuff\mydocs\tractest.cfm]

Path in the web server of the page that contains the cftrace tag.

@ line:14

The line number of the cftrace tag.

[UDF End]

Value of the cftrace tag category attribute.

GetRecords UDF call has completed

The cftrace tag text attribute with any variables replaced with their values.

MyStatus Success

Name and value of the variable specified by the cftrace tag var attribute.

ColdFusion logs all cftrace output to the file logs\cftrace.log in your ColdFusion installation directory.
A log file entry looks like the following:
"Information","web-29","04/01/02","13:21:11","MyApp","[501 ms (1st trace)]
[C:\CFusion\wwwroot\MYStuff\mydocs\tractest.cfm @ line: 14] - [UDF End] [MyStatus = Success]
GetRecords UDF call has completed "

This entry is in standard ColdFusion log format, with comma-delimited fields inside double-quote characters. The
information displayed in the trace output is in the last, message, field.
The following table lists the contents of the trace message and the log entries. For more information on the log file
format, see “Logging errors with the cflog tag” on page 256.

ADOBE COLDFUSION 8 364
ColdFusion Developer’s Guide

Entry

Meaning

Information

The Severity specified in the cftrace call.

web-29

Server thread that executed the code.

04/01/02

Date the trace was logged.

13:21:11

Time the trace was logged.

MyApp

The application name, as specified in a cfapplication tag.

501 ms (1st trace)]

The time ColdFusion took to process the current request up to the
cftrace tag, This is the first cftrace tag processed in this request. If
there had been a previous cftrace tag, the parentheses would

contain the number of milliseconds between when the previous
cftrace tag ran and when this tag ran.
[C:\CFusion\wwwroot\MYStuff\mydocs\tracetest.cfm @ line: 14]

Path of the page on which the trace tag is located and the line number
of the cftrace tag on the page.

[UDF End]

Value of the cftrace tag category attribute.

[MyStatus = Success]

Name and value of the variable specified by the cftrace tag var
attribute. If the variable is a complex data type, such as an array or
structure, the log contains the variable value and the number of
entries at the top level of the variable, such as the number of top-level
structure keys.

GetRecords UDF call has completed

The cftrace tag text attribute with any variables replaced with their
values.

Using tracing
As its name indicates, the cftrace tag is designed to help you trace the execution of your application. It can help
you do any of several things:

• You can time the execution of a tag or code section. This capability is particularly useful for tags and operations
that can take substantial processing time. Typical candidates include all ColdFusion tags that access external
resources, including cfquery, cfldap, cfftp, cffile, and so on. To time execution of any tag or code block, call
the cftrace tag before and after the code you want to time.
• You can display the values of internal variables, including data structures. For example, you can display the raw
results of a database query.
• You can display an intermediate value of a variable. For example, you could use this tag to display the contents
of a raw string value before you use string functions to select a substring or format it.
• You can display and log processing progress. For example, you can put a cftrace call at the head of pages in your
application or before critical tags or calls to critical functions. (Doing this could result in massive log files in a
complex application, so you should use this technique with care.)
• If a page has many nested cfif and cfelseif tags you can put cftrace tags in each conditional block to trace
the execution flow. When you do this, you should use the condition variable in the message or var attribute.
• If you find that the ColdFusion server is hanging, and you suspect a particular block of code (or call to a cfx tag,
COM object, or other third-party component), you can put a cftrace tag before and after the suspect code, to log
entry and exit.

ADOBE COLDFUSION 8 365
ColdFusion Developer’s Guide

Calling the cftrace tag
The cftrace tag takes the following attributes. All attributes are optional.
Attribute

Purpose

abort

A Boolean value. If you specify True, ColdFusion stops processing the current request immediately after the tag. This
attribute is the equivalent of placing a cfabort tag immediately after the cftrace tag. The default is False. If this
attribute is True, the output of the cftrace call appears only in the cftrace.log file. The line in the file includes the
text “[ABORTED]”.

category

A text string specifying a user-defined trace type category. This attribute lets you identify or process multiple trace
lines by categories. For example, you could sort entries in a log according to the category.
The category attribute is designed to identify the general purpose of the trace point. For example, you might identify the point where a custom tag returns processing to the calling page with a “Custom Tag End” category. You can
also use finer categories; for example, by identifying the specific custom tag name in the category.
You can include simple ColdFusion variables, but not arrays, structures, or objects, in the category text by enclosing
the variable name in number signs (#).

inline

A Boolean value. If you specify True, ColdFusion displays trace output in-line in the page. The default is False.
The inline attribute lets you display the trace results at the place that the cftrace call is processed. This provides
a visual cue directly in the ColdFusion page display.
Trace output also appears in a section in the debugging information display.

text

A text message describing this trace point. You can include simple ColdFusion variables, but not arrays, structures,
or objects, in the text output by enclosing the variable name in number signs (#).

type

A ColdFusion logging severity type. The inline trace display and dockable.cfm output format show a symbol for each
type. The default debugging output shows the type name, which is also used in the log file. The type name must be
one of the following:
Information (default)

Warning

Error

Fatal Information
var

The name of a single variable that you want displayed. This attribute can specify a simple variable, such as a string,
or a complex variable, such as a structure name. Do not surround the variable name in number signs.
Complex variables are displayed in inline output in cfdump format; the debugging display and log file report the
number of elements in the complex variable, instead of any values.
You can use this attribute to display an internal variable that the page does not normally show, or an intermediate
value of a variable before the page processes it further.
To display a function return value, put the function inside the message. Do not use the function in the var attribute,
because the attribute cannot evaluate functions.

Note: If you specify inline trace output, and a cftrace tag is inside a cfsilent tag block, ColdFusion does not display
the trace information in line, but does include it in the standard debugging display.
The following cftrace tag displays the information in the example output and log entry in “About the cftrace tag”
on page 362:


ADOBE COLDFUSION 8 366
ColdFusion Developer’s Guide

Using the cftimer tag to time blocks of code
The cftimer tag displays execution time for a specified section of CFML code.

Using timing
Use this tag to determine how long it takes for a block of code to execute. This is particularly useful when ColdFusion
debugging output indicates excessive execution time, but does not pinpoint the long-running block of code.
To use this tag, you must enable debugging in the ColdFusion Administrator Debugging Settings page. In the
Debugging Settings page, you must also specifically enable usage of the cftimer tag by checking the Timer Information check box.
If you enable debugging for the cftimer tag only and display timing information in an HTML comment, you can
generate timing information without disturbing production users.

Calling the cftimer tag
You can control where the cftimer tag displays timing information, as follows:

•

Inline: Displays timing information following the  tag.

• Outline: Displays timing information at the beginning of the timed code and draws a box around the timed
code. (This requires browser support for the HTML FIELDSET attribute.)
•

Comment: Displays timing information in an HTML comment in the format . The default label is cftimer.

•

Debug: Displays timing information in the debugging output under the heading CFTimer Times.

The following example calls the cftimer tag multiple times, each time using a different type attribute:


CFTIMER test



select *
from Employees


#lastname#, #firstname#








select *
from CourseList




ADOBE COLDFUSION 8 367
ColdFusion Developer’s Guide



#Course_ID#
#CorName#
#CorLevel#









select *
from Parks

Select View > Source to see timing information



#Parkname#









select *
from Departments

Scroll down to CFTimer Times heading to see timing information



#Dept_ID#
#Dept_Name#






Using the Code Compatibility Analyzer
The Code Compatibility Analyzer has two purposes:

• It can validate your application’s CFML syntax. To do so, the analyzer runs the ColdFusion compiler on your
pages, but does not execute the compiled code. It reports errors that the compiler encounters.
• It can identify places where ColdFusion might behave differently than previous versions. The analyzer identifies
the following kinds of features:
• No longer supported: Their use results in errors. For example, ColdFusion now generates an error if you use
the cflog tag with the thread="Yes" attribute.
• Deprecated: They are still available, but their use is not recommended and the they might not be available
in future releases. Deprecated features might also behave differently now than in previous releases. For example,
the cfservlet tag is deprecated.

ADOBE COLDFUSION 8 368
ColdFusion Developer’s Guide

•

Modified behavior: They might behave differently than in previous versions. For example, the

StructKeyList function no longer lists the structure key names in alphabetical order.

The analyzer provides information about the incompatibility and its severity, and suggests a remedy where one
is required.
You can run the Code Compatibility Analyzer from the ColdFusion Administrator. Select Code Analyzer from the
list of Debugging & Logging pages.
Note: The CFML analyzer does not execute the pages that it checks. Therefore, it cannot detect invalid attribute combinations if the attribute values are provided dynamically at runtime.
For more information on using the Code Compatibility Analyzer, see Migrating ColdFusion 5 Applications.

Troubleshooting common problems
This section describes a few common problems that you might encounter and ways to resolve them.
For more information on troubleshooting ColdFusion, see the ColdFusion Support Center Testing and Troubleshooting page at http://www.adobe.com/support/coldfusion/troubleshoot.html. For common tuning and precautionary measurements that can help you prevent technical problems and improve application performance, see the
ColdFusion tech tips article, TechNote number 13810. A link to the article is located near the top of the Testing and
Troubleshooting page.

CFML syntax errors
Problem: You get an error message such as the following:
Encountered "function or tag name" at line 12, column 1.
Encountered "\"" at line 37, column 20.
Encountered "," at line 24, column 61.
Unable to scan the character '\"' which follows "" at line 38, column 53.

These errors typically indicate that you have unbalanced <, ", or # characters. One of the most common coding errors
is to forget to close quoted code, number sign-delimited variable names, or opening tags. Make sure the code in the
identified line and previous lines do not have missing characters.
The line number in the error message often does not identify the line that causes the error. Instead, it identifies the
first line where the ColdFusion compiler encountered code that it could not handle as a result of the error.
Problem: You get an error message you do not understand.
Make sure all your CFML tags have matching end tags where appropriate. It is a common error to omit the end tag
for the cfquery, cfoutput, cftable, or cfif tag.
As with the previous problem, the line number in the error message often does not identify the line that causes the
error, but the first line where the ColdFusion compiler encounters code that it could not handle as a result of the
error. Whenever you have an error message that does not appear to report a line with an error, check the code that
precedes it for missing text.
Problem: Invalid attribute or value.
If you use an invalid attribute or attribute values, ColdFusion returns an error message. To prevent such syntax
errors, use the CFML Code Analyzer. Also see “Using the cftrace tag to trace execution” on page 362.

ADOBE COLDFUSION 8 369
ColdFusion Developer’s Guide

Problem: You suspect that there are problems with the structure or contents of a complex data variable, such as a
structure, array, query object, or WDDX-encoded variable.
Use the cfdump tag to generate a table-formatted display of the variable’s structure and contents. For example, to
dump a structure named relatives, use the following line. You must surround the variable name with number
signs (#).


Data source access and queries
Problem: You cannot make a connection to the database.
You must create the data source before you can connect. Connection errors can include problems with the location
of files, network connections, and database client library configuration.
Create data sources before you refer to them in your application source files. Verify that you can connect to the
database by clicking the Verify button on the Data Sources page of the ColdFusion Administrator. If you are unable
to make a simple connection from that page, you might need to consult your database administrator to help solve
the problem.
Also, check the spelling of the data source name.
Problem: Queries take too long.
Copy and paste the query from the Queries section of the debugging output into your database's query analysis tool.
Then retrieve and analyze the execution plan generated by the database server's query optimizer. (The method for
doing this varies from dbms to dbms.) The most common cause of slow queries is the lack of a useful index to
optimize the data retrieval. In general, avoid table scans (or "clustered index" scans) whenever possible.

HTTP/URL
Problem: ColdFusion cannot correctly decode the contents of your form submission.
The method attribute in forms sent to the ColdFusion server must be Post, for example:


Problem: The browser complains or does not send the full URL string when you include spaces in URL parameters.
Some browsers automatically replace spaces in URL parameters with the %20 escape sequence, but others might
display an error or just send the URL string up to the first character (as does Netscape 4.7).
URL strings cannot have embedded spaces. Use a plus sign (+) or the standard HTTP space character escape
sequence, (%20) wherever you want to include a space. ColdFusion correctly translates these elements into a space.
A common scenario in which this error occurs is when you dynamically generate your URL from database text fields
that have embedded spaces. To avoid this problem, include only numeric values in the dynamically generated
portion of URLs.
Or, you can use the URLEncodedFormat function, which automatically replaces spaces with %20 escape sequences.
For more information on the URLEncodedFormat function, see the CFML Reference.

370

Chapter 21: Using the ColdFusion
Debugger
Adobe ColdFusion provides debugging information for individual pages. However, for complex development tasks,
you require a robust and interactive debugger. ColdFusion provides a line debugger that you can use when developing ColdFusion applications in Eclipse or Adobe Flex Builder. You can set breakpoints, step over, into, or out of
code, and inspect variables. You can also view ColdFusion log files.
Contents

About the ColdFusion Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Installing and uninstalling the ColdFusion Debugger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Setting up ColdFusion to use the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
About the Debug perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Using the ColdFusion Debugger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Viewing ColdFusion log files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

About the ColdFusion Debugger
The ColdFusion Debugger is an Eclipse plugin. It runs in the Eclipse Debug perspective. You can use the ColdFusion
Debugger to perform debugging tasks, including the following:

•

Setting breakpoints

•

Viewing variables

•

Stepping over, into, and out of function calls

Installing and uninstalling the ColdFusion Debugger
To use the ColdFusion Debugger, you must have the following software installed:

•

Eclipse version 3.1.2, Eclipse version 3.2, or Flex Builder 2

•

ColdFusion 8

To install the ColdFusion Debugger, you install the ColdFusion Eclipse plugins. For more information, see Installing
and Using ColdFusion.

Setting up ColdFusion to use the Debugger
Before you can use the Debugger, you must enable debugging in the ColdFusion Administrator.

ADOBE COLDFUSION 8 371
ColdFusion Developer’s Guide

Set up ColdFusion to use the Debugger
1 In the ColdFusion Administrator, select Debugging & Logging > Debugger Settings.
2

Enable the Allow Line Debugging option.

3

Specify the port to use for debugging if different from the default that appears.

4

Specify the maximum number of simultaneous debug session if different from the default.

5

Click Submit Changes.

6

You may have to increase the time after which requests time-out by doing the following:
a

Select Server Settings > Settings.

b

Enable the Timeout Requests After (Seconds) option.

c

Enter 300 or other appropriate number in the text box.

7 Restart ColdFusion. If you are running the J2EE configuration of ColdFusion, you must restart the server in
debug mode with the debug port as specified.
8 To modify the debug settings, in Eclipse, select Window > Preferences > ColdFusion > Debug Settings. You can
specify the home page URL, which points to the page that appears in the Debug Output Buffer of the debugger when
you click the Home button. You can also specify the extensions of the types of files that you can debug and variable
scopes that you want the Debugger to recognize. To improve performance when debugging large files, deselect all
scopes for which you do not require information.

Note: To ensure that the debugger stops in the template you are debugging on the line that causes a ColdFusion error,
you must select Preferences > ColdFusion > Debug Settings and select the Enable Robust Exception Information
checkbox.
9

To configure an RDS server, in Eclipse, select Window > Preferences > ColdFusion > RDS Configuration.
If you are running ColdFusion on the same computer as Eclipse, localhost is configured by default. To use any
additional RDS servers, you must enter the configuration information.

10 If ColdFusion and Eclipse are not running on the same computer, in Eclipse, select Window > Preferences >
ColdFusion > Debug Mappings. Then specify the path that Eclipse uses to open files on the ColdFusion server and
the path that ColdFusion uses to find the files that you are editing in Eclipse.

Mapping ensures that Eclipse and ColdFusion are working on the same file. For example, you may be editing
files in an Eclipse project that points to D:\MyCoolApp. Then, when you deploy the files to the ColdFusion
server, you copy them to W:\websites\MyCoolSite\, which the ColdFusion server recognizes as
D:\Shared\websites\MyCoolSite. The mapping in Eclipse specifies that the Eclipse directory is D:\MyCoolApp
and the server is D:\Shared\websites\MyCoolSite. Eclipse translates the file path (D:\MyCoolApp\index.cfm) to
a path that the ColdFusion server recognizes (D:\Shared\websites\MyCoolSite\index.cfm). To see more information about the interaction between the client and the server, add the following to the JVM arguments in the
ColdFusion Administrator:
-DDEBUGGER_TRACE=true

11 If you are not running the server configuration of ColdFusion, you must specify Java debugging parameters in
the configuration file or startup script of the application server you are running. The parameters should look like the
following:
-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=

Ensure that the port number you specify is the same port number specified on the Debugger Settings page of
ColdFusion Administrator.

ADOBE COLDFUSION 8 372
ColdFusion Developer’s Guide

If you are running the server configuration, ColdFusion writes these debugging parameters to the jvm.config file
when you use the Debugger Settings page of the ColdFusion Administrator.
12 If you are not running the server configuration and your application server is not running on JRE 1.6, you must
copy the tools.jar file of the JDK version that your application server is running to the \lib folder of ColdFusion. For
example, if you are running JRun that runs on JRE 1.4, copy the tools.jar file of JDK 1.4 to the \lib folder of
ColdFusion.
13 If you are running the server version of ColdFusion and you specify a JRE version other than JRE 1.6 in the

jvm.config file, you must copy the tools.jar file of the JDK version specified in your jvm.config file to the \lib folder
of ColdFusion.
Note: To debug ColdFusion applications running on the multiserver configuration, you must start the ColdFusion server
from the command line using the following command:
jrun -config  -start 

About the Debug perspective
After you install the ColdFusion Plugin, enable the debugger in ColdFusion, and configure Eclipse, you can use the
ColdFusion Debugger in Eclipse. It is available in the Eclipse Debug perspective.
The Debug perspective includes the following:

• Debug pane, which keeps the results of each completed session. The following buttons appear at the top of this
pane:
•

Resume - Resumes a debugging session

•

Suspend - Pauses a debugging session

•

Terminate - Stops a debugging session

•

Disconnect - Disconnects the debugger from the selected debug target when debugging remotely

•

Remove All Terminated Launches - Clears all terminated debug targets from the display

•

Step Into - Executes code line by line, including included code, UDFs, CFCs, and the like

•

Step Over - Executes code line by line, excluding included code, UDFs, CFCs, and the like

•

Step Return - Returns to the original page from which you entered the included code, UDF, CFC, or the like

• Drop to Frame -Reenters a specified stack frame, which is analogous to going in reverse and restarting your
program partway through
•

Use Step Filters/Step Debug - Ensures that all step functions apply step filters

• Menu - Displays the menu that lets you manage the view, show system threads, show qualified names, and
show monitors
• Variables pane, which shows the current variables, including the variable scope. The following buttons appear at
the top of this pane:
•

Show Type Names - Displays the type of the variables

•

Show Logical Structure - This button is not supported

•

Collapse All - Collapses the information in the panel to show only variable types

ADOBE COLDFUSION 8 373
ColdFusion Developer’s Guide

• Breakpoints pane - Lists breakpoints in the ColdFusion application. The following buttons appear at the top of
this pane:
•

Remove Selected Breakpoints - Removes a breakpoint

•

Remove All Breakpoints - Removes all breakpoints

• Show Breakpoints Supported by Selected Targets - Displays the breakpoints for what you are currently
debugging
•

Go to File for Breakpoint - Goes to the file in which the selected breakpoint is set

•

Skip All Breakpoints - Ignores all breakpoints

•

Expand All - Expands the information in the pane

•

Collapse All - Collapses the information in the pane

• Link with Debug View - Highlights the selected breakpoint when the application stops execution in the
Debug View
• Add Java Exception Breakpoint - Lets you specify which Java exception to throw when you reach the selected
breakpoint
•

Menu - Lets you specify the type of information to display in the Breakpoints pane

• Debug Output Buffer - Contains two panes: Browser, which displays what appears in the browser during application execution; Server Output Buffer, which displays the debug output.
•

Edit pane, which displays the stacked source panes, one for each source file you have open.

•

Outline pane, which displays the current source file’s content in outline form

Using the ColdFusion Debugger
After you enabled the debugger in the ColdFusion Administrator and configure Eclipse, you can debug ColdFusion
pages that are in an Eclipse project. You can use the ColdFusion Debugger to do the following tasks:

•

Setting a breakpoint

•

Executing code line by line

•

Inspecting variables

Begin debugging a ColdFusion application
1 Open the file in the Eclipse project to debug.

You do not have to create an Eclipse project in the same folder as CFML source. You can create a project in a
different folder, create a folder under that project, and then link it to the folder where CFML sources reside.
2

Click Debug in the upper-right corner of the Eclipse workbench to go to the Debug perspective.

3 Select Window > Show View > Debug Output Buffer to be able to see the output from your application and how
your application appears in a browser.
4 Select Window > Preferences and specify the home page for your debugging session, the extensions of the file
types that you can debug, and the variable scopes of the variables to show in the Variables pane. Click OK.

The home page is the page that appears in the Debug Output Buffer pane when you click the Home button in
the Debug Output Buffer pane.

ADOBE COLDFUSION 8 374
ColdFusion Developer’s Guide

5

To begin debugging the file whose source appears in the Edit pane, click the Debug icon in the Eclipse toolbar.

6

Click New to create a new debugging configuration.

7

Specify the home page for the active debug session.
This is the page that appears in the Debug Output Buffer pane when you click the Debug Session Home button
in the Debug Output Buffer pane.

8

Click Debug to start the debug session.

Note: If you are in the process of debugging a template and then try to browse to or refresh that page, doing so can result
in unexpected behavior in the Debugger.

Setting a breakpoint
You can set breakpoints in your CFML file to stop execution of the page at particular points. When you set a breakpoint on a line, execution of the CFML stops just before that line. For example, if you set a breakpoint on the third
line in the following CFML page, execution stops before .

Your name is #yourName#.
 Preferences > ColdFusion > Debug Settings
and deselect all scopes for which you do not require information.
You should avoid using Step In on CFML instructions such as the cfset tag. Step In is more performance intensive
than Step Over. You can use Step In for UDFs, CFCs, custom tags and included files.
When stepping into functions, tags, and files, Eclipse expects the file to be displayed in one of the open projects. The
file that you are stepping in must be in an open Eclipse project.
Sometimes Eclipse 3.2.1 does not show the stack trace, and step buttons are disabled, even though the debugger has
stopped at a line. To enable the step buttons, click the debugger server instance in the Debug window. To see the stack
trace, click either Step In or Step Out.

Inspecting variables
As you observe execution of your code, you can see the values and scope of variables in the Variables panel. The
Variables panel displays the scope and value of variables as the CFML code executes. Only variables whose scopes
are those you selected in the Preferences dialog box appear in the Variables pane.

Viewing ColdFusion log files
You can easily see the contents of all the log files that ColdFusion generates by using the Log File Viewer.
View the ColdFusion log files
1 In Eclipse, select Window > Show View > Other > ColdFusion > CF Log Viewer.
2

To view details of a log file, double-click the name of the file.

3

To include the log files in another folder, click the Add Log Folder button, select the folder, and then click OK.

4 To remove a folder from the list, without deleting it from the computer’s file system, click the Delete Log File
button, select the folder, and then click OK.
5

To remove a log file from the computer’s file system, click the Delete Log File button.

6

To remove the contents of the detail pane, click the Menu button, and then click Clear Log.

7

To update the contents of the detail pane, click the Menu button, and then click Refresh Log.

376

Part 4: Accessing and Using Data
This part contains the following topics:
Introduction to Databases and SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Accessing and Retrieving Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Updating Your Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Using Query of Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .413
Managing LDAP Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
Building a Search Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
Using Verity Search Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488

378

Chapter 22: Introduction to Databases
and SQL
ColdFusion lets you create dynamic applications to access and modify data stored in a database. You do not require
a thorough knowledge of databases to develop ColdFusion applications, but you must know some basic database and
SQL concepts and techniques.
Each database server (such as SQL Server, Oracle, or DB2) has unique capabilities and properties. For more information, see the documentation that ships with your database server.
Contents

What is a database? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Using SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Writing queries by using an editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

What is a database?
A database defines a structure for storing information. Databases are typically organized into tables, which are
collections of related items. You can think of a table as a grid of columns and rows. ColdFusion works primarily with
relational databases, such as Oracle, DB2, and SQL Server.
The following image shows the basic layout of a database table:

A. row B. column

A column defines one piece of data stored in all rows of the table. A row contains one item from each column in the
table.
For example, a table might contain the ID, name, title, and other information for individuals employed by a company.
Each row, called a data record, corresponds to one employee. The value of a column within a record is referred to as
a record field.
The following image shows an example table, named employees, containing information about company employees:

ADOBE COLDFUSION 8 379
ColdFusion Developer’s Guide

Example employees table

The record for employee 4 contains the following field values:

•

LastName field is “Smith”

•

FirstName field is “John”

•

Title field is “Engineer”

This example uses the EmpID field as the table’s primary key field. The primary key contains a unique identifier to
maintain each record's unique identity. Primary keys field can include an employee ID, part number, or customer
number. Typically, you specify which column contains the primary key when you create a database table.
To access the table to read or modify table data, you use the SQL programming language. For example, the following
SQL statement returns all rows from the table where the department ID is 3:
SELECT * FROM employees WHERE DEPTID=3

Note: In this topic, SQL keywords and syntax are always represented by uppercase letters. Table and column names use
mixed uppercase and lowercase letters.

Using multiple database tables
In many database designs, information is distributed to multiple tables. The following image shows two tables, one
for employee information and one for employee addresses:

A. employees table B. addresses table

ADOBE COLDFUSION 8 380
ColdFusion Developer’s Guide

In this example, each table contains a column named EmpID. This column associates a row of the employees table
with a row in the addresses table.
For example, to obtain all information about an employee, you request a row from the employees table and the row
from the addresses table with the same value for EmpID.
One advantage of using multiple tables is that you can add tables containing new information without modifying the
structure of your existing tables. For example, to add payroll information, you add a new table to the database where
the first column contains the employee’s ID and the columns contain current salary, previous salary, bonus payment,
and 401(k) percent.
Also, an access to a small table is more efficient than an access to a large table. Therefore, if you update the street
address of an employee, you update only the addresses table, without having to access any other table in the database.

ADOBE COLDFUSION 8 381
ColdFusion Developer’s Guide

Database permissions
In many database environments, a database administrator defines the access privileges for users accessing the
database, usually through username and password. When a person attempts to connect to a database, the database
ensures that the username and password are valid and then imposes access requirements on the user.
Privileges can restrict user access so that a user can do the following:

•

Read data.

•

Read data and add rows.

•

Read data, add rows, modify existing tables.

In ColdFusion, you use the ColdFusion Administrator to define database connections, called data sources. As part
of defining these connections, you specify the username and password used by ColdFusion to connect to the
database. The database can then control access based on this username and password.
For more information on creating a data source, see Configuring and Administering ColdFusion.

Commits, rollbacks, and transactions
Before you access data stored in a database, it is important to understand several database concepts, including:

•

Commit

•

Rollback

•

Transactions

A database commit occurs when you make a permanent change to a database. For example, when you write a new
row to a database, the write does not occur until the database commits the change.
Rollback is the process of undoing a change to a database. For example, if you write a new row to a table, you can
rollback the write up to the point where you commit the write. After the commit, you can no longer rollback the
write.
Most databases support transactions where a transaction consists of one or more SQL statements. Within a transaction, your SQL statements can read, modify, and write a database. You end a transaction by either committing all
your changes within the transaction or rolling back all of them.
Transactions can be useful when you have multiple writes to a database and want to make sure all writes occurred
without error before committing them. In this case, you wrap all writes within a single transaction and check for
errors after each write. If any write causes an error, you rollback all of them. If all writes occur successfully, you
commit the transaction.
A bank might use a transaction to encapsulate a transfer from one account to another. For example, if you transfer
money from your savings account to your checking account, you do not want the bank to debit the balance of your
savings account unless it also credits your checking account. If the update to the checking account fails, the bank can
rollback the debit of the savings account as part of the transaction.
ColdFusion includes the cftransaction tag that lets you implement database transactions for controlling rollback
and commit. For more information, see the CFML Reference.

Database design guidelines
From this basic description, the following database design rules emerge:

ADOBE COLDFUSION 8 382
ColdFusion Developer’s Guide

• Each record should contain a unique identifier as the primary key such as an employee ID, a part number, or a
customer number. The primary key is typically the column used to maintain each record's unique identity among
the tables in a relational database. Databases allow you to use multiple columns for the primary key.
• When you define a column, you define a SQL data type for the column, such as allowing only numeric values to
be entered in the salary column.
• Assessing user needs and incorporating those needs in the database design is essential to a successful implementation. A well-designed database accommodates the changing data needs within an organization.
The best way to familiarize yourself with the capabilities of your database product or database management system
(DBMS) is to review the product documentation.

Using SQL
The following information introduces SQL, describes basic SQL syntax, and contains examples of SQL statements.
so that you can begin to use ColdFusion. For complete SQL information, see the SQL reference that ships with your
database.
A query is a request to a database. The query can ask for information from the database, write new data to the
database, update existing information in the database, or delete records from the database.
Structured Query Language (SQL) is an ANSI/ISO standard programming language for writing database queries.
All databases supported by ColdFusion support SQL, and all ColdFusion tags that access a database let you pass SQL
statements to the tag.

SQL example
The most commonly used SQL statement in ColdFusion is the SELECT statement. The SELECT statement reads
data from a database and returns it to ColdFusion. For example, the following SQL statement reads all the records
from the employees table:
SELECT * FROM employees

You interpret this statement as "Select all rows from the table employees" where the wildcard symbol (*) corresponds
to all columns.
If you are using Dreamweaver MX 2004, Adobe Dreamweaver CS3, or HomeSite+, you can use the built-in query
builder to build SQL statements graphically by selecting the tables and records to retrieve. For more information, see
“Writing queries by using an editor” on page 389.
In many cases, you do not want all rows from a table, but only a subset of rows. The next example returns all rows
from the employees table, where the value of the DeptID column for the row is 3:
SELECT * FROM employees WHERE DeptID=3

You interpret this statement as "Select all rows from the table employees where the DeptID is 3".
SQL also lets you specify the table columns to return. For example, instead of returning all columns in the table, you
can return a subset of columns:
SELECT LastName, FirstName FROM employees WHERE DeptID=3

You interpret this statement as "Select the columns FirstName and LastName from the table employees where the
DeptID is 3".

ADOBE COLDFUSION 8 383
ColdFusion Developer’s Guide

In addition to with reading data from a table, you can write data to a table using the SQL INSERT statement. The
following statement adds a new row to the employees table:
INSERT INTO employees(EmpID, LastName, Firstname) VALUES(51, 'Doe', 'John')

Basic SQL syntax elements
The following tables briefly describe the main SQL command elements.
Statements

A SQL statement always begins with a SQL verb. The following keywords identify commonly used SQL verbs:
Keyword

Description

SELECT

Retrieves the specified records.

INSERT

Adds a new row.

UPDATE

Changes values in the specified rows.

DELETE

Removes the specified rows.

Statement clauses

Use the following keywords to refine SQL statements:
Keyword

Description

FROM

Names the data tables for the operation.

WHERE

Sets one or more conditions for the operation.

ORDER BY

Sorts the result set in the specified order.

GROUP BY

Groups the result set by the specified select list items.

Operators

The following basic operators specify conditions and perform logical and numeric functions:
Operator

Description

AND

Both conditions must be met

OR

At least one condition must be met

NOT

Exclude the condition following

LIKE

Matches with a pattern

IN

Matches with a list of values

BETWEEN

Matches with a range of values

=

Equal to

<>

Not equal to

<

Less than

>

Greater than

<=

Less than or equal to

ADOBE COLDFUSION 8 384
ColdFusion Developer’s Guide

Operator

Description

>=

Greater than or equal to

+

Addition

-

Subtraction

/

Division

*

Multiplication

Case sensitivity with databases

ColdFusion is a case-insensitive programming environment. Case insensitivity means the following statements are
equivalent:




However, many databases, especially UNIX databases, are case-sensitive. Case sensitivity means that you must match
exactly the case of all column and table names in SQL queries.
For example, the following queries are not equivalent in a case-sensitive database:
SELECT LastName FROM EMPLOYEES
SELECT LASTNAME FROM employees

In a case-sensitive database, employees and EMPLOYEES are two different tables.
For information on how your database handles case, see the product documentation.
SQL notes and considerations

When writing SQL in ColdFusion, keep the following guidelines in mind:

• There is a lot more to SQL than what is covered here. It is a good idea to purchase one or several SQL guides for
reference.
•

The data source, columns, and tables that you reference must exist in order to perform a successful query.

• Some DBMS vendors use nonstandard SQL syntax (known as a dialect) in their products. ColdFusion does not
validate the SQL; it is passed on to the database for validation, so you are free to use any syntax that is supported by
your database. Check your DBMS documentation for nonstandard SQL usage.

Reading data from a database
You use the SQL SELECT statement to read data from a database. The SQL statement has the following general
syntax:
SELECT column_names
FROM table_names
[ WHERE search_condition ]
[ GROUP BY group_expression ] [HAVING condition]
[ ORDER BY order_condition [ ASC | DESC ] ]

The statements in square brackets are optional.
Note: There are additional options to SELECT depending on your database. For a complete syntax description for
SELECT, see the product documentation.

ADOBE COLDFUSION 8 385
ColdFusion Developer’s Guide

Results of a SELECT statement

When the database processes a SELECT statement, it returns a record set containing the requested data. The format
of a record set is a table with rows and columns. For example, if you write the following query:
SELECT * FROM employees WHERE DeptID=3

The query returns the following table:

Because the data returned to ColdFusion by a SELECT statement is in the form of a database table, ColdFusion lets
you write a SQL query on the returned results. This functionality is called query of queries. For more information on
query of queries, see “Accessing and Retrieving Data” on page 392.
The next example uses a SELECT statement to return only a specific set of columns from a table:
SELECT LastName, FirstName FROM employees WHERE DeptID=3

The query returns the following table:

Filtering results

The SELECT statement lets you filter the results of a query to return only those records that meet specific criteria.
For example, if you want to access all database records for employees in department 3, you use the following query:
SELECT * FROM employees WHERE DeptID=3

You can combine multiple conditions using the WHERE clause. For example, the following example uses two conditions:
SELECT * FROM employees WHERE DeptID=3 AND Title='Engineer'

Sorting results

By default, a database does not sort the records returned from a SQL query. In fact, you cannot guarantee that the
records returned from the same query are returned in the same order each time you run the query.
However, if you require records in a specific order, you can write your SQL statement to sort the records returned
from the database. To do so, you include an ORDER BY clause in the SQL statement.
For example, the following SQL statement returns the records of the table ordered by the LastName column:
SELECT * FROM employees ORDER BY LastName

You can combine multiple fields in the ORDER BY clause to perform additional sorting:

ADOBE COLDFUSION 8 386
ColdFusion Developer’s Guide

SELECT * FROM employees ORDER BY DepartmentID, LastName

This statement returns row ordered by department, then by last name within the department.
Returning a subset of columns

You might want only a subset of columns returned from a database table, as in the following example, which returns
only the FirstName, LastName, and Phone columns. This example is useful if you are building a web page that shows
the phone numbers for all employees.
SELECT FirstName, LastName, Phone FROM employees

However, this query does not to return the table rows in alphabetical order. You can include an ORDER clause in the
SQL, as follows:
SELECT the FirstName, LastName, Phone
FROM employees
ORDER BY LastName, FirstName

Using column aliases

You might have column names that you do not want to retain in the results of your SQL statement. For example, your
database is set up with a column that uses a reserved word in ColdFusion, such as EQ. In this case, you can rename
the column as part of the query, as follows:
SELECT EmpID, LastName, EQ as MyEQ FROM employees

The results returned by this query contains columns named EmpID, LastName, and MyEQ.
Accessing multiple tables

In a database, you can have multiple tables containing related information. You can extract information from
multiple tables as part of a query. In this case, you specify multiple table names in the SELECT statement, as follows:
SELECT LastName, FirstName, Street, City, State, Zip
FROM employees, addresses
WHERE employees.EmpID = addresses.EmpID
ORDER BY LastName, FirstName

This SELECT statement uses the EmpID field to connect the two tables. This query prefixes the EmpID column with
the table name. This is necessary because each table has a column named EmpID. You must prefix a column name
with its table name if the column name appears in multiple tables.
In this case, you extract LastName and FirstName information from the employees table and Street, City, State, and
Zip information from the addresses table. You can use output such as this is to generate mailing addresses for an
employee newsletter.
The results of a SELECT statement that references multiple tables is a single result table containing a join of the information from corresponding rows. A join means information from two or more rows is combined to form a single
row of the result. In this case, the resultant record set has the following structure:

ADOBE COLDFUSION 8 387
ColdFusion Developer’s Guide

What is interesting in this result is that even though you used the EmpID field to combine information from the two
tables, you did not include that field in the output.

Modifying a database
You can use SQL to modify a database in the following ways:

•

Inserting data into a database

•

Updating data in a database

•

Deleting data from a database

•

Updating multiple tables

Inserting data into a database

You use SQL INSERT statement to write information to a database. A write adds a new row to a database table. The
basic syntax of an INSERT statement is as follows:
INSERT INTO table_name(column_names) VALUES(value_list)

where:

•

column_names specifies a comma-separated list of columns.

• value_list specifies a comma-separated list of values. The order of values has to correspond to the order that you
specified column names.
Note: There are additional options to INSERT depending on your database. For a complete syntax description for
INSERT, see the product documentation.
For example, the following SQL statement adds a new row to the employees table:
INSERT INTO employees(EmpID, LastName, Firstname) VALUES(51, 'Smith', 'John')

This statement creates a new row in the employees table and sets the values of the EmpID, LastName, and FirstName
fields of the row. The remaining fields in the row are set to Null. Null means the field does not contain a value.
When you, or your database administrator, creates a table, you can set properties on the table and the columns of the
table. One of the properties you can set for a column is whether the field supports Null values. If a field supports
Nulls, you can omit the field from the INSERT statement. The database automatically sets the field to Null when you
insert a new row.
However, if the field does not support Nulls, you must specify a value for the field as part of the INSERT statement;
otherwise, the database issues an error.
The LastName and FirstName values in the query are contained within single-quotation marks. This is necessary
because the table columns are defined to contain character strings. Numeric data does not require the quotation
marks.
Updating data in a database

Use the UPDATE statement in SQL to update the values of a table row. Update lets you update the fields of a specific
row or all rows in the table. The UPDATE statement has the following syntax:
UPDATE table_name
SET column_name1=value1, ... , column_nameN=valueN
[ WHERE search_condition ]

ADOBE COLDFUSION 8 388
ColdFusion Developer’s Guide

Note: There are additional options to UPDATE depending on your database. For a complete syntax description for
UPDATE, see the product documentation.
You should not attempt to update a record’s primary key field. Your database typically enforces this restriction.
The UPDATE statement uses the optional WHERE clause, much like the SELECT statement, to determine which
table rows to modify. The following UPDATE statement updates the e-mail address of John Smith:
UPDATE employees SET Email='jsmith@mycompany.com' WHERE EmpID = 51

Be careful using UPDATE. If you omit the WHERE clause to execute the following statement:
UPDATE employees SET Email = 'jsmith@mycompany.com'

you update the Email field for all rows in the table.
Deleting data from a database

The DELETE statement removes rows from a table. The DELETE statement has the following syntax:
DELETE FROM table_name
[ WHERE search_condition ]

Note: There are additional options to DELETE depending on your database. For a complete syntax description for
DELETE, see the product documentation.
You can remove all rows from a table using a statement in the form:
DELETE FROM employees

Typically, you specify a WHERE clause to the DELETE statement to delete specific rows of the table. For example,
the following statement deletes John Smith from the table:
DELETE FROM employees WHERE EmpID=51

Updating multiple tables

The preceding examples describe how to modify a single database table. However, you might have a database that
uses multiple tables to represent information.
One way to update multiple tables is to use one INSERT statement per table and to wrap all INSERT statements
within a database transaction. A transaction contains one or more SQL statements that can be rolled back or
committed as a unit. If any single statement in the transaction fails, you can roll back the entire transaction,
cancelling any previous writes that occurred within the transaction. You can use the same technique for selects,
updates, and deletes. The following example uses the cftransaction tag to wrap multiple SQL statements:


INSERT INTO Employees (FirstName,LastName,EMail,Phone,Department)
VALUES ('Simon', 'Horwith', 'SHORWITH','(202)-797-6570','Research and Development')


SELECT MAX(Emp_ID) AS New_Employee
FROM Employees



ADOBE COLDFUSION 8 389
ColdFusion Developer’s Guide

Writing queries by using an editor
Dreamweaver and HomeSite+ provide a graphical user interface (GUI) for writing and executing queries. A GUI is
useful for developing and testing your queries before you insert them into a ColdFusion application. For more information about these GUIs, see the documentation in your specific tool.

Writing queries using Dreamweaver
You define a query by using the Dreamweaver Recordset dialog box, which lets you create a record set without
manually entering SQL statements. Defining a record set with this method can be as easy as selecting a database
connection and table from the pop-up menus.
Define a record set without writing SQL
1 In the Dreamweaver Document window, open the page that will use the record set.
2

To open the Data Bindings panel, select Window > Data Bindings.

3

In the Data Bindings panel, click the Plus (+) button and choose Recordset (Query) from the pop-up menu.
The Simple Recordset dialog box appears:

4

Complete the dialog box.

5

Click the Test button to execute the query and ensure that it retrieves the information you intended.
If you defined a filter that uses parameters input by users, the Test button displays the Test Value dialog box.
Enter a value in the Test Value text box and click OK. If an instance of the record set is successfully created, a
table displaying the data from your record set appears.

6

Click OK to add the record set to the list of available content sources in the Data bindings panel.

If you prefer to write your own SQL statements, or need to create more complex queries then the Simple Recordset
dialog box allows, you can define record sets using the Advanced Recordset dialog box
Creating an advanced record set by writing SQL:
1 In the Dreamweaver Document window, open the page that will use the record set.
2

Select Windows > Data Bindings to display the Data Bindings panel.

3

In the Data Bindings panel, click the Plus (+) button and select Recordset (Query) from the pop-up menu.
If the Simple Recordset dialog box appears, switch to the Advanced Recordset dialog box by clicking the
Advanced button.
The Advanced Recordset dialog box appears:

ADOBE COLDFUSION 8 390
ColdFusion Developer’s Guide

4

Complete the dialog box.

5

Click the Test button to execute the query and ensure that it retrieves the information you intended.
If you defined a filter that uses parameters input by users, the Test button displays the Test Value dialog box.
Enter a value in the Test Value text field and click OK. If an instance of the record set is successfully created, a
table displaying the data from your record set appears.

6

Click OK to add the record set to the list of available content sources in the Data Bindings panel.

Writing queries by using HomeSite+
HomeSite+ includes the combined features of HomeSite 5 and ColdFusion Studio 5, with additional support for new
ColdFusion tags. HomeSite+ supports SQL Builder for writing queries.
SQL Builder is a powerful visual tool for building, testing, and saving SQL statements for use in application data
queries. You can copy completed SQL code blocks directly into your ColdFusion applications.
Open SQL Builder
❖ Do one of the following:

• Select Tools > SQL Builder from the HomeSite+ menu, select an RDS server, select a database from the dropdown list, and click New Query.
•

In the Database tab, select an RDS server, right-click a database name or a table, and select New Query.

•

Open the cfquery tag editor, select an RDS server, and click New Query.

The SQL Builder interface

The following image shows the SQL Builder interface:

ADOBE COLDFUSION 8 391
ColdFusion Developer’s Guide

A. Toolbar B. Table Pane C. Properties Pane D. SQL Pane

The SQL Builder is divided into the following four sections:
Section

Use

Toolbar

Contains buttons for SQL keywords and commands.

Table pane

Provides a view of the tables in your query and allows you to create joins between tables.

Properties pane

Allows you to set the properties of the query, such as the columns that are being selected or the columns that are
being updated.

SQL pane

Shows you the SQL statement as it is built.
The SQL pane does not support reverse editing, so any changes you make in this pane will not be made to the query
in the Properties pane or the Table pane.

Writing SQL statements

SQL Builder opens a SELECT statement by default, because this is the most common type of query. SQL Builder
supports the following four types of SQL statements:

•

Select (default)

•

Insert

•

Update

•

Delete

392

Chapter 23: Accessing and Retrieving
Data
Several ColdFusion tags provide a way to retrieve data from a database and work with query data. Use the cfquery
tag to query a data source, the cfoutput tag to output the query results to a web page, and the cfqueryparam tag to
help reduce security risks in your applications.
Contents

Working with dynamic data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Retrieving data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Outputting query data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Getting information about query results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
Enhancing security with cfqueryparam. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398

Working with dynamic data
A web application page is different from a static web page because it can publish data dynamically. This can involve
querying databases, connecting to LDAP or mail servers, and leveraging COM, DCOM, CORBA, or Java objects to
retrieve, update, insert, and delete data at run time—as your users interact with pages in their browsers.
For ColdFusion developers, the term data source can refer to a number of different types of structured content accessible locally or across a network. You can query websites, LDAP servers, POP mail servers, and documents in a
variety of formats. Most commonly though, a database drives your applications, and for this discussion a data source
means the entry point from ColdFusion to a database.
In this topic, you build a query to retrieve data from the cfdocexamples data source.
To query a database, you must use:

•

ColdFusion data sources

•

The cfquery tag

•

SQL commands

Retrieving data
You can query databases to retrieve data at run time. The retrieved data, called the record set, is stored on that page
as a query object. A query object is a special entity that contains the record set values, plus RecordCount,
CurrentRow, ColumnList, SQL, Cached, and SQLParameter query variables. You specify the query object’s name in
the name attribute of the cfquery tag. The query object is often called simply the query.
The following is a simple cfquery tag:

SELECT * FROM Employee

ADOBE COLDFUSION 8 393
ColdFusion Developer’s Guide

ORDER BY LastName


Note: The terms “record set” and “query object” are often used synonymously when discussing record sets for queries.
For more information, see “Using Query of Queries” on page 413.
When retrieving data from a database, perform the following tasks:

•

To tell ColdFusion how to connect to a database, use the cfquery tag on a page.

•

To specify the data that you want to retrieve from the database, write SQL commands inside the cfquery block.

•

Reference the query object and use its data values in any tag that presents data, such as cfoutput, cfgrid,
cftable, cfgraph, or cftree.

The cfquery tag
The cfquery tag is one of the most frequently used CFML tags. You use it to retrieve and reference the data returned
from a query. When ColdFusion encounters a cfquery tag on a page, it does the following:

•

Connects to the specified data source.

•

Performs SQL commands that are enclosed within the block.

•

Returns result set values to the page in a query object.

The cfquery tag syntax
The following code shows the syntax for the cfquery tag:

SQL code...


In this example, the query code tells ColdFusion to do the following:

•

Connect to the cfdocexamples data source (the cfdocexamples.mdb database).

•

Execute SQL code that you specify.

•

Store the retrieved data in the query object EmpList.

When creating queries to retrieve data, keep the following guidelines in mind:

•

You must use opening  and ending  tags, because the cfquery tag is a block tag.

•

Enter the query name and datasource attributes within the opening cfquery tag.

•

To tell the database what to process during the query, place SQL statements inside the cfquery block.

•

When referencing text literals in SQL, use single-quotation marks ('). For example, SELECT * FROM mytable

WHERE FirstName='Jacob' selects every record from mytable in which the first name is Jacob.

•

Surround attribute values with double quotation marks (“attrib_value”).

•

Make sure that a data source exists in the ColdFusion Administrator before you reference it in a cfquery tag.

•

Columns and tables that you refer to in your SQL statement must exist, otherwise the query fails.

•

Reference the query data by naming the query in one of the presentation tags, such as cfoutput, cfgrid,

cftable, cfgraph, or cftree.

ADOBE COLDFUSION 8 394
ColdFusion Developer’s Guide

• When ColdFusion returns database columns, it removes table and owner prefixes. For example, if you query
Employee.Emp_ID in the query, the Employee, is removed and returns as Emp_ID. You can use an alias to handle
duplicate column names; for more information, see “Using Query of Queries” on page 413.
• You cannot use SQL reserved words, such as MIN, MAX, COUNT, in a SQL statement. Because reserved words
are database-dependent, see your database’s documentation for a list of reserved words.
• If you use COMPUTE AVG() in your SQL, ColdFusion 8 returns avg() as the column name. (Previous versions
(ColdFusion 5 and ColdFusion MX 7) returned ave() as the column name.)

Building queries
As discussed earlier, you build queries by using the cfquery tag and SQL.
Note: This and many subsequent procedures use the cfdocexamples data source that connects to the cfdocexamples.mdb
database. This data source is installed by default. For information on adding or configuring a data source, see Configuring and Administering ColdFusion.
Query the table
1 Create a ColdFusion page with the following content:





Employee List

SELECT FirstName, LastName, Salary, Contract
FROM Employee




Note: Adobe recommends that you create structured, reusable code by putting queries in ColdFusion components;
however, for simplicity, the examples in this topic include the query in the body of the ColdFusion page. For more
information about using ColdFusion components, see “Building and Using ColdFusion Components” on page 158.
2 Save the page as emplist.cfm in the myapps directory under your web_root directory. For example, the default
path on a Windows computer would be:

C:\CFusion\wwwroot\myapps\
3

Enter the following URL in your web browser:
http://localhost/myapps/emplist.cfm
Only the header appears.

4

View the source in the browser:

ADOBE COLDFUSION 8 395
ColdFusion Developer’s Guide

ColdFusion creates the EmpList data set, but only HTML and text return to the browser. When you view the
page’s source, you see only HTML tags and the heading “Employee List.” To display the data set on the page, you
must code tags and variables to output the data.
Reviewing the code

The query you just created retrieves data from the cfdocexamples database. The following table describes the
highlighted code and its function:
Code

Description

 Queries the database specified in the cfdocexamples data source.
SELECT FirstName, LastName, Salary, Contract
FROM Employee

Gets information from the FirstName, LastName, Salary, and
Contract fields in the Employee table.



Ends the cfquery block.

Outputting query data
After you define a query, you can use the cfoutput tag with the query attribute to output data from the record set.
When you use the query attribute, keep the following in mind:

• ColdFusion loops through all the code contained within the cfoutput block, once for each row in the record set
returned from the database.
•

You must reference specific column names within the cfoutput block to output the data to the page.

• You can place text, CFML tags, and HTML tags inside or surrounding the cfoutput block to format the data on
the page.
• Although you do not have to specify the query name when you refer to a query column, you should use the query
name as a prefix for best practices reasons. For example, if you specify the Emplist query in your cfoutput tag, you
can refer to the Firstname column in the Emplist query as Firstname. However, using the query name as a prefix—
Emplist.Firstname— is preferred, and is in the following procedure.
The cfoutput tag accepts a variety of optional attributes but, ordinarily, you use the query attribute to define the
name of an existing query.
1

Edit emplist.cfm so that it appears as follows:





ADOBE COLDFUSION 8 396
ColdFusion Developer’s Guide


Employee List

SELECT FirstName, LastName, Salary, Contract
FROM Employee


#EmpList.FirstName#, #EmpList.LastName#, #EmpList.Salary#, #EmpList.Contract#





2

Save the file and view it in your web browser:
A list of employees appears in the browser, with each line displaying one row of data.

Note: You might have to refresh your browser to see your changes.
You created a ColdFusion application page that retrieves and displays data from a database. At present, the output is
raw and needs formatting. For more information, see “Introduction to Retrieving and Formatting Data” on page 511.
Reviewing the code

The results of the query appear on the page. The following table describes the highlighted code and its function:
Code

Description



Displays information retrieved in the EmpList query.

#EmpList.FirstName#, #EmpList.LastName#,
#EmpList.Salary#, #EmpList.Contract#

Displays the value of the FirstName, LastName, Salary, and Contract
fields of each record, separated by commas and spaces.




Inserts a line break (go to the next line) after each record.



Ends the cfoutput block.

Query output notes and considerations
When outputting query results, keep the following guidelines in mind:

• A cfquery must retrieve data before the cfoutput tag can display its results. Although you can include both on
the same page, Adobe recommends that you put queries in ColdFusion components and output the results on a
separate page. For more information, see “Building and Using ColdFusion Components” on page 158.
•

To output data from all the records of a query, specify the query name by using the query attribute in the
cfoutput tag.

•

Columns must exist and be retrieved to the application to output their values.

• Inside a cfoutput block that uses a cfquery attribute, you can prefix the query variables with the name of the
query; for example, Emplist.FirstName.
•

As with other attributes, surround the query attribute value with double-quotation marks (").

• As with any variables that you reference for output, surround column names with number signs (#) to tell
ColdFusion to output the column’s current values.
• Add a 
 tag to the end of the variable references so that ColdFusion starts a new line for each row that the
query returns.

ADOBE COLDFUSION 8 397
ColdFusion Developer’s Guide

Getting information about query results
Each time you query a database with the cfquery tag, you get the data (the record set) and the query variables;
together these comprise the query object. The following table describes the query variables, which are sometimes
called query properties:
Variable

Description

RecordCount

The total number of records returned by the query.

ColumnList

A comma-delimited list of the query columns, in alphabetical order.

SQL

The SQL statement executed.

Cached

Whether the query was cached.

SQLParameters

Ordered array of cfqueryparam values.

ExecutionTime

Cumulative time required to process the query, in milliseconds.

In your CFML code, you use these variables as if they were columns in a database table. Use the result attribute to
specify the name of the structure that ColdFusion populates with these variables. You then use that structure name
to refer to the query variables as the following example shows:
Output information about the query on your page
1 Edit emplist.cfm so that it appears as follows:


SELECT FirstName, LastName, Salary, Contract
FROM Employee
WHERE Emp_ID = 


#EmpList.FirstName#, #EmpList.LastName#, #EmpList.Salary#, #EmpList.Contract#

 


The query returned #tmpResult.RecordCount# records.

The query columns are:#tmpResult.ColumnList#.

The SQL is #tmpResult.SQL#.

Whether the query was cached: #tmpResult.Cached#.

Query execution time: #tmpResult.ExecutionTime#.




2

Save the file and view it in your web browser:
The number of employees now appears below the list of employees. You might have to refresh your browser and
scroll to see the RecordCount output.

Reviewing the code

You now display the number of records retrieved in the query. The following table describes the code and its
function:

ADOBE COLDFUSION 8 398
ColdFusion Developer’s Guide

Code

Description



Displays what follows.

The query returned

Displays the text “The query returned”.

#EmpList.RecordCount#

Displays the number of records retrieved in the EmpList query.

records.

Displays the text “records.”



Ends the cfoutput block.

Query variable notes and considerations
When using query variables, keep the following guidelines in mind:

• Reference the query variable within a cfoutput block so that ColdFusion outputs the query variable value to the
page.
• Surround the query variable reference with number signs (#) so that ColdFusion knows to replace the variable
name with its current value.
• Do not use the cfoutput tag query attribute when you output the RecordCount or ColumnList property. If
you do, you get one copy of the output for each row. Instead, prefix the variable with the name of the query.

Enhancing security with cfqueryparam
Some DBMSs let you send multiple SQL statements in a single query. However, hackers might try to modify URL or
form variables in a dynamic query by appending malicious SQL statements to existing parameters. Be aware that
there are potential security risks when you pass parameters in a query string. This can happen in many development
environments, including ColdFusion, ASP, and CGI. Using the cfqueryparam tag can reduce this risk.

About query string parameters
When you let a query string pass a parameter, ensure that only the expected information is passed. The following
ColdFusion query contains a WHERE clause, which selects only database entries that match the last name specified
in the LastName field of a form:

SELECT FirstName, LastName, Salary
FROM Employee
WHERE LastName='#Form.LastName#'


Someone could call this page with the following malicious URL:
http://myserver/page.cfm?Emp_ID=7%20DELETE%20FROM%20Employee
The result is that ColdFusion tries to execute the following query:

SELECT * FROM Employee
WHERE Emp_ID = 7 DELETE FROM Employee


ADOBE COLDFUSION 8 399
ColdFusion Developer’s Guide

In addition to an expected integer for the Emp_ID column, this query also passes malicious string code in the form
of a SQL statement. If this query successfully executes, it deletes all rows from the Employee table—something you
definitely do not want to enable by this method. To prevent such actions, you must evaluate the contents of query
string parameters.

Using cfqueryparam
You can use the cfqueryparam tag to evaluate query string parameters and pass a ColdFusion variable within a SQL
statement. This tag evaluates variable values before they reach the database. You specify the data type of the corresponding database column in the cfsqltype attribute of the cfqueryparam tag. In the following example, because
the Emp_ID column in the cfdocexamples data source is an integer, you specify a cfsqltype of cf_sql_integer:

SELECT * FROM Employee
WHERE Emp_ID = 


The cfqueryparam tag checks that the value of Emp_ID is an integer data type. If anything else in the query string
is not an integer, such as a SQL statement to delete a table, the cfquery tag does not execute. Instead, the
cfqueryparam tag returns the following error message:
Invalid data '7 DELETE FROM Employee' for CFSQLTYPE 'CF_SQL_INTEGER'.
Using cfqueryparam with strings

When passing a variable that contains a string to a query, specify a cfsqltype value of cf_sql_char, and specify
the maxLength attribute, as in the following example:

SELECT * FROM employees
WHERE LastName = 


In this case, cfqueryparam performs the following checks:

•

It ensures that LastName contains a string.

•

It ensures that the string is 17 characters or less.

• It escapes the string with single-quotation marks so that it appears as a single value to the database. Even if a
hacker passes a bad URL, it appears as follows:
WHERE LastName = 'Smith DELETE FROM MyCustomerTable'.
Using cfSqlType

The following table lists the available SQL types against which you can evaluate the value attribute of the
cfqueryparam tag:
BIGINT

BIT

CHAR

DATE

DECIMAL

DOUBLE

FLOAT

IDSTAMP

INTEGER

LONGVARCHAR

MONEY

MONEY4

NUMERIC

REAL

REFCURSOR

SMALLINT

TIME

TIMESTAMP

TINYINT

VARCHAR

ADOBE COLDFUSION 8 400
ColdFusion Developer’s Guide

Note: Specifying the cfsqltype attribute causes the DBMS to use bind variables, which can greatly enhance performance.

401

Chapter 24: Updating Your Database
ColdFusion lets you insert, update, and delete information in a database.
Contents

About updating your database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Inserting data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Updating data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Deleting data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411

About updating your database
ColdFusion was originally developed as a way to readily interact with databases. You can quickly insert, update, and
delete the contents of your database by using ColdFusion forms, which are typically a pair of pages. One page
displays the form with which your end user will enter values; the other page performs the action (insert, update or
delete).
Depending on the extent and type of data manipulation, you can use CFML with or without SQL commands. If you
use SQL commands, ColdFusion requires a minimal amount of SQL knowledge.

Inserting data
You usually use two application pages to insert data into a database:

•

An insert form

•

An insert action page

You can create an insert form with standard HTML form tags or with cfform tags (see “Creating custom forms with
the cfform tag” on page 530). When the user submits the form, form variables are passed to a ColdFusion action page
that performs an insert operation (and whatever else is called for) on the specified data source. The insert action page
can contain either a cfinsert tag or a cfquery tag with a SQL INSERT statement. The insert action page should
also contain a confirmation message for the end user.

Creating an HTML insert form
The following procedure creates a form using standard HTML tags. The form looks like the following in your web
browser:

ADOBE COLDFUSION 8 402
ColdFusion Developer’s Guide

1

Create a ColdFusion page with the following content:





Insert Data Form


ADOBE COLDFUSION 8 403
ColdFusion Developer’s Guide





Employee ID:



First Name:



Last Name:



Department Number:



Start Date:



Salary:


Contractor:
Yes


 
 







2

Save the file as insert_form.cfm in the myapps directory under your web_root and view it in your web browser.

Note: The form will not work until you write an action page for it. For more information, see “Creating an action page
to insert data” on page 403.

Data entry form notes and considerations
If you use the cfinsert tag in the action page to insert the data into the database, you should follow these rules for
creating the form page:

•

You only need to create HTML form fields for the database columns into which you will insert data.

• By default, cfinsert inserts all of the form’s fields into the database columns with the same names. For example,
it puts the Form.Emp_ID value in the database Emp_ID column. The tag ignores form fields that lack corresponding
database column names.
Note: You can also use the formfields attribute of the cfinsert tag to specify which fields to insert; for example,
formfields="prod_ID,Emp_ID,status".

Creating an action page to insert data
You can use the cfinsert tag or the cfquery tag to create an action page that inserts data into a database.
Creating an insert action page with cfinsert

The cfinsert tag is the easiest way to handle simple inserts from either a cfform or an HTML form. This tag inserts
data from all the form fields with names that match database field names.
1

Create a ColdFusion page with the following content:

  







Employee Added
 You have added #Form.FirstName# #Form.Lastname# to the employee database.

ADOBE COLDFUSION 8 404
ColdFusion Developer’s Guide





2

Save the page as insert_action.cfm.

3

View insert_form.cfm in your web browser and enter values.

Note: You might want to compare views of the Employee table in the cfdocexamples data source before and after inserting
values in the form.
4

Click Submit.
ColdFusion inserts your values into the Employee table and displays a confirmation message.

Reviewing the code

The following table describes the code and its function:
Code

Description





Sets the value of Form.Contract to No if it is not defined. If the Contractor
check box is unchecked, no value is passed to the action page; however, the
database field must have some value.



Creates a row in the Employee table of the cfdocexamples database. Inserts data
from the form into the database fields with the same names as the form fields.

You have added
#Form.FirstName# #Form.Lastname#
to the employee database.


Informs the user that values were inserted into the database.

Note: If you use form variables in cfinsert or cfupdate tags, ColdFusion automatically validates any form data it
sends to numeric, date, or time database columns. You can use the hidden field validation functions for these fields to
display a custom error message. For more information, see “Introduction to Retrieving and Formatting Data” on
page 511.
Creating an insert action page with cfquery

For more complex inserts from a form submittal, you can use a SQL INSERT statement in a cfquery tag instead of
using a cfinsert tag. The SQL INSERT statement is more flexible because you can insert information selectively or
use functions within the statement.
The following procedure assumes that you have created the insert_action.cfm page, as described in “Creating an
insert action page with cfinsert” on page 403.
1

In insert_action.cfm, replace the cfinsert tag with the following highlighted cfquery code:










ADOBE COLDFUSION 8 405
ColdFusion Developer’s Guide



INSERT INTO Employee
VALUES (#Form.Emp_ID#, '#Form.FirstName#',
'#Form.LastName#', #Form.Dept_ID#,
'#Form.StartDate#', #Form.Salary#, '#Form.Contract#')

Employee Added
You have added #Form.FirstName# #Form.Lastname# to the employee database.




2

Save the page.

3

View insert_form.cfm in your web browser and enter values.

4

Click Submit.
ColdFusion inserts your values into the Employee table and displays a confirmation message.

Reviewing the code

The following table describes the highlighted code and its function:
Code

Description


INSERT INTO Employee
VALUES (#Form.Emp_ID#,
'#Form.FirstName#',
'#Form.LastName#',
#Form.Dept_ID#,
'#Form.StartDate#',
#Form.Salary#,
'#Form.Contract#')


Inserts a new row into the Employee table of the cfdocexamples database. Specifies each
form field to be added.
Because you are inserting data into all database fields in the same left-to-right order as in the
database, you do not have to specify the database field names in the query.
Because #From.Emp_ID#, #Form.Dept_ID#, and #Form.Salary# are numeric, they do
not need to be enclosed in quotation marks.

Inserting into specific fields

The preceding example inserts data into all the fields of a table (the Employee table has seven fields). There might be
times when you do not want users to add data into all fields. To insert data into specific fields, the SQL statement in
the cfquery must specify the field names following both INSERT INTO and VALUES. For example, the following
cfquery omits salary and start date information from the update. Database values for these fields are 0 and NULL,
respectively, according to the database’s design.

INSERT INTO Employee
(Emp_ID,FirstName,LastName,
Dept_ID,Contract)
VALUES
(#Form.Emp_ID#,'#Form.FirstName#','#Form.LastName#',
#Form.Dept_ID#,'#Form.Contract#')


Updating data
You usually use the following two application pages to update data in a database:

ADOBE COLDFUSION 8 406
ColdFusion Developer’s Guide

•

An update form

•

An update action page

You can create an update form with cfform tags or HTML form tags. The update form calls an update action page,
which can contain either a cfupdate tag or a cfquery tag with a SQL UPDATE statement. The update action page
should also contain a confirmation message for the end user.

Creating an update form
The following are the key differences between an update form and an insert form:

•

An update form contains a reference to the primary key of the record that is being updated.
A primary key is a fields in a database table that uniquely identifies each record. For example, in a table of
employee names and addresses, only the Emp_ID is unique to each record.

•

An update form is usually populated with existing record data.

The easiest way to designate the primary key in an update form is to include a hidden input field with the value of
the primary key for the record you want to update. The hidden field indicates to ColdFusion which record to update.
1

Create a ColdFusion page with the following content:






SELECT * FROM Employee
WHERE Emp_ID = #URL.Emp_ID#






ADOBE COLDFUSION 8 407
ColdFusion Developer’s Guide





First Name:



Last Name:



Department Number:



Start Date:



Salary:


Contractor:

Yes

Yes



 








2

Save the file as update_form.cfm.

3 View update_form.cfm in your web browser by specifying the page URL and an Employee ID; for example, enter
the following: http://localhost/myapps/update_form.cfm?Emp_ID=3

Note: Although you can view an employee’s information, you must code an action page before you can update the
database. For more information, see “Creating an action page to update data” on page 408.
Reviewing the code

The following table describes the code and its function:
Code

Description


SELECT * FROM Employee
WHERE Emp_ID = #URL.Emp_ID#


Queries the cfdocexamples data source and returns records in which
the employee ID matches what was entered in the URL that called
this page.


...


Makes available as variables the results of the GetRecordtoUpdate
query in the form created in subsequent lines.


...


Creates a form whose variables are processed on the
update_action.cfm action page.

ADOBE COLDFUSION 8 408
ColdFusion Developer’s Guide

Code

Description




Uses a hidden input field to pass the Emp_ID (primary key) value to
the action page.

First Name:


Last Name:


Department Number:


Start Date:


Salary:



Populates the fields of the update form. This example does not use
ColdFusion formatting functions. As a result, start dates look like
1985-03-12 00:00:00 and salaries do not have dollar signs or
commas. The user can replace the information in any field using any
valid input format for the data.

Contractor:

Yes



Yes 








The Contract field requires special treatment because a check box
appears and sets its value. The cfif structure puts a check mark in
the check box if the Contract field value is Yes, and leaves the box
empty otherwise.

Creating an action page to update data
You can create an action page to update data with either the cfupdate tag or cfquery with the UPDATE statement.
Creating an update action page with cfupdate

The cfupdate tag is the easiest way to handle simple updates from a front-end form. The cfupdate tag has an
almost identical syntax to the cfinsert tag.
To use the cfupdate tag, you must include the primary key fields in your form submittal. The cfupdate tag
automatically detects the primary key fields in the table that you are updating and looks for them in the submitted
form fields. ColdFusion uses the primary key fields to select the record to update (therefore, you cannot update the
primary key value itself). It then uses the remaining form fields that you submit to update the corresponding fields
in the record. Your form only needs to have fields for the database fields that you want to change.
1

Create a ColdFusion page with the following content:











Employee Updated

ADOBE COLDFUSION 8 409
ColdFusion Developer’s Guide


You have updated the information for #Form.FirstName# #Form.LastName# in the employee
database.




2

Save the page as update_action.cfm.

3 View update_form.cfm in your web browser by specifying the page URL and an Employee ID; for example, enter
the following: http://localhost/myapps/update_form.cfm?Emp_ID=3

The current information for that record appears:

4

Enter new values in any of the fields, and click Update Information.
ColdFusion updates the record in the Employee table with your new values and displays a confirmation message.

Reviewing the code

The following table describes the code and its function:
Code

Description







Sets the value of Form.Contract to No if it is not defined, or to Yes if it is defined.
If the Contractor check box is unchecked, no value is passed to the action page;
however, the database field must have some value.



Updates the record in the database that matches the primary key on the form
(Emp_ID). Updates all fields in the record with names that match the names of form
controls.


You have updated the information for
#Form.FirstName# #Form.LastName#
in the employee database.


Informs the user that the change was made successfully.

ADOBE COLDFUSION 8 410
ColdFusion Developer’s Guide

Creating an update action page with cfquery

For more complicated updates, you can use a SQL UPDATE statement in a cfquery tag instead of a cfupdate tag.
The SQL UPDATE statement is more flexible for complicated updates.
The following procedure assumes that you have created the update_action.cfm page as described in “Creating an
update action page with cfupdate” on page 408.
1

In update_action.cfm, replace the cfupdate tag with the following highlighted cfquery code:












UPDATE Employee
SET FirstName = '#Form.Firstname#',
LastName = '#Form.LastName#',
Dept_ID = #Form.Dept_ID#,
StartDate = '#left(Form.StartDate,19)#',
Salary = #Form.Salary#
WHERE Emp_ID = #Form.Emp_ID#

Employee Updated

You have updated the information for
#Form.FirstName# #Form.LastName#
in the employee database.




2

Save the page.

3 View update_form.cfm in your web browser by specifying the page URL and an Employee ID; for example, enter
the following: http://localhost/myapps/update_form.cfm?Emp_ID=3
4

Enter new values in any of the fields, and click Update Information.
ColdFusion updates the record in the Employee table with your new values and displays a confirmation message.

When the cfquery tag retrieves date information from a Microsoft Access database, it displays the date and time
with tenths of seconds, as follows:

ADOBE COLDFUSION 8 411
ColdFusion Developer’s Guide

Deleting data
You use a cfquery tag with a SQL DELETE statement to delete data from a database. ColdFusion has no cfdelete
tag.

Deleting a single record
To delete a single record, use the table’s primary key in the WHERE condition of a SQL DELETE statement. In the
following procedure, Emp_ID is the primary key, so the SQL Delete statement is as follows:
DELETE FROM Employee WHERE Emp_ID = #Form.Emp_ID#

You often want to see the data before you delete it. The following procedure displays the data to be deleted by reusing
the form page used to insert and update data. Any data that you enter in the form before submitting it is not used,
so you can use a table to display the record to be deleted instead.
1

In update_form.cfm, change the title to “Delete Form” and the text on the submit button to “Delete Record”.

2

Change the form tag so that it appears as follows:


3

Save the modified file as delete_form.cfm.

4

Create a ColdFusion page with the following content:






DELETE FROM Employee
WHERE Emp_ID = #Form.Emp_ID#

The employee record has been deleted.

You have deleted #Form.FirstName# #Form.LastName# from the employee database.




5

Save the page as delete_action.cfm.

6 View delete_form.cfm in your web browser by specifying the page URL and an Employee ID; for example, enter
the following: http://localhost/myapps/delete_form.cfm?Emp_ID=3.Click Delete Record

ColdFusion deletes the record in the Employee table and displays a confirmation message.
Reviewing the code

The following table describes the code and its function:

ADOBE COLDFUSION 8 412
ColdFusion Developer’s Guide

Code

Description


DELETE FROM Employee
WHERE Emp_ID = #Form.Emp_ID#


Deletes the record in the database whose Emp_ID column matches the Emp_ID
(hidden) field on the form. Since the Emp_ID is the table’s primary key, only one
record is deleted.


You have deleted #Form.FirstName#
#Form.LastName# from the
employee database.


Informs the user that the record was deleted.

Deleting multiple records
You can use a SQL condition to delete several records. The following example deletes the records for everyone in the
Sales department (which has Dept_ID number 4) from the Employee table:
DELETE FROM Employee WHERE Dept_ID = 4

To delete all the records from the Employee table, use the following code:
DELETE FROM Employee

Important: Deleting records from a database is not reversible. Use DELETE statements carefully.

413

Chapter 25: Using Query of Queries
A query that retrieves data from a record set is called a Query of Queries. After you generate a record set, you can
interact with its results as if they were database tables by using Query of Queries.
Contents

About record sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
About Query of Queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
Query of Queries user guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420

About record sets
Query of Queries is based on manipulating the record set, which you can create using the cfquery tag and other
ways.
When you execute a database query, ColdFusion retrieves the data in a record set. In addition to presenting record
set data to the user, you can manipulate this record set to improve your application’s performance.
Because a record set contains rows (records) and columns (fields), you can think of it as a virtual database table, or
as a spreadsheet. For example, the cfpop tag retrieves a record set in which each row is a message and each column
is a message component, such as To, From, and Subject.

Creating a record set
You can perform a Query of Queries on any ColdFusion tag or function that generates a record set, including the
following:

•

cfcollection

•

cfdirectory

•

cfftp

•

cfhttp

•

cfindex

•

cfldap

•

cfmail

•

cfpop

•

cfprocresult

•

cfquery (against a database or against another Query of Queries)

•

cfsearch

•

cfstoredproc

•

cfwddx

•

The QueryNew function

ADOBE COLDFUSION 8 414
ColdFusion Developer’s Guide

Creating a record set with the QueryNew() function
In addition to creating a record set by using a cfquery or other CFML tags, you can create it with the QueryNew()
function.
1

Create a ColdFusion page with the following content:





QueryNew Example
















#name##instrument# #years_playing#

Individual record retrieval:

#qInstruments.name[2]# has played #qInstruments.instrument[2]# for
#qInstruments.years_playing[2]# years.




2

Save the page as queryNew.cfm in the myapps directory under the web_root directory.

3

Display queryNew.cfm in your browser

About Query of Queries
After you have created a record set with a tag or function, you can retrieve data from the record set in one or more
dependent queries. A query that retrieves data from a record set is called a Query of Queries. A typical use of a Query
of Queries is to retrieve an entire table into memory with one query, and then access the table data (the record set)
with subsequent sorting or filtering queries. In essence, you query the record set as if it were a database table.

ADOBE COLDFUSION 8 415
ColdFusion Developer’s Guide

Note: Because you can generate a record set in ways other than using the cfquery tag, the term In Memory Query is
sometimes used instead of Query of Queries.

Benefits of Query of Queries
Performing a Query of Queries has many benefits, including the following:
1 If you need to access the same tables multiple times, you greatly reduce access time, because the data is already
in memory (in the record set).

A Query of Queries is ideal for tables of 5,000 to 50,000 rows, and is limited only by the memory of the
ColdFusion host computer.
2

You can perform joins and union operations on results from different data sources.
For example, you can perform a union operation on queries from different databases to eliminate duplicates for
a mailing list.

You can efficiently manipulate cached query results in different ways. You can query a database once, and then
use the results to generate several different summary tables.
3

For example, if you need to summarize the total salary by department, by skill, and by job, you can make one
query to the database and use its results in three separate queries to generate the summaries.
4

You can obtain drill-down, master-detail information for which you do not access the database for the details.
For example, you can select information about departments and employees in a query, and cache the results. You
can then display the employees’ names. When users select an employee, the application displays the employee’s
details by selecting information from the cached query, without accessing the database.

5 You can use a Query of Queries in report definitions to generate subreport data. For more information, see
“Using subreports” on page 838.

Performing a Query of Queries
There are four steps to perform a Query of Queries.
1

Generate a record set through a master query.
You can write a master query using a tag or function that creates a record set. For more information, see
“Creating a record set” on page 413.

2

Write a detail query—a cfquery tag that specifies dbtype="query".

3 In the detail query, write a SQL statement that retrieves the relevant records. Specify the names of one or more
existing queries as the table names in your SQL code. Do not specify a datasource attribute.

If the database content does not change rapidly, use the cachedwithin attribute of the master query to cache the
query results between page requests. This way, ColdFusion accesses the database on the first page request, and does
not query the database again until the specified time expires. You must use the CreateTimeSpan function to specify
the cachedwithin attribute value (in days, hours, minutes, seconds format).
4

The detail query generates a new query result set, identified by the value of the name attribute of the detail query. The
following example illustrates the use of a master query and a single detail query that extracts information from the
master.
Use the results of a query in a query
1 Create a ColdFusion page with the following content:

ADOBE COLDFUSION 8 416
ColdFusion Developer’s Guide

Employee List




SELECT * from Employee



SELECT Emp_ID, FirstName, LastName
FROM master
WHERE LastName=

Output using a query of query:

#Emp_ID#: #FirstName# #LastName#


Columns in the master query:

#master.columnlist#


Columns in the detail query:

#detail.columnlist#



2

Save the page as query_of_query.cfm in the myapps directory under the web_root.

3

Display query_of_query.cfm in your browser

Reviewing the code

The master query retrieves the entire Employee table from the cfdocexamples data source. The detail query selects
only the three columns to display for employees with the specified last name. The following table describes the code
and its function:
Code

Description

cfset LastNameSearch="Doe"

Sets the last name to use in the detail query. In a complete application,
this information comes from user interaction.


SELECT * from Employee


Queries the cfdocexamples data source and selects all data in the
Employees table. Caches the query data between requests to this page,
and does not query the database if the cached data is less than an hour
old.


SELECT Emp_ID, FirstName, LastName
FROM master
WHERE LastName=

Uses the master query as the source of the data in a new query, named
detail. This new query selects only entries that match the last name
specified by the LastNameSearch variable. The query also selects only
three columns of data: employee ID, first name, and last name. The
query uses the cfqueryparam tag to prevent passing erroneous or
harmful code.

ADOBE COLDFUSION 8 417
ColdFusion Developer’s Guide

Code

Description


#Emp_ID#: #FirstName# #LastName# 



Uses the detail query to display the list of employee IDs, first names, and
last names.


#master.columnlist#



Lists all the columns returned by the master query.


#detail.columnlist#



Lists all the columns returned by the detail query.

Displaying record set data incrementally

If your database is large, you can limit the number of rows displayed at one time. The following example shows how
to use the currentRow query variable of a Query of Queries to do this. For more information on query variables, see
“Getting information about query results” on page 397.
1

Create a ColdFusion page with the following content:





QoQ with incremental row return





SELECT * FROM Employee
ORDER BY LastName



SELECT FirstName, LastName, Salary
FROM GetSals
ORDER BY LastName






 


FirstName


LastName


Salary

ADOBE COLDFUSION 8 418
ColdFusion Developer’s Guide






#GetSals2.currentRow#


#FirstName#


#LastName#


#LSCurrencyFormat(Salary)#







See next #MaxRows#
rows







2

Save the page as qoq_next_row.cfm in the myapps directory under the web_root.

3

Display qoq_next_row.cfm in your browser

Using the cfdump tag with query results

As you debug your CFML code, you can use the cfdump tag to quickly display the contents of your query. This tag
has the following format:


For more information on the cfdump tag, see the CFML Reference.
Using Query of Queries with non-SQL record sets

A Query of Queries can operate on any CFML tag or function that returns a record set; you are not limited to
operating on cfquery results. You can perform queries on non-SQL record sets, such as a cfdirectory tag, a
cfsearch tag, a cfldap tag, and so on.

ADOBE COLDFUSION 8 419
ColdFusion Developer’s Guide

The following example shows how a Query of Queries interacts with the record set of a Verity search. This example
assumes that you have a valid Verity collection, called bbb, which contains documents with a target word, film, or its
variants (films, filmed, filming). Change the name of the collection and the search criteria to as appropriate for your
Verity collection. For more information on Verity, see “Building a Search Interface” on page 459.
Use Query of Queries with a Verity record set
1 Create a ColdFusion page with the following content:







Master query dump:



SELECT * from quick
WHERE quick.score > 0.7743

Detail query dump:




2

Save the page as qoq_verity.cfm in the myapps directory under the web_root.

3

Display qoq_verity.cfm in your browser

The next example shows how a Query of Queries combines record sets from a cfdirectory tag, which is limited to
retrieval of one file type per use.
Use Query of Queries to combine record sets
1 Create a ColdFusion page with the following content:





Image Retrieval with QoQ




ADOBE COLDFUSION 8 420
ColdFusion Developer’s Guide






SELECT * FROM GetGIF
UNION
SELECT * FROM GetJPG
ORDER BY Name



The #dir# directory contains #GetBoth.RecordCount#
images:



#GetBoth.Name#







2

Save the page as qoq_cfdirectory.cfm in the myapps directory under the web_root.

3

Display qoq_cfdirectory.cfm in your browser

Query of Queries user guide
If you know SQL or have interacted with databases, you might be familiar with some of the Query of Queries
functionality.

Using dot notation
ColdFusion supports using dot notation in table names.
Example
If a structure named A contains a field named B, which contains a table named Products, you can refer to the table
with dot notation, as follows:
SELECT tape_ID, length
FROM A.B.Products;

ADOBE COLDFUSION 8 421
ColdFusion Developer’s Guide

Using joins
A join operation uses a single SELECT statement to return a result set from multiple, related tables, typically those
with a primary key - foreign key relationship. There are two SQL clauses that perform joins:

•

WHERE clause: ColdFusion supports joins through a WHERE clause.

• INNER JOIN and OUTER JOIN: ColdFusion does not support joins through INNER JOIN or OUTER JOIN
clauses.
Note: Query of Queries supports joins between two tables only.

Using unions
The UNION operator lets you combine the results of two or more SELECT expressions into a single record set. The
original tables must have the same number of columns, and corresponding columns must be UNION-compatible
data types. Columns are UNION-compatible data types if they meet one of the following conditions:

•

The same data type; for example, both Tinyint

•

Both Numeric; for example, Tinyint, Smallint, Integer, Bigint, Double, Float, Real, Decimal, or Numeric

•

Both Characters; for example, Char, Varchar, or LongVarchar

•

Both Dates; for example, Time, TimeStamp, or Date

Note: Query Of Queries does not support ODBC-formatted dates and times.
Syntax
select_expression = select_expression UNION [ALL] select_expression

Example
This example uses the following tables:
Table1
Type(int)

Name(varchar)

1

Tennis

2

Baseball

3

Football

Table2
ID(int)

Sport(varchar)

3

Football

4

Volleyball

5

PingPong

To combine Table1 and Table2, use a UNION statement, as follows:
SELECT * FROM Table1
UNION
SELECT * FROM Table2

The UNION statement produces the following result (UNION) table:

ADOBE COLDFUSION 8 422
ColdFusion Developer’s Guide

Result table
Type(int)

Name(varchar)

1

Tennis

2

Baseball

3

Football

4

Volleyball

5

PingPong

Using aliases for column names

The column names of a UNION table are the column names in the result set of the first SELECT statement in the
UNION operation; ColdFusion ignores the column names in the other SELECT statement. To change the column
names of the result table, you can use an alias, as follows:
Select Type as SportType, Name as SportName from Table1
UNION
Select * from Table2
Duplicate rows and multiple tables

By default, the UNION operator removes duplicate rows from the result table. If you use the keyword ALL, then
duplicates are included.
You can combine an unlimited number of tables using the UNION operator, for example:
Select * from Table1
UNION
Select * from Table2
UNION
Select * from Table3
...
Parentheses and evaluation order

By default, the Query of Queries SQL engine evaluates a statement containing UNION operators from left to right.
You can use parentheses to change the order of evaluation. For example, the following two statements are different:
/* First statement. */
SELECT * FROM TableA
UNION ALL
(SELECT * FROM TableB
UNION
SELECT * FROM TableC
)
/* Second statement. */
(SELECT * FROM TableA
UNION ALL
SELECT * FROM TableB
)
UNION
SELECT * FROM TableC

In the first statement, there are no duplicates in the union between TableB and TableC. Then, in the union between
that set and TableA, the ALL keyword includes the duplicates. In the second statement, duplicates are included in the
union between TableA and TableB but are eliminated in the subsequent union with TableC. The ALL keyword has
no effect on the final result of this expression.

ADOBE COLDFUSION 8 423
ColdFusion Developer’s Guide

Using other keywords with UNION

When you perform a UNION, the individual SELECT statements cannot have their own ORDER BY or COMPUTE
clauses. You can only have one ORDER BY or COMPUTE clause after the last SELECT statement; this clause is
applied to the final, combined result set. You can only specify GROUP BY and HAVING expressions in the
individual SELECT statements.

Using conditional operators
ColdFusion lets you use the following conditional operators in your SQL statements:

•

Test

•

Null

•

Comparison

•

Between

•

IN

•

LIKE

Test conditional

This conditional tests whether a Boolean expression is True, False, or Unknown.
Syntax
cond_test ::= expression [IS [NOT] {TRUE | FALSE | UNKNOWN} ]

Example
SELECT _isValid FROM Chemicals
WHERE _isValid IS true;
Null conditional

This conditional tests whether an expression is null.
Syntax
null_cond ::= expression IS [NOT] NULL

Example
SELECT bloodVal FROM Standards
WHERE bloodVal IS NOT null;
Comparison conditional

This conditional lets you compare an expression against another expression of the same data type (Numeric, String,
Date, or Boolean). You can use it to selectively retrieve only the relevant rows of a record set.
Syntax
comparison_cond ::= expression [> | >= | <> | != | < | <=] expression

Example
The following example uses a comparison conditional to retrieve only those dogs whose IQ is at least 150:
SELECT dog_name, dog_IQ
FROM Dogs
WHERE dog_IQ >= 150;

ADOBE COLDFUSION 8 424
ColdFusion Developer’s Guide

Between conditional

This conditional lets you compare an expression against another expression. You can use it to selectively retrieve only
the relevant rows of a record set. Like the comparison conditional, the BETWEEN conditional makes a comparison;
however, the between conditional makes a comparison against a range of values. Therefore, its syntax requires two
values, which are inclusive, a minimum and a maximum. You must separate these values with the AND keyword.
Syntax
between_cond ::= expression [NOT] BETWEEN expression AND expression

Example
The following example uses a BETWEEN conditional to retrieve only those dogs whose IQ is between 150 and 165,
inclusive:
SELECT dog_name, dog_IQ
FROM Dogs
WHERE dog_IQ BETWEEN 150 AND 165;
IN conditional

This conditional lets you specify a comma-delimited list of conditions to match. It is similar in function to the OR
conditional. In addition to being more legible when working with long lists, the IN conditional can contain another
SELECT statement.
Syntax
in_cond ::= expression [NOT] IN (expression_list)

Example
The following example uses the IN conditional to retrieve only those dogs who were born at either Ken’s Kennels or
Barb’s Breeders:
SELECT dog_name, dog_IQ, Kennel_ID
FROM Dogs
WHERE kennel_ID IN ('Kens','Barbs');
LIKE conditional

This conditional lets you perform wildcard searches, in which you compare your data to search patterns. This
strategy differs from other conditionals, such as BETWEEN or IN, because the LIKE conditional compares your data
to a value that is partially unknown.
Syntax
like_cond ::= left_string_exp [NOT] LIKE right_string_exp [ESCAPE escape_char]

The left_string_exp can be either a constant string, or a column reference to a string column. The right_string_exp
can be either a column reference to a string column, or a search pattern. A search pattern is a search condition that
consists of literal text and at least one wildcard character. A wildcard character is a special character that represents
an unknown part of a search pattern, and is interpreted as follows:

•

The underscore (_) represents any single character.

•

The percent sign (%) represents zero or more characters.

•

Square brackets ([ ]) represents any character in the range.

•

Square brackets with a caret [^] represent any character not in the range.

•

All other characters represent themselves.

Note: Earlier versions of ColdFusion do not support bracketed ranges.

ADOBE COLDFUSION 8 425
ColdFusion Developer’s Guide

Examples
The following example uses the LIKE conditional to retrieve only those dogs of the breed Terrier, whether the dog
is a Boston Terrier, Jack Russell Terrier, Scottish Terrier, and so on:
SELECT dog_name, dog_IQ, breed
FROM Dogs
WHERE breed LIKE '%Terrier';

The following examples are select statements that use bracketed ranges:
SELECT
SELECT
SELECT
SELECT
SELECT

lname
lname
lname
lname
lname

FROM
FROM
FROM
FROM
FROM

Suspects
Suspects
Suspects
Suspects
Suspects

WHERE
WHERE
WHERE
WHERE
WHERE

lname
lname
lname
lname
lname

LIKE
LIKE
LIKE
LIKE
LIKE

'A[^c]%';
'[a-m]%';
'%[]';
'A[%]%';
'A[^c-f]%';

Case sensitivity

Unlike the rest of ColdFusion, Query of Queries is case-sensitive. However, Query of Queries supports two string
functions, UPPER() and LOWER(), which you can use to achieve case-insensitive matching.
Examples
The following example matches only 'Sylvester':
SELECT dog_name
FROM Dogs
WHERE dog_name LIKE 'Sylvester';

The following example is not case-sensitive; it uses the LOWER() function to treat 'Sylvester', 'sylvester', 'SYLVESTER',
and so on as all lowercase, and matches them with the all lowercase string, ‘sylvester’:
SELECT dog_name
FROM Dogs
WHERE LOWER(dog_name) LIKE 'sylvester';

If you use a variable on the right side of the LIKE conditional and want to ensure that the comparison is not casesensitive, use the LCase or UCase function to force the variable text to be all of one case, as in the following example:
WHERE LOWER(dog_name) LIKE '#LCase(FORM.SearchString)#';
Escaping wildcards

You can specify your own escape character by using the conditional ESCAPE clause.
Example
The following example uses the ESCAPE clause to enable a search for a literal percent sign (%), which ColdFusion
normally interprets as a wildcard character:
SELECT emp_discount
FROM Benefits
WHERE emp_discount LIKE '10\%'
ESCAPE '\';

Managing data types for columns
A Query of Queries requires that every column have metadata that defines the column’s data type. All queries that
ColdFusion creates have metadata. However, a query created with QueryNew function that omits the second
parameter does not contain metadata. You use this optional second parameter to define the data type of each column
in the query.

ADOBE COLDFUSION 8 426
ColdFusion Developer’s Guide

Specify column data types in the QueryNew function

Type a QueryNew function, specifying the column names in the first parameter and the data types in the second
parameter, as the following example shows:


Note: To see the metadata for a Query of Queries, use the GetMetaData function.
Specify the column data types in the QueryAddColumn function
1 Create a query by specifying the QueryNew function with no parameters.



2

Add and populate a column with the QueryAddColumn function, specifying the data type in the third parameter:










If you do not specify the data type, ColdFusion examines the first fifty rows of each column to determine the data
type when performing conditional expressions.
In some cases, ColdFusion can guess a data type that is inappropriate for your application. In particular, if you use
columns in a WHERE clause or other conditional expression, the data types must be compatible. If they are not
compatible, you must use the CAST function to recast one of the columns to a compatible data type. For more information on casting, see “Using the CAST function” on page 426. For more information on data type compatibility, see
“Understanding Query of Queries processing” on page 433.
Note: Specifying the data type in the QueryNew function helps you avoid compatibility issues.

Using the CAST function
In some cases, a column’s data type may not be compatible with the processing you want to do. For example, query
columns returned by the cfhttp tag are all of type CF_SQL_VARCHAR, even though the contents may be numeric.
In this case, you can use the Query of Queries CAST function to convert a column value into an expression of the
correct data type.
The syntax for the CAST function is as follows:
CAST ( expression AS castType )

Where castType is one of the following:

•

BINARY

•

BIGINIT

•

BIT

•

DATE

•

DECIMAL

ADOBE COLDFUSION 8 427
ColdFusion Developer’s Guide

•

DOUBLE

•

INTEGER

•

TIME

•

TIMESTAMP

•

VARCHAR

For example:







#qStockItems.getMetaData().getColumnTypeName(javaCast("int",i))#





SELECT SUM(CAST(qStockItems.LastTradedPrice as INTEGER))
AS SUMNOW from qStockItems

Error in Query of Queries





Using aggregate functions
Aggregate functions operate on a set of data and return a single value. Use these functions for retrieving summary
information from a table, as opposed to retrieving an entire table and then operating on the record set of the entire
table.
Consider using aggregate functions to perform the following operations:

•

To display the average of a column

•

To count the number of rows for a column

•

To find the earliest date in a column

Since not every relational database management system (RDBMS) supports all aggregate functions, refer to your
database’s documentation. The following table lists the aggregate functions that ColdFusion supports:

ADOBE COLDFUSION 8 428
ColdFusion Developer’s Guide

Function

Description

AVG()

Returns the average (mean) for a column.

COUNT()

Returns the number of rows in a column.

MAX()

Returns the largest value of a column.

MIN()

Returns the lowest value of a column.

SUM()

Returns the sum of values of a column.

Syntax
aggregate_func ::= (* | column_name) | AVG | SUM | MIN | MAX)
([ALL | DISTINCT] numeric_exp)

Example
The following example uses the AVG() function to retrieve the average IQ of all terriers:
SELECT dog_name, AVG(dog_IQ) AS avg_IQ
FROM Dogs
WHERE breed LIKE '%Terrier';
Arbitrary expressions in aggregate functions

ColdFusion supports aggregate functions of any arbitrary expression, as follows:
SELECT lorange, count(lorange+hirange)
FROM roysched
GROUP BY lorange;
Aggregate functions in arbitrary expressions

ColdFusion supports mathematical expressions that include aggregate functions, as follows:
SELECT MIN(lorange) + MAX(hirange)
FROM roysched
GROUP BY lorange;

Using group by and having expressions
ColdFusion supports the use of any arbitrary arithmetic expression, as long as it is referenced by an alias.
Examples
The following code is correct:
SELECT (lorange + hirange)/2 AS midrange,
COUNT(*)
FROM roysched
GROUP BY midrange;

The following code is correct:
SELECT (lorange+hirange)/2 AS x,
COUNT(*)
FROM roysched GROUP BY x
HAVING x > 10000;

The following code is not supported in Query of Queries:
SELECT (lorange + hirange)/2 AS midrange,
COUNT(*)
FROM roysched

ADOBE COLDFUSION 8 429
ColdFusion Developer’s Guide

GROUP BY (lorange + hirange)/2;

Using ORDER BY clauses
ColdFusion supports the ORDER BY clause to sort. Make sure that it is the last clause in your SELECT statement.
You can sort by multiple columns, by relative column position, by nonselected columns. You can specify a
descending sort direction with the DESC keyword (by default, most RDBMS sorts are ascending, which makes the
ASC keyword unnecessary).
Syntax
order_by_column ::= (  |  ) [ | ]

Example
The following example shows a simple sort using an ORDER BY clause:
SELECT acetylcholine_levels, dopamine_levels
FROM results
ORDER BY dopamine_levels

The following example shows a more complex sort; results are first sorted by ascending levels of dopamine, then by
descending levels of acetylcholine. The ASC keyword is unnecessary, and is used only for legibility.
SELECT acetylcholine_levels, dopamine_levels
FROM results
ORDER BY 2 ASC, 1 DESC

Using aliases
ColdFusion supports the use of database column aliases. An alias is an alternate name for a database field or value.
ColdFusion lets you reuse an alias in the same SQL statement.
One way to create an alias is to concatenate (append) two or more columns to generate a value. For example, you can
concatenate a first name and a last name to create the value fullname. Because the new value does not exist in a
database, you refer to it by its alias. The AS keyword assigns the alias in the SELECT statement.
Examples
ColdFusion supports alias substitutions in the ORDER BY, GROUP BY, and HAVING clauses.
Note: ColdFusion does not support aliases for table names.
SELECT FirstName + ' ' + LastName AS fullname
from Employee;

The following examples rely on these two master queries:

SELECT * FROM employee


SELECT * FROM roysched

ORDER BY example

SELECT (job_id || job_lvl)/2 AS job_value
FROM employee
ORDER BY job_value

ADOBE COLDFUSION 8 430
ColdFusion Developer’s Guide


GROUP BY example

SELECT lorange || hirange AS x, count(hirange)
FROM roysched
GROUP BY x

HAVING example

SELECT (lorange || hirange)/2 AS x,
COUNT(*)
FROM roysched GROUP BY x
HAVING x > 10000


Handling null values
ColdFusion uses Boolean logic to handle conditional expressions. Proper handling of NULL values requires the use
of ternary logic. The IS [NOT] NULL clause works correctly in ColdFusion. However the following expressions do
not work properly when the column breed is NULL:
WHERE (breed > 'A')
WHERE NOT (breed > 'A')

The correct behavior should not include NULL breed columns in the result set of either expression. To avoid this
limitation, you can add an explicit rule to the conditionals and rewrite them in the following forms:
WHERE breed IS NOT NULL AND (breed > 'A')
WHERE breed IS NOT NULL AND not (breed > 'A')

Concatenating strings
Query of Queries support two string concatenation operators: + and ||, as the following examples show:
LASTNAME + ', ' + FIRSTNAME
LASTNAME || ', ' || FIRSTNAME

Escaping reserved keywords
ColdFusion has a list of reserved keywords, which are typically part of the SQL language and are not normally used
for names of columns or tables. To escape a reserved keyword for a column name or table name, enclose it in
brackets.
Important: Earlier versions of ColdFusion let you use some reserved keywords without escaping them.
Examples
ColdFusion supports the following SELECT statement examples:
SELECT [from] FROM parts;
SELECT [group].firstname FROM [group];
SELECT [group].[from] FROM [group];

ColdFusion does not support nested escapes, such as in the following example:
SELECT [[from]] FROM T;

The following table lists ColdFusion reserved keywords:

ADOBE COLDFUSION 8 431
ColdFusion Developer’s Guide

ABSOLUTE

ACTION

ADD

ALL

ALLOCATE

ALTER

AND

ANY

ARE

AS

ASC

ASSERTION

AT

AUTHORIZATION

AVG

BEGIN

BETWEEN

BIT

BIT_LENGTH

BOTH

BY

CASCADE

CASCADED

CASE

CAST

CATALOG

CHAR

CHARACTER

CHARACTER_LENGTH

CHAR_LENGTH

CHECK

CLOSE

COALESCE

COLLATE

COLLATION

COLUMN

COMMIT

CONNECT

CONNECTION

CONSTRAINT

CONSTRAINTS

CONTINUE

CONVERT

CORRESPONDING

COUNT

CREATE

CROSS

CURRENT

CURRENT_DATE

CURRENT_TIME

CURRENT_TIMESTAMP

CURRENT_USER

CURSOR

DATE

DAY

DEALLOCATE

DEC

DECIMAL

DECLARE

DEFAULT

DEFERRABLE

DEFERRED

DELETE

DESC

DESCRIBE

DESCRIPTOR

DIAGNOSTICS

DISCONNECT

DISTINCT

DOMAIN

DOUBLE

DROP

ELSE

END

END-EXEC

ESCAPE

EXCEPT

EXCEPTION

EXEC

EXECUTE

EXISTS

EXTERNAL

EXTRACT

FALSE

FETCH

FIRST

FLOAT

FOR

FOREIGN

FOUND

FROM

FULL

GET

GLOBAL

GO

GOTO

GRANT

GROUP

HAVING

HOUR

IDENTITY

IMMEDIATE

IN

INDICATOR

INITIALLY

INNER

INPUT

INSENSITIVE

INSERT

INT

INTEGER

INTERSECT

INTERVAL

INTO

IS

ISOLATION

JOIN

KEY

LANGUAGE

LAST

LEADING

LEFT

LEVEL

LIKE

LOCAL

LOWER

MATCH

MAX

MIN

MINUTE

MODULE

MONTH

NAMES

NATIONAL

NATURAL

NCHAR

NEXT

NO

NOT

NULL

NULLIF

NUMERIC

OCTET_LENGTH

OF

ON

ONLY

OPEN

OPTION

OR

ORDER

OUTER

OUTPUT

OVERLAPS

PAD

PARTIAL

POSITION

PRECISION

PREPARE

PRESERVE

PRIMARY

PRIOR

PRIVILEGES

PROCEDURE

PUBLIC

READ

REAL

REFERENCES

RELATIVE

RESTRICT

REVOKE

ADOBE COLDFUSION 8 432
ColdFusion Developer’s Guide

RIGHT

ROLLBACK

ROWS

SCHEMA

SCROLL

SECOND

SECTION

SELECT

SESSION

SESSION_USER

SET

SMALLINT

SOME

SPACE

SQL

SQLCODE

SQLERROR

SQLSTATE

SUBSTRING

SUM

SYSTEM_USER

TABLE

TEMPORARY

THEN

TIME

TIMESTAMP

TIMEZONE_HOUR

TIMEZONE_MINUTE

TO

TRAILING

TRANSACTION

TRANSLATE

TRANSLATION

TRIM

TRUE

UNION

UNIQUE

UNKNOWN

UPDATE

UPPER

USAGE

USER

USING

VALUE

VALUES

VARCHAR

VARYING

VIEW

WHEN

WHENEVER

WHERE

WITH

WORK

WRITE

YEAR

ZONE

Using Queries of Queries with dates
If you create a query object with the QueryNew function and populate a column with date constants, ColdFusion
stores the dates as a string inside the query object until a Query of Queries is applied to the query object. When
ColdFusion applies a Query of Queries to the query object, it converts the string representations into date objects.
Query of Queries supports date constants in SQL and ODBC format, as follows:

•

•

SQL format: Dates, times, or timestamps in one of the following format:

•

Date string: yyyy-mm-dd, for example, 1955-06-13.

•

Time string: hh:mm:ss[.[nnn]], for example, 14:34:30.75.

•

Timestamp string: yyyy-mm-dd hh:mm:ss[.[nnn]], for example, 1924-01-14 12:00:00.000.

ODBC format: Dates, times, or timestamps in one of the following format:

•

Date string: {d 'value'}, for example, {d '2004-07-06'}.

•

Time string: {t 'value'}, for example, {t '13:45:30'}.

•

Timestamp string: {ts 'value'}, for example, {ts '2004-07-06 13:45:30'}.

If you want to convert the date to its original format, use the DateFormat function and apply the "mm/dd/yy" mask.

Understanding Query of Queries performance
Query of Queries performs very well on single-table query objects that were accessed directly from a database. This
is because ColdFusion stores meta information for a query object accessed from a database.
When working with a query resulting in a SQL join, Query of Queries performs as follows:
1 Query of Queries is very efficient for simple joins in which there is only one equality between two column references or constants, for example:
SELECT T1.a, b, c, d FROM T1, T2 WHERE T1.a = T2.a

2

Query of Queries is less efficient for joins in which the predicate contains multiple expressions, for example:
SELECT T1.a, b, c, d FROM T1, T2

ADOBE COLDFUSION 8 433
ColdFusion Developer’s Guide

WHERE T1.a = T2.a AND T1.b + T1.c = T2.b + T2.c

Understanding Query of Queries processing
Query of Queries can process the following:

•

Column comparisons

•

Queries passed by reference

•

Complex objects

Comparing columns with different data types

Starting with ColdFusion MX 7, ColdFusion includes enhancements that allow you to compare columns with
different data types.
If one of the operands has a known column type (only constants have an unknown column type), Query of Queries
tries to coerce the constant with an unknown type to the type of the operand with metadata. The pairs of allowed
coercions are as follows:

•

Binary, string

•

Dates, string

•

Numeric, bigdecimal

•

Boolean, numeric

That is, ColdFusion can coerce between binary and string, but not between date and string.
If both operands have known data types, the types must be the same. The only exception is that ColdFusion can
coerce among integer, float, and double.
If both operands are constants, ColdFusion tries to coerce the values, first to the most restrictive type, then to the
least restrictive type.

•

First to binary then to string.

•

First to date then to string.

•

First to boolean then to numeric.

Passing queries by reference

A Query of Queries is copied by reference from its related query; this means that ColdFusion does not create a new
query when you create a Query of Queries. It also means that changes to a Query of Queries, such as ordering,
modifying, and deleting data, are also applied to the base query object.
If you do not want the original query to change, use the Duplicate function to create a copy and create the Query
of Queries using the copied query.
Managing complex objects

You cannot use Query Of Queries on a record set that contains complex objects, such as arrays and structures.
Note: You can store a record set in a complex objects.

434

Chapter 26: Managing LDAP Directories
CFML applications use the cfldap tag to access and manage LDAP (Lightweight Directory Access Protocol) directories. This chapter provides information on how to use this tag to view, query, and update LDAP directories.
This topic teaches you how to query and update an LDAP database. It does not assume that you are familiar with
LDAP, and provides an introduction to LDAP directories and the LDAP protocol. However, it does assume that you
have information on your LDAP database’s structure and attributes, and it does not explain how to create an LDAP
directory or manage a directory server. To learn more about LDAP and LDAP servers, see your LDAP server
documentation and published books on LDAP.
The examples in this topic use the Airius sample LDAP database that is supplied with the Netscape and iPlanet
Directory Servers.
Contents

About LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
The LDAP information structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
Using LDAP with ColdFusion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
Querying an LDAP directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
Updating an LDAP directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
Advanced topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452

About LDAP
The LDAP protocol enables organizations to arrange and access directory information in a hierarchy. In this context,
directory refers to a collection of information, such as a telephone directory, not a collection of files in a folder on a
disk drive.
LDAP originated in the mid-1990s as a response to the need to access ISO X.500 directories from personal
computers that had limited processing power. Since then, products such as iPlanet Server have been developed that
are native LDAP directory servers. Several companies now provide LDAP access to their directory servers, including
Novell NDS, Microsoft Active Directory Services (ADS), Lotus Domino, and Oracle.
An LDAP directory is typically a hierarchically structured database. Each layer in the hierarchy typically corresponds
to a level of organizational structure.
The following example shows a simple directory structure:

ADOBE COLDFUSION 8 435
ColdFusion Developer’s Guide

World

Italy

USA

Ferrari

Macromedia

Jack

R&D

Sales

R&D

Laura

Amy

Ben

Enzo

Sales

Gina

Marco

Sophia

This example is fully symmetrical: all the entries at each layer are of the same type.
You can also structure an LDAP directory so that the layers under one entry contain different information from the
layers under another entry.
The following image show such an asymmetric directory:

airius.com

groups

people

Bruce

Laura

Ben

Amy

HR Managers

Directory
Managers

QA Managers

Accounting
Managers

In this directory structure, the second level of the tree divides the directory into two organizational units: people and
groups. The third level contains entries with information that is specific to the organizational unit. Each person’s
entry includes a name, e-mail address, and telephone number. Each group’s entry includes the names of group
members.

ADOBE COLDFUSION 8 436
ColdFusion Developer’s Guide

This complexity and flexibility is a key to LDAP's usefulness. With it, you can represent any organizational structure.
LDAP offers performance advantages over conventional databases for accessing hierarchical, directory-like information that is read frequently and changed infrequently.
Although LDAP is often used for e-mail, address, telephone, or other organizational directories, it is not limited to
these types of applications. For example, you can store ColdFusion Advanced Security information in an LDAP
database.

The LDAP information structure
There are several LDAP concepts that are the basis of the LDAP information structure:

•

Entry

•

Attribute

•

Distinguished name (DN)

•

Schema, including the object class and attribute type

Entry
The basic information object of LDAP is the entry. An entry is composed of one or more attributes. Entries are
subject to content rules defined by the directory schema (see “Schema” on page 437).
Each node, not just the terminal nodes, of an LDAP directory is an entry. In the preceding images, each item is an
entry. For example, in the first diagram, both USA and Ferrari are entries. The USA entry’s attributes could include
a Language attribute, and the Ferrari entry could include an entry for the chief executive officer.

Attribute
An LDAP directory entry consists of one or more attributes. Attributes have types and values. The type determines
the information that the values can contain. The type also specifies how the value is processed. For example, the type
determines whether an attribute can have multiple values. The mail attribute type, which contains an e-mail address,
is multivalued so you can store multiple e-mail addresses for one person.
Some commonly used attribute types have short keyword type names. Often these correspond to longer type names,
and the two names can be used interchangeably. The following table lists common attribute type keywords used in
LDAP directories:
Keyword

Long name

c

CountryName

st

stateOrProvinceName

l

LocalityName

street

StreetAddress

o

OrganizationName

ou

OrganizationalUnitName

cn

CommonName

Comment

Typically, city, but can be any geographical unit

Typically, first and last name

ADOBE COLDFUSION 8 437
ColdFusion Developer’s Guide

Keyword

Long name

sn

SurName

dc

domaincomponent

mail

mail

Comment

E-mail address

For more information, see “Attribute type” on page 438.

Distinguished name (DN)
An entry’s distinguished name uniquely identifies it in the directory. A DN is made up of relative distinguished names
(RDNs). An RDN identifies the entry among the children of its parent entry. For example, in the first image in About
LDAP, the RDN for the Ferrari entry is “o=Ferrari”.
An entry’s DN consists of an entry’s RDN followed by the DN of its parent. In other words, it consists of the RDNs
for the entry and each of the entry’s parent entries, up to the root of the directory tree. The RDNs are separated by
commas and optional spaces. For example, in the first image, the DN for the Ferrari entry is “o=Ferrari, c=Italy”.
As with file system pathnames and URLs, entering the correct LDAP name format is essential to successful search
operations.
Note: The RDN is an attribute of a directory entry. The full DN is not. However, you can output the full DN by specifying
"dn" in a query’s attributes list. For more information, see cfldap in CFML Reference. ColdFusion always returns
DNs with spaces after the commas.
A multivalued RDN is made up of more than one attribute-value pair. In multivalued RDNs, the attribute-value pairs
are separated by plus signs (+). In the sample directories, individuals could have complex RDNs consisting of their
common name and their e-mail address, for example, “cn=Robert Boyd + mail=rjboyd@adobe.com”.

Schema
The concepts of schemas and object classes are central to a thorough understanding of LDAP. Although detailed
descriptions of them are beyond the scope of this topic, the following sections provide enough information to use
the cfldap tag effectively.
A directory schema is a set of rules that determines what can be stored in a directory. It defines, at a minimum, the
following two basic directory characteristics:

•

The object classes to which entries can belong

•

The directory attribute types

Object class

Object classes enable LDAP to group related information. Frequently, an object class corresponds to a real object or
concept, such as a country, person, room, or domain (in fact, these are all standard object type names). Each entry
in an LDAP directory must belong to one or more object classes.
The following characteristics define an object class:

•

The class name

•

A unique object ID that identifies the class

•

The attribute types that entries of the class must contain

•

The attribute types that entries of the class can optionally contain

ADOBE COLDFUSION 8 438
ColdFusion Developer’s Guide

•

(Optional) A superior class from which the class is derived

If an entry belongs to a class that derives from another class, the entry’s objectclass attribute lists the lowest-level class
and all the superior classes from which the lowest-level class derives.
When you add, modify, or delete a directory entry, you must treat the entry’s object class as a possibly multivalued
attribute. For example, when you add a new entry, you specify the object class in the cfldap tag attributes
attribute. To retrieve an entry’s object class names, specify “objectclass” in the list of query attributes. To retrieve
entries that provide a specific type of information, you can use the object class name in the cfldap tag filter
attribute.
Attribute type

A schema’s attribute type specification defines the following properties:

•

The attribute type name

•

A unique object ID that identifies the attribute type

•

(Optional) An indication of whether the type is single-valued or multivalued (the default is multivalued)

•

The attribute syntax and matching rules (such as case sensitivity)

The attribute type definition can also determine limits on the range or size of values that the type represents, or
provide an application-specific usage indicator. For standard attributes, a registered numeric ID specifies the syntax
and matching rule information. For more information on attribute syntaxes, see ETF RFC 2252 at
http://www.ietf.org/rfc/rfc2252.txt.
Operational attributes, such as creatorsName or modifyTimeStamp, are managed by the directory service and cannot
be changed by user applications.

Using LDAP with ColdFusion
The cfldap tag extends the ColdFusion query capabilities to LDAP network directory services. The cfldap tag lets
you use LDAP in many ways, such as the following:

•

Create Internet White Pages so users can locate people and resources and get information about them.

•

Provide a front end to manage and update directory entries.

•

Build applications that incorporate data from directory queries in their processes.

•

Integrate applications with existing organizational or corporate directory services.

The cfldap tag action attribute supports the following operations on LDAP directories:
Action

Description

query

Returns attribute values from a directory.

add

Adds an entry to a directory.

delete

Deletes an entry from a directory.

modify

Adds, deletes, or changes the value of an attribute in a directory entry.

modifyDN

Renames a directory entry (changes its distinguished name).

ADOBE COLDFUSION 8 439
ColdFusion Developer’s Guide

The following table lists the attributes that are required and optional for each action. For more information on each
attribute, see the cfldap tag in the CFML Reference.
Action

Required attributes

Optional attributes

query

server, name, start,
attributes

port, username, password, timeout, secure, rebind, referral, scope,
filter, sort, sortControl, startRow, maxRows, separator, delimiter

add

server, dn, attributes

port, username, password, timeout, secure, rebind, referral,
separator, delimiter

delete

server, dn

port, username, password, timeout, secure, rebind, referral

modify

server, dn, attributes

port, username, password, timeout, secure, rebind, referral,
modifyType, separator, delimiter

modifyDN

server, dn, attributes

port, username, password, timeout, secure, rebind, referral

Querying an LDAP directory
The cfldap tag lets you search an LDAP directory. The tag returns a ColdFusion query object with the results, which
you can use as you would any query result. When you query an LDAP directory, you specify the directory entry
where the search starts and the attributes whose values to return. You can specify the search scope and attribute
content filtering rules and use other attributes to further control the search.

Scope
The search scope sets the limits of a search. The default scope is the level below the distinguished name specified in
the start attribute. This scope does not include the entry identified by the start attribute. For example, if the
start attribute is “ou=support, o=adobe” the level below support is searched. You can restrict a query to the level of
the start entry, or extend it to the entire subtree below the start entry.

Search filter
The search filter syntax has the form attribute operator value. The default filter, objectclass=*, returns all entries in
the scope.
The following table lists the filter operators:
Operator

Example

Matches

=*

(mail=*)

All entries that contain a mail attribute.

=

(o=adobe)

Entries in which the organization name is adobe.

~=

(sn~=Hansen)

Entries with a surname that approximates Hansen. The matching rules for approximate matches
vary among directory vendors, but anything that “sounds like” the search string should be
matched. In this example, the directory server might return entries with the surnames Hansen and
Hanson.

>=

(st>=ma)

The name “ma” and names appearing after “ma” in an alphabetical state attribute list.

<=

(st<=ma)

The name “ma” and names appearing before “ma” in an alphabetical state attribute list.

*

(o=macro*)

Organization names that start with “macro”.

(o=*media)

Organization names that end with “media”.

ADOBE COLDFUSION 8 440
ColdFusion Developer’s Guide

Operator

&

Example

Matches

(o=mac*ia)

Organization names that start with “mac” and end with “ia”. You can use more than one * operator
in a string; for example, m*ro*dia.

(o=*med*)

Organization names that contain the string “med”, including the exact string match “med”.

(&(o=adobe)

Entries in which the organization name is “adobe” and the country is “usa”.

(co=usa))
|

(|(o=adobe)
(sn=adobe)

Entries in which the organization name is “adobe” or the surname is “adobe”, or the common name
is “adobe”.

(cn=adobe))
!

(!(STREET=*))

Entries that do not contain a StreetAddress attribute.

The Boolean operators & and | can operate on more than two attributes and precede all of the attributes on which
they operate. You surround a filter with parentheses and use parentheses to group conditions.
If the pattern that you are matching contains an asterisk, left parenthesis, right parenthesis, backslash, or NUL
character, you must use the following three-character escape sequence in place of the character:
Character

Escape sequence

*

\2A

(

\28

)

\29

\

\5C

NUL

\00

For example, to match the common name St*r Industries, use the filter:
(cn=St\2Ar Industries).
LDAP v3 supports an extensible match filter that permits server-specific matching rules. For more information on
using extensible match filters, see your LDAP server documentation.
Searching and sorting notes

• To search for multiple values of a multivalued attribute type, use the & operator to combine expressions for each
attribute value. For example, to search for an entry in which cn=Robert Jones and cn=Bobby Jones, specify the
following filter:
filter="(&(cn=Robert Jones)(cn=Bobby Jones))"

•

You can use object classes as search filter attributes; for example, you can use the following search filter:
filter="(objectclass=inetorgperson)"

• To specify how query results are sorted, use the sort field to identify the attribute(s) to sort. By default,
ColdFusion returns sorted results in case-sensitive ascending order. To specify descending order, case-insensitive
sorting, or both, use the sortControl attribute.
•

ColdFusion requests the LDAP server to do the sorting. This can have the following effects:

•

The sort order might differ between ColdFusion MX and previous versions.

ADOBE COLDFUSION 8 441
ColdFusion Developer’s Guide

• If you specify sorting and the LDAP server does not support sorting, ColdFusion generates an error. To sort
results from servers that do not support sorting, use a query of queries on the results.
• If you use filter operators to construct sophisticated search criteria, performance might degrade if the LDAP
server is slow to process the synchronous search routines that cfldap supports. You can use the cfldap tag timeout
and maxRows attributes to control the apparent performance of pages that perform queries, by limiting the number
of entries and by exiting the query if the server does not respond in a specified time.

Getting all the attributes of an entry
Typically, you do not use a query that gets all the attributes in an entry. Such a query would return attributes that are
used only by the directory server. However, you can get all the attributes by specifying attributes="*" in your query.
If you do this, ColdFusion returns the results in a structure in which each element contains a single attribute namevalue pair. The tag does not return a query object. ColdFusion does this because LDAP directory entries, unlike the
rows in a relational table, vary depending on their object class.
For example, the following code retrieves the contents of the Airius directory:


This tag returns entries for all the people in the organization and entries for all the groups. The group entries have a
different object class, and therefore different attributes from the person entries. If ColdFusion returned both types
of entries in one query object, some rows would have only the group-specific attribute values and the other rows
would have only person-specific attribute values. Instead, ColdFusion returns a structure in which each attribute is
an entry.

Example: querying an LDAP directory
The following example uses the cfldap tag to get information about the people in the Airius corporation’s Santa
Clara office. Users can enter all or part of a person’s name and get a list of matching names with their departments,
e-mail addresses, and telephone numbers.
This example uses the sample Airius corporate directory that is distributed with the Netscape Directory Server. If
you do not have access to this directory, modify the code to work with your LDAP directory.
1

Create a file that looks like the following:


  
cfldap Query Example

This tool queries the Airius.com database to locate all people in the company's
Santa Clara office whose common names contain the text entered in the form.
Enter a full name, first name, last name, or name fragment.





ADOBE COLDFUSION 8 442
ColdFusion Developer’s Guide











#results.RecordCount# matches found



Name
Department
E-Mail
Phone


#cn#
#listFirst(ou)#
#mail#
#telephonenumber#







2

Change the server attribute from ldap.airius.com to the name of your installation of the Airius database.

3

Save the page as cfldap.cfm and run it in your browser.

Reviewing the code

The following table describes the code:

ADOBE COLDFUSION 8 443
ColdFusion Developer’s Guide

Code

Description









Uses a form to get the name or name fragment to search for.



Ensures that the user has submitted the form. This is necessary because the
form page is also the action page. Ensures that the user entered search text.






#results.RecordCount#
matches found



Name
Department
E-Mail
Phone


#cn#
#ListFirst(ou)#
#mail#

#telephonenumber#





Limit the request to 100 entries. If the server does not return the data in 20
seconds, generates an error indicating that LDAP timed out.

Starts a table to display the output

Displays the number of records returned.

Displays the common name, department, e-mail address, and telephone
number of each entry.
Displays only the first entry in the list of organizational unit values. (For more
information, see the description that follows this table.)

This search shows the use of a logical AND statement in a filter. It returns one attribute, the surname, that is used
only for sorting the results.
In this query, the ou attribute value consists of two values in a comma-delimited list. One is the department name.
The other is People. This is because the Airius database uses the ou attribute type twice:

• In the distinguished names, at the second level of the directory tree, where it differentiates between organizational units such as people, groups, and directory servers

ADOBE COLDFUSION 8 444
ColdFusion Developer’s Guide

•

As the department identifier in each person’s entry

Because the attribute values are returned in order from the person entry to the directory tree root, the ListFirst
function extracts the person’s department name.

Updating an LDAP directory
The cfldap tag lets you perform the following actions on LDAP directory entries:

•

Add

•

Delete

•

Add attributes

•

Delete attributes

•

Replace attributes

•

Change the DN (rename the entry)

These actions let you manage LDAP directory contents remotely.
You build a ColdFusion page that lets you manage an LDAP directory. The form displays directory entries in a table
and includes a button that lets you populate the form fields based on the unique user ID.
The example ColdFusion page does not add or delete entry attributes or change the DN. For information on these
operations, see “Adding and deleting attributes of a directory entry” on page 451 and “Changing a directory entry’s
DN” on page 452.
To keep the code short, this example has limitations that are not appropriate in a production application. In
particular, it has the following limitations:

• If you enter an invalid user ID and click either the Update or the Delete button, ColdFusion generates a “No such
object” error, because there is no directory entry to update or delete. Your application should verify that the ID exists
in the directory before it tries to change or delete its entry.
• If you enter a valid user ID in an empty form and click Update, the application deletes all the attributes for the
User. The application should ensure that all required attribute fields contain valid entries before updating the
directory.

Adding a directory entry
When you add an entry to an LDAP directory, you specify the DN, all the required attributes, including the entry’s
object class, and any optional attributes. The following example builds a form that adds an entry to an LDAP
directory.
1

Create a file that looks like the following:








ADOBE COLDFUSION 8 445
ColdFusion Developer’s Guide








You must enter a value in every field.








Entry for User ID #Form.uid# has been added









Manage LDAP Entries



ADOBE COLDFUSION 8 446
ColdFusion Developer’s Guide


Full Name:


Surname:


E-mail Address:



Telephone Number:



User ID:









*All fields are required for Add



User List for the Human Resources Department




ADOBE COLDFUSION 8 447
ColdFusion Developer’s Guide



Full Name
Surname
Mail
Phone
UID


#GetList.cn#
#GetList.sn#
#GetList.mail#
#GetList.telephonenumber#
#GetList.uid#






At the top of the file, change the myServer, myUserName, and myPassword variable assignments to values that
are valid for your LDAP server.

2
3

Save the page as update_ldap.cfm and run it in your browser.

Reviewing the code

The following table describes the code:
Code

Description





Initializes the LDAP connection information variables. Uses variables for
all connection information so that any changes have to be made in only
one place.


name="surnameValue" default="">
name="emailValue" default="">
name="phoneValue" default="">
name="uidValue" default="">



Ensures that the user entered a User ID in the form.



If the user clicks Add, processes the code that follows.


You must enter a value in every
field.






If any field in the submitted form is blank, display a message and set the
other form fields to display data that the user submitted.




If the user entered data in all fields, sets the attributelist variable to specify
the entry’s attributes, including the object class and the organizational
unit (in this case, Human Resources).
The Trim function removes leading or trailing spaces from the user data.

ADOBE COLDFUSION 8 448
ColdFusion Developer’s Guide

Code

Description


Entry for User ID
#Form.uid# has been added





Adds the new entry to the directory.



.
.
.

Full Name:







*All fields are required for Add



Outputs the data entry form, formatted as a table. Each cfinput field
always has a value, set by the value attribute when the page is called. The
value attribute lets ColdFusion update the form contents when the form
is redisplayed after the user clicks Add. The code that handles cases in
which the user fails to enter all the required data uses this feature.



Queries the directory and gets the common name, surname, e-mail
address, telephone number, and user ID from the matching entries.




Full Name
Surname
Mail
Phone
UID


#GetList.cn#
#GetList.sn#
#GetList.mail#
#GetList.telephonenumber#
#GetList.uid#






Displays the query results in a table.

Searches the subtree from the entry with the DN of o=Airius.com, and
selects all entries in which the organizational unit is Human Resources.
Sorts the results by surname and then common name (to sort by last
name, then first). Sorts in default ascending order that is not case-sensitive.

ADOBE COLDFUSION 8 449
ColdFusion Developer’s Guide

Deleting a directory entry
To delete a directory entry, you must specify the entry DN.
The following example builds on the code that adds an entry. It adds Retrieve and Delete buttons. The Retrieve
button lets you view a user’s information in the form before you delete it.
1

Open update_ldap.cfm, which you created in “Adding a directory entry” on page 444.

2

Between the first and second  tags, add the following code:









Entry for User ID #Form.UID# has been deleted


3

At the end of the code for the Add button (the input tag with Value=Add at the bottom of the form), delete the

 end tag.

4

After the end of the Add button input tag, add the following code:
 

 


5

Save the file and run it in your browser.

Reviewing the code

The following table describes the code:

ADOBE COLDFUSION 8 450
ColdFusion Developer’s Guide

Code

Description









If the user clicks Retrieve, queries the directory and gets the information for
the specified User ID.
Sets the form field’s Value attribute to the corresponding query column.
This example uses the array index [1] to identify the first row of the GetEntry
query object. Because the query always returns only one row, the index can be
omitted.



Entry for User
ID #Form.UID# has been
deleted

The user clicks delete, deletes the entry with the specified User ID and informs
the user that the entry was deleted.

 

 


Displays submit buttons for the Retrieve and Delete actions.

Updating a directory entry
The cfldap tag lets you change the values of entry attributes. To do so, you specify the entry DN in the dn attribute,
and list the attributes to change and their new values in the attributes attribute.
The following example builds on the code that adds and deletes an entry. It can update one or more of an entry’s
attributes. Because the UID is part of the DN, you cannot change it.
1

Open update_ldap.cfm, which you created in “Adding a directory entry” on page 444.

2

Between the cfelseif Form.action is "Retrieve" block and the  tag, add the following code:



Entry for User ID #Form.UID# has been updated


ADOBE COLDFUSION 8 451
ColdFusion Developer’s Guide

At the end of the code for the Delete button (the input tag with Value=Delete at the bottom of the form), delete
the  mark.

3
4

After the end of the Delete button input tag, add the following code:
 


5

Save the file and run it in your browser.

Reviewing the code

The following table describes the code:
Code

Description




Entry for User ID
#Form.UID# has been updated


If the user clicks Update, sets the attribute list to the form field values
and replaces the attributes for the entry with the specified UID.

 


Defines the Submit button for the update action.

Displays a message to indicate that the entry was updated.
This code replaces all of the attributes in a form, without checking
whether they are blank. A more complete example would check for
blank fields and either require entered data or not include the corresponding attribute in the attributes string.

Adding and deleting attributes of a directory entry
The following table lists the cfldap tag attributes that you must specify to add and delete LDAP attributes in an
entry:
Action

cfldap syntax

Add attribute to entry

dn = "entry dn"
action = "modify"
modifyType = "add"
attributes = "attribname=attribValue[;...]"

Delete attribute from entry

dn = "entry dn"
action = "modify"
modifyType = "delete"
attributes = "attribName[;...]"

You can add or delete multiple attributes in one statement. To do this, use semicolons to separate the attributes in
the attribute string.
The following example specifies the description and seealso LDAP attributes:
attributes="description=Senior Technical Writer;seealso=writers"

ADOBE COLDFUSION 8 452
ColdFusion Developer’s Guide

You can change the character that you use to separate values of multivalued attributes in an attribute string. You can
also change the character that separates attributes when a string contains multiple attributes. For more information,
see “Specifying an attribute that includes a comma or semicolon” on page 452.
You can add or delete attributes only if the directory schema defines them as optional for the entry’s object class.

Changing a directory entry’s DN
To change the DN of an entry, you must provide the following information in the cfldap tag:
dn="original DN"
action="modifyDN"
attributes="dn=new DN"

For example:


The new DN and the entry attributes must conform to the directory schema; therefore, you cannot move entries
arbitrarily in a directory tree. You can only modify a leaf only. For example, you cannot modify the group name if
the group has children.
Note: LDAP v2 does not let you change entry DNs.

Advanced topics
Some more advanced techniques enable you to use LDAP directories more effectively.

Specifying an attribute that includes a comma or semicolon
LDAP attribute values can contain commas. The cfldap tag normally uses commas to separate attribute values in a
value list. Similarly, an attribute can contain a semicolon, which cfldap normally uses to delimit (separate)
attributes in an attribute list. To override the default separator and delimiter characters, you use the cfldap tag
separator and delimiter attributes.
For example, assume you want to add the following attributes to an LDAP entry:
cn=Proctor, Goodman, and Jones
description=Friends of the company; Rationalists

Use the cfldap tag in the following way:


ADOBE COLDFUSION 8 453
ColdFusion Developer’s Guide

Using cfldap output
You can create a searchable Verity collection from LDAP data. For an example of building a Verity collection using
an LDAP directory, see “Indexing query results obtained from an LDAP directory” on page 485.
The ability to generate queries from other queries is very useful when cfldap queries return complex data. For more
information on querying queries, see “Using Query of Queries” on page 413.

Viewing a directory schema
LDAP v3 exposes a directory's schema information in a special entry in the root DN. You use the directory root
subschemaSubentry attribute to access this information.
The following ColdFusion query shows how to get and display the directory schema. It displays information from
the schema’s object class and attribute type definitions. For object classes, it displays the class name, superior class,
required attribute types, and optional attribute types. For attribute types, it displays the type name, type description,
and whether the type is single- or multivalued.
The example does not display all the information in the schema. For example, it does not display the matching rules.
It also does not display the object class IDs, attribute type IDs, attribute type syntax IDs, or the object class descriptions. (The object class description values are all “Standard Object Class.”)
Note: To be able to view the schema for an LDAP server, the server must support LDAP v3
This example does not work on iPlanet Directory Server 5.0. It does work on a 4.x server.
View the schema for an LDAP directory
1 Create a file that looks like the following:










Object Classes


ADOBE COLDFUSION 8 454
ColdFusion Developer’s Guide



thiselement = Trim(thisElement);
nameloc = Find("NAME", thisElement);
descloc = Find("DESC", thisElement);
suploc = Find("SUP", thisElement);
mustloc = Find("MUST", thisElement);
mayloc = Find("MAY", thisElement);
endloc = Len(thisElement);







Name
Superior class
Must have
May have


#Mid(thisElement, nameloc+6, descloc-nameloc-8)#

#Mid(thisElement, suploc+5, mustloc-suploc-7)#

NONE

#Replace(Mid(thisElement, mustloc+6,
mayloc-mustloc-9), " $ ", ", ", "all")#
#Replace(Mid(thisElement, mayloc+5, endloc-mayloc-8),
" $ ", ", ", "all")#
#Replace(Mid(thisElement, mustloc+6,
endloc-mustloc-9), " $ ", ", ", "all")#
NONE







Attribute Types
 Alias",
"all")# delimiters = ",">

thiselement = Trim(thisElement);
nameloc = Find("NAME", thisElement);
descloc = Find("DESC", thisElement);
syntaxloc = Find("SYNTAX", thisElement);
singleloc = Find("SINGLE", thisElement);
endloc = Len(thisElement);



ADOBE COLDFUSION 8 455
ColdFusion Developer’s Guide





Name
Description
multivalued?


#Mid(thisElement, nameloc+6, descloc-nameloc-8)#

#Mid(thisElement, descloc+6, syntaxloc-descloc-8)#
Yes
No







Change the server from ldap.mycorp.com to your LDAP server. You might also need to specify a user ID and
password in the cfldap tag.

2
3

Save the template as ldapschema.cfm in myapps under your web root directory and view it in your browser.

Reviewing the code

The following table describes the code and its function:
Code

Description



Gets the value of the subschemaSubentry attribute from the root of
the directory server. The value is the DN of the schema.



Uses the schema DN to get the objectclasses and attributetypes
attributes from the schema.

ADOBE COLDFUSION 8 456
ColdFusion Developer’s Guide

Code

Description

Object Classes


thisElement = Trim(thisElement);
nameloc = Find("NAME",
thisElement);
descloc = Find("DESC",
thisElement);
suploc = Find("SUP", thisElement);
mustloc = Find("MUST",
thisElement);
mayloc = Find("MAY", thisElement);
endloc = Len(thisElement);


Displays the object class name, superior class, required attributes,
and optional attributes for each object class in a table.







Name
Superior class
Must have
May have


#Mid(thisElement,
nameloc+6, descloc-nameloc-8)
#
#Mid(thisElement,
suploc+5, mustloc-suploc-7)#

NONE

#Replace
(Mid(thisElement, mustloc+6,
mayloc-mustloc-9), " $ ", ", ",
"all")#
#Replace
(Mid(thisElement, mayloc+5,
endloc-mayloc-8), " $ ", ", ",
"all")#
#Replace
(Mid(thisElement, mustloc+6,
endloc-mustloc-9), " $ ", ", ",
"all")#
NONE





The schema contains the definitions of all object classes in a comma
delimited list, so the code uses a list type cfloop tag.
The thisElement variable contains the object class definition. Trim
off any leading or trailing spaces, then use the class definition field
keywords in Find functions to get the starting locations of the
required fields, including the Object class ID. (The ID is not
displayed.)
Gets the length of the thisElement string for use in later calculations.

Displays the field values. Uses the Mid function to extract individual
field values from the thisElement string.
The top object class does not have a superior class entry. Handles
this special case by testing the suploc location variable. If the value
is not 0, handles normally, otherwise, output "NONE".
There might not be any optional attributes. Handles this case similarly to the superior class. The calculation of the location of required
attributes uses the location of the optional attributes if the field
exists; otherwise, uses the end of the object class definition string.

ADOBE COLDFUSION 8 457
ColdFusion Developer’s Guide

Code

Description

Attribute Types
 Alias", "all")#
delimiters = ",">

thiselement = Trim(thisElement);
nameloc = Find("NAME",
thisElement);
descloc = Find("DESC",
thisElement);
syntaxloc = Find("SYNTAX",
thisElement);
singleloc = Find("SINGLE",
thisElement);
endloc = Len(thisElement);





Name
Description
Multivalued?


#Mid(thisElement,
nameloc+6, descloc-nameloc-8)#

#Mid(thisElement,
descloc+6, syntaxloc-descloc-8)
#
Yes

No







Does the same types of calculations for the attribute types as for the
object classes.

The attribute type field can contain the text ", alias for....". This text
includes a comma, which also delimits attribute entries. Use the
REReplaceNoCase function to replace any comma that precedes
the word "alias" with an HTML 
 tag.

The attribute definition includes a numeric syntax identifier, which
the code does not display, but uses its location in calculating the
locations of the other fields.

Referrals
An LDAP database can be distributed over multiple servers. If the requested information is not on the current server,
the LDAP v3 standard provides a mechanism for the server to return a referral to the client that informs the client
of an alternate server. (This feature is also included in some LDAP v2-compliant servers.)
ColdFusion can handle referrals automatically. If you specify a nonzero referral attribute in the cfldap tag,
ColdFusion sends the request to the server specified in the referral.
The referral attribute value specifies the number of referrals allowed for the request. For example, if the referral
attribute is 1, and server A sends a referral to server B, which then sends a referral to server C, ColdFusion returns
an error. If the referral attribute is 2, and server C has the information, the LDAP request succeeds. The value to
use depends on the topology of the distributed LDAP directory, the importance of response speed, and the value of
response completeness.
When ColdFusion follows a referral, the rebind attribute specifies whether ColdFusion uses the cfldap tag login
information in the request to the new server. The default, No, sends an anonymous login to the server.

Managing LDAP security
When you consider how to implement LDAP security, you must consider server security and application security.

ADOBE COLDFUSION 8 458
ColdFusion Developer’s Guide

Server security

The cfldap tag supports secure socket layer (SSL) v2 security. This security provides certificate-based validation of
the LDAP server. It also encrypts data transferred between the ColdFusion server and the LDAP server, including
the user password, and ensures the integrity of data passed between the servers. To specify SSL v2 security, set the
cfladap tag secure="cfssl_basic" attribute.
About LDAP Server Security

ColdFusion uses Java Native Directory Interface (JNDI), the LDAP provider, and an SSL package to create the client
side of an SSL communication. The LDAP server provides the server side. The LDAP server that the cfldap tag
connects to using SSL holds an SSL server certificate, a certificate that is securely “signed” by a trusted authority and
identifies (authenticates) the sender. During the initial SSL connection, the LDAP server presents its server certificate to the client. If the client trusts this certificate, the SSL connection is established and secure LDAP communication can begin.
ColdFusion determines whether to trust the server by comparing the server’s certificate with the information in the
jre/lib/security/cacerts keystore of the JRE used by ColdFusion. The ColdFusion default cacerts file contains information about many certificate granting authorities. If you must update the file with additional information, you can
use the keytool utility in the ColdFusion jre/bin directory to import certificates that are in X.509 format. For
example, enter the following:
keytool -import -keystore cacerts -alias ldap -file ldap.crt -keypass bl19mq

The keytool utility initial keypass password is “change it”. For more information on using the keytool utility, see the
Sun JDK documentation.
Once ColdFusion establishes secure communication with the server, it must provide the server with login credentials. You specify the login credentials in the cfldap tag username and password attributes. When the server determines that the login credentials are valid, ColdFusion can access the directory.
Using LDAP security

To use security, first ensure that the LDAP server supports SSL v2 security.
Specify the cfldap tag secure attribute as follows:
secure = "cfssl_basic"

For example:


The port attribute specifies the server port used for secure LDAP communications, which is 636 by default. If you
do not specify a port, ColdFusion attempts to connect to the default, nonsecure, LDAP port 389.
Application security

To ensure application security, you must prevent outsiders from gaining access to the passwords that you use in
cfldap tags. The best way to do this is to use variables for your username and password attributes. You can set these
variables on one encrypted application page. For more information on securing applications, see “Securing Applications” on page 311.

459

Chapter 27: Building a Search Interface
You can provide a full text search capability for documents and data sources on a ColdFusion site by enabling the
Verity search engine. Verity full text search lets people visiting your site use simple one- and two-word searches to
quickly find the information they need. You can use the more robust Verity Query Language and the Verity advanced
search operators to transparently implement business-specific meaning behind searches. This allows even one word
searches to return accurate results.
You can build a Verity search interface with which users can perform powerful searches on your site. You also can
index your documents and data sources so that users can search them.
Contents

About Verity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
Creating a search tool for ColdFusion applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
Creating a search page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
Enhancing search results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
Working with data returned from a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480

About Verity
To efficiently search through paragraphs of text or files of varying types, you need full-text search capabilities. Adobe
ColdFusion includes the Verity search engine, which provides full-text indexing and searching.
The Verity engine performs searches against collections, not against the actual documents. A collection is a special
database created by Verity that contains metadata that describes the documents that you have indexed. The indexing
process examines documents of various types in a collection and creates a metadata description—the index—which
is specialized for rapid search and retrieval operations.
The ColdFusion implementation of Verity supports collections of the following basic data types:

•

Text files such as HTML pages and CFML pages

•

Binary documents (see “Supported file types” on page 460)

•

Record sets returned from a query and CF query object, including: cfquery, cfldap, and cfpop queries

You can build collections from individual documents or from an entire directory tree. Collections can be stored
anywhere, so you have a great deal of flexibility in accessing indexed data.
In your ColdFusion application, you can search multiple collections, each of which can focus on a specific group of
documents or queries, according to subject, document type, location, or any other logical grouping. Because you can
perform searches against multiple collections, you have substantial flexibility in designing your search interface.

Using Verity with ColdFusion
Here are some ways to use Verity with ColdFusion:

•

Index your website and provide a generalized search mechanism, such as a form interface, for executing searches.

•

Index specific directories that contain documents for subject-based searching.

ADOBE COLDFUSION 8 460
ColdFusion Developer’s Guide

• Index specific categories of documents. By organizing your documents into categories, you can let users search
specific types of documents. For example, if your website contains FAQs, documentation, and tutorials, you can
create a search that lets users search within each of these categories.
• Index cfquery record sets, giving users the ability to search against the data. Because collections contain data
optimized for retrieval, this method is much faster than performing multiple database queries to return the same
data.
•

Index cfldap and cfpop query results.

• Manage and search collections generated outside of ColdFusion using native Verity tools. Collections must be
registered with the Verity K2 administration service. To do this you must either use the Verity tools, or map the
collection using the cfcollection tag.
• Index e-mail generated by ColdFusion application pages and create a searching mechanism for the indexed
messages.
• Build collections of inventory data and make those collections available for searching from your ColdFusion
application pages.
•

Support international users in a range of languages using the cfindex, cfcollection, and cfsearch tags.

Advantages of using Verity
Verity can index the output from queries so that you or a user can search against the record sets. Searching query
results has a clear advantage over using SQL to search a database directly in speed of execution because metadata
from the record sets are stored in a Verity index that is optimized for searching.
Performing a Verity search has the following advantages over other search methods:

• You can reduce the programming overhead of query constructs by allowing users to construct their own queries
and execute them directly. You need to be concerned only with presenting the output to the client web browser.
• Verity can index database text fields, such as notes and product descriptions, that cannot be effectively indexed
by native database tools.
• When indexing collections that contain documents in formats such as Adobe Acrobat (PDF) and Microsoft
Word, Verity scans for the document title (if one was entered), in addition to the document text, and displays the
title in the search results list.
• When Verity indexes web pages, it can return the URL for each document. This is a valuable document
management feature.
For more information, see “Indexing data returned by a query” on page 480.

Supported file types
The ColdFusion Verity implementation supports a wide array of file and document types. As a result, you can index
web pages, ColdFusion applications, and many binary document types and produce search results that include
summaries of these documents.
Verity supports the following formats:

ADOBE COLDFUSION 8 461
ColdFusion Developer’s Guide

Document format

Format

Version(s)

Text and markup

ANSI (TXT)

All versions

ASCII (TXT)

All versions

HTML (HTM)

3

IBM DCA/RFT (Revisable Form Text) (DC)

SC23-0758-1

Rich Text Format/WordPad (RTF)

1 through 1.6

Unicode Text (TXT)

3, 4

Adobe Maker Interchange Format (MIF)

5, 5.5, 6, 7

Applix Words (AW)

3.11, 4.2, 4.3, 4.4, 4, 41, 4.2

DisplayWrite (IP)

4

Folio Flat File (FFF)

3.1

Fujitsu Oasys (OA2)

7

JustSystems Ichitaro (JTD)

8, 9, 10, 12

Lotus AMI Pro (SAM)

2, 3

Lotus Word Pro (LWP) (Windows only)

96, 97, Millennium Edition R9

Microsoft Word for PC (DOC)

4, 5, 5.5, 6

Microsoft Word for Windows (DOC)

1 through 2002

Microsoft Word for Macintosh (DOC)

4, 5, 6, 98

Microsoft Works (WPS)

1 through 2000

Microsoft Windows Write (WRI)

1, 2, 3

WordPerfect for Windows V5 (WO)

5, 5.1

WordPerfect for Windows V6 and higher (WPD)

6, 7, 8, 10, 2000

WordPerfect for Macintosh

1.02, 2, 2.1, 2.2, 3, 3.1

WordPerfect for Linux

6

XyWrite (XY4)

4.12

Word processing

ADOBE COLDFUSION 8 462
ColdFusion Developer’s Guide

Document format

Format

Version(s)

Spreadsheet formats

Applix Spreadsheets (AS)

4.2, 4.3, 4.4

Comma Separated Values (CSV)

No specific version

Corel Quattro Pro (QPW, WB3)

5, 6, 7, 8

Lotus 1-2-3 for SmartSuite (123)

96, 97, Millennium Edition R9

Lotus 1-2-3 (WK4)

2, 3, 4, 5

Lotus 1-2-3 Charts (123)

2, 3, 4, 5

Microsoft Excel for Windows (XLS)

2.2, 3, 4, 5, 96, 97, 2000, 2002

Microsoft Excel for Macintosh (XLS)

98

Microsoft Excel Charts (XLS)

2, 3, 4, 5, 6, 7

Microsoft Works Spreadsheet (S30,S40)

1, 2, 3, 4

Applix Presents (AG)

4.0, 4.2, 4.3, 4.4

Corel Presentations (SHW)

7, 9, 10, 11, 2000

Lotus Freelance Graphics for Windows (PRE)

2, 96, 97, 98, Millennium Edition R9

Lotus Freelance Graphics 2 (PRE)

2

Microsoft PowerPoint for Windows (PPT)

95, 97, 2000, 2002

Microsoft PowerPoint for PC (PPT)

4

Microsoft PowerPoint for Macintosh (PPT)

98

Microsoft Project (MPP)

98, 2000, 2002

Display formats

Adobe Portable Document Format (PDF)

1.1 (Acrobat 2.0) to 1.4 (Acrobat 5.0)

Graphics formats
supported for indexing

AutoCAD Drawing format (DWG) (standalone) (does not extract R13, R14, and R2000
metadata)

Presentation formats

Multimedia formats

AutoCAD Drawing format (DXF) (standalone) (does not extract
metadata)

R13, R14, and R2000

Computer Graphics Metafile (CGM) (embedded)

No specific version

Enhanced Metafile (EMF) (embedded and standalone)

No specific version

Lotus Pic (PIC) (standalone)

No specific version

Microsoft Visio (standalone)

6

Tagged Image File (TIFF) (standalone)

5

Windows Metafile (WMF) (embedded and standalone)

3

MPEG-1 audio layer 3 (MP3)

ID3 versions 1 and 2

ADOBE COLDFUSION 8 463
ColdFusion Developer’s Guide

Document format

Format

Version(s)

Container formats

DynaZIP

No specific version

PKZIP (zip)

PKWARE versions through 2.04g

WinZIP

No specific version

Microsoft Outlook (msg)

97, 2000, 2002

Microsoft Outlook Express (eml)

No specific version

E-mail formats

Specifying a language
If you install the optional ColdFusion International Search pack, you can specify a language other than English when
creating a collection.
ColdFusion supports Verity Locales in European, Asian, and Middle Eastern languages. For more information about
installing Verity Locales, see Installing and Using ColdFusion.
For English language support, Verity provides two options: English (Basic) and English (Advanced). The default
language for Verity collections is English (Basic). Indexing a collection using English (Basic) is faster than using
English (Advanced), however, English (Advanced) provides better search results.
You must specify a language when you create the collection. The language you specify should match the language
the documents were authored in. By specifying the language your documents are written in, Verity is able to correctly
interpret accented characters, and, in many languages, use variations of word stems and roots. However, Verity does
not support the following in Eastern European and Middle Eastern languages, including these languages in the
Universal language pack:

•

Stemming

•

Normalization

•

Decomposition of compound words into subwords

•

Part of speech

•

Special number handling

If you have documents in several languages, create separate collections for each of them.
To specify a language when you are indexing data, select the language from the pop-up menu when you create a
collection with the ColdFusion Administrator. In CFML, the cfcollection, cfindex, and cfsearch tags have an
optional language attribute that you use to specify the language of the collection.
Use the following table to find the correct value for the language attribute for your collection; for example, the
following code creates a collection for simplified Chinese:


The following table lists the languages names and attributes that ColdFusion supports:

ADOBE COLDFUSION 8 464
ColdFusion Developer’s Guide

Language

Language attribute

Arabic

arabic

Chinese (simplified)

simplified_chinese

Chinese (traditional)

traditional_chinese

Czech

czech

Danish

danish

Dutch

dutch

English (Basic)

english

English (Advanced)

englishx

Finnish

finnish

French

french

German

german

Greek

greek

Hebrew

hebrew

Hungarian

hungarian

Italian

italian

Japanese

japanese

Korean

korean

Norwegian

norwegian

Norwegian (Bokmal)

bokmal

Norwegian (Nynorsk)

nynorsk

Polish

polish

Portuguese

portuguese

Russian

russian

Spanish

spanish

Swedish

swedish

Turkish

turkish

Multiple languages

uni

You can register collections in the ColdFusion Administrator or by creating a collection with the cfcollection tag.
If you register a given collection with ColdFusion and you specify a language attribute, you do not have to specify
the language attribute when using cfindex and cfsearch tags for that collection. If you do not register a given
collection with ColdFusion, ColdFusion uses English (Basic), the default language, unless you specify the language
in the language attribute for the cfindex and cfsearch tags for that collection.
Note: When you search a collection in a language other than English, you must translate operators such as AND and
OR into the language of the collection.

ADOBE COLDFUSION 8 465
ColdFusion Developer’s Guide

Creating a search tool for ColdFusion applications
There are three main tasks in creating a search tool for your ColdFusion application:
1

Create a collection.

2

Index the collection.

3

Design a search interface.

You can perform each task programmatically—that is, by writing CFML code. Alternatively, you can use the
ColdFusion Administrator to create and index a collection.

Creating a collection with the ColdFusion Administrator
Use the following procedure to quickly create a collection with the ColdFusion Administrator:
1

In the ColdFusion Administrator, select Data & Services > Verity Collections.

2

Enter a name for the collection; for example, DemoDocs.

3

Enter a path for the directory location of the new collection, for example, C:\CFusion\verity\collections\.
By default in the server configuration, ColdFusion stores collections in cf_root\verity\collections\ in Windows
and in cf_root/verity/collections on UNIX. In the multiserver configuration, the default location for collections
is cf_webapp_root/verity/collections. In the J2EE configuration, the default location for collections is
verity_root/verity/collections, where verity_root is the directory in which you installed Verity.
Note: This is the location for the collection, not for the files that you will search.

4

(Optional) Select a language other than English for the collection from the Language drop-down list.
For more information on selecting a language, see “Specifying a language” on page 463.

5

(Optional) Select Enable Category Support to create a Verity Parametric collection.
For more information on using categories, see “Narrowing searches by using categories” on page 476.

6

Click Create Collection.
The name and full path of the new collection appears in the list of Verity Collections.

You have successfully created an empty collection. A collection becomes populated with data when you index it.

About indexing a collection
In order for information to be searched, it must be indexed. Indexing extracts both meaning and structure from
unstructured information by indexing each document that you specify into a separate Verity collection that contains
a complete list of all the words used in a given document along with metadata about that document. Indexed collections include information such as word proximity, metadata about physical file system addresses, and URLs of
documents.
When you index databases and other record sets that you generated using a query, Verity creates a collection that
normalizes both the structured and unstructured data. Search requests then check these collections rather than
scanning the actual documents and database fields. This provides a faster search of information, regardless of the file
type and whether the source is structured or unstructured.
Just as with creating a collection, you can index a collection programmatically or by using the ColdFusion Administrator. Use the following guidelines to determine which method to use:

ADOBE COLDFUSION 8 466
ColdFusion Developer’s Guide

Use the Administrator

Use the cfindex tag

To index document files

To index ColdFusion query results

When the collection does not require frequent updates

When the collection requires frequent updates

To create the collection without writing any CFML code

To dynamically update a collection from a ColdFusion application page

To create a collection once

When the collection requires updating by others

You can use cfcollection action="optimize" if you notice that searches on a collection take longer than they
did previously.
Updating an index

Documents are modified frequently in many user environments. After you index your documents, any changes that
you make are not reflected in subsequent Verity searches until you re-index the collection. Depending on your
environment, you can create a scheduled task to automatically keep your indexes current. For more information on
scheduled tasks, see Configuring and Administering ColdFusion.

Creating a ColdFusion search tool programmatically
You can create a Verity search tool for your ColdFusion application in CFML. Although writing CFML code can take
more development time than using these tools, there are situations in which writing code is the preferred development method.
Creating a collection with the cfcollection tag

The following are cases in which you might prefer using the cfcollection tag rather than the ColdFusion Administrator to create a collection:

•

You want your ColdFusion application to be able to create, delete, and maintain a collection.

•

You do not want to expose the ColdFusion Administrator to users.

•

You want to create indexes on servers that you cannot access directly; for example, if you use a hosting company.

When using the cfcollection tag, you can specify the same attributes as in the ColdFusion Administrator:
Attribute

Description

action

(Optional) The action to perform on the collection (create, delete, or optimize). The default value for the action
attribute is list. For more information, see cfcollection in CFML Reference.

collection

The name of the new collection, or the name of a collection upon which you will perform an action.

path

The location for the Verity collection.

language

The language.

categories

(Optional) Specifies that cfcollection create a Verity Parametric Index (PI) for this collection. By default, the
categories attribute is set to False. To create a collection that uses categories, specify Yes.

You can create a collection by directly assigning a value to the collection attribute of the cfcollection tag, as
shown in the following code:


ADOBE COLDFUSION 8 467
ColdFusion Developer’s Guide

If you want your users to be able to dynamically supply the name and location for a new collection, use the following
procedures to create form and action pages.
Create a simple collection form page
1 Create a ColdFusion page with the following content:





Specify a collection

Collection name:

What do you want to do with the collection?
Create

Optimize






2

Save the file as collection_create_form.cfm in the myapps directory under the web root directory.

Note: The form will not work until you write an action page for it, which is the next procedure.
Create a collection action page
1 Create a ColdFusion page with the following content:





Collection creation




The collection #Form.CollectionName# is created.



The collection #Form.CollectionName# is optimized.



The collection is deleted.






2

Save the file as collection_create_action.cfm in the myapps directory under the web root directory.

3

In the web browser, enter the following URL to display the form page:
http://hostname:portnumber/myapps/collection_create_form.cfm

4

Enter a collection name; for example, CodeColl.

5

Verify that Create is selected and submit the form.

6

(Optional) In the ColdFusion Administrator, reload the Verity Collections page.

The name and full path of the new collection appear in the list of Verity Collections.
You successfully created a collection, named CodeColl, that currently has no data.
Indexing a collection by using the cfindex tag

You can index a collection in CFML by using the cfindex tag, which eliminates the need to use the ColdFusion
Administrator. The cfindex tag populates the collection with metadata that is then used to retrieve search results.
You can use the cfindex tag to index either physical files (documents stored within your website’s root folder), or
the results of a database query.
Note: Prior to indexing a collection, you must create a Verity collection by using the ColdFusion Administrator, or the
cfcollection tag. For more information, see “Creating a collection with the ColdFusion Administrator” on page 465,
or “Creating a collection with the cfcollection tag” on page 466.
When using the cfindex tag, the following attributes correspond to the values that you would enter by using the
ColdFusion Administrator to index a collection:
Attribute

Description

collection

The name of the collection.

action

Specifies what the cfindex tag should do to the collection. The default action is to update the collection, which
generates a new index. Other actions are to delete, purge, or refresh the collection.

type

Specifies the type of files or other data to which the cfindex tag applies the specified action. The value you assign
to the type attribute determines the value to use with the key attribute (see the following list). When you enter a
value for the type attribute, cfindex expects a corresponding value in the key attribute. For example, if you specify
type=file, cfindex expects a directory path and filename for the key attribute.
The type attribute has the following possible values:

•

file: Specifies a directory path and filename for the file that you are indexing.

•

path: Specifies a directory path that contains the files that you are indexing.

•

custom: Specifies custom data, such as a record set returned from a query.

ADOBE COLDFUSION 8 469
ColdFusion Developer’s Guide

Attribute

Description

extensions

(Optional) The delimited list of file extensions that ColdFusion uses to index files if
type="path".

The value that you specify for the key attribute depends on the value set for the type attribute:

key

•

If type="file", the key is the directory path and filename for the file you are indexing.

•

If type="path", the key is the directory path that contains the files you are indexing.

• If type="custom", the key is a unique identifier specifying the location of the documents you are indexing;
for example, the URL of a specific web page or website whose contents you want to index. If you are indexing
data returned by a query (from a database for example), the key is the name of the record set column that contains
the primary key.
(Optional) The URL path for files if type="file" and type="path". When the collection is searched with the
cfsearch tag, ColdFusion works as follows:

URLpath

•

type="file": The URLpath attribute contains the URL to the file.

•

type="path": The path name is automatically prefixed to filenames and returned as the URLpath attribute.

recurse

(Optional) Yes or No. If type = "path" , Yes specifies that directories below the path specified in the key attribute
are included in the indexing operation.

language

(Optional) The language of the collection. The default language is English Basic.
To learn more about support for languages, see “Specifying a language” on page 463.

You can use form and action pages similar to the following examples to select and index a collection.
Select which collection to index
1 Create a ColdFusion page with the following content:





Specify the index you want to build

Enter the collection you want to index:

Enter the location of the files in the collection:

Enter a Return URL to prepend to all indexed files:






2

Save the file as collection_index_form.cfm in the myapps directory under the web_root.

Note: The form does not work until you write an action page for it, which you do when you index a collection.

ADOBE COLDFUSION 8 470
ColdFusion Developer’s Guide

Use cfindex to index a collection
1 Create a ColdFusion page with the following content:





Indexing Complete


The collection #Form.IndexColl# has been indexed.




2

Save the file as collection_index_action.cfm.

3

In the web browser, enter the following URL to display the form page:
http://hostname:portnumber/myapps/collection_index_form.cfm

4

Enter a collection name; for example, CodeColl.

5

Enter a file location; for example, C:\CFusion\wwwroot\vw_files.

Enter a URL prefix; for example, http://localhost:8500/vw_files (assuming that you are using the built-in web
server).

6
7

Click Index.
A confirmation message appears on successful completion.

Note: For information about using the cfindex tag with a database to index a collection, see “Working with data
returned from a query” on page 480.
Indexing a collection with the ColdFusion Administrator

As an alternative to programmatically indexing a collection, use the following procedure to index a collection with
the ColdFusion Administrator.
1

In the list of Verity Collections, select a collection name; for example, CodeColl.

2

Click Index to open the index page.

3 For File Extensions, enter the types of files to index. Use a comma to separate multiple file types; for example,
.htm, .html, .xls, .txt, .mif, .doc.
4 Enter (or Browse to) the directory path that contains the files to be indexed; for example,
C:\Inetpub\wwwroot\vw_files.

(Optional) To extend the indexing operation to all directories below the selected path, select the Recursively
index subdirectories check box.
5
6

(Optional) Enter a Return URL to prepend to all indexed files.

ADOBE COLDFUSION 8 471
ColdFusion Developer’s Guide

This step lets you create a link to any of the files in the index; for example, http://127.0.0.1/vw_files/.
7

(Optional) Select a language other than English.
For more information, see “Specifying a language” on page 463.

8

Click Submit Changes.
On completion, the Verity Collections page appears.

Note: The time required to generate the index depends on the number and size of the selected files in the path.
This interface lets you easily build a very specific index based on the file extension and path information you enter.
In most cases, you do not need to change your server file structures to accommodate the generation of indices.

Creating a search page
You use the cfsearch tag to search an indexed collection. Searching a Verity collection is similar to a standard
ColdFusion query: both use a dedicated ColdFusion tag that requires a name attribute for their searches and both
return a query object that contains rows matching the search criteria. The following table compares the two tags:
cfquery

cfsearch

Searches a data source

Searches a collection

Requires a name attribute

Requires a name attribute

Uses SQL statements to specify search criteria

Uses a criteria attribute to specify search criteria

Returns variables keyed to database table field names

Returns a unique set of variables

Uses cfoutput to display query results

Uses cfoutput to display search results

Note: You receive an error if you attempt to search a collection that has not been indexed.
The following are important attributes for the cfsearch tag:
Attribute

Description

name

The name of the search query.

collection

The name of the collection(s) being searched. Separate multiple collections with a comma; for example,
collection = "sprocket_docs,CodeColl".

criteria

The search target (can be dynamic).

maxrows

The maximum number of records returned by the search. Always specify this attribute to ensure optimal performance (start with 300 or less, if possible).

Each cfsearch returns variables that provide the following information about the search:
Attribute

Description

RecordCount

The total number of records returned by the search.

CurrentRow

The current row of the record set.

RecordsSearched

The total number of records in the index that were searched. If no records were returned in the search, this property returns a null value.

ADOBE COLDFUSION 8 472
ColdFusion Developer’s Guide

Attribute

Description

Summary

Automatic summary saved by the cfindex tag.

Context

A context summary that contains the search terms, highlighted in bold (by default). This is enabled if you set the
contextpassages attribute to a number greater than zero.

Additionally, if you specify the status attribute, the cfsearch tag returns the status structure, which contains the
information in the following table:
Variable

Description

found

The number of documents that contain the search criteria.

searched

The number of documents searched. Corresponds to the recordsSearched column in the search results.

time

The number of milliseconds the search took, as reported by the Verity K2 search service.

suggestedQuery

An alternative query, as suggested by Verity, that may produce better results. This often contains corrected spellings of search terms. Present only when the suggestions tag attribute criteria is met.

Keywords

A structure that contains each search term as a key to an array of up to five possible alternative terms in order of
preference. Present only when the suggestions tag attribute criteria is met.

You can use search form and results pages similar to the following examples to search a collection.
Create a search form
1 Create a ColdFusion page with the following content:





Searching a collection

Enter search term(s) in the box below. You can use AND, OR, NOT, and
parentheses. Surround an exact phrase with quotation marks.







2

Save the file as collection_search_form.cfm.

Enter search target words in this form, which ColdFusion passes as the variable criteria to the action page, which
displays the search results.
Create the results page
1 Create a ColdFusion page with the following content:






Search Results

Your search returned #codecoll_results.RecordCount# file(s).



File: #Key#

Document Title (if any): #Title#

Score: #Score#

Summary: #Summary#

Highlighted Summary: #context#




2

Save the file as collection_search_action.cfm.

3

View collection_search_form.cfm in the web browser.

4

Enter a target word(s) and click Search.

Note: As part of the indexing process, Verity automatically produces a summary of every document file or every query
record set that gets indexed. The default summary result set column selects the best sentences, based on internal rules,
up to a maximum of 500 characters. Every cfsearch operation returns summary information by default. For more
information on this topic, see “Using Verity Search Expressions” on page 488. Alternatively, you can use the context result
set column, which provides a context summary with highlighted search terms.

Enhancing search results
ColdFusion lets you enhance the results of searches by letting you incorporate search features that let users more
easily find the information they need. Verity provides the following search enhancements:

•

Highlighting search terms

•

Providing alternative spelling suggestions

•

Narrowing searches using categories

Highlighting search terms
Term highlighting lets users quickly scan retrieved documents to determine whether they contain the desired information. This can be especially useful when searching lengthy documents, letting users quickly locate relevant information returned by the search.
To implement term highlighting, use the following cfsearch attributes in the search results page:

ADOBE COLDFUSION 8 474
ColdFusion Developer’s Guide

Attributes

Description

ContextHighlightBegin

Specifies the HTML tag to prepend to the search term within the returned documents. This attribute
must be used in conjunction with ContextHighlightEnd to highlight the resulting search terms. The
default HTML tag is , which highlights search terms using bold type.

ContextHighlightEnd

Specifies the HTML tag to append to the search term within the returned documents.

ContextPassages

The number of passages/sentences Verity returns in the context summary (the context column of the
results). The default value is 0; this disables the context summary.

ContextBytes

The total number of bytes that Verity returns in the context summary. The default is 300 bytes.

The following example adds to the previous search results example by highlighting the returned search terms with
bold type.
Create a search results page that includes term highlighting
1 Create a ColdFusion page with the following content:






ContextHighlightBegin=""
ContextHighlightEnd=""
ContextPassages="1"
ContextBytes="500"
maxrows = "100">
Search Results

Your search returned #codecoll_results.RecordCount# file(s).



File: #Key#

Document Title (if any): #Title#

Score: #Score#

Summary: #Summary#

Highlighted Summary: #context#




2

Save the file as collection_search_action.cfm.
Note: This overwrites the previous ColdFusion example page.

3

View collection_search_form.cfm in the web browser:

4

Enter a target word(s) and click Search.

Providing alternative spelling suggestions
Many unsuccessful searches are the result of incorrectly spelled query terms. Verity can automatically suggest alternative spellings for misspelled queries using a dictionary that is dynamically built from the search index.

ADOBE COLDFUSION 8 475
ColdFusion Developer’s Guide

To implement alternative spelling suggestions, you use the cfsearch tag’s suggestions attribute with an integer
value. If the number of documents returned by the search is less than or equal to the value you specify, Verity
provides alternative search term suggestions. In addition to using the suggestions attribute, you may also use the
cfif tag to output the spelling suggestions, and a link through which to search on the suggested terms.
Note: Using alternative spelling suggestions incurs a small performance penalty. This occurs because the cfsearch tag
must also look up alternative spellings in addition to the specified search terms.
The following example specifies that if the number of search results returned is less than or equal to 5, an alternative
search term—which is displayed using the cfif tag—is displayed with a link that the user can click to activate the
alternate search.
Create a search results page that provides alternative spelling suggestions
1 Create a ColdFusion page with the following content:






status = "info"
suggestions="5"
ContextPassages = "1"
ContextBytes = "300"
maxrows = "100">
Search Results

Your search returned #codecoll_results.RecordCount# file(s).


Did you mean:


File: #Key#

Document Title (if any): #Title#

Score: #Score#

Summary: #Summary#

Highlighted Summary: #context#




2

Save the file as collection_search_action.cfm.
Note: This overwrites the previous ColdFusion example page.

3

View collection_search_form.cfm in the web browser:

4

Enter any misspelled target words and click Search.

ADOBE COLDFUSION 8 476
ColdFusion Developer’s Guide

Narrowing searches by using categories
Verity lets you organize your searchable documents into categories. Categories are groups of documents (or database
tables) that you define, and then let users search within them. For example, if you wanted to create a search tool for
a software company, you might create categories such as whitepapers, documentation, release notes, and marketing
collateral. Users can then specify one or more categories in which to search for information. Thus, if users visiting
the website wanted to learn about a conceptual aspect of your company’s technology, they might restrict their search
to the whitepaper and marketing categories.
Typically, you will want to provide users with pop-up menus or check boxes from which they can select categories
to narrow their searches. Alternately, you might create a form that lets users enter both a category name in which to
search, and search keywords.
Create a search application that uses categories
1 Create a collection with support for categories enabled.
2

Index the collection, specifying the category and categoryTree attributes appropriate to the collection.
For more information on indexing Verity collections with support for categories, see “Indexing collections that
contain categories” on page 476.

3

Create a search page that lets users search within the categories that you created.
Create a search page using the cfsearch tag that lets users more easily search for information by restricting
searches to the specified category and, if specified, its hierarchical tree.
For more information on searching Verity collections with support for categories, see “Searching collections that
contain categories” on page 477.

Creating collections with support for categories

You can either select Enable Category Support from the ColdFusion Administrator, or write a cfcollection tag
that uses the category attribute. By enabling category support, you create a collection that contains a Verity
Parametric Index (PI).


For more information on using the cfcollection tag to create Verity collections with support for categories, see
cfcollection in the CFML Reference.
Indexing collections that contain categories

When you index a collection with support for categories enabled, you must do the following:

• Specify a category name using the category attribute. The name (or names) that you provide identifies the
category so that users can specify searches on the documents that the collection contains. For example, you might
create five categories named taste, touch, sight, sound, and smell. When performing a search, users could select from
either a pop-up menu or check box to search within one or more of the categories, thereby limiting their search
within a given range of topics.


• Specify a hierarchical document tree (similar to a file system tree) within which you can limit searches, when
you use the categoryTree attribute. With the categoryTree attribute enabled, ColdFusion limits searches to
documents contained within the specified path.
To use the categoryTree attribute, you specify a hierarchical document tree by listing each category as a string,
and separating them using forward slashes (/). The tree structure that you specify in a search is the root of the
document tree from which you want the search to begin. The type=path attribute appends directory names to
the end of the returned value (as it does when specifying the urlpath attribute).
Note: You can specify only a single category tree.


For more information on using the cfindex tag to create Verity collections with support for categories, see cfindex
in the CFML Reference.
Searching collections that contain categories

When searching data in a collection created with categories, you specify category and categoryTree. The values
supplied to these attributes specify what category should be searched for the specified search string (the criteria
attribute). The category attribute can contain a comma separated list of categories to search. Both attributes can be
specified at the same time.


Note: If cfsearch is executed on a collection that was created without category information, an exception is thrown.
To search collections that contain categories, you use the cfsearch tag, and create an application page that searches
within specified categories. The following example lets the user enter and submit the name of the collection, the
category in which to search, and the document tree associated with the category through a form. By restricting the
search in this way, the users are better able to retrieve the documents that contain the information they are looking
for. In addition to searching with a specified category, this example also makes use of the contextHighlight
attribute, which highlights the returned search results.



Collection Name: 


ADOBE COLDFUSION 8 478
ColdFusion Developer’s Guide

Category: 

CategoryTree: 


Search: 




Search results for: #criteria#





Number of records in query: #sr.recordcount#



Title: #title#

URL: #url#

Score: #score#


#context#



#summary#





For more information on using the cfindex tag to create Verity collections with support for categories, see
cfsearch in the CFML Reference.
Retrieving information about the categories contained in a collection

You can retrieve the category information for a collection by using the cfcollection tag’s categoryList action.
The categoryList action returns a structure that contains two keys:
Variable

Description

categories

The name of the category and its hit count, where hit count is the number of documents in the specified category.

categorytrees

The document tree (a/b/c) and hit count, where hit count is the number of documents at or below the branch of the
document tree.

You can use the information returned by categoryList to display to users the number of documents available for
searching, as well the document tree available for searching. You can also create a search interface that lets the user
select what category to search within based on the results returned by categoryList.

ADOBE COLDFUSION 8 479
ColdFusion Developer’s Guide





 Category: #cat# 

Documents: #catStruct[cat]#




To retrieve information about the categories contained in a collection, you use the cfcollection tag, and create an
application page that retrieves category information from the collection and displays the number of documents
contained by each category. This example lets the user enter and submit the name of the collection via a form, and
then uses the categoryList action to retrieve information about the number of documents contained by the
collection, and the hierarchical tree structure into which the category is organized.







Enter Collection Name: 






Getting collection info...











Category
 
Documents

#x#
 
#categories[x]#







ADOBE COLDFUSION 8 480
ColdFusion Developer’s Guide


Category
 
Documents

#x#
 
#tree[x]#






For more information on using the cfcollection tag to create Verity collections with support for categories, see
cfcollection in CFML Reference.

Working with data returned from a query
Using Verity, you can search data returned by a query—such as a database record set—as if it were a collection of
documents stored on your web server. Using Verity to search makes implementing a search interface much easier, as
well as letting users more easily find information contained in database files. A database can direct the indexing
process, by using different values for the type attribute of the cfindex tag. There are also several reasons and procedures for indexing the results of database and other queries.

Recordsets and types of queries
When indexing record sets generated from a query (using the cfquery, cfldap, or cfpop tag), cfindex creates
indexes based on the type attribute and its set value:
Type

Attribute values

File

The key attribute is the name of a column in the query that contains a full filename (including path).

Path

The key attribute is the name of a column in the query that contains a directory pathname.

Custom

The key attribute specifies a column name that can contain anything you want. In this case, the body attribute is
required, and is a comma-delimited list of the names of the columns that contain the text data that is to be indexed.

The cfindex tag treats all collections the same, whether they originate from a database recordset, or if they are a
collection of documents stored within your website’s root folder.

Indexing data returned by a query
Indexing the results of a query is similar to indexing physical files located on your website, with the added step that
you must write a query that retrieves the data to search. The following are the steps to perform a Verity search on
record sets returned from a query:
1

Create a collection.

2

Write a query that retrieves the data you want to search, and generate a record set.

3

Index the record set using the cfindex tag.
The cfindex tag indexes the record set as if it were a collection of documents in a folder within your website.

4

Search the collection.
The information returned from the collection includes the database key and other selected columns. You can
then use the information as-is, or use the key value to retrieve the entire row from the database table.

You should use Verity to search databases in the following cases:

• You want to perform full-text search on database data. You can search Verity collections that contain textual data
much more efficiently with a Verity search than using SQL to search database tables.

ADOBE COLDFUSION 8 481
ColdFusion Developer’s Guide

•

You want to give your users access to data without interacting directly with the data source itself.

•

You want to improve the speed of queries.

•

You want users to be able to execute queries, but not update database tables.

Unlike indexing documents stored on your web server, indexing information contained in a database requires an
additional step—you must first write a query (using the cfquery, cfldap, or cfpop tag) that retrieves the data you
want to let your users search. You then pass the information retrieved by the query to a cfindex tag, which indexes
the data.
When indexing data with the cfindex tag, you must specify which column of the query represents the filename,
which column represents the document title, and which column (or columns) represents the document’s body (the
information that you want to make searchable).
When indexing a recordset retrieved from a database, the cfindex tag uses the following attributes that correspond
to the data source:
Attribute

Description

key

Primary key column of the data source table.

title

Specifies a query column name.

body

Columns that you want to search for the index.

type

If set to custom, this attribute specifies the columns that you want to index. If set to file or path, this is a column
that contains either a directory path and filename, or a directory path that contains the documents to be indexed.

Using the cfindex tag to index tabular data is similar to indexing documents, with the exception that you refer to
column names from the generated record set in the body attribute. In the following example, the type attribute is
set to custom, specifying that the cfindex tag index the contents of the record set columns Emp_ID, FirstName,
LastName, and Salary, which are identified using the body attribute. The Emp_ID column is listed as the key
attribute, making it the primary key for the record set.
Index a ColdFusion query
1 Create a Verity collection for the data that you want to index.

The following example assumes that you have a Verity collection named CodeColl. You can use the ColdFusion
Administrator to create the collection, or you can create the collection programmatically by using the
cfcollection tag. For more information, see “Creating a collection with the ColdFusion Administrator” on
page 465 or “Creating a collection with the cfcollection tag” on page 466.
2

Create a ColdFusion page with the following content:







SELECT * FROM EMPLOYEE



Indexing Complete

Your collection now includes the following items:

#Emp_ID# #FirstName# #LastName# #Salary#




3

Save the file as collection_db_index.cfm in the myapps directory under the web root directory.

4

Open the file in the web browser to index the collection.
The resulting record set appears.

Search and display the query results
1 Create a ColdFusion page with the following content:





Searching a collection

Collection name: 
Enter search term(s) in the box below. You can use AND, OR, NOT,
and parentheses. Surround an exact phrase with quotation marks.







2

Save the file as collection_db_search_form.cfm in the myapps directory under the web_root.
This file is similar to collection_search_form.cfm, except the form uses collection_db_results.cfm, which you
create in the next step, as its action page.

3

Create another ColdFusion page with the following content:








Your search returned #getEmps.RecordCount# file(s).



Title: 
#Title#
Score: 
#Score#
Key: 
#Key#
Summary: 
#Summary#
Custom 1:
#Custom1#
Column list: 
#ColumnList#





4

Save the file as collection_db_results.cfm in the myapps directory under the web_root.

5

View collection_db_search_form.cfm in the web browser and enter the name of the collection and search terms.

Indexing a file returned by using a query
You can index an individual file that uses a query by retrieving a table row whose contents are a filename. In this case,
the key specifies the column that contains the complete filename. The file is indexed using the cfindex tag as if it
were a document under the web server root folder.
In the following example, the cfindex tag’s type attribute has been set to file, and the specified key is the name of
the column that contains the full path to the file and the filename.

SELECT * FROM EMPLOYEE WHERE EMP_ID = 1



Search and display the file
1 Create a ColdFusion page that contains the following content:

Your collection now includes the following items:

#Emp_ID# #FirstName# #LastName# #Contract_File#




Your search returned #getEmps.RecordCount# file(s).



Title: 
#Title#
Score: 
#Score#
Key: 
#Key#
Summary: 
#Summary#
Custom 1:
#Custom1#
Column list: 
#ColumnList#



Indexing a path returned by using a query
You can index a directory path to a document (or collection of documents) using a query by retrieving a row whose
contents are a full directory path name. In this case, the key specifies the column that contains the complete directory
path. Documents located in the directory path are indexed using the cfindex tag as if they were under the web
server root folder.
In this example, the type attribute is set to path, and the key attribute is assigned the column name Project_Docs.
The Project_Docs column contains directory paths, which Verity indexes as if they were specified as a fixed path
pointing to a collection of documents without the use of a query.
Index a directory path within a query
1 Create a ColdFusion page that contains the following content:

SELECT * FROM EMPLOYEE WHERE Emp_ID = 15




Indexing Complete
Your collection now includes the following items:

#Emp_ID# #FirstName# #LastName# #Project_Docs#


2

Save the file as indexdir.cfm in the myapps directory.

The ColdFusion cfindex tag indexes the contents of the specified directory path.
Search and display the directory path
1 Create a ColdFusion page that contains the following content:

ADOBE COLDFUSION 8 485
ColdFusion Developer’s Guide




Your search returned #getEmps.RecordCount# file(s).



Title: 
#Title#
Score: 
#Score#
Key: 
#Key#
Summary: 
#Summary#
Custom 1:
#Custom1#
Column list: 
#ColumnList#



2

Save the file as displaydir.cfm.

Indexing query results obtained from an LDAP directory
The widespread use of the Lightweight Directory Access Protocol (LDAP) to build searchable directory structures,
internally and across the web, gives you opportunities to add value to the sites that you create. You can index contact
information or other data from an LDAP-accessible server and let users search it.
When creating an index from an LDAP query, remember the following considerations:

• Because LDAP structures vary greatly, you must know the server’s directory schema and the exact name of every
LDAP attribute that you intend to use in a query.
•

The records on an LDAP server can be subject to frequent change.

In the following example, the search criterion is records with a telephone number in the 617 area code. Generally,
LDAP servers use the Distinguished Name (dn) attribute as the unique identifier for each record so that attribute is
used as the key value for the index.




DN: #dn# 

O: #o# 

TELEPHONENUMBER: #telephonenumber# 

MAIL: #mail# 

=============================




ADOBE COLDFUSION 8 486
ColdFusion Developer’s Guide







#Key#, #Title#, #Body# 



Indexing cfpop query results
The contents of mail servers are generally volatile; specifically, the message number is reset as messages are added
and deleted. To avoid mismatches between the unique message number identifiers on the server and in the Verity
collection, you must re-index the collection before processing a search.
As with the other query types, you must provide a unique value for the key attribute and enter the data fields to index
in the body attribute.
The following example updates the pop_query collection with the current mail for user1, and searches and returns
the message number and subject line for all messages that contain the word action:




#messagenumber# 

#from# 

#to# 

#subject# 

#body# 









#key#, #title# 



488

Chapter 28: Using Verity Search
Expressions
You can use Verity search expressions to refine your searches to yield the most accurate results.
Contents

About Verity query types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
Using simple queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
Using explicit queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
Using natural queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
Using Internet queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
Composing search expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
Refining your searches with zones and fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505

About Verity query types
When you search a Verity collection, you can use a simple, explicit, natural, or Internet query. The following table
compares the query types:
Query type

Content

Use of operators and modifiers

CFML example

Simple

One or more
words

Uses STEM operator and MANY
modifier, by default



Explicit

Words, operators,
modifiers

Must be specified



Natural

One or more
words

Uses STEM operator and MANY
modifier, by default



Internet

Words, operators,
modifiers



The query type determines whether the search words that you enter are stemmed, and whether the retrieved words
contribute to relevance-ranked scoring. Both of these conditions occur by default in simple queries. For more information on the STEM operator and MANY modifier, see “Stemming in simple queries” on page 489.
Note: Operators and modifiers are formatted as uppercase letters in this topic solely to enhance legibility. They might be
all lowercase or uppercase.

ADOBE COLDFUSION 8 489
ColdFusion Developer’s Guide

Using simple queries
The simple query is the default query type and is appropriate for the vast majority of searches. When entering text
on a search form, you perform a simple query by entering a word or comma-delimited strings, with optional
wildcard characters. Verity treats each comma as a logical OR. If you omit the commas, Verity treats the expression
as a phrase.
Important: Many web search engines assume a logical AND for multiple word searches, and search for a phrase only if
you use quotation marks. Because Verity treats multiple word searches differently, it might help your users if you provide
examples on your search page or a brief explanation of how to search.
The following table shows examples of simple searches:
Example

Search result

low,brass,instrument

low or brass or instrument

low brass instrument

the phrase, low brass instrument

film

film, films, filming, or filmed

filming AND fun

film, films, filming, or filmed, and fun

filming OR fun

film, films, filming, or filmed, or fun

filming NOT fun

film, films, filming, or filmed, but not fun

The operators AND and OR, and the modifier NOT, do not require angle brackets (<>). Operators typically require
angle brackets and are used in explicit queries. For more information about operators and modifiers, see “Operators
and modifiers” on page 497.

Stemming in simple queries
By default, Verity interprets words in a simple query as if you entered the STEM operator (and MANY modifier).
The STEM operator searches for words that derive from a common stem. For example, a search for instructional
returns files that contain instruct, instructs, instructions, and so on.
The STEM operator works on words, not word fragments. A search for “instrument” returns documents containing
“instrument,” “instruments,” “instrumental,” and “instrumentation,” whereas a search for “instru” does not. (A
wildcard search for instru* returns documents with these words, and also those with instruct, instructional, and so
on.)
Note: The MANY modifier presents the files returned in the search as a list based on a relevancy score. A file with more
occurrences of the search word has a higher score than a file with fewer occurrences. As a result, the search engine ranks
files according to word density as it searches for the word that you specify, as well as words that have the same stem. For
more information on the MANY modifier, see “Modifiers” on page 504.
In CFML, enter your search terms, operators, and modifiers in the criteria attribute of the cfsearch tag:


ADOBE COLDFUSION 8 490
ColdFusion Developer’s Guide

Preventing stemming
When entering text on a search form, you can prevent Verity from implicitly adding the STEM operator by doing
one of the following:

•

Perform an explicit query.

•

Use the WORD operator. For more information, see “Operators” on page 497.

•

Enclose the search term that has double-quotation marks with single-quotation marks, as follows:
 'hoist{s,ing,ed}'
comma,

hoists, hoisting, or hoisted

^

Matches any character not in the set.

'sl[^ia]m'

slum, but not slim or slam

-

Specifies a range for a single character in a set.

 'c[a-r]t'

cat, cot, but not cut (that is, every
word beginning with c, ending
with t, and containing any single
letter from a to r)

 'sl[iau]m'

To search for a wildcard character as a literal, place a backslash character before it:

ADOBE COLDFUSION 8 492
ColdFusion Developer’s Guide

• To match a question mark or other wildcard character, precede the ? with one backslash. For example, type the
following in a search form: Checkers\?
• To match a literal asterisk, you precede the * with two backslashes, and enclose the search term with either single
or double quotation marks. For example, type the following in a search form: 'M\\*' (or "M\\*") The following is the
corresponding CFML code:


Note: The last line is equivalent to criteria='"M\\*"'>.
Searching for special characters

The search engine handles a number of characters in particular ways as the following table describes:
Characters

Description

,()[

These characters end a text token.
A token is a variable that stores configurable properties. It lets the administrator or user configure various settings and
options.

=> using \ or `` as your
search term.

ADOBE COLDFUSION 8 493
ColdFusion Developer’s Guide

Using natural queries
The Natural parser supports searching for similar documents, a search method sometimes referred to as similarity
searching. The Natural parser supports searching the full text of documents only. The Natural parser does not
support searching collection fields and zones. The Natural parser does not support Verity query language except for
topics.
Note: The Verity products and documentation refer to the Natural parser as the Query-By-Example parser, as well as
the Free Text parser.
Meaningful words are automatically treated as if they were preceded by the MANY modifier and the STEM operator.
By implicitly applying the STEM operator, the search engine searches not only for the meaningful words themselves,
but also for words that have the same stem. By implicitly applying the MANY modifier, Verity calculates each
document’s score based on the word density it finds for meaningful words; the denser the occurrences of a word in
a document, the higher the document’s score.
By default, common words (such as the, has, and for) are stripped away, and the query is built based on the more
significant words (such as personnel, interns, schools, and mentors). Therefore, the results of a natural language search
are likely to be less precise than a search performed using the simple or explicit parser.
The Natural parser interprets topic names as topic objects. This means that if the specified text block contains a topic
name, the query expression represented by the topic is considered in the search.

Using Internet queries
With the Internet query parser, users can search entire documents or parts of documents (zones and fields) entering
words, phrases, and plain language similar to that used by many web search engines. ColdFusion supports two
Internet query parsers in the cfsearch type attribute.
Internet: Uses standard, web-style query syntax. For more information, see “Query syntax” on page 494.
Internet_basic: Similar to Internet. This query parser enhances performance, but produces less accurate relevancy
statistics.
Note: Verity also includes the Internet_BasicWeb and Internet_AdvancedWeb query parsers, which are not directly
supported by ColdFusion.

Search terms
In a search form enabled with the Internet query parser, users can enter words, phrases, and plain language. The
Internet parser does not support the Verity query language (VQL).

Words
To search for multiple words, separate them with spaces.

Phrases
To search for an exact phrase, surround it with double-quotation marks. A string of capitalized words is assumed to
be a name. Separate a series of names with commas. Commas aren’t needed when the phrases are surrounded by
quotation marks.

ADOBE COLDFUSION 8 494
ColdFusion Developer’s Guide

The following example searches for a document that contains the phrases “San Francisco” and “sourdough bread”:
"San Francisco" "sourdough bread"

Plain language
To search with plain language, enter a question or concept. The Internet Query Parser identifies the important words
and searches for them. For example, enter a question such as:
Where is the sales office in San Francisco?

This query produces the same results as entering:
sales office San Francisco

Including and excluding search terms
You can limit searches by excluding or requiring search terms, or by limiting the areas of the document that are
searched.
A minus sign (–) immediately preceding a search term (word or phrase) excludes documents containing the term.
A plus sign (+) immediately preceding a search term (word or phrase) means returned documents are guaranteed to
contain the term.
If neither sign is associated with the search term, the results may include documents that do not contain the specified
term as long as they meet other search criteria.

Field searches
The Internet parser lets users perform field searches. The fields that are available for searching depend on field
extraction rules based on the document type of the documents in the collection.
To search a document field, type the name of the field, a colon (:), and the search term with no spaces.
field:term

If you enter a minus sign (–) immediately preceding field, documents that contain the specified term are excluded
from the search results. For example, if you enter -field:term, documents that contain the specified term in the
specified field are excluded from the results of the search.
If you enter a plus sign (+) immediately proceeding the field search specification, such as +field:term, documents
are included in the search results only if the search term is present in the specified field.
Field searches are enabled by the enableField parameter in a template file. This parameter, set to 0 by default, must
be set to 1 to allow searching a document field.
Important: The enableField parameter is the only thing in a template file that should be modified.

Query syntax
The query syntax is very similar to the syntax that users expect to use on the web. Queries are interpreted according
to the following rules:

•

Individual search terms are separated by whitespace characters, such as a space, tab, or comma, for example:
cake recipes

•

Search phrases are entered within double-quotation marks, for example:

ADOBE COLDFUSION 8 495
ColdFusion Developer’s Guide

"chocolate cake" recipe

•

Exclude terms with the negation operator, minus ( - ), or the NOT operator, for example:
cake recipes -rum
cake recipes NOT rum

• Require a compulsory term with the unary inclusion operator, plus sign (+); in this example, the term chocolate
must be included:
cake recipes +chocolate
1 Require compulsory terms with the binary inclusion operator AND; in this example, the terms recipes and
chocolate must be included:

cake recipes and chocolate

Field searches
You can search fields or zones by specifying name: term, where:
name is the name of the field or zone
term is an individual search term or phrase

For example:
bakery city:"San Francisco"
bakery city:Sunnyvale

For more information, see “Refining your searches with zones and fields” on page 505.

Pass-through of terms
Search terms are passed through to the VDK-level and are interpreted as Verity Query Language (VQL) syntax. No
issues arise if the terms contain only alphabetic or numeric characters. Other kinds of characters might be interpreted by the language you’re using. If a term contains a character that is not handled by the specified language, it
might be interpreted as VQL. For example, a search term that includes an asterisk (*) might be interpreted as a
wildcard.

Stop words
The configurable Internet query parser uses its own stop-word list, qp_inet.stp, to specify terms to ignore for natural
language processing.
Note: You can override the “stop out” by using quotation marks around the word.
For example, the following stop words are provided in the query parser’s stop-word file for the English (Basic)
template:
a

did

i

or

what

also

do

i’m

should

when

an

does

if

so

where

and

find

in

than

whether

ADOBE COLDFUSION 8 496
ColdFusion Developer’s Guide

any

for

is

that

which

am

from

it

the

who

are

get

its

there

whose

as

got

it’s

to

why

at

had

like

too

will

be

has

not

want

with

but

have

of

was

would

can

how

on

were



Verity provides a populated stop-word file for the English and English (Advanced) languages. You do not need to
modify the qp_inet.stp file for these languages. If you use the configurable Internet query parser for another
language, you must provide your own qp_inet.stp file that contains the stop words that you want to ignore in that
language. This stop-word file must contain, at a minimum, the language-equivalent words for or and .
Note: The configurable Internet query parser’s stop-word file contains a different word list than the vdk30.stp word file,
which is used for other purposes, such as summarization.

Composing search expressions
The following rules apply to the composition of search expressions.

Case sensitivity
Verity searches are case-sensitive only when the search term is entered in mixed case. For example, a search for zeus
finds zeus, Zeus, or ZEUS; however, a search for Zeus finds only Zeus.
To have your application always ignore the case that the user types, use the ColdFusion LCase() function in the
criteria attribute of cfsearch. The following code converts user input to lowercase, thereby eliminating casesensitivity concerns:


Prefix and infix notation
By default, Verity uses infix notation, in which precedence is implicit in the expression; for example, the AND
operator takes precedence over the OR operator.
You can use prefix notation with any operator except an evidence operator (typically, STEM, WILDCARD, or
WORD; for a description of evidence operators, see “Evidence operators” on page 501). In prefix notation, the
expression explicitly specifies precedence. Rather than repeating an operator, you can use prefix notation to list the
operator once and list the search targets in parentheses. For example, the following expressions are equivalent:

•

Moses  Larry  Jerome  Daniel  Jacob

•

(Moses,Larry,Jerome,Daniel,Jacob)

ADOBE COLDFUSION 8 497
ColdFusion Developer’s Guide

The following prefix notation example searches first for documents that contain Larry and Jerome, and then for
documents that contain Moses:
OR (Moses, AND (Larry,Jerome))
The infix notation equivalent of this is as follows:
Moses OR (Larry AND Jerome)

Commas in expressions
If an expression includes two or more search terms within parentheses, a comma is required between the elements
(whitespace is ignored). The following example searches for documents that contain any combination of Larry and
Jerome together:
AND (Larry, Jerome)

Precedence rules
Expressions are read from left to right. The AND operator takes precedence over the OR operator; however, terms
enclosed in parentheses are evaluated first. When the search engine encounters nested parentheses, it starts with the
innermost term.
Example

Search result

Moses AND Larry OR Jerome

Documents that contain Moses and Larry, or Jerome

(Moses AND Larry) OR Jerome

(Same as above)

Moses AND (Larry OR Jerome)

Documents that contain Moses and either Larry or Jerome

Delimiters in expressions
You use angle brackets (< >), double quotation marks ("), and backslashes (\) to delimit various elements in a search
expression, as the following table describes:
Character

Usage

<>

Left and right angle brackets are reserved for designating operators and modifiers. They are optional for the AND,
OR, and NOT, but required for all other operators.

"

Use double quotation marks in expressions to search for a word that is otherwise reserved as an operator or modifier,
such as AND, OR, and NOT.

\

To include a backslash in a search expression, insert two backslashes for each backslash character that you want
included in the search; for example, C:\\CFusion\\bin.

Operators and modifiers
You are probably familiar with searches containing AND, OR, and NOT. Verity has many additional operators and
modifiers, of various types, that offer you a high degree of specificity in setting search parameters.
Operators

An operator represents logic to be applied to a search element. This logic defines the qualifications that a document
must meet to be retrieved. You can use operators to refine your search or to influence the results in other ways.

ADOBE COLDFUSION 8 498
ColdFusion Developer’s Guide

For example, you can construct an HTML form for conducting searches. In the form, you can search for a single
term. You can refine the search by limiting the search scope in a number of ways. Operators are available for limiting
a query to a sentence or paragraph, and you can search words based on proximity.
Ordinarily, you use operators in explicit searches, as follows:
"search_string"

The following operator types are available:
Operator type

Purpose

Concept

Identifies a concept in a document by combining the meanings of search elements.

Relational

Searches fields in a collection.

Evidence

Specifies basic and intelligent word searches.

Proximity

Specifies the relative location of words in a document.

Score

Manipulates the score returned by a search element. You can set the score percentage display to four decimal places.

The following table shows the operators, according to type, that are available for conducting searches of ColdFusion
Verity collections:
Concept

Relational

Evidence

Proximity

Score

ACCRUE

<

STEM

NEAR

YESNO

ALL

<=

WILDCARD

NEAR/N

PRODUCT

AND

=

WORD

PARAGRAPH

SUM

ANY

>

THESAURUS

PHRASE

COMPLEMENT

OR

>=

SOUNDEX

SENTENCE

CONTAINS

TYPO/N

IN

MATCHES
STARTS
ENDS
SUBSTRING

Concept operators

Concept operators combine the meaning of search elements to identify a concept in a document. Documents
retrieved using concept operators are ranked by relevance. The following table describes each concept operator:
Operator

Description

AND

Selects documents that contain all the search elements that you specify.

OR

Selects documents that show evidence of at least one of the search elements that you specify.

ADOBE COLDFUSION 8 499
ColdFusion Developer’s Guide

Operator

Description

ACCRUE

Selects documents that include at least one of the search elements that you specify. Documents are ranked based on
the number of search elements found.

ALL

Selects documents that contain all of the search elements that you specify. A score of 1.00 is assigned to each retrieved
document. ALL and AND retrieve the same results, but queries using ALL are always assigned a score of 1.00.

ANY

Selects documents that contain at least one of the search elements that you specify. A score of 1.00 is assigned to each
retrieved document. ANY and OR retrieve the same results, but queries using ANY are always assigned a score of 1.00.

Relational operators

Relational operators search document fields (such as AUTHOR) that you defined in the collection. Documents that
contain specified field values are returned. Documents retrieved using relational operators are not ranked by
relevance, and you cannot use the MANY modifier with relational operators.
You use the following operators for numeric and date comparisons:
Operator

Description

=

Equal

!=

Not equal

>

Greater than

>=

Greater than or equal to

<

Less than

<=

Less than or equal to

For example, to search for documents that contain values for 1999 through 2002, you perform either of the following
searches:

•

A simple search for 1999,2000,2001,2002

•

An explicit search using the = operator: >=1999,<=2002

If a document field named PAGES is defined, you can search for documents that are 5 pages or fewer by entering
PAGES < 5 in your search. Similarly, if a document field named DATE is defined, you can search for documents
dated prior to and including December 31, 1999 by entering DATE <= 12-31-99 in your search.
The following relational operators compare text and match words and parts of words:

ADOBE COLDFUSION 8 500
ColdFusion Developer’s Guide

Operator

Description

CONTAINS

Selects documents by matching the word or phrase that you specify
with the values stored in a specific document field. Documents are
selected only if the search elements specified appear in the same
sequential and contiguous order in the field value.

Example

•

In a document field named TITLE, to retrieve
documents whose titles contain music, musical,
or musician, search for TITLE  Musi*.

•

To retrieve CFML and HTML pages whose
meta tags contain Framingham as a content
word, search for KEYWORD 
Framingham.

MATCHES

Selects documents by matching the query string with values stored For examples, see the text immediately following
in a specific document field. Documents are selected only if the
this table.
search elements specified match the field value exactly. If a partial
match is found, a document is not selected. When you use the
MATCHES operator, you specify the field name to search, and the
word, phrase, or number to locate. You can use ? and * to represent
individual and multiple characters, respectively, within a string.

STARTS

Selects documents by matching the character string that you
In a document field named REPORTER, to retrieve
specify with the starting characters of the values stored in a specific documents written by Clark, Clarks, and Clarkson,
document field.
search for REPORTER  Clark.

ENDS

Selects documents by matching the character string that you
specify with the ending characters of the values stored in a specific
document field.

In a document field named OFFICER, to retrieve
arrest reports written by Tanner, Garner, and
Milner, search for OFFICER  ner.

SUBSTRING

Selects documents by matching the query string that you specify
with any portion of the strings in a specific document field.

In a document field named TITLE, to retrieve documents whose titles contain words such as solution,
resolution, solve, and resolve, search for TITLE
 sol.

For example, assume a document field named SOURCE includes the following values:

•

Computer

•

Computerworld

•

Computer Currents

•

PC Computing

To locate documents whose source is Computer, enter the following:
SOURCE  computer

To locate documents whose source is Computer, Computerworld, and Computer Currents, enter the following:
SOURCE  computer*

To locate documents whose source is Computer, Computerworld, Computer Currents, and PC Computing, enter the
following:
SOURCE  *comput*

For an example of ColdFusion code that uses the CONTAINS relational operator, see “Field searches” on page 506.
You can use the SUBSTRING operator to match a character string with data stored in a specified data source. In the
example described in this section, a data source called TEST1 contains the table YearPlaceText, which contains three
columns: Year, Place, and Text. Year and Place make up the primary key. The following table shows the TEST1
schema:

ADOBE COLDFUSION 8 501
ColdFusion Developer’s Guide

Year

Place

Text

1990

Utah

Text about Utah 1990

1990

Oregon

Text about Oregon 1990

1991

Utah

Text about Utah 1991

1991

Oregon

Text about Oregon 1991

1992

Utah

Text about Utah 1992

The following application page matches records that have 1990 in the TEXT column and are in the Place Utah. The
search operates on the collection that contains the TEXT column and then narrows further by searching for the
string Utah in the CF_TITLE document field. Document fields are defaults defined in every collection corresponding to the values that you define for URL, TITLE, and KEY in the cfindex tag.

SELECT Year || Place AS Identifier, text
FROM YearPlaceText




Record Counts: 

#GetText.RecordCount# 

#GetText_Search.RecordCount# 


Query Results --- Should be 5 rows 


#Identifier# 


Search Results -- should be 1 row 


#GetText_Search.TITLE# 


Evidence operators

Evidence operators let you specify a basic word search or an intelligent word search. A basic word search finds
documents that contain only the word or words specified in the query. An intelligent word search expands the query
terms to create an expanded word list so that the search returns documents that contain variations of the query
terms.
Documents retrieved using evidence operators are not ranked by relevance unless you use the MANY modifier.
The following table describes the evidence operators:

ADOBE COLDFUSION 8 502
ColdFusion Developer’s Guide

Operator

Description

Example

STEM

Expands the search to include the word that you enter and its vari- believe retrieves matches such as
ations. The STEM operator is automatically implied in any simple “believe,” “believing,” and “believer”.
query.

WILDCARD

Matches wildcard characters included in search strings. Certain
spam* retrieves matches such as, spam,
characters automatically indicate a wildcard specification, such as spammer, and spamming.
apostrophe (*) and question mark(?).

WORD

Performs a basic word search, selecting documents that include
one or more instances of the specific word that you enter. The
WORD operator is automatically implied in any SIMPLE query.

 logic retrieves logic, but not variations
such as logical and logician.

THESAURUS

Expands the search to include the word that you enter and its
synonyms. Collections do not have a thesaurus by default; to use
this feature you must build one.

 altitude retrieves documents
containing synonyms of the word altitude, such
as height or elevation.

SOUNDEX

Expands the search to include the word that you enter and one or  sale retrieves words such as sale, sell,
more words that “sound like,” or whose letter pattern is similar to, seal, shell, soul, and scale.
the word specified. Collections do not have sound-alike indexes by
default; to use this feature you must build sound-alike indexes.

TYPO/N

Expands the search to include the word that you enter plus words  swept retrieves kept.
that are similar to the query term. This operator performs “approximate pattern matching” to identify similar words. The optional N
variable in the operator name expresses the maximum number of
errors between the query term and a matched term, a value called
the error distance. If N is not specified, the default error distance is
2.

The following example uses an evidence operator:

Proximity operators

Proximity operators specify the relative location of specific words in the document. To retrieve a document, the
specified words must be in the same phrase, paragraph, or sentence. In the case of NEAR and NEAR/N operators,
retrieved documents are ranked by relevance based on the proximity of the specified words. Proximity operators can
be nested; phrases or words can appear within SENTENCE or PARAGRAPH operators, and SENTENCE operators
can appear within PARAGRAPH operators.
The following table describes the proximity operators:

ADOBE COLDFUSION 8 503
ColdFusion Developer’s Guide

Operator

Description

Example

NEAR

Selects documents containing specified search terms. The closer
the search terms are to one another within a document, the higher
the document’s score. The document with the smallest possible
region containing all search terms always receives the highest
score. Documents whose search terms are not within 1000 words of
each other are not selected.

war  peace retrieves documents that
contain stemmed variations of these words
within close proximity to each other (as defined
by Verity). To control search proximity, use
NEAR/N.

NEAR/N

Selects documents containing two or more search terms within N
number of words of each other, where N is an integer between 1
and 1024. NEAR/1 searches for two words that are next to each
other. The closer the search terms are within a document, the
higher the document's score.

commute  bicycle  train
 retrieves documents that contain
stemmed variations of these words within 10
words of each other.

You can specify multiple search terms using multiple instances of
NEAR/N as long as the value of N is the same.
PARAGRAPH

Selects documents that include all of the words you specify within  (mission, goal, statement)
the same paragraph. To search for three or more words or phrases retrieves documents that contain these terms
in a paragraph, you must use the PARAGRAPH operator between
within a paragraph.
each word or phrase.

PHRASE

Selects documents that include a phrase you specify. A phrase is a
grouping of two or more words that occur in a specific order.

SENTENCE

Selects documents that include all of the words you specify within  (jazz, musician) returns documents
the same sentence.
that contain these words in the same sentence.

IN

Selects documents that contain specified values in one or more
Chang  author searches document zones
document zones. A document zone represents a region of a docu- named author for the word Chang.
ment, such as the document’s summary, date, or body text. To
search for a term only within the one or more zones that have
certain conditions, you qualify the IN operator with the WHEN
operator.

 (mission, oak) returns documents that
contain the phrase mission oak.

The following example uses a proximity operator:


For an example using the IN proximity operator to search XML documents, see “Zone searches” on page 505.
Score operators

Score operators control how the search engine calculates scores for retrieved documents. The maximum score that
a returned search element can have is 1.000. You can set the score to display a maximum of four decimal places.
When you use a score operator, the search engine first calculates a separate score for each search element found in a
document, and then performs a mathematical operation on the individual element scores to arrive at the final score
for each document.
The document’s score is available as a result column. You can use the SCORE result column to get the relevancy score
of any document retrieved, for example:

#Search1.Title#

Document Score=#Search1.SCORE#



The following table describes the score operators:

ADOBE COLDFUSION 8 504
ColdFusion Developer’s Guide

Operator

Description

Example

YESNO

Forces the score of an element to 1 if the element’s score is nonzero. mainframe. If the retrieval result of
the search on mainframe is 0.75, the YESNO
operator forces the result to 1. You can use
YESNO to avoid relevance ranking.

PRODUCT

Multiplies the scores for the search elements in each document
matching a query.

(computers, laptops) takes the
product of the resulting scores.

SUM

Adds the scores for the search element in each document matching
a query, up to a maximum value of 1.

(computers, laptops) takes the sum of
the resulting scores.

COMPLEMENT

Calculates scores for documents matching a query by taking the
computers. If the search
complement (subtracting from 1) of the scores for the query’s search element’s original score is .785, the COMPLEelements. The new score is 1 minus the search element’s original
MENT operator recalculates the score as .215.
score.

Modifiers

You combine modifiers with operators to change the standard behavior of an operator in some way. The following
table describes the available modifiers:
Modifier

Description

Example

CASE

Specifies a case-sensitive search. Normally, Verity searches are caseinsensitive for search text entered in all uppercase or all lowercase,
and case-sensitive for mixed-case search strings.

Java OR java retrieves documents that contain Java or java, but not
JAVA.

MANY

Counts the density of words, stemmed variations, or phrases in a
javascript 
document and produces a relevance-ranked score for retrieved docu- vbscript.
ments. Use with the following operators:
You cannot use the MANY modifier with the
• WORD
following operators:

•

WILDCARD

•

AND

•

STEM

•

OR

•

PHRASE

•

ACCRUE

•

SENTENCE

•

Relational operators

•

PARAGRAPH

NOT

Excludes documents that contain the specified word or phrase. Use
only with the AND and OR operators.

Java  programming  coffee
retrieves documents that contain Java and
programming, but not coffee.

ORDER

Specifies that the search elements must occur in the same order in
which you specify them in the query. Use with the following operators:

 ("server", "Java")
retrieves documents that contain server
before Java.

•

PARAGRAPH

•

SENTENCE

•

NEAR/N

Place the ORDER modifier before any operator.

ADOBE COLDFUSION 8 505
ColdFusion Developer’s Guide

Refining your searches with zones and fields
One of the strengths of Verity is its ability to perform full-text searches on documents of many formats. However,
there are often times when you want to restrict a search to certain portions of a document, to improve search
relevance. If a Verity collection contains some documents about baseball and other documents about caves, a search
for the word bat might retrieve several irrelevant results.
If the documents are structured documents, you can take advantage of the ability to search zones and fields. The
following are some examples of structured documents:

•

Documents created with markup languages (XML, SGML, HTML)

•

Internet Message Format documents

•

Documents created by many popular word-processing applications

Note: Although your word processor might open with what appears to be a blank page, the document has many regions
such as title, subject, and author. Refer to your application’s documentation or online help system for how to view a
document’s properties.

Zone searches
You can perform zone searches on markup language documents. The Verity zone filter includes built-in support for
HTML and several file formats; for a list of supported file formats, see “Building a Search Interface” on page 459.
Verity searches XML files by treating the XML tags as zones. When you use the zone filter, the Verity engine builds
zone information into the collection’s full-word index. This index, enhanced with zone information, permits quick
and efficient searches over zones. The zone filter can automatically define a zone, or you can define it yourself in the
style.zon file. You can use zone searching to limit your search to a particular zone. This can produce more accurate,
but not necessarily faster, search results than searching an entire file.
Note: The contents of a zone cannot be returned in the results list of an application.
Examples
The following examples perform zone searching on XML files. In a list of rock bands, you could have XML files with
tags for the instruments and for comments. In the following XML file, the word Pete appears in a comment field:

Dan
Jake
Mike
Chris
Dan plays guitar, better than Pete.
Jake plays rhythm guitar.


The following CFML code shows a search for the word Pete:


The above search for Pete returns this XML file because this search target is in the COMMENT_A field. In contrast,
Pete is the lead guitarist in the following XML file:

Pete
Roger

ADOBE COLDFUSION 8 506
ColdFusion Developer’s Guide

John
Kenny
Who knows who's better than this band?
Ticket prices correlated with decibels.


To retrieve only the files in which Pete is the lead guitarist, perform a zone search using the IN operator according
to the following syntax:
(query)  (zone1, zone2, ...)

Note: As with other operators, IN might be uppercase or lowercase. Unlike AND, OR, or NOT, you must enclose IN
within brackets.
Thus, the following explicit search retrieves files in which Pete is the lead guitarist:
(Pete)  Lead_Guitar

This is expressed in CFML as follows:


To retrieve files in which Pete plays either lead or rhythm guitar, use the following explicit search:
(Pete)  (Lead_Guitar,Rhythm_Guitar)

This is expressed in CFML as follows:


Field searches
Fields are extracted from the document and stored in the collection for retrieval and searching, and can be returned
on a results list. Zones, on the other hand, are merely the definitions of “regions” of a document for searching
purposes, and are not physically extracted from the document in the same way that fields are extracted.
You must define a region of text as a zone before it can be a field. Therefore, it can be only a zone, or it can be both
a field and a zone. Whether you define a region of text as a zone only or as both a field and a zone depends on your
particular requirements.
A field must be defined in the style file, style.ufl, before you create the collection. To map zones to fields (to display
field data), you must define and add these extra fields to style.ufl.
You can specify the values for the cfindex attributes TITLE, KEY, and URL as document fields for use with
relational operators in the criteria attribute. (The SCORE and SUMMARY attributes are automatically returned
by a cfsearch; these attributes are different for each record of a collection as the search criteria changes.) Text
comparison operators can reference the following document fields:

•

cf_title

•

cf_key

•

cf_url

•

cf_custom1

•

cf_custom2

ADOBE COLDFUSION 8 507
ColdFusion Developer’s Guide

•

cf_custom3

•

cf_custom4

Text comparison operators can also reference the following automatically populated document fields:

•

title

•

key

•

url

•

vdksummary

•

author

•

mime-type

To explore how to use document fields to refine a search, consider the following database table, named Calls. This
table has four columns and three records, as the following table shows:
call_ID

Problem_Description

Short_Description

Product

1

Can’t bold text properly under certain conditions

Bold Problem

HomeSite+

2

Certain optional attributes are acting as required attributes

Attributes Problem

ColdFusion

3

Can’t do a File/Open in certain cases

File Open Problem

HomeSite+

A Verity search for the word certain returns three records. However, you can use the document fields to restrict your
search; for example, a search to retrieve HomeSite+ problems with the word certain in the problem description.
These are the requirements to run this procedure:

•

Create and populate the Calls table in a database of your choice

•

Create a collection named Training (you can do this in CFML or in the ColdFusion Administrator).

The following table shows the relationship between the database column and cfindex attribute:
Database column

The cfindex
attribute

Comment

call_ID

key

The primary key of a database table is often a key attribute.

Problem_Description

body

This column is the information to be indexed.

Short_Description

title

A short description is conceptually equivalent to a title, as in a running title of a journal article.

Product

custom1

This field refines the search.

You begin by selecting all data in a query:

Select * from Calls


The following code shows the cfindex tag for indexing the collection (the type attribute is set to custom for tabular
data):


To perform the refined search for HomeSite+ problems with the word certain in the problem description, the
cfsearch tag uses the CONTAINS operator in its criteria attribute:


The following code displays the results of the refined search:



KEY
TITLE
CUSTOM1


#KEY#
#TITLE#
#CUSTOM1#




509

Part 5: Requesting and Presenting
Information
This part contains the following topics:
Introduction to Retrieving and Formatting Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
Building Dynamic Forms with cfform Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
Validating Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553
Creating Forms in Flash. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
Creating Skinnable XML Forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594
Using Ajax UI Components and Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .613
Using Ajax Data and Development Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647
Using the Flash Remoting Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674
Using Flash Remoting Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688
Using the LiveCycle Data Services ES Assembler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .691
Using Server-Side ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706

511

Chapter 29: Introduction to Retrieving
and Formatting Data
ColdFusion lets you retrieve and format data. You can use forms to get user data and control the data that is displayed
by a dynamic web page. You can also populate a table with query results and use ColdFusion functions to format and
manipulate data. To use these features, you should be familiar with HTML forms.
Contents

Using forms in ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
Working with action pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514
Working with queries and data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
Returning results to the user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
Dynamically populating list boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
Creating dynamic check boxes and multiple-selection list boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526

Using forms in ColdFusion
ColdFusion lets you use a variety of types of forms. You can use plain HTML or CFML, and you can generate HTML,
Flash, or skinned XML forms. This section describes your form options and introduces a basic ColdFusion form.

ColdFusion forms tags
You can use HTML or CFML tags to define your form. ColdFusion includes the following CFML tags that correspond to HTML tags, but provide additional functionality:

•

cfapplet

•

cfform

•

cfinput

•

cfselect

•

cftextarea

These tags support all the attributes of their HTML counterparts, plus ColdFusion attributes and features.
ColdFusion also provides the following forms tags that have no direct equivalent in HTML:

•

cfcalendar

•

cfgrid

•

cfslider

•

cftree

Lets users select dates from a Flash month-by-month calendar.

Displays and lets users enter data in a row and column grid format; can get data directly from a query.
Lets users input data by moving a sliding marker.

Displays data in a hierarchical tree format with graphical indicators; can get data directly from a query.

ColdFusion Form tag features
ColdFusion forms tags provide the following features:

ADOBE COLDFUSION 8 512
ColdFusion Developer’s Guide

Built-in validation support: You can validate data in the client browser or on the server. You can specify that a field
is required, contains a specific type of data, has a maximum length, or is in a range of values. You can also use data
masking to control user input. For more information on validation, see “Validating Data” on page 553.
Note: ColdFusion also provides a method of doing on-server validation of HTML form controls.
Flash format forms and elements: You can display a form as Flash, which works identically on a variety of platforms
and provides additional display features not available in HTML. These features include accordion-style and multipletab form panes and automatic element positioning. You can also display cftree, cfgrid, and cfcalendar form
elements as Flash items in an otherwise-HTML form. For more information on Flash forms and form elements, see
“Creating Forms in Flash” on page 576.
XML Skinable forms: ColdFusion can generate XML forms and apply XSLT skins to format the forms. XML format
forms let you separate the form presentation from the form logic and data field information. They give you detailed
control over the appearance of the forms by applying custom skins, and let you create custom controls. For more
information on XML skinnable forms, see “Creating Skinnable XML Forms” on page 594.
Direct support for ColdFusion variables: You can easily use ColdFusion variables directly to populate your form
controls. For example you can specify a query result to populate the cfgrid and cftree tags.
These features make CFML forms tags powerful and flexible, and let you easily develop fully featured, pleasing
forms.
This topic uses CFML tags, but does not describe or use most of their special features. “Building Dynamic Forms
with cfform Tags” on page 530 describes how to use many of the tags that are specific to ColdFusion, such as cftree
and cfgrid.

Creating a basic form
The following simple form shows how you can create a form that lets a user enter data. This form uses basic CFML
form tags. It does not use any of the advanced features of ColdFusion, such as validation, Flash or XML format, or
special input controls. You could convert it to a purely HTML form by removing the initial “cf ” prefix from the tag
names, and the form would work.

The following table shows the format of form control tags:

ADOBE COLDFUSION 8 513
ColdFusion Developer’s Guide

Control

Code

Text control



List (select) box 
DisplayName1
DisplayName2
DisplayName3


Radio buttons

DisplayName1
DisplayName2
DisplayName3

Check box

Yes

Reset button



Submit button



The following listing shows the form source in detail. To test the form and use it as input for later examples in this
topic, save this code as formpage.cfm.









First Name: 

Last Name: 

Salary: 



City

Arlington
Boston
Cambridge
Minneapolis
Seattle




Department:

Training

Sales

Marketing





ADOBE COLDFUSION 8 514
ColdFusion Developer’s Guide

Contractor? Yes









Forms guidelines
When using forms, keep the following guidelines in mind:

• To make the coding process easy to follow, name form controls the same as target database fields. For example,
if a text control corresponds to a data source FirstName field, use FirstName as the control name.
• For ease of use, limit radio buttons to between three and five mutually exclusive options. If you need more
options, consider a drop-down list.
•

Use list boxes to allow the user to choose from many options or to choose multiple items from a list.

• Check boxes, radio buttons, and list boxes do not pass data to action pages unless they are selected on a form. If
you try to reference these variables on the action page, you receive an error if they are not present. For information
on how to determine whether a variable exists on the action page, see “Testing for a variable’s existence” on page 517.
• You can dynamically populate drop-down lists using query data. For more information, see “Dynamically
populating list boxes” on page 524.

Working with action pages
When the user submits a form, ColdFusion runs the action page specified by the cfform or form tag action
attribute. A ColdFusion action page is like any other application page, except that you can use the form variables that
are passed to it from an associated form. The following sections describe how to create effective action pages.

Processing form variables on action pages
The action page gets a form variable for every form control that contains a value when the form is submitted.
Note: If multiple controls have the same name, one form variable is passed to the action page with a comma-delimited
list of values.
A form variable’s name is the name that you assigned to the form control on the form page. Refer to the form variable
by name within tags, functions, and other expressions on an action page.
On the action page, the form variables are in the Form scope, so you should prefix them with “Form.” to explicitly
tell ColdFusion that you are referring to a form variable. For example, the following code references the LastName
form variable for output on an action page:

#Form.LastName#


ADOBE COLDFUSION 8 515
ColdFusion Developer’s Guide

The Form scope also contains a list variable called Form.fieldnames. It contains a list of all form variables
submitted to the action page. If no form variables are passed to the action page, ColdFusion does not create the
Form.fieldnames list.

Using form data to generate SQL statements
As described in previous chapters, you can retrieve a record for every employee in a database table by composing a
query like the following:

SELECTFirstName, LastName, Contract
FROM Employee


When you want to return information about employees that matches user search criteria, you use the SQL WHERE
clause with a SQL SELECT statement. When the WHERE clause is processed, it filters the query data based on the
results of the comparison.
For example, to return employee data for only employees with the last name of Smith, you build a query that looks
like the following:

SELECT FirstName, LastName, Contract
FROM Employee
WHERE LastName = 'Smith'


However, instead of putting the LastName directly in the SQL WHERE clause, you can use the text that the user
entered in the form for comparison:

SELECT FirstName, LastName, Salary
FROM Employee
WHERE LastName=


For security, this example encapsulates the form variable within the cfqueryparam tag to ensure that the user passed
a valid string value for the LastName. For more information on using the cfqueryparam tag with queries and on
dynamic SQL, see “Accessing and Retrieving Data” on page 392.

Creating action pages
Use the following procedure to create an action page for the formpage.cfm page that you created in the previous
example.
Create an action page for the form
1 Create a ColdFusion page with the following content:






SELECT FirstName, LastName, Salary
FROM Employee

ADOBE COLDFUSION 8 516
ColdFusion Developer’s Guide

WHERE LastName=

Employee Data Based on Criteria from Form

#FirstName#
#LastName#
#Salary#




Contractor: #Form.Contractor#



2

Save the page as actionpage.cfm in the myapps directory.

3

View the formpage.cfm page in your browser.

4

Enter data, for example, Smith, in the Last Name box and submit the form.
The browser displays a line with the first and last name and salary for each entry in the database that match the
name you typed, followed by a line with the text “Contractor: Yes”.

5

Click Back in your browser to redisplay the form.

6

Remove the check mark from the check box and submit the form again.
This time an error occurs because the check box does not pass a variable to the action page. For information on
modifying the actionpage.cfm page to fix the error, see “Testing for a variable’s existence” on page 517.

Reviewing the code

The following table describes the highlighted code and its function:
Code

Description



Queries the data source cfdocexamples and names the query GetEmployees.

SELECT FirstName, LastName, Salary
FROM Employee
WHERE LastName=

Retrieves the FirstName, LastName, and Salary fields from the Employee table,
but only if the value of the LastName field matches what the user entered in the
LastName text box in the form on formpage.cfm.



Displays results of the GetEmployees query.

#FirstName#
#LastName#
#Salary#


Displays the value of the FirstName, LastName, and Salary fields for a record,
starting with the first record, then goes to the next line. Keeps displaying the
records that match the criteria you specified in the SELECT statement, followed
by a line break, until you run out of records.



Closes the cfoutput block.



Contractor: #Form.Contractor#


Displays a blank line followed by the text “Contractor”: and the value of the form
Contractor check box.
A more complete example would test to ensure the existence of the variable and
would use the variable in the query.

ADOBE COLDFUSION 8 517
ColdFusion Developer’s Guide

Testing for a variable’s existence
Before relying on a variable’s existence in an application page, you can test to see if it exists using the ColdFusion
IsDefined function. A function is a named procedure that takes input and operates on it. For example, the
IsDefined function determines whether a variable exists. CFML provides a large number of functions, which are
documented in the CFML Reference.
The following code prevents the error in the previous example by checking to see whether the Contractor Form
variable exists before using it:

Contractor: #Form.Contractor#


The argument passed to the IsDefined function must always be enclosed in double-quotation marks. For more
information on the IsDefined function, see the CFML Reference.
If you attempt to evaluate a variable that you did not define, ColdFusion cannot process the page and displays an
error message. To help diagnose such problems, turn on debugging in the ColdFusion Administrator. The Administrator debugging information shows which variables are being passed to your application pages.

Requiring users to enter values in form fields
One of the limitations of HTML forms is the inability to define input fields as required. Because this is a particularly
important requirement for database applications, ColdFusion lets you require users to enter data in fields. To specify
a field as required, you can do either of the following:

•

Use the required attribute of the cfinput, cfselect, cftextarea, and cftree tags.

• Use a hidden field that has a name attribute composed of the field name and the suffix _required. You can use
this technique with CFML and HTML form tags.
For example, to require that the user enter a value in the FirstName field of a cfinput tag, use the following syntax:


To require that the user enter a value in the FirstName field of an HTML input tag, use the following syntax:



In either of these examples, if the user leaves the FirstName field empty, ColdFusion rejects the form submittal and
returns a message informing the user that the field is required. You can customize the contents of this error message.
If you use a required attribute, you customize the message by using the message attribute, as follows:


If you use a hidden field tag, you customize the message using the value attribute of the hidden field, as follows:


Form variable notes and considerations
When using form variables in an action page, keep the following guidelines in mind:

•

A form variable is available on the action page and pages that it includes.

•

Prefix form variables with "Form." when referencing them on the action page.

ADOBE COLDFUSION 8 518
ColdFusion Developer’s Guide

•

Surround variable values with number signs (#) for output.

• Variables for check boxes, radio buttons, and list boxes with size attributes greater than 1 only get passed to the
action page if you select an option. Text boxes, passwords, and textarea fields pass an empty string if you do not enter
text.
•

An error occurs if the action page tries to use a variable that was not passed.

• If multiple controls have the same name, one form variable is passed to the action page with a comma-delimited
list of values.
•

You can validate form variable values on the client or the server.

Working with queries and data
The ability to generate and display query data is one of the most important and flexible features of ColdFusion. The
following sections describe more about using queries and displaying their results. Some of these tools are effective
for presenting any data, not just query results.

Using HTML tables to display query results
You can use HTML tables to specify how the results of a query appear on a page. To do so, you put the cfoutput tag
inside the table tags. You can also use the HTML th tag to put column labels in a header row. To create a row in the
table for each row in the query results, put the tr block inside the cfoutput tag.
In addition, you can use CFML functions to format individual pieces of data, such as dates and numeric values.
Put the query results in a table
1 Open the ColdFusion actionpage.cfm page in your editor.
2

Modify the page so that it appears as follows:






SELECT FirstName, LastName, Salary
FROM Employee
WHERE LastName=

Employee Data Based on Criteria from Form



ADOBE COLDFUSION 8 519
ColdFusion Developer’s Guide



First Name
Last Name
Salary


#FirstName#
#LastName#
#Salary#





Contractor: #Form.Contractor#




3

Save the page as actionpage.cfm in the myapps directory.

4

View the formpage.cfm page in your browser.

5

Enter Smith in the Last Name text box and submit the form.
The records that match the criteria specified in the form appear in a table.

Reviewing the code

The following table describes the highlighted code and its function:
Code

Description



Puts data into a table.



In the first row of the table, includes three columns, with the headings: First Name, Last
Name, and Salary.



Tells ColdFusion to display the results of the GetEmployees query.



For each record in the query, creates a new row in the table, with three columns that display
the values of the FirstName, LastName, and Salary fields of the record.



Ends the output region.

First Name
Last Name
Salary

#FirstName#
#LastName#
#Salary#



Ends the table.

Formatting individual data items
You can format individual data items. For example, you can format the salary data as monetary values. To format the
salary data using the dollar format, you use the CFML function DollarFormat(number).
Change the format of the Salary
1 Open the file actionpage.cfm in your editor.
2

Change the following line:
#Salary#

to
#DollarFormat(Salary)#

3

Save the page.

ADOBE COLDFUSION 8 520
ColdFusion Developer’s Guide

Building flexible search interfaces
One option with forms is to build a search based on the form data. For example, you could use form data as part of
the WHERE clause to construct a database query.
To give users the option to enter multiple search criteria in a form, you can wrap conditional logic around a SQL
AND clause as part of the WHERE clause. The following action page allows users to search for employees by
department, last name, or both.
Note: ColdFusion provides the Verity search utility that you can also use to perform a search. For more information, see
“Building a Search Interface” on page 459.
Build a more flexible search interface
1 Open the ColdFusion actionpage.cfm page in your editor.
2

Modify the page so that it appears as follows:






SELECT Departmt.Dept_Name,
Employee.FirstName,
Employee.LastName,
Employee.StartDate,
Employee.Salary
FROM Departmt, Employee
WHERE Departmt.Dept_ID = Employee.Dept_ID

AND Departmt.Dept_Name=


AND Employee.LastName=


Employee Data Based on Criteria from Form



First Name
Last Name
Salary


#FirstName#
#LastName#
#Salary#






3

Save the file.

4

View the formpage.cfm page in your browser.

ADOBE COLDFUSION 8 521
ColdFusion Developer’s Guide

5

Select a department, optionally enter a last name, and submit the form.

Reviewing the code

The following table describes the highlighted code and its function:
Code

Description

SELECT Departmt.Dept_Name,
Employee.FirstName,
Employee.LastName,
Employee.StartDate,
Employee.Salary
FROM Departmt, Employee
WHERE Departmt.Dept_ID =
Employee.Dept_ID

Retrieves the fields listed from the Departmt and Employee tables, joining the
tables based on the Dept_ID field in each table.


AND Departmt.Dept_Name =



If the user specified a department on the form, only retrieves records where the
department name is the same as the one that the user specified. You must use
number signs (#) in the SQL AND statement to identify Form.Department as a
ColdFusion variable, but not in the IsDefined function.


AND Employee.LastName = 


If the user specified a last name in the form, only retrieves the records in which
the last name is the same as the one that the user entered in the form.

Returning results to the user
When you return your results to the user, you must make sure that your pages respond to the user’s needs and are
appropriate for the type and amount of information. In particular, you must consider the following situations:

•

When there are no query results

•

When you return partial results

Handling no query results
Your code must accommodate the cases in which a query does not return any records. To determine whether a search
has retrieved records, use the RecordCount query variable. You can use the variable in a conditional logic expression
that determines how to display search results appropriately to users.
Note: For more information on query variables, including RecordCount, see “Accessing and Retrieving Data” on
page 392.
For example, to inform the user when no records were found by the GetEmployees query, insert the following code
before displaying the data:

No records match your search criteria. 



You must do the following:

•

Prefix RecordCount with the query name.

•

Add a procedure after the cfif tag that displays a message to the user.

•

Add a procedure after the cfelse tag to format the returned data.

ADOBE COLDFUSION 8 522
ColdFusion Developer’s Guide

•

Follow the second procedure with a  tag end to indicate the end of the conditional code.

Return search results to users
1 Edit the actionpage.cfm page.
2

Change the page so that it appears as follows:






SELECT Departmt.Dept_Name,
Employee.FirstName,
Employee.LastName,
Employee.StartDate,
Employee.Salary
FROM Departmt, Employee
WHERE Departmt.Dept_ID = Employee.Dept_ID

AND Departmt.Dept_Name = 


AND Employee.LastName = 



No records match your search criteria. 

Please go back to the form and try again.

Employee Data Based on Criteria from Form



First Name
Last Name
Salary


#FirstName#
#LastName#
#Salary#







3

Save the file.

4

Return to the form, enter search criteria, and submit the form.

5

If no records match the criteria you specified, the message appears.

ADOBE COLDFUSION 8 523
ColdFusion Developer’s Guide

Returning results incrementally
You can use the cfflush tag to incrementally display long-running requests to the browser before a ColdFusion
page is fully processed. This tag lets you give the user quick feedback when it takes a long time to complete processing
a request. For example, when a request takes time to return results, you can use the cfflush tag to display the
message, “Processing your request -- please wait.” You can also use it to incrementally display a long list as it gets
retrieved.
The first time you use the cfflush tag on a page, it sends to the browser all of the HTML headers and any other
available HTML. Subsequent cfflush tags on the page send only the output that ColdFusion generated after the
previous flush.
You can specify an interval attribute to tell ColdFusion to flush the output each time that at least the specified
number of bytes become available. (The count does not include HTML headers and any data that is already available
when you make this call.) You can use the cfflush tag in a cfloop tag to incrementally flush data as it becomes
available. This format is particularly useful when a query responds slowly with large amounts of data.
When you flush data, make sure that a sufficient amount of information is available, because some browsers might
not respond if you flush only a very small amount. Similarly, if you use an interval attribute, set it for a reasonable
size, such as a few hundred bytes or more, but not many thousands of bytes.
Limitations of the cfflush tag: Because the cfflush tag sends data to the browser when it executes, it has several
limitations, including the following:

• Using any of the following tags or functions on a page anywhere after the cfflush tag can cause errors or
unexpected results: cfcontent, cfcookie, cfform, cfheader, cfhtmlhead, cflocation, and SetLocale. (These
tags and functions normally modify the HTML header, but cannot do so after a cfflush tag, because the cfflush
tag sends the header.)
• Using the cfset tag to set a cookie anywhere on a page that has a cfflush tag does not set the cookie in the
browser.
• Using the cfflush tag within the body of several tags, including cfsavecontent, cfqueryparam, and custom
tags, can cause errors.
• If you save Client variables as cookies, any client variables that you set after a cfflush tag are not saved in the
browser.
• You can catch cfflush errors, except Cookie errors, with a cfcatch type="template" tag. Catch cookie
errors with a cfcatch type="Any" tag.
Example: using the cfloop tag and Rand function

The following example uses the cfloop tag and the Rand random number generating function to artificially delay
the generation of data for display. It simulates a situation in which it takes time to retrieve the first data and additional
information becomes available slowly.





Your Magic numbers
It will take us a little while to calculate your ten magic numbers.
It takes a lot of work to find numbers that truly fit your personality.
So relax for a minute or so while we do the hard work for you.
We are sure you will agree it was worth the short wait!


ADOBE COLDFUSION 8 524
ColdFusion Developer’s Guide












Magic number #Myindex# is:  #RandRange(
100000, 999999)#






Reviewing the code

The following table describes the code and its function:
Code

Description

We are sure you will agree it was worth
the short wait!


Sends the HTML header and all HTML output to the cfflush tag to the user. This
displays the explanatory paragraph and H2 tag contents.



Flushes additional data to the user whenever at least 10 bytes are available.





Inserts an artificial delay by using the Rand function to calculate many random
numbers.






Magic number #Myindex#
is:  #RandRange
(100000,999999)#





Generates and displays 10 random numbers. This code uses two loops. The outer
loop repeats ten times, once for each number to display. The inner loop uses the
Rand function to create another delay by generating more (unused) random
numbers. It then calls the RandRange function to generate a six-digit random
number for display.

Dynamically populating list boxes
The code in “Creating a basic form” on page 512 hard-coded the form’s list box options. Instead of manually entering
the information on a form, you can dynamically populate a list box with database fields. When you write code this
way, the form page automatically reflects the changes that you make to the database.
You use two tags to dynamically populate a list box:

•

Use the cfquery tag to retrieve the column data from a database table.

•

Use the cfselect tag with the query attribute to dynamically populate the options of this form control.

ADOBE COLDFUSION 8 525
ColdFusion Developer’s Guide

Dynamically populate a list box
1 Open the formpage.cfm page.
2

Modify the file so that it appears as follows:






SELECT DISTINCT Location
FROM Departmt





First Name: 

Last Name: 

Salary: 


City


Select All



Department:



value="Training">Training

value="Sales">Sales

value="Marketing">Marketing

value="HR">HR




Contractor? Yes









3

Save the page as formpage.cfm.

4

View the formpage.cfm page in a browser.

ADOBE COLDFUSION 8 526
ColdFusion Developer’s Guide

The changes that you just made appear in the form.
Remember that you need an action page to submit values.
Reviewing the code

The following table describes the highlighted code and its function:
Code

Description


SELECT DISTINCT Location
FROM Departmt


Gets the locations of all departments in the Departmt table.
The DISTINCT clause eliminates duplicate location names
from the returned query results.



Sets the optsize variable to the number of entries to add
dynamically to the selection list, plus one for the manually
coded Select All option.


Select All


Populates the City selection list from the Location column of
the GetDepartments query. The control has one option for
each row returned by the query.
Adds an option that allows users to select all locations. If the
user selects this option, the form value is an empty string. The
action page must check for the empty string and handle it
appropriately.

Creating dynamic check boxes and multiple-selection
list boxes
When an HTML or CFML form contains a list of check boxes with the same name or a multiple-selection list box
(that is, a box in which users can select multiple items from the list), the user’s entries are made available as a commadelimited list with the selected values. These lists can be very useful for a wide range of input types.
Note: If the user does not select a check box or make a selection from a list box, no variable is created. The cfinput and
cfupdate tags do not work correctly if there are no values. To prevent errors, make the form fields required, use dynamic
SQL, or use the cfparam tag to set a default value for the form field.

Check boxes
When you put a series of check boxes with the same name in a form, the variable that is created contains a commadelimited list of values. The values can be either numeric values or alphanumeric strings. These two types of values
are treated slightly differently.
Handling numeric values

Suppose you want a user to select one or more departments using check boxes. You then query the database to
retrieve detailed information on the selected department(s). The code for a simple set of check boxes that lets the
user select departments looks like the following:

Training


Marketing


HR


Sales



The user sees the name of the department, but the value attribute of each check box is a number that corresponds
to the underlying database primary key for the department’s record.
If the user checks the Marketing and Sales items, the value of the SelectedDepts form field is 2,4 and you use the
SelectedDepts value in the following SQL statement:
SELECT *
FROM Departmt
WHERE Dept_ID IN ( #Form.SelectedDepts# )

The ColdFusion server sends the following statement to the database:
SELECT *
FROM Departmt
WHERE Dept_ID IN ( 2,4 )
Handling string values

To search for a database field that contains string values (instead of numeric), you must modify the checkbox and
cfquery syntax to make sure that the string values are sent to the data source in single-quotation marks (').
The first example searched for department information based on a numeric primary key field called Dept_ID.
Suppose, instead, that the primary key is a database field called Dept_Name that contains string values. In that case,
your code for check boxes should look like the following:

Training


Marketing


HR


Sales


If the user checked Marketing and Sales, the value of the SelectedDepts form field would be the list Marketing,Sales
and you use the following SQL statement:

ADOBE COLDFUSION 8 528
ColdFusion Developer’s Guide

SELECT *
FROM Departmt
WHERE Dept_Name IN
(#ListQualify(Form.SelectedDepts,"'")#)

In SQL, all strings must be surrounded in single-quotation marks. The ListQualify function returns a list with the
specified qualifying character (here, a single-quotation mark) around each item in the list.
If you select the second and fourth check boxes in the form, the following statement gets sent to the database:
SELECT *
FROM Departmt
WHERE Dept_Name IN ('Marketing','Sales')

Multiple selection lists
A multiple-selection list box is defined by a select or cfselect tag with a multiple or multipe="yes" attribute
and a size attribute value greater than 1. ColdFusion treats the result when a user selects multiple choices from a
multiple-selection list box like the results of selecting multiple check boxes. The data made available to your page
from any multiple-selection list box is a comma-delimited list of the entries selected by the user; for example, a list
box could contain the four entries: Training, Marketing, HR, and Sales. If the user selects Marketing and Sales, the
form field variable value is Marketing,Sales.
You can use multiple-selection lists to search a database in the same way that you use check boxes. The following
sections describe how you can use different types of multiple-selection data values.
Handling numeric values

Suppose you want the user to select departments from a multiple-selection list box. The query retrieves detailed
information on the selected department(s), as follows:
Select one or departments to get more information on:

Training
Marketing
HR
Sales


If the user selects the Marketing and Sales items, the value of the SelectDepts form field is 2,4. If this parameter is
used in the following SQL statement:
SELECT *
FROM Departmt
WHERE Dept_ID IN (#form.SelectDepts#)

The following statement is sent to the database:
SELECT *
FROM Departmt
WHERE Dept_ID IN (2,4)
Handling string values

Suppose you want the user to select departments from a multiple-selection list box. The database search field is a
string field. The query retrieves detailed information on the selected departments, as follows:

Training
Marketing
HR

ADOBE COLDFUSION 8 529
ColdFusion Developer’s Guide

Sales


If the user selects the Marketing and Sales items, the SelectDepts form field value is Marketing,Sales.
Just as you did when using check boxes to search database fields containing string values, use the ColdFusion
ListQualify function with multiple-selection list boxes:
SELECT *
FROM Departmt
WHERE Dept_Name IN (#ListQualify(Form.SelectDepts,"'")#)

The following statement is sent to the database:
SELECT *
FROM Departmt
WHERE Dept_Name IN ('Marketing','Sales')

530

Chapter 30: Building Dynamic Forms
with cfform Tags
You can use the cfform tag to create rich, dynamic forms with sophisticated graphical controls, including several
Java applet or Flash controls. You can use these controls without writing a line of Java or Flash code.
Contents

Creating custom forms with the cfform tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
Building tree controls with the cftree tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
Building drop-down list boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539
Building slider bar controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
Creating data grids with the cfgrid tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
Embedding Java applets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551

Creating custom forms with the cfform tag
The cfform tag and its CFML subtags let you create dynamic forms in three formats:
HTML: Generates standard HTML tags wherever possible, and uses applets or Flash for more complex controls,
such as grids, trees, and calendars. HTML format lets you present a familiar appearance, but does not let you easily
separate data and presentation, or provide some of the more complex structures, such as Flash tabbed navigators or
accordions, or customized XML controls.
Flash: Presents a modern, visually pleasing appearance. Flash format supports several controls, such as tabbed
navigators and accordions, that are not available in HTML format. Flash forms are also browser-independent. In
Flash format, Flash Player works in all commonly used browsers on Windows and Macintosh systems, and in
Netscape and Mozilla on Linux.
XML: Lets you specify an Extensible Stylesheet Language Transformation (XSLT) skin that converts the XML into
styled HTML output. ColdFusion provides several skins that you can use, and you can write your own custom skins
and support custom controls.
The cfform tag and its subtags also provide you with several methods for validating input data. For example, you
can perform the validation on the browser or on the server. You can check the data type, or you can mask data input.
Individual cfform tags have additional dynamic features. Several of the tags do not have HTML counterparts, and
others directly support dynamically populating the control from data sources. Also, the cfform tag preservedata
attribute retains user input in a form after the user submits the form, so the data reappears if the form gets redisplayed.
This chapter describes features of the cfform tag and focuses on using several of the cfform child tags that do not
have HTML counterparts. The following chapters describe other features of ColdFusion forms that you create using
the cfform tag:

•

“Validating Data” on page 553

•

“Creating Forms in Flash” on page 576

ADOBE COLDFUSION 8 531
ColdFusion Developer’s Guide

•

“Creating Skinnable XML Forms” on page 594

The cfform controls
The following table describes the ColdFusion controls that you use in forms created using the cfform tag. You can
use these tags only inside a cfform tag. Unless otherwise stated, these controls are supported in HTML, Flash, and
XML skinable forms.
Control

Description

For more information

cfapplet

Embeds a custom Java applet in the form. Not supported in Flash
format forms.

“Embedding Java applets” on page 551.

cfcalendar

Displays an interactive Flash calendar that can be included in an HTML The cfcalendar tag in the CFML Reference
or Flash format form. ignored in XML skinable forms. The calendar lets
a user select a date for submission as a form variable.

cfform

Creates a container control for organizing and formatting multiple
“Creating Forms in Flash” on page 576,
form controls. Used in the cfform tag body of Flash and XML skinable “Creating Skinnable XML Forms” on
forms. Ignored in HTML forms.
page 594

cfformitem

“Creating Forms in Flash” on page 576,
Inserts a horizontal line, a vertical line, or formatted or unformatted
text in a Flash form. Used in the cfform or cfformgroup tag body for “Creating Skinnable XML Forms” on
Flash and XML forms. Ignored in HTML forms.
page 594

cfgrid

Creates a Java applet or Flash data grid that you can populate from a
query or by defining the contents of individual cells. You can also use
grids to insert, update, and delete records from a data source.

“Creating data grids with the cfgrid tag” on
page 541

cfinput

Equivalent to the HTML input tag, with the addition of input validation.

“Creating a basic form” on page 512

cfselect

Displays a selection box. Equivalent to the HTML select tag, with the “Building drop-down list boxes” on
addition of input validation.
page 539

cfslider

Creates a Java applet-based control that lets users enter data by
moving a slider. Not supported in Flash format forms.

cftextarea

Displays a text input area. Equivalent to the HTML textarea tag, with The cftree tag in the CFML Reference
the addition of input validation.

cftree

Creates a Java applet or Flash hierarchical tree-format control that can “Building tree controls with the cftree tag”
include graphical images for the different elements. Can also generate on page 532
a ColdFusion structure that represents the tree data and attributes.

“Building slider bar controls” on page 540

Preserving input data with the preservedata attribute
The cfform preservedata attribute tells ColdFusion to continue displaying the user data in a form after the user
submits the form. Data is preserved in the cfinput, cfslider, cftextinput, and cftree controls and in
cfselect controls populated by queries. If you specify a default value for a control, and a user overrides that default
in the form, the user input is preserved.
You can retain data on the form when the same page contains the form and the form’s action code; that is, the form
submits to itself. You can also retain the data if the action page has a copy of the form, and the control names are the
same in the forms on both pages. (The action page form does not need to be identical to the initial form. It can have
more or fewer elements than the initial page form; only the form elements with identical names on both pages keep
their data.)
Note: The preservedata setting on the action page controls the preservation of the data.

ADOBE COLDFUSION 8 532
ColdFusion Developer’s Guide

For example, if you save this form as preserve.cfm, it continues to display any text that you enter after you submit it,
as follows:

Please enter your name:

 

Usage notes for the preservedata attribute

When you use the preservedata attribute, follow these guidelines:

• In the cftree tag, the preservedata attribute causes the tree to expand to the previously selected element. For
this to work correctly, you must also set the completePath attribute to True.
• The preservedata attribute has no effect on a cfgrid tag. If you populate the control from a query, you must
update the data source with the new data (typically by using a cfgridupdate tag) before redisplaying the grid. The
grid then displays the updated database information.

Browser considerations
The applet-based versions of the cfgrid, cfslider, and cftree forms use JavaScript and Java to display their
content. To allow them to display consistently across a variety of browsers, these applets use the Java plug-in. As a
result, they are independent of the level of Java support provided by the browser.
ColdFusion downloads and installs the browser plug-in if necessary. Some browsers display a single permission
dialog box asking you to confirm the plug-in installation. Other browsers, particularly older versions of Netscape,
require you to navigate some simple option windows.
Because the controls use JavaScript to return data to ColdFusion, if you disable JavaScript in your browser, it cannot
properly run forms that contain these controls. In that case, the controls still display, but data return and validation
does not work and you can receive a JavaScript error.
Because Java is handled by the plug-in and not directly by the browser, disabling Java execution in the browser does
not affect the operation of the controls. If for some other reason, however, the browser is unable to render the
controls as requested, a "not supported" message appears in place of the control.
You can use the cfform tag’s notsupported attribute to specify an alternative error message.
You can avoid browser Java and JavaScript issues with the cfgrid and cftree controls by using the Flash format
versions of these controls. These controls work on Windows, Mac OS X, and Linux, and do not rely on Java support.
There is no Flash format version of the cfslider control, and there is no applet format version of the cfcalendar
control.

Building tree controls with the cftree tag
The cftree tag lets you display hierarchical information within a form in a space-saving collapsible tree populated
from data source queries. To build a tree control with the cftree tag, you use individual cftreeitem tags to
populate the control..
You can create trees in three formats:

ADOBE COLDFUSION 8 533
ColdFusion Developer’s Guide

Applet: Creates a Java applet that the client must download. Downloading an applet takes time; therefore, using the
cftree tag can be slightly slower than using an HTML form element to retrieve the same information. In addition,
browsers must be Java-enabled for the cftree tag to work properly.
Flash: Generates a Flash control that you can include in an HTML or Flash format form. For more information on
Flash Format see “Creating Forms in Flash” on page 576.
Object: Creates a hierarchical ColdFusion structure that represents the tree data and many of the cftree and
cftreeitem attributes.
The different formats support different sets of features and attributes. This section discusses general techniques that
apply to all three formats, and indicates any techniques that do not apply to a specific format. It uses applet format
for all examples, which use applet-specific attributes. For details on the features and attributes supported in each
format, see the cftree entry in the CFML Reference.
Create and populate a tree control from a query
1 Create a ColdFusion page with the following content:

SELECT FirstName || ' ' || LastName AS FullName
FROM Employee







2

Save the page as tree1.cfm and view it in your browser.
The following image shows the output of this CFML page:

Reviewing the code

The following table describes the highlighted code and its function:

ADOBE COLDFUSION 8 534
ColdFusion Developer’s Guide

Code

Description



SELECT Dept_ID, FirstName || ' ' || LastName
AS FullName
FROM Employee
ORDER BY Dept_ID












2

Save the page and view it in your browser. It should look as follows

ADOBE COLDFUSION 8 535
ColdFusion Developer’s Guide

Reviewing the code

The following table describes the highlighted code and its function
:

Code

Description

ORDER BY Dept_ID

Orders the query results by department.


SELECT Dept_ID, FirstName || ' ' || LastName
AS FullName
FROM Employee
ORDER BY Dept_ID




img="folder,document">





Creating a multilevel tree control

The following image shows an example of a multilevel tree control:

ADOBE COLDFUSION 8 537
ColdFusion Developer’s Guide

When populating a cftree control, you create the multilevel structure of the tree by specifying a parent for each
item in the tree. The parent attribute of the cftreeitem tag allows your cftree tag to show relationships between
elements in the tree.
In this example, every cftreeitem tag, except the top level Divisions, specifies a parent. For example, the
cftreeitem value="Development" tag specifies Divisions as its parent.
The following code populates the tree directly, not from a query:





















Image names in a cftree tag
Note: This section applies to applet format trees. In Flash format, you cannot control the tree icons. Flash format uses
open and closed folders and documents as the icons. In object format, the image information is preserved in fields in the
object structure.
The default image displayed in a tree is a folder. However, you can use the img attribute of the cftreeitem tag to
specify a different image.

ADOBE COLDFUSION 8 538
ColdFusion Developer’s Guide

When you use the img attribute, ColdFusion displays the specified image beside the tree items when they are not
open. When you use the imgopen attribute, ColdFusion displays the specified image beside the tree items when they
are open (expanded). You can specify a built-in ColdFusion image name, the file path to an image file, or the URL
of an image of your choice, such as http://localhost/Myapp/Images/Level3.gif. You cannot use a custom image in
Flash format. As a general rule, make the height of your custom images less than 20 pixels.
When populating a cftree control with data from a cfquery tag, you can use the img attribute of cftreeitem tag
to specify images or filenames for each level of the tree as a comma-separated list.
The following are the ColdFusion built-in image names:

•

computer

•

document

•

element

•

folder

•

floppy

•

fixed

•

remote

Note: In applet format, you can also control the tree appearance by using the cftree tag lookAndFeel attribute to
specify a Windows, Motif, or Metal look.

Embedding URLs in a cftree tag
The href attribute in the cftreeitem tag lets you designate tree items as links. To use this feature in a cftree
control, you define the destination of the link in the href attribute of the cftreeitem tag. The URL for the link can
be a relative URL or an absolute URL, as in the following examples.
Embed links in a cftree control
1 Create a ColdFusion page named tree3.cfm with the following contents:








2

Save the page and view it in your browser.

ADOBE COLDFUSION 8 539
ColdFusion Developer’s Guide

The following image shows the output of this code:

Reviewing the code

The following table describes the highlighted code and its function:
Code

Description

href="http://www.adobe.com">

Makes the node of the tree a link.

href="http://www.
adobe.com/devnet/mx/coldfusion/">

Makes the node of the tree a link.
Although this example does not show it, the href attribute can refer to the name of a
column in a query if that query populates the tree item.

Specifying the tree item in the URL
When a user clicks on a tree item to link to a URL, the cftreeItemKey variable, which identifies the selected value,
is appended to the URL in the following form:
http://myserver.com?CFTREEITEMKEY=selected_item_value_attribute

If the value attribute includes spaces, ColdFusion replaces the spaces with plus characters (+).
Automatically passing the name of the selected tree item as part of the URL makes it easy to implement a basic “drill
down” application that displays additional information based on the selection. For example, if the specified URL is
another ColdFusion page, it can access the selected value as the variable URL.CFTREEITEMKEY.
To disable this behavior, set the appendkey attribute in the cftree tag to no.

Building drop-down list boxes
The drop-down list box that you can create in a cfform tag with a cfselect tag is similar to the HTML select tag.
However, the cfselect tag gives you more control over user inputs, provides error handling, and, most importantly,
lets you automatically populate the selection list from a query.
You can populate the drop-down list box from a query, or using lists of option elements created by the option tag.
The syntax for the option tag with the cfselect tag is the same as for the HTML option tag.
When you populate a cfselect tag with data from a query, you only need to specify the name of the query that is
supplying data for the cfselect tag and the query column name for each list element to display.
Populate a drop-down list box with query data using the cfselect tag
1 Create a ColdFusion page with the following content:

SELECT * FROM Employee



ADOBE COLDFUSION 8 540
ColdFusion Developer’s Guide







2

Save the file as selectbox.cfm and view it in your browser.
The following image shows the output of this code:

Because the tag includes the multiple attribute, the user can select multiple entries in the list box. Also, because the
value tag specifies Emp_ID, the primary key for the Employee table, Employee IDs (not first names) get passed in
the Form.Employee variable to the application page specified in the cfform action attribute.
You can use a query to create a two-level hierarchical list grouped by one of the query columns. For an example of
this use, see the example for the cfselect entry in the CFML Reference.

Building slider bar controls
You can use the cfslider control in a cfform tag to create a slider control and define a variety of characteristics,
including label text, label font name, size, boldface, italics, and color, and slider range, positioning, and behavior.
Slider bars are useful because they are highly visual and users can only enter valid values. The cfslider tag is not
supported in Flash format forms.
Create a slider control
1 Create a ColdFusion page with the following content:




2

Save the file as slider.cfm and view it in your browser.

ADOBE COLDFUSION 8 541
ColdFusion Developer’s Guide

The following image shows the output of this code:

To get the value of the slider in the action page, use the variable Form.slider_name; in this case, Form.myslider.

Creating data grids with the cfgrid tag
The cfgrid tag creates a cfform grid control that resembles a spreadsheet table and can contain data populated
from a cfquery tag or from other sources of data. As with other cfform tags, the cfgrid tag offers a wide range of
data formatting options, as well as the option of validating user selections with a JavaScript validation script.
You can also perform the following tasks with a cfgrid tag:

•

Sort data in the grid alphanumerically.

•

Update, insert, and delete data.

•

Display images in the grid.

Note: Flash format grids support a subset of the features available in applet format grids. For details on features
supported in each format, see the cfgrid tag in the CFML Reference.
Users can sort the grid entries in ascending order by double-clicking any column header. Double-clicking again sorts
the grid in descending order. In applet format, you can also add sort buttons to the grid control.
When users select grid data and submit the form, ColdFusion passes the selection information as form variables to
the application page specified in the cfform action attribute.
Just as the cftree tag uses the cftreeitem tag, the cfgrid tag uses the cfgridcolumn and cfgridrow tags. You
can define a wide range of row and column formatting options, as well as a column name, data type, selection
options, and so on. You use the cfgridcolumn tag to define individual columns in the grid or associate a query
column with a grid column.
Use the cfgridrow tag to define a grid that does not use a query as the source for row data. If a query attribute is
specified in the cfgrid tag, the cfgridrow tags are ignored.
The cfgrid tag provides many attributes that control grid behavior and appearance. This chapter describes only the
most important of these attributes. For detailed information on these attributes, see the cfgrid tag in the CFML
Reference.

Working with a data grid and entering data
The following image shows an example applet format grid created using a cfgrid tag:

ADOBE COLDFUSION 8 542
ColdFusion Developer’s Guide

The following table describes some navigating tips:
Action

Procedure

Sorting grid rows

Double-click the column header to sort a column in ascending order. Double-click again to sort the
rows in descending order.

Rearranging columns

Click any column heading and drag the column to a new position.

Determining editable grid areas

When you click an editable cell, it is surrounded by a yellow box.

Determining noneditable grid areas

When you click a cell (or row or column) that you cannot edit, its background color changes. The
default color is salmon pink.

Editing a grid cell

Double-click the cell. You must press Return when you finish entering the data.

Deleting a row

Click any cell in the row and click the Delete button. (Not available in Flash format grids.)

Inserting a row

Click the Insert button. An empty row appears at the bottom of the grid. To enter a value in each
cell, double-click the cell, enter the value, and click Return. (Not available in Flash format grids.)

Populate a grid from a query
1 Create a new ColdFusion page named grid1.cfm with the following contents:

SELECT * FROM Employee












Note: Use the cfgridcolumn display="No" attribute to hide columns that you want to include in the grid but not
expose to an end user. You typically use this attribute to include columns such as the table’s primary key column in the
results returned by the cfgrid tag.

ADOBE COLDFUSION 8 543
ColdFusion Developer’s Guide

2

Save the file and view it in your browser.
The following image shows the output of this code:

Reviewing the code

The following table describes the highlighted code and its function:
Code

Description



Allows the user to select only one cell; does not allow editing. Other modes
are row, column, and edit.



Puts the contents of the Emp_ID column in the query results in the first
column of the grid.



Puts the contents of the LastName column in the query results in the second
column of the grid.



Puts the contents of the Dept_ID column in the query results in the third
column of the grid.

Creating an editable grid
You can build grids to allow users to edit data within them. Users can edit individual cell data, as well as insert,
update, or delete rows. To enable grid editing, you specify selectmode="edit" in the cfgrid tag.
You can let users add or delete grid rows by setting the insert or delete attributes in the cfgrid tag to Yes. Setting
the insert and delete attribute to Yes causes the cfgrid tag to display Insert and Delete buttons as part of the grid,
as the following image shows:

ADOBE COLDFUSION 8 544
ColdFusion Developer’s Guide

You can use a grid in two ways to make changes to your ColdFusion data sources:

• Create a page to which you pass the cfgrid form variables. In that page, perform cfquery operations to update
data source records based on the form values returned by the cfgrid tag.
• Pass grid edits to a page that includes the cfgridupdate tag, which automatically extracts the form variable
values and passes that data directly to the data source.
Using the cfquery tag gives you complete control over interactions with your data source. The cfgridupdate tag
provides a much simpler interface for operations that do not require the same level of control.
Controlling cell contents

You can control the data that a user can enter into a cfgrid cell in the following ways:

•

By default, a cell is not editable. Use the cfgrid attribute selectmode="edit" to edit cell contents.

• Use the cfgridcolumn type attribute to control sorting order, to make the fields check boxes, or to display an
image.
• Use the cfgridcolumn values attribute to specify a drop-down list of values from which the user can choose.
You can use the valuesDisplay attribute to provide a list of items to display that differs from the actual values that
you enter in the database. You can use the valuesDelimiter attribute to specify the separator between values in the
values valuesDisplay lists.
• Although the cfgrid tag does not have a validate attribute, it does have an onValidate attribute that lets you
specify a JavaScript function to perform validation.
For more information on controlling the cell contents, see the attribute descriptions for the cfgridcolumn tag in the
CFML Reference.
How user edits are returned

When a user inserts or deletes a row in a grid or changes any cells in a row and submits the grid, ColdFusion creates
the following arrays as Form variables:
Array name

Description

gridname.colname

Stores the new values of inserted, deleted, or updated cells. (Entries for deleted cells contain
empty strings.)

gridname.Original.colname

Stores the original values of inserted, deleted, or updated cells.

gridname.RowStatus.Action

Stores the type of change made to the grid rows: D for delete, I for insert, or U for update.

Note: The periods in these names are not structure separators; they are part of the text of the array name.

ADOBE COLDFUSION 8 545
ColdFusion Developer’s Guide

ColdFusion creates a gridname.colname array and a gridname.Original.colname array for each column in the grid.
For each inserted, deleted, or changed row in the grid, ColdFusion creates a row in each of these arrays.
For example, the following arrays are created if you update a cfgrid tag called mygrid that consists of two
displayable columns (col1, col2) and one hidden column (col3):
Form.mygrid.col1
Form.mygrid.col2
Form.mygrid.col3
Form.mygrid.original.col1
Form.mygrid.original.col2
Form.mygrid.original.col3
Form.mygrid.RowStatus.Action

The value of the array index increments for each row that is added, deleted, or changed, and does not indicate a grid
row number. All rows for a particular change have the same index in all arrays. Unchanged rows do not have entries
in the arrays.
If the user makes a change to a single cell in col2, the following array elements contain the edit operation, the edited
cell value, and the original cell value:
Form.mygrid.RowStatus.Action[1]
Form.mygrid.col2[1]
Form.mygrid.original.col2[1]

If the user changes the values of the cells in col1 and col3 in one row and the cell in col2 in another row, the information about the original and changed values is in the following array entries:
Form.mygrid.RowStatus.Action[1]
Form.mygrid.col1[1]
Form.mygrid.original.col1[1]
Form.mygrid.col3[1]
Form.mygrid.original.col3[1]
Form.mygrid.RowStatus.Action[2]
Form.mygrid.col2[2]
Form.mygrid.original.col2[2]

The remaining cells in the arrays (for example, Form.mygrid.col2[1] and Form.mygrid.original.col2[1]) have the
original, unchanged values.
Example: editing data in a grid

The following example creates an editable grid. For code brevity, the example handles only three of the fields in the
Employee table. A more realistic example would include, at a minimum, all seven table fields. It might also hide the
contents of the Emp_ID column or display the Department name (from the Departmt table), instead of the
Department ID.
Create the editable grid
1 Create a ColdFusion page with the following content:

SELECT * FROM Employee












2

Save the file as grid2.cfm.

3

View the results in your browser.
The following image shows the output of this code:

The following sections describe how to write the handle_grid.cfm page to process user edits to the grid.

ADOBE COLDFUSION 8 547
ColdFusion Developer’s Guide

Reviewing the code

The following table describes the code and its function:
Code

Description



Populates a cfgrid control with data from the empdata query. Selecting a grid cell enables
you to edit it. You can insert and delete rows. The grid is 425 X 300 pixels and has 10 pixels of
space above and below it.



Creates a 50-pixel wide column for the data in the Emp_ID column of the data source. Centers
a header named Emp ID and makes it bold.



Creates a 100-pixel wide column for the data in the LastName column of the data source.
Centers a header named Last Name and makes it bold.




Creates a 35-pixel wide column for the data in the Dept_ID column of the data source.
Centers a header named Dept and makes it bold.

Does not allow users to select fields in this column for editing. Since this field is the table’s
primary key, users should not be able to change it for existing records, and the DBMS should
generate this field as an autoincrement value.

Updating the database with the cfgridupdate tag

The cfgridupdate tag provides a simple mechanism for updating the database, including inserting and deleting
records. It can add, update, and delete records simultaneously. It is convenient because it automatically handles
collecting the cfgrid changes from the various form variables, and generates appropriate SQL statements to update
your data source.
In most cases, use the cfgridupdate tag to update your database. However, this tag does not provide the complete
SQL control that the cfquery tag provides. In particular, the cfgridupdate tag has the following characteristics:

•

You can update only a single table.

• Rows are deleted first, then rows are inserted, then any changes are made to existing rows. You cannot modify
the order of changes.
• Updating stops when an error occurs. It is possible that some database changes are made, but the tag does not
provide any information on them.
Update the data source with the cfgridupdate tag
1 Create a ColdFusion page with the following contents:





Updating grid using cfgridupdate tag.

Click here to display updated grid.



2

Save the file as handle_grid.cfm.

3

View the grid2.cfm page in your browser, make changes to the grid, and then submit them.

Note: To update a grid cell, modify the cell contents, and then press Return.
Reviewing the code

The following table describes the highlighted code and its function:
Code

Description






Grid values for Form.employee_grid row updates



The row action for #counter# is:
#Form.employee_grid.rowstatus.action[counter]#





DELETE FROM Employee
WHERE Emp_ID=


ADOBE COLDFUSION 8 549
ColdFusion Developer’s Guide



UPDATE Employee
SET
LastName=,
Dept_ID=
WHERE Emp_ID=



INSERT into Employee (LastName, Dept_ID)
VALUES (,
)




Click here to display updated grid.



2 Rename your existing handle_grid.cfm file as handle_grid2.cfm to save it, and then save this file as
handle_grid.cfm.
3

View the grid2.cfm page in your browser, make changes to the grid, and then submit them.

Reviewing the code

The following table describes the code and its function:

ADOBE COLDFUSION 8 550
ColdFusion Developer’s Guide

Code

Description


nothing. Loops through the remaining code once for each row to be


of change information for the row being changed.


The row action for #counter# is:
#Form.employee_grid.rowstatus.action[counter]#




Displays the action code for this row: U for update, I for insert, or D for
delete.


fying the Emp_ID (the primary key) of the row to be deleted.

DELETE FROM Employee
WHERE Emp_ID=


query to update the LastName and Dept_ID fields for the row speci
UPDATE Employee
SET LastName=,
Dept_ID=
WHERE Emp_ID=



INSERT into Employee (LastName, Dept_ID)
VALUES (,
)


Otherwise, if the action is to insert a row, generates a SQL INSERT
query to insert the employee’s last name and department ID from the
grid row into the database. The INSERT statement assumes that the
DBMS automatically increments the Emp_ID primary key. If you use
the version of the cfdocexamples database that is provided for UNIX
installations, the record is inserted without an Emp_ID number.





Closes the cfif tag used to select among deleting, updating, and
inserting.
Closes the loop used for each row to be changed.
Closes the cfif tag that surrounds all the active code.

ADOBE COLDFUSION 8 551
ColdFusion Developer’s Guide

Embedding Java applets
The cfapplet tag lets you embed Java applets either on a ColdFusion page or in a cfform tag. To use the cfapplet
tag, you must first register your Java applet using the ColdFusion Administrator Java Applets page (under Extensions). In the ColdFusion Administrator, you define the interface to the applet, encapsulating it so that each
invocation of the cfapplet tag is very simple.
The cfapplet tag within a form offers several advantages over using the HTML applet tag:

• Return values: The cfapplet tag requires a form field name attribute, so you can avoid coding additional JavaScript to capture the applet’s return values. You can reference return values like any other ColdFusion form variable:
Form.variablename.
• Ease of use: The applet’s interface is defined in the ColdFusion Administrator, so each instance of the cfapplet
tag in your pages only needs to reference the applet name and specify a form variable name.
• Parameter defaults: ColdFusion uses the parameter value pairs that you defined in the ColdFusion Administrator. You can override these values by specifying parameter value pairs in the cfapplet tag.
When an applet is registered, you enter just the applet source and the form variable name:


By contrast, with the HTML applet tag, you must declare all the applet’s parameters every time you want to use it
in a ColdFusion page.

Registering a Java applet
Before you can use a Java applet in your ColdFusion pages, you must register the applet in the ColdFusion Administrator.
Register a Java applet
1 Open the ColdFusion Administrator by clicking the Administrator icon in the ColdFusion Program group and

entering the Administrator password.
2

Under Extensions, click Java Applets.
The Java Applets page appears.

3

Click the Register New Applet button.
The Add/Edit Applet page appears.

4 Enter options in the applet registration fields, as described in the ColdFusion Administrator online help. Use the
Add button to add parameters.
5

Click Submit.

Using the cfapplet tag to embed an applet
After you register an applet, you can use the cfapplet tag to place the applet in a ColdFusion page. The cfapplet
tag has two required attributes: appletsource and name. Because you registered the applet and you defined each
applet parameter with a default value, you can invoke the applet with a very simple form of the cfapplet tag:


ADOBE COLDFUSION 8 552
ColdFusion Developer’s Guide

Overriding alignment and positioning values

To override any of the values defined in the ColdFusion Administrator for the applet, you can use the optional
cfapplet parameters to specify custom values. For example, the following cfapplet tag specifies custom spacing
and alignment values:

Overriding parameter values

You can override the values that you assigned to applet parameters in the ColdFusion Administrator by providing
new values for any parameter. To override a parameter, you must have already defined the parameter and its default
value in the ColdFusion Administrator Applets page. The following example overrides the default values of two
parameters, Param1 and Param2:


Handling form variables from an applet
The cfapplet tag name attribute corresponds to a variable in the action page, Form.appletname, which holds any
value that the applet method returns when it is executed in the cfform tag.
Not all Java applets return values. For instance, graphical widgets might not return a specific value. For this type of
applet, the method field in the ColdFusion Administrator remains empty, but you must still provide a cfapplet
name attribute.
You can only use one method for each applet that you register. If an applet includes more than one method that you
want to access, you can register the applet with a unique name for each additional method you want to use.
Reference a Java applet return value in your application page
1 Specify the name of the method in the Add/Registered Java Applet page of the ColdFusion Administrator.
2

Specify the method name in the name attribute of the cfapplet tag.

When your page executes the applet, ColdFusion creates a form variable with the name that you specified. If you do
not specify a method, ColdFusion does not create a form variable.

553

Chapter 31: Validating Data
You can validate data in ColdFusion, including form data, variable data and function parameters.
Contents

About ColdFusion validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553
Validating form fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558
Handling invalid data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
Masking form input values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
Validating form data with regular expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562
Validating form data using hidden fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565
Validating form input and handling errors with JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569
Validating data with the IsValid function and the cfparam tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572

About ColdFusion validation
Data validation lets you control data that is entered into an application by ensuring that the data conforms to specific
type or formatting rules. Validation techniques have the following features:

• They let you provide feedback to users so that they can immediately correct information they provide. For
example, a form can provide immediate feedback when a user enters a name in a telephone number field, or the form
could force the user to enter the number in the correct format.
• They help prevent application errors that might arise when processing invalid data. For example, a validation test
can prevent a variable that is used in a calculation from having nonnumeric data.
• They can help enhance security by preventing malicious users from providing data that takes advantage of
system security weaknesses, such as buffer overrun attacks.
ColdFusion provides several techniques to ensure that data is valid. These include techniques for validating form
data and for validating ColdFusion variables. They also include techniques for validating form data before the user
submits it to ColdFusion, or on the ColdFusion server.
When you design data validation you consider the following factors:
The validation technique: Whether to validate on the client’s browser or on the server, and the specific server- or
client-side validation technique, such as whether to validate when a field loses focus or when the user submits the
form.
The validation type: The specific method that you use to validate the data, including the rules that you apply to test
the data validity, such as testing for a valid telephone number.
The following sections describe the ColdFusion validation techniques and provide information on selecting a
technique that is appropriate for your application. They also describe the validation types that ColdFusion supports.
Later sections describe particular techniques in detail.

ADOBE COLDFUSION 8 554
ColdFusion Developer’s Guide

Validation techniques
Different validation techniques apply to different ColdFusion tags or coding environments; for example, you can use
masking only in HTML and Flash format cfinput tags. Validation techniques also vary in where and when they
execute; for example, on the client browser when the user submits form data, or on the server when processing data.
The following table describes the ColdFusion validation techniques:
Validation technique

Applies to

Where and when
performed

Description

mask

HTML and Flash format
cfinput tags

On the client as the user
enters data

ColdFusion generates JavaScript or ActionScript to
directly control the data a user enters by specifying a
pattern. For example, 999-999-9999 requires a user to
enter ten digits, and automatically fills in the dash (-)
separators to create a formatted telephone number.

(mask attribute)

For detailed information on using masks, see
“Handling invalid data” on page 560.
onBlur
(validateat="onBlur"
attribute)

cfinput and
cftextarea tags

On the client when the
data field loses focus

In HTML and XML format, ColdFusion generates JavaScript that runs on the browser to check whether
entered data is valid and provide immediate feedback, if the entry is invalid.
In Flash format, uses Flash built-in validation routines.

onSubmit
(validateat="onSubmit"
attribute)

cfinput and
cftextarea tags

On the client when the
user clicks Submit

In HTML or XML format, the validation logic is identical to onBlur validation, but the test is not done until
the user submits the form.
In Flash format, this validation type is identical to
onBlur Validation. Flash checks do not differentiate
between the two events for validation.

onServer
(validateat="onServer"
attribute)
hidden field

cfinput and cftextarea

tags

All Forms, including
HTML-only forms

On the server when
ColdFusion gets the
submitted form

ColdFusion checks submitted data for validity and
runs a validation error page if the data is not valid.
You can use the cferror tag to specify the validation error page.

On the server when
ColdFusion gets the
submitted form

ColdFusion uses the same validation logic as with
onServer validation, but you must create additional,
hidden, fields and you can use this technique with
HTML tags or CFML tags.
For detailed information on using hidden fields, see
“Validating form data using hidden fields” on
page 565..

cfgrid, cfinput,
cfslider,
(onValidate ="function" cftextarea, and
attribute)
cftree tags in HTML
and XML format forms

JavaScript

On the client, when the
user clicks Submit,
before field-specific
onSubmit validation

ColdFusion includes the specified JavaScript function
in the HTML page it sends to the browser, and the
browser calls it.
For detailed information on using JavaScript for validation, see “Validating form input and handling
errors with JavaScript” on page 569..

ADOBE COLDFUSION 8 555
ColdFusion Developer’s Guide

Validation technique

Applies to

Where and when
performed

Description

IsValid function

ColdFusion variables

On the server, when the
function executes

ColdFusion tests the variable to determine whether it
follows a specified validation rule and the function
returns true or false.
For more information on using the IsValid function
for validation, see “Validating data with the IsValid
function and the cfparam tag” on page 572.

cfparam tag

ColdFusion variables

On the server, when the
tag executes

ColdFusion checks the specified variable. If the value
does not meet the validation criteria, ColdFusion
generates an expression exception.
For more information on using the cfparam tag for
validation, see, “Validating data with the IsValid function and the cfparam tag” on page 572.

cfargument tag

UDF and CFC function
arguments

On the server, when a
function is called or
invoked

ColdFusion checks the argument value when it is
passed to the function. If the value does not meet the
validation criteria, ColdFusion generates an application exception.
For more information on using the cfargument tag,
see “Writing and Calling User-Defined Functions” on
page 134.

Note: For more information on ColdFusion error handling, see “Handling Errors” on page 246.

Selecting a validation technique
The following considerations affect the validation technique that you select:

• If you are validating form data, the techniques you use can vary depending on whether you are using HTML,
Flash, or XML forms; for example, different form types have different validation limitations.
•

Different validation techniques are appropriate for different form controls and data types.

• Available techniques vary depending on when and where you want the data validated; on the client or the server,
when the user enters data or submits a form, or when ColdFusion processes a variable or function argument.
• Each technique has specific features and considerations, such as the form of user feedback, feature limitations,
and so on.
•

Security issues or concerns that apply to your environment or application can affect the technique you select.

The table in the preceding section described some of the considerations (see “Validation techniques” on page 554).
The following table describes additional considerations for selecting a validation technique. For additional considerations that are specific to form fields, see “Validation type considerations” on page 559.

ADOBE COLDFUSION 8 556
ColdFusion Developer’s Guide

Validation technique

Features

Considerations

Security issues

mask

Directly controls user input.

Limited to cfinput tags.
Provides limited control over
user input patterns.

In HTML and XML format, can be
circumvented because JavaScript
runs directly in the browser.

Provides immediate feedback
if a user enters invalid data.

Limited to cfinput and
cftextarea tags. In HTML or
XML format, requires the
browser to enable JavaScript.

In HTML and XML format, can be
circumvented because JavaScript
runs directly in the browser.

All entered data is available to
the user; only the invalid data
needs reentering.

Limited to cfinput and
In HTML and XML format, can be
cftextarea tags. In Flash
circumvented because JavaScript
format, is identical to onBlur. In runs directly in the browser.
HTML or XML format, validates
after all fields have been
entered, and requires the
browser to enable JavaScript.

Does not require browser
support.

Limited to cfinput and
cftextarea tags.

Can be circumvented because validation rules are submitted with the
form.

Hidden form field

Does not require browser
support. Can be used with
HTML or CFML form elements.

Limited to forms.

Can be circumvented because validation rules are submitted with the
form.

JavaScript

Allows all on-client processing
supported by the browser. Can
be used with HTML or CFML
form elements.

Limited to specific ColdFusion Can be circumvented because JavaSform tags. Calls a single JavaS- cript runs directly in the browser.
cript function. JavaScript levels
of support can vary among
browsers, and users can
disable JavaScript in their
browsers.

IsValid function

Can be used for any variable,
not just form fields. Returns a
Yes or No result that you use to
determine further processing.

When used with a form field,
runs after the data is
submitted. Must be used each
time a variable needs to be
validated. Provides some data
type checks not available in
forms validation techniques.

cfparam tag

Can be used for any variable,
not just form fields. The tag can
set a default value in addition
to validating data.

When used with a form field,
None
the tag runs after the data is
submitted. You respond to validation failures using errorhandling code.

cfargument tag

Used for arguments to functions written using the
cffunction tag.

Runs when the function is
called on the server. You
respond to validation failures
using error-handling code.

(mask attribute)
onBlur
(validateat="onBlur"
attribute)
onSubmit
(validateat="onSubmit"
attribute)

onServer
(validateat="onServer"
attribute)

(onValidate = "function"
attribute)

None

None

Security considerations

Although form-specific validation techniques provide good methods for preventing users from submitting invalid
or badly formatted data, they cannot prevent users from submitting maliciously formatted data from HTML forms.
Malicious users can circumvent validation techniques that require validation on the browser using JavaScript or
submission of validation rules in hidden fields. If you must use a technique for preventing malicious data submissions, consider using the following techniques:

•

The onSubmit or OnBlur validation in Flash forms, which use Flash built-in validation.

ADOBE COLDFUSION 8 557
ColdFusion Developer’s Guide

• The IsValid function and the cfparam, and cfargument tags, which let you test variables and arguments in your
CFML code.
• The cfqueryparam tag in cfquery tags, which can help protect databases from malicious query input (see
“Enhancing security with cfqueryparam” on page 398.
• The script protection option, which helps prevent cross-site scripting attacks. You can set this option on the
ColdFusion Administrator Server Settings > Settings page or by using the Application.cfc This.scriptProtect variable
or the cfapplication tag scriptprotect attribute. For more information on cross-site scripting attacks and this
option, see the cfapplication tag page in the CFML Reference.

Data validation types
The following table lists the types of data you can validate when you use most ColdFusion validation techniques. It
does not include mask validation. Some validation types are not available for all techniques; in these cases the table
indicates the limitations. The onBlur and onSubmit validation algorithms for Flash format forms might vary from
those described in the following table, and most commonly have less functionality. For more detailed descriptions
of the onServer validation algorithms, see the table in “Validating form data using hidden fields” on page 565.
Type field

Description

date

When validating on the server, allows any date/time format that returns true in the IsDate function,
including a time value. When validating on the client, same as USdate.

USdate *

A U.S. date of the format mm/dd/yy, with 1- or 2-digit days and months, and 1-through 4-digit years. The
separators can be slash (/), hyphen (-), or period (.) characters

eurodate *

A date of the format dd/mm/yy, with 1- or 2-digit days and months, and 1- through 4-digit years. The
separators can be slash (/), hyphen (-), or period (.) characters.

time *

When validating on the server, allows any date/time format that returns True in the IsDate function,
including a date value. When validating on the client, allows a time of format hh:mm[:ss] [A/PM].

float *

A number; allows integers. When validating form fields on the server, integer values are converted to real
numbers.

numeric

A number; allows integers. When validating form fields on the server, integer values are unchanged.

integer *

An integer.

range *

A numeric range specified by a range attribute or max and min attributes.

boolean

A value that can be converted to a Boolean value: Yes, No, True, or False, (all case-independent), or a
number.

telephone *

Standard U.S. telephone formats. Allows an initial 1 long-distance designator and up to 5-digit extensions, optionally starting with x.

zipcode *

U.S. 5- or 9-digit ZIP code format #####-####. The separator can be a hyphen (-) or a space.

creditcard *

Strips blanks and dashes; verifies number using mod10 algorithm. The number must have 13–16 digits.

ssn * or social_security_number * US. Social Security number format, ###-##-####. The separator can be a dash (-) or a space.
email *

A valid e-mail address of the form name@server.domain. ColdFusion validates the format only; it does
not check that entry is a valid active e-mail address.

URL *

A valid URL pattern; supports http, https, ftp file, mailto, and news URLs.

guid *

A unique identifier that follows the Microsoft/DCE format, xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, where
x is a hexadecimal number.

uuid *

A universally unique identifier (UUID) that follows the ColdFusion format, xxxxxxxx-xxxx-xxxxxxxxxxxxxxxxxxxx, where x is a hexadecimal number.

regex * or regular_expression *

Matches the value against a regular expression specified in a pattern attribute. Valid in HTML and XML
format only; ignored in Flash format.

ADOBE COLDFUSION 8 558
ColdFusion Developer’s Guide

Note: For more details on how ColdFusion handles data when it does onServer and hidden field validation, see
“Validating form data using hidden fields” on page 565.
The following validation types can only be used in cfinput tags:
Type

Description

maxlength

Limits the input to a maximum number of characters specified by a maxlength attribute.

noblanks

Does not allow fields that consist only of blanks. ColdFusion uses this validation only if the required attribute is
True.

SubmitOnce

Used only with cfform submit and image types; prevents the user from submitting the same form multiple times
before until the next page loads, Use this attribute, for example, to prevent a user from submitting an order form a
second time before getting the confirmation for the initial order, and thereby making a duplicate order, Valid in
HTML and XML format only; ignored in Flash format.

You can use the following validation types in cfparam and cfargument tags and the IsValid function only:
:

Type

Description

any

Any type of value

array

An array of values

binary

A binary value

query

A query object

string

A string value or single character

struct

A structure

variableName *

A string formatted according to ColdFusion variable naming conventions.

Validating form fields
This section describes basic validation of form fields. Later sections in this chapter describe other validation types
and techniques that you can use, including regular expression validation, masking, hidden field validation, JavaScript validation, and validation using CFML tags and functions.
In basic form field validation, you do the following:

•

Use a cfinput or cftextarea tag.

•

Specify a validation type, such as numeric, or multiple types.

•

Optionally, specify an error message.

•

Optionally, specify a validation technique. (By default, ColdFusion uses onSubmit validation.)

The following example specifies onBlur validation of a telephone number:
Phone: 

ADOBE COLDFUSION 8 559
ColdFusion Developer’s Guide

The following sections describe considerations for validation in cfinput and cftextarea tags, and show a more
complete example.

Validation type considerations
General considerations: Consider the following issues when you determine how to validate form data:

• When you validate form data using onBlur, onSubmit, onServer, or hidden form field validation, you can specify
one or more validation types for each field that you validate. For example, you can specify that a field entry is
required and that it must be numeric. To specify multiple validation types for onSubmit, onBlur, or onServer
validation, specify the type values in a comma-delimited list.
• If you use onBlur, onSubmit, or onServer type validation, you can specify only one error message for each field
that you validate. If you use hidden field validation, you can create a custom message for each validation rule (with
the exception of range checking).
•

In the cfinput tag, most validation type attributes apply only to text or password fields.

Validation algorithm differences: The underlying validation code used when validating form data can differ
depending on the validation technique and the form type. As a result, the algorithms used vary in some instances,
including the following:

• The validation algorithms used for date/time values in onSubmit and OnBlur validation are different from those
used for all server-side validation techniques.
• The algorithms used for onSubmit and OnBlur validation in Flash might vary from those used for HTML or
XML format, and generally follow simpler rules.
For detailed information on the validation algorithms used for validation techniques used on the server, see
“Validating form data using hidden fields” on page 565.

Validating data in XML skinnable forms
If you create an XML skinnable form and use any skin provided by Adobe, such as the basic.xsl or silver.xsl skin, you
can use all form validation techniques that are available for HTML forms.
If you use a custom skin (XSL file), the available validation techniques depend on the skin. The
cf_webroot\CFIDE\scripts\xsl directory contains a _cfformvalidation.xsl file that implements all ColdFusion HTML
form validation techniques and supports onBlur, onSubmit, onServer, and hidden form field validation. XML skin
writers can include this file in their skin XSLT to implement ColdFusion validation for their skin.

Example: basic form validation
The following form asks for information that might be used when registering a new user. It checks to make sure that
the user enters required information. (Only the telephone number is optional.) It also checks to make sure that the
telephone number and e-mail address are properly formatted and that the number to be used in a challenge question
is in the proper range. This example performs onSubmit validation. It posts back to itself, and dumps the submitted
results.





First Name: 


ADOBE COLDFUSION 8 560
ColdFusion Developer’s Guide

Last Name: 

Telephone: 

E-mail: 

Password:

Reenter password:

We will ask you for the following number, in the range 100-999 if you forget
your password.

Number: 




Handling invalid data
How you handle invalid data depends on the validation type. This section describes validation error-handling rules
and considerations. For detailed information on error handling in ColdFusion, including invalid data handling, see
“Handling Errors” on page 246.
For onBlur, onSubmit, or onServer validation, you can use the cfinput or cftextarea tag’s message attribute
to specify a text-only error message to display. Otherwise, ColdFusion uses a default message that includes the name
of the form field that was invalid. (For OnServer validation, you can customize this message, as described in
“Handling form field validation errors” on page 252.) The following example displays an error message when the
user enters an invalid e-mail address:

1

E-mail: 

For hidden form validation, you can specify a text-only error message in the hidden field’s value attribute.
Otherwise, ColdFusion uses a default message that includes the name of the form field that was invalid. (You can
customize this message, as described in “Handling form field validation errors” on page 252.) The following
cfinput tag, for example, uses a hidden field validation to display an error message if the user enters an invalid
address. (It uses onServer validation to display a different error message if the user fails to enter a number.)
2

Telephone: 


• For HTML and XML format forms (using ColdFusion skins), most ColdFusion form tags have an onError
attribute that lets you specify a Javascript function to run if an onSubmit error occurs.
• For the IsValid function, you write separate code paths to handle valid and invalid data. The following example
shows a simplified case that displays an error message if the user entered an invalid e-mail address, or a different
message if the address is valid:

ADOBE COLDFUSION 8 561
ColdFusion Developer’s Guide


Thank you for entering a valid address.


You must enter a valid e-mail address.

Click the Back button and try again.


3 For cfparam and cfargument tags, you use standard ColdFusion error-handling techniques. You can include
the tag in a try block and use a catch block to handle the error, or you can use a custom error-handling page. The
following example form action page code uses a custom error page, expresserr.cfm, to handle the error that the
cfparam tag generates if a user submits a form with an invalid e-mail address:






Masking form input values
The cfinput tag mask attribute controls the format of data that can be entered into a text or datefield input field.
You can also use a mask attribute in the cfcalendar tag. You can combine masking and validation on a field.

•

In HTML and Flash form format, a mask can control the format of data entered into a text field.

• In the cfcalendar tag, and, for Flash format forms, the datefield type cfinput field, a mask can control the
format of the date that ColdFusion uses for the date a user chooses in the displayed calendar.
Note: The standard ColdFusion XML skins do not support masking.

Masking text input
In text fields, ColdFusion automatically inserts literal mask characters, such as - characters in telephone numbers.
Users type only the variable part of the field. You can use the following characters to mask data:
Mask character

Effect

A

Allows an uppercase or lowercase character: A–Z and a–z.

X

Allows an uppercase or lowercase character or number: A–Z, a–z, and 0–9.

9

Allows a number: 0–9.

?

Allows any character.

All other characters

Automatically inserts the literal character.

The following pattern enforces entry of a part number of the format EB-1234-c1-098765, where the user starts the
entry by typing the first numeric character, such as 1. ColdFusion fills in the preceding EB prefix and all hyphen (-)
characters. The user must enter four numbers, followed by two alphanumeric characters, followed by six numbers.


Note: You cannot force a user to type an A, X, 9, or question mark (?) character. To ensure that a pattern is all-uppercase
or all-lowercase, use the ColdFusion UCase or LCase functions in the action page.

ADOBE COLDFUSION 8 562
ColdFusion Developer’s Guide

Masking cfcalendar and datefield input
In the cfcalendar tag and the Flash format datefield input control, you use the following masks to determine the
format of the output. You can use uppercase or lowercase characters in the mask:
Mask

Pattern

D

Single- or double-digit day of month, such as 1 or 28

DD

Double-digit day of month, such as 01 or 28

M

Single- or double-digit month, such as 1 or 12

MM

Double-digit month, such as 01 or 12

MMM

Abbreviated month name, such as Jan or Dec

MMMM

Full month name, such as January or December

YY

Two-character year, such as 05

YYYY

Four-character year, such as 2005

E

Single-digit day of week, in the range 0 (Sunday)–6 (Saturday)

EEE

Abbreviated day of week name, such as Mon or Sun

EEEE

Full month day of week name, such as Monday or Sunday

The following pattern specifies that the Flash forms sends the date selected using a datefield input control to
ColdFusion as text in the format 04/29/2004:


Validating form data with regular expressions
You can use regular expressions to match and validate the text that users enter in cfinput and cftextinput tags.
Ordinary characters are combined with special characters to define the match pattern. The validation succeeds only
if the user input matches the pattern.
Regular expressions let you check input text for a wide variety of custom conditions for which the input must follow
a specific pattern. You can concatenate simple regular expressions into complex search criteria to validate against
complex patterns, such as any of several words with different endings.
You can use ColdFusion variables and functions in regular expressions. The ColdFusion server evaluates the
variables and functions before the regular expression is evaluated. For example, you can validate against a value that
you generate dynamically from other input data or database values.
Note: The rules listed in this section are for JavaScript regular expressions, and apply to the regular expressions used in
cfinput and cftextinput tags only. These rules differ from those used by the ColdFusion functions REFind,
Replace, REFindNoCase, and REReplaceNoCase. For information on regular expressions used in ColdFusion
functions, see “Using Regular Expressions in Functions” on page 107.

Special characters
Because special characters are the operators in regular expressions, in order to represent a special character as an
ordinary one, you must escape it by preceding it with a backslash. For example, use two backslash characters (\\) to
represent a backslash character.

ADOBE COLDFUSION 8 563
ColdFusion Developer’s Guide

Single-character regular expressions
The following rules govern regular expressions that match a single character:

•

Special characters are: + * ? . [ ^ $ ( ) { | \

•

Any character that is not a special character or escaped by being preceded by a backslash (\) matches itself.

• A backslash (\) followed by any special character matches the literal character itself; that is, the backslash escapes
the special character.
•

A period (.) matches any character except newline.

• A set of characters enclosed in brackets ([]) is a one-character regular expression that matches any of the
characters in that set. For example, “[akm]” matches an a, k, or m. If you include ] (closing square bracket) in square
brackets, it must be the first character. Otherwise, it does not work, even if you use \].
•

A dash can indicate a range of characters. For example, [a-z] matches any lowercase letter.

• If the first character of a set of characters in brackets is the caret (^), the expression matches any character except
those in the set. It does not match the empty string. For example: “[^akm]” matches any character except a, k, or m.
The caret loses its special meaning if it is not the first character of the set.
• You can make regular expressions case insensitive by substituting individual characters with character sets; for
example, “[Nn][Ii][Cc][Kk]” is a case-insensitive pattern for the name Nick (or NICK, or nick, or even nIcK).
•

You can use the following escape sequences to match specific characters or character classes:

Escape

Matches

seq

Escape

Meaning

seq

[\b]

Backspace.

\s

Any of the following white space characters: space, tab,
form feed, and line feed.

\b

A word boundary, such as a space.

\S

Any character except the white space characters matched
by \s.

\B

A nonword boundary.

\t

Tab.

\cX

The control character Ctrl-x. For example, \cv
matches Ctrl-v, the usual control character for
pasting text.

\v

Vertical tab.

\d

A digit character [0-9].

\w

An alphanumeric character or underscore. The equivalent
of [A-Za-z0-9_].

\D

Any character except a digit.

\W

Any character not matched by \w. The equivalent of [^AZa-z0-9_].

\f

Form feed.

\n

Backreference to the nth expression in parentheses. See
“Backreferences” on page 564.

\n

Line feed.

\ooctal

The character represented in the ASII character table by the
specified octal number.

\r

Carriage return.

\xhex

The character represented in the ASCII character table by
the specified hexadecimal number.

Multicharacter regular expressions
Use the following rules to build a multicharacter regular expression:

ADOBE COLDFUSION 8 564
ColdFusion Developer’s Guide

• Parentheses group parts of regular expressions together into a subexpression that can be treated as a single unit.
For example, “(ha)+” matches one or more instances of ha.
• A one-character regular expression or grouped subexpression followed by an asterisk (*) matches zero or more
occurrences of the regular expression. For example, “[a-z]*” matches zero or more lowercase characters.
• A one-character regular expression or grouped subexpression followed by a plus sign (+) matches one or more
occurrences of the regular expression. For example, “[a-z]+” matches one or more lowercase characters.
• A one-character regular expression or grouped subexpression followed by a question mark (?) matches zero or
one occurrences of the regular expression. For example, “xy?z” matches either xyz or xz.
•

The carat (^) at the beginning of a regular expression matches the beginning of the field.

•

The dollar sign ($) at the end of a regular expression matches the end of the field.

• The concatenation of regular expressions creates a regular expression that matches the corresponding concatenation of strings. For example, “[A-Z][a-z]*” matches any capitalized word.
• The OR character (|) allows a choice between two regular expressions. For example, “jell(y|ies)” matches either
jelly or jellies.
• Braces ({}) indicate a range of occurrences of a regular expression. You use them in the form “{m, n}” where m
is a positive integer equal to or greater than zero indicating the start of the range and n is equal to or greater than m,
indicating the end of the range. For example, “(ba){0,3}” matches up to three pairs of the expression ba. The form
“{m,}” requires at least m occurrences of the preceding regular expression. The form “{m}” requires exactly m occurrences of the preceding regular expression. The form “{,n}” is not allowed.

Backreferences
Backreferencing lets you match text in previously matched sets of parentheses. A slash followed by a digit n (\n)
refers to the nth parenthesized subexpression.
One example of how you can use backreferencing is searching for doubled words; for example, to find instances of
“the the” or “is is” in text. The following example shows backreferencing in a regular expression:
(\b[A-Za-z]+)[ ]+\1

This code matches text that contains a word that is repeated twice; that is, it matches a word, (specified by the \b word
boundary special character and the “[A-Za-z]+)” followed by one or more spaces (specified by “[ ]+”), followed by
the first matched subexpression, the first word, in parentheses. For example, it would match “is is”, but not “This is”.

Exact and partial matches
ColdFusion validation normally considers a value to be valid if any of it matches the regular expression pattern.
Often you might want to ensure that the entire entry matches the pattern. If so, you must “anchor” it to the beginning
and end of the field, as follows:

•

If a caret (^) is at the beginning of a pattern, the field must begin with a string that matches the pattern.

•

If a dollar sign ($) is at the end of a pattern, the field must end with a string that matches the pattern.

•

If the expression starts with a caret and ends with a dollar sign, the field must exactly match the pattern.

Expression examples
The following examples show some regular expressions and describe what they match:

ADOBE COLDFUSION 8 565
ColdFusion Developer’s Guide

Expression

Description

[\?&]value=

Any string containing a URL parameter value.

^[A-Z]:(\\[A-Z0-9_]+)+$

An uppercase Windows directory path that is not the root of a drive and has only letters,
numbers, and underscores in its text.

^(\+|-)?[1-9][0-9]*$

An integer that does not begin with a zero and has an optional sign.

^(\+|-)?[1-9][0-9]*(\.[0-9]*)?$

A real number.

^(\+|-)?[1-9]\.[0-9]*E(\+|-)?[0-9]+$

A real number in engineering notation.

a{2,4}

A string containing two to four occurrences of a: aa, aaa, aaaa; for example, aardvark, but not
automatic.

(ba){2,}

A string containing least two ba pairs; for example, Ali baba, but not Ali Baba.

Note: An excellent reference on regular expressions is Mastering Regular Expressions by Jeffrey E.F. Friedl, published
by O'Reilly & Associates, Inc.

Validating form data using hidden fields
ColdFusion lets you specify form field validation on the server by using hidden form fields whose names consist of
the name of the field to validate and the validation type. Hidden field validation uses the same underlying techniques
and algorithms as onServer validation of ColdFusion form fields.
Hidden field validation has the following features:

• You can use it with standard HTML tags. For example, you can validate data in an HTML input tag. This feature
was particularly useful in releases prior to ColdFusion MX 7, because the cfinput tag did not support all HTML
type attributes.
• It is backward-compatible with validation prior to ColdFusion MX 7, when hidden field validation was the only
way to do validation on the server.
• Because you use a separate tag for each validation type, if you specify multiple validation rules for a field, you
can specify a different error message for each rule.
•

You can use hidden field validation with any form field type that submits a data value, not just input, cfinput,

textarea, or cftextarea.

Specifying hidden form field validation
To specify hidden field validation, you do the following:

•

Create one HTML input element or CFML cfinput tag of type="hidden" for each validation rule.

•

Specify the name of the field to validate as the first part of the hidden field name.

• Specify the type of validation, starting with an underscore character (_), as the second part of the hidden field
name.
• You can specify multiple rules for each form data field. For example, to specify range and required validation for
a field named myValue, create hidden myValue_cfformrange and myValue_cfformrequired fields.
•

For most types of validation, specify the error message as the field value attribute.

ADOBE COLDFUSION 8 566
ColdFusion Developer’s Guide

• For range, maximum length, or regular expression validation, specify the rule, such as the maximum length, in
the value attribute. For these validation types, you cannot specify a custom error message.
The following example uses hidden fields to require data in a date field and ensure that the field contains a date. It
consists only of HTML tags.





Use the following suffixes at the end of hidden form field names to specify the validation type. The type identifier
always starts with an underscore. Several validation rules have two names you can use. The names that do not start
with “_cf ” were used in earlier releases and are retained for backward compatibility. For consistency and clarity,
Adobe recommends using the names that start with “_cf ” in new forms.
Field name suffix

Verifies

_integer, _cfforminteger

An integer of the range -2,147,483,648 — 2,147,483,647. Treats the initial characters “$ ¤ ¥ £ +” as valid
input, but removes them from the number.

_cfformnumeric

Any numeric value. Treats the initial characters “$ ¤ ¥ £ +”as valid input, but does NOT remove them from
the number.

_float, _cfformfloat

Any value (including an integer) that can be represented as a floating point number with up to 12 significant digits. Treats the initial characters “$ ¤ ¥ £ +” as valid input, but removes them from the number.
Converts input data to a real number; for example a dump of an integer value on the action page includes
a decimal point followed by a 0.

_range, _cfformrange

A numeric value within boundaries specified by the value attribute. Specify the range in the value
attribute using the format “min=minvalue max=maxvalue.” You cannot specify a custom error message
for this validation.

_date, _cfformdate

A date in any format that ColdFusion can understand; converts the input to ODBC date format. Allows
entry of a time part, but removes it from the ODBC value.

_cfformusdate

A date in the form m/d/y, m-d-y , or m.d.y, The m and d format can be 1 or 2 digits; y can be 2 or 4 digits.
Does not convert the string to an ODBC value and does not allow a time part.

_eurodate, _cfformeurodate

A date in the form d/m/y, d-m-y, or d.m.y. The m and d format can be 1 or 2 digits; y can be 2 or 4 digits.
Converts the input to ODBC date format. Allows entry of a time part, but removes it from the ODBC value.

_time, _cfformtime

A time. Can be in 12-hour or 24-hour clock format, and can include seconds in the form hh:mm:ss or a
case-independent am or pm indicator.
Converts the input to ODBC time format. Allows entry of a date part, but removes it from the ODBC value.

_cfformcreditcard

After stripping blanks and dashes, a number that conforms to the mod10 algorithm. Number must have
13-16 digits.

_cfformSSN,
_cfformsocial_security_number

A nine-digit Social Security number. Can be of the form xxx-xx-xxxx or xxx xx xxxx.

_cfformtelephone

Standard U.S. telephone formats. Does not support international telephone numbers.
Allows area codes with or without parentheses, and hyphens (-), spaces, periods, or no separators
between standard number groups. Can be preceded by a 1 long-distance designator, and can end with
an up-to-5 digit extension, optionally starting with x. The area code and exchange must begin with a digit
in the range 1 - 9.

_cfformzipcode

A 5-digit or 9-digit U.S. ZIP code. In 9-digit codes, the final four digits must be preceded by a hyphen (-)
or space.

_cfformemail

A valid e-mail address. Valid address characters are a-zA-Z0-9_- and the period and separator. There must
be a single at sign (@) and the text after the @ character must include a period, as in
my_address@MyCo.com or b-b.jones27@hisco.co.uk.

ADOBE COLDFUSION 8 567
ColdFusion Developer’s Guide

Field name suffix

Verifies

_cfformURL

A valid URL. Must start with http:\\, https:\\, ftp:\\, file:\\, mailto:, or news:. Can include, as appropriate,
user name and password designators and query strings. The main part of the address can only have the
characters A-Za-z0-9 and -.

_cfformboolean

A value that can be treated as a Boolean: Yes, No, True, False, 0, 1.

_cfformUUID

A universally unique identifier (UUID) that follows the ColdFusion format, xxxxxxxx-xxxx-xxxxxxxxxxxxxxxxxxxx, where x is a hexadecimal number.

_cfformGUID

A unique identifier that follows the Microsoft/DCE format, xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, where
x is a hexadecimal number.

_cfformnoblanks

The field must not include blanks. ColdFusion uses this validation only if you also specify a _required
hidden field.

_cfformmaxlength

The number of characters must not exceed the number specified by the tag value attribute.

_cfformregex,
_cfformregular_expression

The data must match a JavaScript regular expression specified by the tag value attribute.

_required, _cfformrequired

Data must be entered or selected in the form field.

Hidden form field considerations
Consider the following rules and recommendations when determining whether and how to use hidden form field
validation:

•

Use hidden field validation if you want to validate data from standard HTML input tags. The cfinput and

cftextarea tags include a validateAt attribute that provides a simpler method for specifying server-side

validation.

• Consider using hidden field validation with the cfinput and cftextarea tags if you specify multiple validation
rules for a single field and want to provide a separate error message for each validation.
•

Do not use the suffixes listed in the table as field names.

• Adding a validation rule to a field does not make it a required field. You must add a separate _required hidden
field to ensure user entry.

Hidden form field example
The following procedure creates a simple form for entering a start date and a salary. It uses hidden fields to ensure
that you enter data and that the data is in the right format.
This example uses a self-submitting form; the same ColdFusion page is both the form page and its action page. The
page uses an IsDefined function to check that form data has been submitted. This way, the pages does not show any
results until you submit the input. The form uses HTML tags only; you can substitute these tags with the CFML
equivalents.





Simple Data Form






Start Date:


Salary:










Start Date is: #DateFormat(Form.StartDate)#

Salary is: #DollarFormat(Form.Salary)#




When the user submits this form, ColdFusion scans the form fields to find any validation rules. It then uses the rules
to analyze the user’s input. If any of the input rules are violated, ColdFusion displays an error page with the error
message that you specified in the hidden field’s value attribute. The user must go back to the form, correct the
problem, and resubmit the form. ColdFusion does not accept form submission until the user enters the entire form
correctly.
Because numeric values often contain commas and currency symbols, ColdFusion automatically deletes these
characters from fields with _cfforminteger and _cfformfloat rules before it validates the form field and passes the
data to the form's action page. ColdFusion does not delete these characters from fields with _cfformnumeric rules.
Reviewing the code

The following table describes the code and its function:

ADOBE COLDFUSION 8 569
ColdFusion Developer’s Guide

Code

Description



Gathers the information from this form sends it to the dataform.cfm page (this
page) using the Post method.




Requires input into the StartDate input field. If there is no input, displays the error
information “You must enter a start date.” Requires the input to be in a valid date
format. If the input is not valid, displays the error information “Enter a valid date
as the start date.”


If it is not valid, displays the error information “The salary must be a number.”

Start Date:



Creates a text box called StartDate in which users can enter their starting date.
Makes it 16-characters wide.

Salary:



Creates a text box called Salary in which users can enter their salary. Makes it tencharacters wide.



Start Date is:

Displays the values of the StartDate and Salary form fields only if they are defined.
They are not defined until you submit the form, so they do not appear on the
initial form. Uses the DateFormat function to display the start date in the default
date format. Uses the DollarFormat function to display the salary with a dollar
sign and commas.

#DateFormat(Form.StartDate)#

Salary is:
#DollarFormat(Form.Salary)#



Validating form input and handling errors with
JavaScript
ColdFusion lets you write your own validation routines in JavaScript, and lets you create JavaScript error handlers.

Validating input with JavaScript
In addition to native ColdFusion input validation using the validate attribute of the cfinput and cftextarea
tags, the following tags support the onValidate attribute, which lets you specify a JavaScript function to handle your
cfform input validation:

•
•

cfgrid

•
•

cfslider

cfinput

cftextarea

• cftree
ColdFusion passes the following arguments to the JavaScript function that you specify in the onValidate attribute:
•

The form JavaScript DOM object

ADOBE COLDFUSION 8 570
ColdFusion Developer’s Guide

•

The name attribute of the form element

•

The value of the control to validate

For example, if you write the cfinput tag as the following:

onvalidate="handleValidation"
...
>

You define the JavaScript function as the following:


Example: validating a password
The following example validates a password. The password must have at least one of each of the following: an
uppercase letter, a lowercase letter, and a number. It must be between 8 and 12 characters long. If the password is
invalid, the browser displays a message box. If the password is valid, it redisplays the page with a brief success
message.
Use JavaScript to validate form data
1 Create a ColdFusion page with the following content:







JavaScript validation test


Your Password if valid.

Please enter your new password:








2

Save the page as validjs.cfm.

3

View the validjs.cfm page in your browser.

Handling failed validation
The onError attribute lets you specify a JavaScript function to execute if an onValidate, onBlur or onSubmit
validation fails. For example, if you use the onValidate attribute to specify a JavaScript function to handle input
validation, you can also use the onError attribute to specify a JavaScript function to handle a failed validation (that
is, when onValidate returns a False value). If you use the onValidate attribute, you can also use the onError
attribute to specify a JavaScript function that handles the validation errors. The following cfform tags support the
onerror attribute:

•

cfgrid

•

cfinput

•

cfselect

•

cfslider

•

cftextinput

•

cftree

ColdFusion passes the following JavaScript objects to the function in the onerror attribute:

•

The JavaScript form object

•

The name attribute of the form element

•

The value that failed validation

•

The error message text specified by the CFML tag’s message attribute

ADOBE COLDFUSION 8 572
ColdFusion Developer’s Guide

The following example shows a form that uses an onError attribute to tell ColdFusion to call a showErrorMessage
JavaScript function that uses the alert method to display an error message. The function assembles the message
from the invalid value and the contents of the cfinput tag’s message attribute.





Minimum Quantity: 


Maximum Quantity: 




Validating data with the IsValid function and the
cfparam tag
The IsValid function and cfparam tag validate any ColdFusion variable value, not just forms variables. Because
they reside entirely on the ColdFusion server, they can provide a secure mechanism for ensuring that the required
validation steps get performed. Users cannot evade any of the checks by modifying the form data that gets submitted.
These techniques also provide greater flexibility in how you respond to user errors, because you can use full CFML
syntax in your error-handling code.
These two validation techniques operate as follows:

• The IsValid function tests the value of a ColdFusion variable. If the value is valid, it returns True; if the value
is invalid, it returns False.
• The cfparam tag with a type attribute tests the value of a ColdFusion value for validity. If the value is valid, it
does nothing; if the value is invalid, it throws a ColdFusion expression exception.
You can use either technique interchangeably. The one you choose should depend on your coding style and
programming practices. It can also depend on the specific information that you want to display if an error occurs.

Example: IsValid function validation
The following example checks whether a user has submitted a numeric ID and a valid e-mail address and phone
number. If any of the submitted values does not meet the validation test, the page displays an error message.


ADOBE COLDFUSION 8 573
ColdFusion Developer’s Guide





The e-mail address and phone number for user #Form.UserID#
have been added


Please enter a valid user ID, phone number, and e-mail address.





User ID:

Phone: 

E-mail: 





Examples: cfparam tag validation
The following two examples use cfparam tags to do the same tests as in the “Example: IsValid function validation”
on page 572. They check whether a user has submitted a numeric ID and a valid e-mail address and phone number.
If any of the submitted values does not meet the validation test, ColdFusion throws an expression exception.
In the first example, the error is handled by the exprerr.cfm page specified in the cferror tag. In this case, if the user
made multiple errors, ColdFusion lists only one.
In the second example, each invalid field is handled in a separate try/catch block. In this case, the user gets information about each error.
Using an error-handling page

The self-posting form and action page looks as follows:











The e-mail address and phone number for user #Form.UserID#
have been added




User ID:

Phone: 

E-mail: 




ADOBE COLDFUSION 8 574
ColdFusion Developer’s Guide



The expresserr.cfm page looks as follows:

You entered invalid data.

Please click the browser Back button and try again

#cferror.RootCause.detailMessage#

Using cftry and cfcatch tags

The self-posting form and action page looks as follows:














Invalid user ID.

#cfcatch.detail#











Invalid e-mail address.

#cfcatch.detail#











Invalid telephone number.

#cfcatch.detail#









The e-mail address and phone number for user #Form.UserID#
have been added

ADOBE COLDFUSION 8 575
ColdFusion Developer’s Guide


 
 

User ID:

Phone: 

E-mail: 





576

Chapter 32: Creating Forms in Flash
You can create effective forms in Adobe Flash format, in which ColdFusion displays forms using Flash, not HTML.
This chapter describes Flash forms and how they differ from HTML forms, and discusses how to create Flash forms.
Contents

About Flash forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
Building Flash forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578
Binding data in Flash forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586
Setting styles and skins in Flash forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587
Using ActionScript in Flash forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590
Best practices for Flash forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592

About Flash forms
ColdFusion can deliver forms to the client in Flash (SWF) file format. ColdFusion automatically generates the Flash
binary from your CFML code and displays it on the client. Flash forms have the following advantages over HTML
forms:

• They are browser-independent. Flash Player works in all commonly used browsers on Windows and Macintosh
systems, and in Netscape and Mozilla on Linux.
• By default, they present a modern, visually pleasing appearance, and you can apply predefined color skins or
customize the appearance with specifications similar to those in a Cascading Style Sheet (CSS).
• They let you develop complex, multipart forms that do not require multiple pages, by using tabbed or accordionstyle dialog boxes.
•

They automatically do much of the layout work for you.

Note: Flash form configuration requirements differ from ColdFusion requirements. For example, Flash forms might not
work with all J2EE servers supported by ColdFusion. For more information, see Installing and Using ColdFusion.
In addition to creating Flash forms, ColdFusion lets you specify Flash format for cfcalendar, cftree, and cfgrid
tags. Use these tags to embed Flash calendar choosers, trees, and grids in HTML forms, to eliminate the need to use
Java applets. This chapter does not specifically discuss using Flash grids and trees in HTML forms; however, the
information in this chapter about grids and trees also applies to these elements.

A Flash form example
Flash forms provide many features that help you quickly create easy-to-use, professional-looking, complex forms.
The following image contains a two-tab form that shows many of these features:

ADOBE COLDFUSION 8 577
ColdFusion Developer’s Guide

This form includes the following features:

• Each tab contains a different section of the overall form, and users can enter data on both tabs before submitting
the form. This technique can eliminate the need for multiple forms on multiple HTML pages.
•

The first and last names are required fields, indicated by the red asterisks.

• The Flash form automatically fills the e-mail field with data from the name fields, but the user can override this
information.
•

When the user selects the date field, a calendar automatically opens for picking the date.

Flash form CFML differences from HTML forms
Because ColdFusion sends a Flash form to the client in SWF format, everything inside a Flash form is rendered by
Flash. Rendering the form in Flash has several effects:

•

Plain text and HTML tags in the body of a Flash Form have no effect.

•

You must specify all form content inside CFML tags that support Flash forms.

• ColdFusion provides two tags that let you take advantage of Flash features and perform tasks that you would
otherwise do in HTML: you use the cfformitem tag to add text blocks and horizontal and vertical rules to your
form, and you use the cfformgroup tag to structure your form.
• Standard ColdFusion forms tags, such as cfinput and cftree, include attributes that work only with Flash
forms, and attribute values that let you specify form style and behavior. These include the skin attribute with many
Flash-specific style attribute values for appearance, and the bind attribute for filling a field value with data from
other fields.
The reference pages for the individual tags in the CFML Reference describe the form tags and their features,
indicating which attributes and values work with Flash forms. This chapter describes how you can use CFML tags to
build effective Flash forms.

ADOBE COLDFUSION 8 578
ColdFusion Developer’s Guide

Building Flash forms
You build Flash forms using standard ColdFusion form tags, plus the cfformgroup and cfformitem tags. These
tags create the elements of the form, as follows:

• The cfcalendar, cfgrid, cfinput, cfselect, cftextarea, and cftree tags create controls for data display
and user input.
• The cfformitem tag lets you add formatted or unformatted text, spacers, and horizontal and vertical rules
without using HTML.
• The cfformgroup tag creates containers, such as horizontally aligned boxes or tabbed navigators, that let you
group, organize, and structure the form contents.
Flash forms follow a hierarchical structure of containers and children.
1

The cfform tag is the master container, and its contents are child containers and controls.

2

The cfformgroup tag defines a container that organizes its child elements.

3

All other tags create individual controls, including display elements such as rules.

For example, the image in the About Flash forms section has the following hierarchical structure of containers and
children. (This outline only shows the structure of the page that is visible in the image. It omits the structure of the
Preferences tab.)
1
2
3
4
5
5
5
4
4
4
4
4
4
4
3

2
3
3

cfform
cfformgroup type="tabnavigator" -- Tab navigator container
cfformgroup type="page" -- Tabbed page container, child of tabnavigator
cfformgroup type="horizontal" -- Aligns its two children horizontally
cfinput type="text" -- First name input control
cfinput type="spacer" -- Space between the name input controls
cfinput type="text" -- Last name input control
cfformitem type="hrule" -- Displays a rule
cfformitem type="html" -- Displays formatted text
cffinput type="text" -- E-mail input control
cfformitem type="hrule" -- Displays a rule
cfinput type="text" -- Phone number input control
cfinput type="spacer" -- Space between the phone and date controls
cfinput type="datefield" -- Date input control
cfinput type="page" -- Second tabbed page container for preferences
.
.
cfformgroup type="horizontal" -- Follows the tabnavigator in the form
cfinput type="submit" -- Submit button control
cfinput type="reset" -- Reset button control

The following sections describe how you use the various Flash form elements to build a Flash form.

Adding text, images, rules, and space with the cfformitem tag
Because Flash forms do not support inline HTML, you use the cfformitem tag to add text blocks and horizontal
and vertical rules to your form. (Flash form controls, such as cfinput, use the label or value attribute to specify
text labels.) You can also use the cfformitem tag to add spacers between visual form elements.
The cfformitem type="hrule" and cfformitem type="vrule" tags put horizontal and vertical rules in the
form. You can specify the rule thickness, color, and shadow characteristics by using style specifications. For more
information on specifying rule styles, see “Styles for cfformitem with hrule or vrule type attributes” on page 1296 in
“ColdFusion Flash Form Style Reference” on page 1287 in the CFML Reference.

ADOBE COLDFUSION 8 579
ColdFusion Developer’s Guide

The cfformitem type="spacer" tag puts a blank space of the specified height and width on the form. This tag
type does not use styles; it can be useful in improving the form appearance by helping you control the form layout.
The cfformitem type="text" tag lets you insert plain text in the form You can use the style attribute to apply a
consistent format to the text.
The cfformitem type="html" tag lets you insert formatted text and images in the form. You can include basic
HTML-style formatting tags in the body of this tag to add images and to format and style the text.
You can use the following formatting tags and attributes in the body of a cfformitem type="html" tag:
:

Tag

Valid attributes

a

href

URL to link to.

target

window name; can be a standard HTML window name such as _blank.

b

None.

br

None.

font

color Must be in hexadecimal format, such as #FF00AA. Use a single number sign (#) character.
face

Can be a comma-delimited list of font face names; Flash uses the first font that is available on the client

system.
size

In pixels; + and -relative values are allowed.

i

None.

img

See the attribute table for the img tag.
Note: You must close this tag with /> or an  tag.

li

None.

p

align Must be one of the following: left, right, center.

textformat

See the attribute table for the textformat tag.

u

None.

The img tag supports the following attributes:
Attribute

Description

src

(Required) URL or pathname to a JPEG or SWF file. Images are not displayed until they have downloaded completely.
Flash Player does not support progressive JPEG files.

width

Width of the image, in pixels.

height

Height of the image in pixels.

align

Horizontal alignment of the embedded image within the text field. Valid values are left and right. The default
value is left.

hspace

Number of pixels of horizontal space that surround the image where no text appears. The default value is 8.

vspace

Number of pixels of vertical space that surround the image where no text appears. The default value is 8.

Note: Because of the Flash dynamic sizing rules, to ensure that the image displays properly, you might have to specify the
formitem tag height attribute and the width and height attributes for the form or the containing cfformgroup tag.
Also, the image always displays on a new line, not inline with text, and text that follows the image in your code occupies
any available space to the right of the image.
The textformat tag is specific to Flash, and has the following attributes:

ADOBE COLDFUSION 8 580
ColdFusion Developer’s Guide

Attribute

Description

blockindent

Block indentation, in points.

indent

Indentation from the left margin to the first character in the paragraph.

leading

Amount of leading (vertical space) between lines.

leftmargin

Left margin of the paragraph, in points.

rightmargin

Right margin of the paragraph, in points.

tabstops

Custom tab stops as an array of nonnegative integers. To specify tabs in text, use the \t escape character.

For detailed descriptions of these tags, see the Flash documentation.
The following code creates a simple Flash form that consists of a formatted text area surrounded by horizontal rules:



Flash form with formatted text and rules






This form has formatted text, including:


colored text
italic and bold text
a bulleted list in an indented block

The text is preceded and followed by horizontal rules
It also has a link to a web page.



This link displays the Adobe home page in a new browser window






This form appears as follows:

ADOBE COLDFUSION 8 581
ColdFusion Developer’s Guide

Using the cfformgroup tag to structure forms
ColdFusion provides form group container types that provide basic structure to a Flash form. You specify these types
in the type attribute of the cfformgroup tag. Use the following container types to control the layout of controls and
groups of controls:
Type

Description

horizontal

Arranges individual controls horizontally, and optionally applies a label to the left of the controls. Use only for
arranging ColdFusion form controls, including cfformitem controls. As a general rule, do not use to organize
cfformgroup containers; use the hbox attribute instead.
If you put other cfformgroup tags inside a horizontal form group, the controls inside the included
cfformgroup tag do not align with other controls in the horizontal group.

vertical

Arranges individual controls vertically, and optionally applies a label to the left (not top) of the controls. Use only for
groups of ColdFusion form controls, including cfformitem controls. As a general rule, do not use to organize
cfformgroup containers; use the vbox attribute instead.
If you put other cfformgroup tags inside a vertical form group, the controls inside the included cfformgroup
tag do not align with other controls in the vertical group.

hbox

Arranges groups of controls horizontally. Does not apply a label. Use this attribute value to arrange other
cfformgroup containers. This tag does not enforce alignment of child controls that have labels, so you should not
use it to align individual controls.

vbox

Arranges groups of controls vertically. Does not apply a label. Use this attribute value to arrange other cfformgroup
containers. This tag does not enforce alignment of child controls that have labels, so you should not use it to align
individual controls.

hdividedbox

Arranges two or more children horizontally, and puts divider handles between the children that users can drag to
change the relative sizes of the children. Does not apply a label. The direct children of an hdividedbox container
must be cfformgroup tags with type attributes other than horizontal or vertical.

vdividedbox

Arranges two or more children vertically, and puts divider handles between the children that users can drag to
change the relative sizes of the children. Does not apply a label. The direct children of a vdividedbox container must
be cfformgroup tags with type attributes other than horizontal or vertical.

tile

Arranges its children in a rectangular grid in row-first order. Does not apply a label.

panel

Consists of a title bar containing the label attribute text, a border, and a content area with vertically arranged children.

accordion

Puts each of its child pages in an accordion pleat with a label bar. Displays the contents of one pleat at a time. Users
click the labels to expand or contract the pleat pages. Does not apply a label.

tabnavigator

Puts each of its children on a tabbed page. Users click the tabs to display a selected page. Does not apply a label.

page

The immediate child of an accordion or tab navigator container. Specifies the label on the pleat bar or tab, and
arranges its child containers and controls vertically.

For more information on using the accordion, tabnavigator, and page cfformgroup types, see “Creating
complex forms with accordion and tab navigator containers” on page 584.
Example: structuring with the cfformgroup tag

The following example shows a form with an hdividedbox container with two vbox containers. The left box uses a
horizontal container to arrange two radio buttons. The right box uses a tile container to lay out its check boxes.
You can drag the divider handle to resize the two boxes. When you submit the form, the ColdFusion page dumps the
Form scope to show the submitted data.








ADOBE COLDFUSION 8 582
ColdFusion Developer’s Guide


Tell us your preferences






Pets:









Fruits:


<--- Flash requires unique names for all controls --->















Controlling sizes in Flash forms
Sizing elements in a Flash form is something of an art, rather than a science. As a general rule, if you don’t specify
the height and width attributes, Flash tends to do a good job of laying out the form. However, keep in mind the
following considerations:

• If you do not specify the height and width attributes in the cfform tag, Flash reserves the full dimensions of
the visible browser window, if the form is not in a table, or the table cell, if the form is in a table, even if they are not
required for the form contents. Any HTML output that precedes or follows the form causes the output page to exceed
the size of the browser window.
• If you do not specify the height or width of a control, including a form group, Flash adjusts the dimensions,
trying to fit the controls in the available space. For example, Flash often extends input boxes to the width of the
containing control, if not otherwise specified.

ADOBE COLDFUSION 8 583
ColdFusion Developer’s Guide

In general, it is best to use the following process when you design your Flash form.
Determine the sizes of a Flash form and its controls
1 When you first create the form, don’t specify any height and width attributes on the form or its child tags. Run

the form and examine the results to determine height and width values to use.
2 Specify height and width attributes in the cfform tag for the desired dimensions of the form. You can specify
absolute pixel values, or percentage values relative to the size of the containing window.
3

Specify any height or width attributes on individual tags. These values must be in pixels.

4

Repeat step 3 for various tags, and possibly step 2, until your form has a pleasing appearance.

Repeating Flash form elements based on query data
The repeater cfformgroup type tells Flash Player to iterate over a query and create a set of the cfformgroup tag’s
child controls for each row in the query. For each set of child controls, bind attributes in the child tags can access
fields in the current query row. This cfformgroup type lets you create Flash forms where the number of controls can
change based on a query, without requiring ColdFusion to recompile the Flash SWF file for the form. This significantly enhances server performance.
Note: For more information on binding data, see “Binding data in Flash forms” on page 586.
Optionally, you can specify a start row and a maximum number of rows to use in the repeater. Unlike most
ColdFusion tags, repeater index values start at 0, not 1. To specify a repeater that starts on the first line of the query
object and uses no more than 15 rows, use a tag such as the following:


One example that might use a repeater is a form that lets a teacher select a specific class and update the student
grades. Each class can have a different number of students, so the form must have a varying number of input lines.
Another example is a shopping cart application that displays the product name and quantity ordered and lets users
change the quantity.
The following example uses the cfformgroup tag with a repeater type attribute value to populate a form. It creates
a query, and uses the repeater to iterate over a query and create a firstname and lastname input box for each row in
the query.







q1 = queryNew("id,firstname,lastname");
queryAddRow(q1);
querySetCell(q1, "id", "1");
querySetCell(q1, "firstname", "Rob");
querySetCell(q1, "lastname", "Smith");
queryAddRow(q1);
querySetCell(q1, "id", "2");
querySetCell(q1, "firstname", "John");
querySetCell(q1, "lastname", "Doe");
queryAddRow(q1);
querySetCell(q1, "id", "3");
querySetCell(q1, "firstname", "Jane");
querySetCell(q1, "lastname", "Doe");
queryAddRow(q1);
querySetCell(q1, "id", "4");

ADOBE COLDFUSION 8 584
ColdFusion Developer’s Guide

querySetCell(q1, "firstname", "Erik");
querySetCell(q1, "lastname", "Pramenter");












Creating complex forms with accordion and tab navigator containers
The accordion and tabnavigator attributes of the cfformgroup tag let you construct complex forms that would
otherwise require multiple HTML pages. With accordions and tab navigator containers, users can switch among
multiple entry areas without submitting intermediate forms. All data that they enter is available until they submit the
form, and all form elements load at one time.
An accordion container puts each logical form page on an accordion pleat. Each pleat has a label bar; when the user
clicks a bar, the current page collapses and the selected page expands to fill the available form space. The following
image shows a three-pleat accordion, open to the middle pleat, Preferences:

A tab navigator container puts each logical form page on a tabbed frame. When the user clicks a tab, the selected
page replaces the previous page. The image in About Flash forms shows a tab navigator container.
The following example generates a two-tab tab navigator container that gets contact information and preferences.
You can change it to an accordion container by changing the type attribute of the first cfformgroup tag from
accordion to tabnavigator. To prevent the accordion from having scroll bars, you must also increase the cfform
tag height attribute to 310 and the tabnavigator tag height attribute to 260.












ADOBE COLDFUSION 8 585
ColdFusion Developer’s Guide








Flash fills this field in automatically.
You can replace the text.












Tell us your preferences






Pets:









Fruits:


<--- Flash requires unique names for all controls. --->






ADOBE COLDFUSION 8 586
ColdFusion Developer’s Guide













Binding data in Flash forms
The bind attribute lets you set the value of the fields using the contents of other form fields. You can use the bind
attribute with the cftextarea tag and any cfinput type that takes a value, including hidden. This data binding
occurs dynamically as the user enters data within Flash on the client system. Flash does not send any information to
ColdFusion until the user submits the form. To use the bind attribute to specify the field value, use the following
formats:
Data source

bind attribute format

cfinput type = "text" or
cftextarea text

bind="{sourceName.text}"

cfinput selected radio button

bind="{sourceName.selectedData}"

cftree selected item

bind="{sourceName.selectedNode.getProperty('data').value}

cfgrid selected item

bind="{sourceName.selectedItem.COLUMNAME}"

cfselect selected item

bind="{sourceName.selectedItem.data}"

Note: If you use the bind attribute, you cannot use the value attribute.
The following rules and techniques apply to the binding formats:

• The sourceName value in these formats is the name attribute of the tag that contains the element that you are
binding to.
• You can bind to additional information about a selected item in a tree. Replace value with display to get the
displayed value, or with path to get the path to the node in the tree.
•

You can bind to the displayed value of a cfselect item by replacing data with label.

• If the user selects multiple items in a cfselect control, the selectedItem object contains the most recent
selection, and a selectedItems array contains all selected items. You can access the individual values in the array, as
in myTree.selectedItems[1].data. The selectedItems array exists only if the user selects multiple items; otherwise, it
is undefined.
•

You can use ActionScript expressions in Flash bind statements.

The following example shows how to use the values from the firstName and lastName fields to construct an e-mail
address. The user can change or replace this value with a typed entry.






Setting styles and skins in Flash forms
ColdFusion provides the following methods for controlling the style and appearance of Flash forms and their
elements:
Skins: provide a simple method for controlling the overall appearance of your form. A single skin controls the entire
form.
Styles: provide a finer-grained level of control than skins. Each style specifies a particular characteristic for a single
control. Many styles are also inherited by a control’s children.
You can use both techniques in combination: you can specify a skin for your form and use styles to specify the
appearance (such as input text font) of individual controls.
The following sections describe these methods and how you can use them. For detailed information on the style
names and values that you can use, see “ColdFusion Flash Form Style Reference” on page 1287 in the CFML
Reference.

Controlling form appearance with Flash skins
The cfform tag takes a skin attribute, which lets you select an overall appearance for your form. The skin determines the color used for highlighted and selected elements.
You can select the following Flash skins:

•

haloBlue

•

haloGreen (the default)

•

haloOrange

•

haloSilver

About Flash form styles
The ColdFusion Flash form tags have a style attribute that lets you specify control characteristics using CSS syntax.
You can specify a style attribute in the following tags:

•
•
•
•

cfform

•
•
•
•
•

cfgrid

cfformgroup
cfcalendar
cfformitem, types hrule and vrule

cfinput
cfselect
cftextarea
cftree

ADOBE COLDFUSION 8 588
ColdFusion Developer’s Guide

The attributes for the cfform and cfformgroup generally apply to all the form or form group’s children.
Flash supports many, but not all, standard CSS styles. ColdFusion Flash forms only support applying specific CSS
style specifications to individual CFML tags and their corresponding Flash controls and groups. You cannot use an
external style sheet or define a document-level style sheet, as you can for HTML format forms.

Flash form style specification syntax
To specify a Flash style, use the following format:
style="stylename1: value; stylename2: value; ..."

For example, the following code specifies three style values for a text input control:


About Flash form style value formats
Style properties can be Boolean values, strings, numbers, or arrays of these values. The following sections describe
the formats for length, time, and color values.
Length format

You specify styles that take length or dimension values, including font sizes, in pixels.
The fontSize style property lets you use a set of keywords in addition to numbered units. You can use the following
keywords when you set the fontSize style property. The exact sizes are defined by the client browser.

•

xx-small

•

x-small

•

small

•

medium

•

large

•

x-large

•

xx-large

The following cfinput tag uses the style attribute with a fontSize keyword to specify the size of the text in the
input box:

Time format

You specify styles that take time values, such as the openDuration style that specifies how fast an accordion pleat
opens, in milliseconds. The following example shows an accordion tag that takes one-half second to change
between accordion pleats:

Color format

You define color values, such as those for the backgroundColor style, in the following formats:

ADOBE COLDFUSION 8 589
ColdFusion Developer’s Guide

Format

Description

hexadecimal

Hexadecimal colors are represented by a six-digit code preceded by two number sign characters (##). Two # characters are required to prevent ColdFusion from interpreting the character. The range of possible values is ##000000 to
##FFFFFF.

VGA color names

VGA color names are a set of 16 basic colors supported by all browsers that support CSS. The available color names
are Aqua, Black, Blue, Fuchsia, Gray, Green, Lime, Maroon, Navy, Olive, Purple, Red, Silver, Teal, White,
and Yellow. Some browsers support a larger list of color names. VGA color names are not case-sensitive.

Some styles support only the hexadecimal color format.
Some controls accept multiple colors. For example, the tree control’s depthColors style property can use a different
background color for each level in the tree. To assign multiple colors, use a comma-delimited list, as the following
example shows:
style="depthColors: ##EAEAEA, ##FF22CC, ##FFFFFF"

About Flash form style applicability and inheritance
Because of the way Flash control styles are implemented, some common styles are valid, but have no effect, in some
tags. Therefore, in the table in “Styles valid for all controls” on page 1288 in “ColdFusion Flash Form Style Reference”
on page 1287 in the CFML Reference, the listed styles do not cause errors when used in controls, but might not have
any effect.
Styles can be inheritable or noninheritable. If a style is noninheritable, it only affects the tag, and does not affect any
of its children. For example, to maintain a consistent background color in an hbox form group and its children tags,
you must specify the color in all tags. If a style is inheritable, it applies to the tag and its children.

Example: applying styles to a Flash form
The following form uses a skin and styles to control its appearance:

The code for the form is as follows. Comments in the code explain how formatting controls and styles determine the
appearance.



ADOBE COLDFUSION 8 590
ColdFusion Developer’s Guide














 Flash fills this field in
automatically. You can replace the text.






 
 







Using ActionScript in Flash forms
ActionScript 2 is a powerful scripting language that is used in Flash and other related products and is similar to
JavaScript. You can use a subset of ActionScript 2 code in your Flash forms.

ADOBE COLDFUSION 8 591
ColdFusion Developer’s Guide

The following sections tells you how to include ActionScript in your Flash forms, and describes restrictions and
additions to ActionScript that apply to ColdFusion Flash forms. It does not provide information on writing ActionScript. For details on ActionScript and how you can use it, see the Flash ActionScript 2 documentation, including
the documents available in the Flash and Flex sections of LiveDocs at http://www.adobe.com/support/documentation/.

Using ActionScript code in CFML
You can use ActionScript in the following attribute of tags in CFML Flash format forms:

• Form and control events, such as the onSubmit attribute of the cfform tag, or the onChange and onClick
attributes of the cfinput tag. The attribute description on the tag reference pages in the CFML Reference list the
event attributes.
• Bind expressions, which you can use to set field values. For more information on binding data, see “Binding data
in Flash forms” on page 586.
Your ActionScript code can be inline in the form attribute specification, you can make a call to a custom function
that you define, or you can use the ActionScript include command in the attribute specification to get the ActionScript from a .as file.
The following example shows a simple Fahrenheit to Celsius converter that does the conversion directly on the client,
without requiring the user to submit a form to the ColdFusion server.






Note: You do not use the text property (for example, fieldname.text) to access hidden fields. To access a hidden field,
use the format formname.fieldname = 'value'.

Custom ActionScript functions
Custom ActionScript functions are the equivalent of CFML UDFs. You can define your own functions in ColdFusion
by using the cfformitem tag with a type attribute value of script, or you can define the functions in an ActionScript (.as) file. Also, ColdFusion includes a small number of predefined custom ActionScript functions that you can
use in your Flash form controls.
You can use the following custom functions in the ActionScript for all form controls to reset or submit the form:

• resetForm()
• submitForm()
You can use the following custom functions in cfgrid tags only to insert and delete rows in the grid:
•

GridData.insertRow(gridName)

•

GridData.deleteRow(gridName)

The following example shows how you can use the two GridData functions to add custom buttons that add and
delete rows from a Flash form. These buttons are equivalent to the buttons that ColdFusion creates if you specify
insert="yes" and delete="yes" in the cfgrid tag, but they allow you to specify you own button text and
placement. This example puts the buttons on the side of the grid, instead of below it and uses longer than standard
button labels.

ADOBE COLDFUSION 8 592
ColdFusion Developer’s Guide



You can edit this grid as follows:

To change an item, click the field and type.
To add a row, click the Insert Row button and type in the fields
in the highlighted row.
To delete a row, click anywhere in the row and click the
Delete Row button

When you are done, click the submit button.
































Best practices for Flash forms
The following sections describe best practices that can help you increase the performance of Flash forms.

ADOBE COLDFUSION 8 593
ColdFusion Developer’s Guide

Minimizing form recompilation
Flash forms are sent to the client as SWF files, which ColdFusion must compile from your CFML code. The following
techniques can help limit how frequently ColdFusion must recompile a Flash form.

• Only data should be dynamic. Whenever a variable name changes, or a form characteristic, such as an element
width or a label changes, the Flash output must be recompiled. If a data value changes, the output does not need to
be recompiled.
• Use cfformgroup type="repeater" if you must loop no more than ten times over no more than ten elements.
This tag does not require recompiling when the number of elements changes. It does have a processing overhead that
increases with the number of loops and elements, however, so for large data sets or many elements, it is often more
efficient not to use the repeater.

Caching data in Flash forms
The cfform tag timeout attribute specifies how many seconds ColdFusion retains Flash form data on the server.
When a Flash form is generated, the values for the form are stored in memory on the server. When the Flash form
is loaded on the client, it requests these form values from the server. If this attribute is 0, the default, the data on the
server is immediately deleted after the data has been requested from the Flash form.
A Flash form can be reloaded multiple times if a user displays a page with a Flash form, goes to another page, and
uses the browser Back button to return to the page with the form. This kind of behavior is common with search
forms, login forms, and the like. When the user returns to the original page:

• If the timeout value is 0, or the time-out period has expired, the data is no longer available, and ColdFusion
returns a data-expired exception to the browser; in this case, the browser typically tells the user to reload the page.
•

If the time-out has not expired, the browser displays the original data.

If your form data contains sensitive information, such as credit card numbers or social security numbers, you should
leave the time-out set to 0. Otherwise, consider setting a time-out value that corresponds to a small number of
minutes.

Using Flash forms in a clustered environment
Flash forms require sticky sessions when used in a cluster.

594

Chapter 33: Creating Skinnable XML
Forms
You can create XML skinnable forms, which are forms that generate XForms-compliant XML and are normally
formatted using an XSLT (extensible stylesheet language transformations) skin.
You can use XML skinnable forms with the skins that ColdFusion provides without having any knowledge of either
XML or XSLT. For information on using XML with ColdFusion, see “Using XML and WDDX” on page 865.
Contents

About XML skinnable forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594
Building XML skinnable forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596
ColdFusion XML format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
Creating XSLT skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610

About XML skinnable forms
A ColdFusion form with a format="XML" attribute is an XML skinnable form. When ColdFusion processes an XML
skinnable form, it generates the form as XML. By default, it applies an XML Stylesheet Language Transform (XSLT)
skin to the XML and generates a formatted HTML page for display on the user’s browser. Optionally, you can specify
an XSLT file, or you can process the raw XML in your ColdFusion page.
By using XML skinnable forms, you can control the type and appearance of the forms that ColdFusion generates and
displays. ColdFusion provides a set of standard skins, including a default skin that it uses if you do not specify
another skin (or tell it not to apply a skin). You can also create your own XSLT skin and have ColdFusion use it to
give your forms a specific style or appearance.

ColdFusion forms and XForms
ColdFusion skinnable forms conform to and extend the W3C XForms specification. This specification provides an
XML syntax for defining interactive forms using a syntax that is independent of form appearance. ColdFusion forms
tags include attributes that provide information that does not correspond directly to the XForms model, such as
appearance information, validation rules, and standard HTML attributes. ColdFusion skinnable forms retain this
information in XForms extensions so that an XSL transformation can use the values to determine appearance or do
other processing.
For more information on XML structure of ColdFusion skinnable forms, see “ColdFusion XML format” on page 599.

The role of the XSLT skin
An XSLT skin and associated cascading style sheet (CSS) determine how an XML skinnable form is processed and
displayed, as follows:

• The XSLT skin tells ColdFusion how to process the XML, and typically converts it to HTML for display. The skin
specifies the CSS style sheet to use to format the output.
•

The CSS style sheet specifies style definitions that determine the appearance of the generated output.

ADOBE COLDFUSION 8 595
ColdFusion Developer’s Guide

XSLT skins give you extensive freedom in the generated output. They let you create a custom appearance for your
forms, or even different appearances for different purposes. For example, you could use the same form in an intranet
and on the Internet, and change only the skin to give a different appearance (or even select different subsets of the
form for display). You can also create skins that process your form for devices, such as wireless mobile devices.

How ColdFusion processes XML skinnable forms
When ColdFusion processes a cfform tag that specifies XML format and an XSLT skin, it does the following to the
form:
1 Converts the CFML form tags into an XForms-compliant XML text format and makes it available in a variable
with the same name as the form. ColdFusion ignores in-line text or HTML tags in the form, and does not pass them
to the XML. (It does process HTML option tags that are children of a cfselect tag.)
2 Applies an XSLT skin to the XML; for example, to convert the form into HTML. The XSLT file specifies the CSS
style sheet.
3

Returns the resulting, styled, form to the client, such as a user’s browser.

If you omit the cfform tag skin attribute, ColdFusion uses a default skin.
If you specify skin="none", ColdFusion performs the first step, but omits the remaining steps. Your application
must handle the XML version of the form as needed. This technique lets you specify your own XSL engine, or incorporate the form as part of a larger form.

ColdFusion XSL skins
ColdFusion provides the following XSLT skins:

•

basic

•

basiccss

•

basiccss_top

•

beige

•

blue

•

default

•

lightgray

•

red

•

silver

The XSLT skin files are located in the cf_webroot\CFIDE\scripts\xsl directory, and the CSS files that they use for style
definitions are located in the cf_webroot\CFIDE\scripts\css directory.
The default skin and the basic skin format forms identically. ColdFusion uses the default skin if you do not specify
a skin attribute in the cfform tag. The default and basic skins are simple skins that use tables for arranging the form
contents. The basic skin uses div and span tags to arrange the elements. The skins with names of colors are similar
to the basic skin, but make more use of color.

Example: a simple skinnable form
The following image shows a simple XML skinnable form that uses the default skin to format the output:

ADOBE COLDFUSION 8 596
ColdFusion Developer’s Guide

Later sections in this chapter use this form in their examples and description.

Building XML skinnable forms
You build ColdFusion XML skinnable forms using standard ColdFusion forms tags, including cfformgroup and
cfformitem tags. These tags create the elements of the form, the building blocks of the form.
ColdFusion converts the following tags to XML for processing by the XSLT:
Standard ColdFusion form data control tags: The cfgrid, cfinput, cfselect, cfslider, cftextarea, and tree
tags specify the controls that the form displays.
cfformitem tags: Add individual items to your form, such as text or rules. The valid types depend on the skin.
cfformgroup tags: Group, organize, and structure the form contents. The valid types depend on the skin.
These tags are designed so you can develop forms in a hierarchical structure of containers and children. Using this
model, the cfform tag is the master container, and its contents are children containers and controls. Each
cfformgroup tag defines a container that organizes its child elements.
The specific tags and attributes that you use in your form depend on the capabilities of the XSLT skin. You use only
the tag and attribute combinations that the skin supports. If you are using a skin provided by a third party, make sure
that the supplier provides information on the supported attributes.

Using standard ColdFusion form tags
You use standard ColdFusion form tags, such as cfinput or cftree, as you normally do in standard CFML forms
to generate form input elements. ColdFusion maps most of these tags and their subtags (such as option tags in the
cfselect tag) to equivalent XForms elements. ColdFusion maps applet and Flash format cfgrid and cftree tags
to ColdFusion XML extensions that contain Java applet or Flash objects. It converts XML format cfgrid and cftree
tags to ColdFusion XML extension.
The specific attributes you can use and their meanings can depend on the skins.
Using ColdFusion skins: The skins that are supplied with ColdFusion support the attributes that you can use with
HTML forms. You can also use label attributes to provide labels for the following tags:

•

cfinput with type attribute values of text, button, password, and file

ADOBE COLDFUSION 8 597
ColdFusion Developer’s Guide

•

cfselect

•

cfslider

•

cftextarea

Using other skins: If you use any other skin, some attributes might not be supported, or the skin might support
custom attributes. Get the information about the supported attributes from the XSLT skin developer.

Using cfformitem tags
ColdFusion does not process inline text or standard HTML tags when it generates an XML form; therefore, you use
the cfformitem tag to add formatted HTML or plain text blocks and any other display elements, such as horizontal
and vertical rules, to your form.
ColdFusion converts all cfformitem type attribute values to all-lowercase. For example, if you specify
type="MyType" ColdFusion converts the type name to "mytype".

ColdFusion makes no other limitations on the cfformitem type attributes that you can use in a form, but the XSLT
skin must process the attributes to display the items.
Using ColdFusion skins: The skins provided in ColdFusion support the following cfformitem types:

•

hrule

•

text

•

html

The hrule type inserts an HTML hr tag, and the text type displays unformatted plain text.
The html type displays HTML-formatted text. You can include standard HTML text markup tags, such as strong,
p, ul, or li, and their attributes. For example, the following text from the Example: a simple skinnable form section

shows how you could use a cfformitem tag to insert descriptive text in a form:

We value your input.

Please tell us a little about yourself and your thoughts.


Using other skins: If you use any other skin, the supported attributes and attribute values depend on the skin implementation. Get the information about the supported attributes and attribute values from the XSLT skin developer.

Using cfformgroup tags
The cfformgroup tag lets you structure forms by organizing its child tags, for example, to align them horizontally
or vertically. Some skins might use cfformgroup tags for more complex formatting, such as tabbed navigator or
accordion containers. ColdFusion makes no limitations on the type attributes that you can use in a form, but the
XSLT must process the resulting XML to affect the display.
Using ColdFusion skins: The skins provided in ColdFusion support the following type attribute values:

•

horizontal

•

vertical

•

fieldset

The horizontal and vertical types arrange their child tags in the specified direction and place a label to the left
of the group of children. The following text from the Example: a simple skinnable form section shows how you could
use a cfformgroup tag to apply a Name label and align first and last name fields horizontally:

ADOBE COLDFUSION 8 598
ColdFusion Developer’s Guide






The fieldset type corresponds to the HTML fieldset tag, and groups its children by drawing a box around them
and replacing part of the top line with legend text. To specify the legend, use the label attribute. To specify the box
dimensions, use the style attribute with height and width values.
The following code shows a simple form group with three text controls. The cfformgroup type="vertical" tag
ensures that the contents of the form is consistently aligned. The cfformgroup type="horizontal" aligns the
firstname and lastname fields horizontally.












Note: Because XML is case-sensitive, but ColdFusion is not, ColdFusion converts cfformgroup and cfformitem
attributes to all-lowercase letters. For example, if you specify cfformgroup type="Random", ColdFusion converts the
type to random in the XML.
Using other skins: If you use any other skin, the supported attributes and attribute values depend on the skin implementation. Get the information about the supported attributes and attribute values from the skin developer.

Example: CFML for a skinnable XML form
The following CFML code creates the form shown in the image in “About XML skinnable forms” on page 594. It
shows how you can use CFML to structure your form.










very satisfied
somewhat satisfied
somewhat dissatisfied
very dissatisfied
no opinion




We value your input.

Please tell us a little about yourself and your thoughts.

ADOBE COLDFUSION 8 599
ColdFusion Developer’s Guide


We really
want to hear from you!






ColdFusion XML format
This section describes the XML generated from a ColdFusion cfform tag and its children. It provides a building
block toward creating your own XSL skins.

XML namespace use
The XML that ColdFusion generates for forms uses elements and attributes in several XML namespaces. Namespaces
are named collections of names that help ensure that XML names are unique. They often correspond to a web
standard, a specific document type definition (DTD), or a schema. In XML, the namespace name and a colon (:)
precede the name of the tag that is defined in that namespace; for example xf:model for the XForms namespace
model tag.
ColdFusion uses several standard XML namespaces defined by the World Wid Web Consortium (W3C). These
namespaces correspond to specifications for standard XML dialects such as XHTML, XForms and XML Events.
ColdFusion XML forms also use a custom namespace for skinnable forms XML extensions. The following table lists
the namespaces in the XML that ColdFusion generates.
Prefix

URL

Used for

html

http://www.w3.org/1999/xhtml

Form tag information, including action, height, width, and name. XHTML
compliant.

xf

http://www.w3.org/2002/xforms

XForms model (including initial field values) and XForms elements that
correspond to cfform tags.

ev

http://www.w3.org/2001/xml-events

System events. Used for the cfinput type="reset".

cf

All ColdFusion extensions, including passthrough of attributes that do
not correspond to XForms elements or attributes.

XML structure
For each CFML tag, ColdFusion converts attributes and element values to XML in the XForms xf:model element,
or in individual control elements, such as the XForms xf:input, xf:secret, or xf:group elements.
ColdFusion generates XForms XML in the following format. The numbers on each line indicate the level of nesting
of the tags.
1
2
3
4
3
3
3
3

form tag
XForms model element
XForms instance element
cf:data element
XForms submission element
XForms bind element
XForms bind element
.

ADOBE COLDFUSION 8 600
ColdFusion Developer’s Guide

3
3
2
2
2

1

.
.
(end of model element)
XForms or ColdFusion extension control element
XForms or ColdFusion extension control element
.
.
.
(end of form)

The following sections describe the data model and the elements that make up the XForms document.

Data model
The XForms data model specifies the data that the form submits. It includes information on each displayed control
that can submit data, including initial values and validation information. It does not contain information about
cfformgroup or cfformitem tags. The data model consists of the following elements and their children:

•

One xf:instance element

•

One xf:submission element

•

One xf:bind element for each form control that can submit data

xf:instance element

The XForms xf:instance element contains information about the form data controls. Any control that can submit
data has a corresponding instance element. If the control has an initial value, the instance element contains that
value.
The xf:instance element contains a single cf:data element that contains an element for each data control:
cfgrid, most cfinput tag types, cfselect, cfslider, cftextarea, and cftree. Each element name is the corre-

sponding CFML tag’s name attribute. For applet and Flash format cfgrid and cftree tags, the element name is the
value of the cf_param_name parameter of the tree or grid’s Java applet object. Only cfinput tags of types submit,
image, reset and button do not have instance data, because they cannot submit data.
Each element’s body contains the initial control data from the CFML tag’s value attribute or its equivalent. For
example, for a cfselect tag, the xf:instance element body is a comma-delimited list that contains the name
attributes of all the option tags with a selected attribute. For submit and image buttons, the body contains the
name attribute value.
The following example shows the xf:instance element for the form shown in the image in “About XML skinnable
forms” on page 594:





Comment Form revision 12a
very satisfied
We really want to hear from you!


xf:submission element

The xf:submission element specifies the action when the form is submitted, and contains the values of the cfform
action and method attributes.:

ADOBE COLDFUSION 8 601
ColdFusion Developer’s Guide

The following example shows the XML for the form shown in the image in “About XML skinnable forms” on
page 594:

xf:bind elements

The xf:bind elements provide information about the input control behavior, including the control type and any
data validation rules. The XML has one bind element for each instance element that can submit data. It does not have
bind elements for controls such as cfformitem tags, or cfinput tags with submit, input, reset, or image types. Each
element has the following attributes:
Attribute

Description

id

CFML tag name attribute value

nodeset

XPath expression with the path in the XML to the instance element for the control

required

CFML tag required attribute value

Each xf:bind element has an xf:extension element with ColdFusion specific information, including type and
validation values. The following table lists the cf namespace elements that are used in this section:
Element

Description

cf:attribute name="type"

Control type. One of the following:
CHECKBOX, FILE, IMAGE, PASSWORD, RADIO, SELECT, SUBMIT TEXT, CFSLIDER.
The TEXT type is used for cfinput type="text" and cftextinput.

cf:attribute name="onerror"

JavaScript function specified by the control’s onError attribute, if any.

cfargument name="maxlength"

Value of the control’s maxlength attribute, if any.

cf:validate type="valiadationtype"

Data validation information.
Has one attribute, type, the validation type, and one or more cf:argument and
cf:trigger children. ColdFusion generates a cf:validate element for each of the
following:

•

cfinput or cftextarea validation attribute

•

cfinput or cftextarea range attribute

• cfslider: the range and message attributes are specified by a cf:validate
type="range" element

ADOBE COLDFUSION 8 602
ColdFusion Developer’s Guide

Element

Description

cf:argument

Data validation specification.

(in the body of a cf:validate element)

Has one attribute, name, and body text. Each cf:validate element can have multiple
cf:argument children, corresponding to the validation-related CFML tag attribute
values, such as maximum length, and maximum and minimum range values. The
element body contains the CFML attribute value.
Valid name values are as follows. Unless specified otherwise, the name is identical to the
corresponding CFML tag attribute name.

•

max

•

message

•

min

•

pattern

cf:trigger

When to do the validation; specifies a form element validateAt attribute value.

(in the body of a cf:validate element)

Has one attribute, event, which can be one of the following:

•

onBlur

•

onSubmit

•

onServer

If a validateAt attribute specifies multiple validation triggers, the XML has one
cf:trigger element for each entry in the list.

The following example shows the xf:bind element of the form shown in the image in “About XML skinnable forms”
on page 594:


TEXT
_CF_onError




TEXT
_CF_onError




TEXT
_CF_onError




SELECT
_CF_onError



ADOBE COLDFUSION 8 603
ColdFusion Developer’s Guide



TEXT
_CF_onError



Control elements
The XML tags that follow the xf:bind element specify the form controls and their layout. The XML includes one
element for each form control and cfformitem or cfformgroup tag.
CFML to XML tag mapping

ColdFusion maps CFML tags to XForms elements and ColdFusion extensions as the following table shows:
CFML tag

XML tag

cfinput type="text"

xf:input

cfinput type="password"

xf:secret

cfinput type="hidden"

None: instance data only

cfinput type="file"

xf:upload

cfinput type="radio"

xf:select1

cfinput type="checkbox"

xf:select

cfinput type="button"

xf:trigger

cfinput type="image"

xf:submit

cfinput type="reset"

xf:submit

cfinput type="submit"

xf:submit

cfselect multiple="false"

xf:select1

cfselect multiple="true"

xf:select

cftextarea

xf:textarea

cfslider

xf:range

cfgrid

cf:grid

cftree

cf:tree

cfformitem type="text"

xf:output

cfformitem type="html"

xf:output

cfformitem type="*" (all but text, html)

xf:group appearance="*"

cfformgroup type="*"

xf:group appearance="*"

ColdFusion converts cfformitem tags with text and html type attributes to XForms output elements with the tag
body in a 
label

controltype
attribvalue
.
.
.



The following table describes the variable parts of this structure:
Part

Description

tagname

The xf or cf namespace element name, as identified in the table in “CFML to XML tag mapping” on page 603.

bindid

ID attribute of the model xf:bind element for this control. Specified by the control’s CFML tag name attribute.

label

Control label text. Specified by one of the following:

controltype

•

The CFML tag label attribute

•

The value attribute of the radiobutton, submit, and reset cfinput tags

•

The tag body content of cfselect option subtags,

•

Not used for cfgrid and cftree tags.

Type of control. One of the following:

•

The cfinput type attribute

•

Select, slider, or textarea, for the cfselect, cfslider, or cftextarea tags, respectively.

•

Not used for cfgrid and cftree tags.

attribname

Name of a CFML tag attribute. There is a cf:attribute tag for each attribute specified in the CFML code that does
not otherwise have an entry in the XML.

attribvalue

Value of a CFML tag attribute.

Tag-specific element structure

The following sections describe tag-specific features of the XML for several types of input tags. It is not all-inclusive.
For the specific structure of any ColdFusion form tag, see the XML generated from the tag by ColdFusion.
Selection tags

Tags that are used for selection, cfselect, cfinput type="radio", and cfinput type="checkbox" are converted
to XForms select and select1 elements. These elements include an xf:choices element, which in turn has an
xf:item element for each item a user can choose. Each item normally has an xf:label element and an xf:value
element. Check boxes have a single item; select and radio button controls have more than one.
The following example shows the CFML code for a group of two radio buttons, followed by the generated XML
control elements. This example also shows the use of a cfformgroup tag to arrange and label the radio button group.
CFML



ADOBE COLDFUSION 8 605
ColdFusion Developer’s Guide



XML

Accept?



radio



Yes
Yes

checked



No
No





cfgrid tags

ColdFusion represents a cfgrid tag using the cf:grid XML tag. This tag has four attributes: format, which can be
Flash, Applet, or XML; and the id, name, and bind attributes, which all have the value of the cfgrid tag name
attribute.
For applet and Flash format grids, ColdFusion inserts cfgrid controls in the XML as HTML embed objects in


attributeValue
...
(There are an entry for attributes with a specified or default value.)



...



row1Column1Value
row1Column2Value
...


row2Column1Value
row2Column2Value

...


ADOBE COLDFUSION 8 606
ColdFusion Developer’s Guide



The following example shows a minimal grid with two nodes.
CFML






XML

Most metadata lines are omitted for brevity:


false
false
false
false
false
false
true
true
Left
true
true
Left
false
false
true
Left
false
false
Edit
<b> Browser must support Java to view ColdFusion Java
Applets</b>
false
insert
delete
SortAsc
SortDesc







one0
two0


one1
two1


ADOBE COLDFUSION 8 607
ColdFusion Developer’s Guide



The cftree tags

For applet and Flash format trees, ColdFusion inserts cftree controls in the XML as HTML embed objects in


attributeValue
...



...

...


The following example shows a minimal tree with two nodes:
CFML






XML

The following code shows only the XML that is related to the tree appearance:




windows
\
false
false
false
false
true
true
false
false




ADOBE COLDFUSION 8 608
ColdFusion Developer’s Guide



The cfformgroup and cfformitem tags

All cfformgroup tags and all cfformitem tags, except type="html" and type="text", generate xf:group
elements. The following rules determine the element structure:

•

The CFML tag type attribute determines the xf:group appearance attribute.

•

ColdFusion converts type attribute values to all-lowercase characters.

•

For cfformgroup tags only, the CFML label attribute determines the xf:group label attribute.

•

All other CFML attributes are put in cf:attribute elements in a xf:extension element.

•

The cfformitem tags generate an xf:output element with the body text in a 
Please tell us a little about yourself and your thoughts.


XML


color:green




200
3
testvalue


Example: control element XML

The following code shows the XML for the input controls for the form shown in the image in “About XML skinnable
forms” on page 594. This code immediately follows the end of the xf:model element.

name


First

text
20



Last

text
25



ADOBE COLDFUSION 8 609
ColdFusion Developer’s Guide



Email

text
email


We value your input.

Please tell us a little about yourself and your thoughts.]]>





Satisfaction

select
width:200



very satisfied
very satisfied


somewhat satisfied
somewhat satisfied


somewhat dissatisfied
somewhat dissatisfied


very dissatisfied
very dissatisfied


no opinion
no opinion




Additional Comments

textarea
5
40






Tell Us

submit
submit



ADOBE COLDFUSION 8 610
ColdFusion Developer’s Guide


Clear Fields


reset




Creating XSLT skins
You can create your own XSLT skins to process the XML that ColdFusion generates. You should be familiar with
XSLT and CSS programming. This document does not provide general information on writing XSLT transformations or CSS styles. It does provide information about the following areas:

•

How ColdFusion passes form attribute values to the XML file

•

How to extend XSLT skins that ColdFusion provides as templates

• Basic techniques for extending the basic.xsl file to support additional cfformgroup and cfformitem tag type
attributes
•

How to extend the ColdFusion CSS files to enhance form appearance.

XSLT skin file locations
If you specify an XSLT skin by name and omit the .xsl extension, ColdFusion looks for the file in the cfform script
source directory and its subdirectories. You can specify the script source directory in your cfform tag scriptsrc
attribute, and you can set a default location on the Settings page in the ColdFusion Administrator. When you install
ColdFusion, the default location is set to /CFIDE/scripts/ (relative to the web root).
You can also use a relative or absolute file path, or a URL, to specify the XSLT skin location. ColdFusion uses the
CFML page’s directory as the root of relative paths. The following formats are valid:
Format

Location



Searches for XML/CSS in the default directory and its subdirectories.



Uses the absolute path.



Searches in the current directory.



Searches the parent of the current directory.

 Uses the specified URL.

Note: Hosting companies might move the default skin location folder out of CFIDE; this lets them secure the CFIDE
while giving site developers access to the files that you need for cfform.

Attribute and value passthrough
ColdFusion passes form tag attributes or attribute values that it does not specifically process directly to the XML, as
follows:

•

It converts cfformitem and cfformgroup type attributes to xf:group element appearance attributes.

•

It passes the name and value of tag attributes that it does not recognize or process in cf:attribute elements.

ADOBE COLDFUSION 8 611
ColdFusion Developer’s Guide

This passthrough feature lets you create custom versions of any of the following items for your XSLT to process:

•

The cfformitem types, such as rules, spacers, or other display elements

•

The cfgroup types, such as divided boxes or tabbed dialog boxes

•

The custom cfinput types, such as a custom year chooser element

•

ColdFusion tag attributes, such as those used to control validation

Extending ColdFusion XSLT skins
ColdFusion provides basic XSLT transforms that you can use as templates and extend for making your own skin.
Each skin has a base XSL file, which include several utility XSL files. Utility filenames start with an underscore (_),
and the files are shared by multiple base skins. The following tables describes the XSL files, which are located in the
cf_webroot\CFIDE\scripts\xsl directory:
File

Description

default.xsl

The default transform that ColdFusion uses if you do not specify a skin attribute for an XML format form.
Identical to the basic.xsl file.

basic.xsl

A basic form format that arranges form elements using a table.

basiccss.xsl

A basic form format that arranges form elements using HTML div and span tags.

colorname.xsl

A basic form format that arranges form elements using a table and applies a color scheme determined by the
colorname to the form. Based on the basic.xsl file.

_cfformvalidation.xsl

Applies ColdFusion validation rules. Used by all skins.

_formelements.xsl

Transformation rules for form elements except for those defined using cfformgroup tags. Used by all skins

_group_type.xsl

Transformation rules for cfformgroup tags. The tag type attribute is part of the filename. Files with table in
the name are used by basic.xsl and its derivatives. Files with css in the name are used by basiccss.xsl.

_group_type_table.xsl
_group_type_css.xsl

All skins support the same set of CFML tags and tag types, and do a relatively simple transformation from XML to
HTML. For example, they do not support horizontal or vertical rules.
The ColdFusion skin XSL files have several features that you can use when designing and developing your own transformation. They do the following:

•

Provide an overall structure and initial templates for implementing custom transformations.

•

Show how you can handle the various elements in the ColdFusion-generated XML.

•

Use a structure of included files that can form a template for your XSLT code.

• The base XSL files include a separate file, _cfformvalidation.xsl, with complete code for generating the hidden
fields required for ColdFusion onServer validation and the JavaScript for performing ColdFusion onSubmit and
onBlur validation. You can include this file without modification to do ColdFusion validation in your XSLT template,
or you can change it to add other forms of validation or to change the validation rules.
• The base XSL files include files, that implement several form groups, laying out the child tags and applying a label
to the group. These files can serve as templates for implementing additional form group types or you can expand
them to provide more sophisticated horizontal and vertical form groups.
•

You can add custom cfformgroup and cfformitem type attributes by including additional XSL files.

ADOBE COLDFUSION 8 612
ColdFusion Developer’s Guide

Extending basic.xsl cfformgroup and cfformitem support

The following procedure describes the steps for extending the basic.xsl file to support additional cfformgroup and
cfformitem types. You can use similar procedures to extend other xsl files.
Add support for cfformgroup and cfformitem types to the basic.xsl
1 Create an XSL file.

For each type attribute that you want to support, create an xsl:template element to do the formatting. The
element’s match attribute must have the following format:

2

match="xf:group[@appearance='type_attribute_name']"

For example, to add a panel cfformgroup type, add an element with a start tag such as the following:


3

Deploy your XSL file or files to the cf_webroot\CFIDE\scripts\xsl directory.

4 Add an include statement to the basic.xsl file at the end of the Supported groups section; for example, if you
create a my_group_panel.xsl file to handle a panel cfformgroup type, your basic.xsl file would include the following
lines:

href="_group_vertical_table.xsl" />
href="_group_horizontal_table.xsl" />
href="_group_fieldset.xsl"/>
href="my_group_panel.xsl" />

Styling forms by extending the ColdFusion CSS files

Each ColdFusion skinnable form XSL file uses a corresponding CSS style sheet to specify the form style and layout
characteristics. The following CSS files are located in the cf_webroot\CFIDE\scripts\css directory:
File

Description

basic_style.css

Provides a plain style for ColdFusion XSL files that use table-based formatting. These files are identical and are
used by the basic.xsl and default.xsl transforms. ColdFusion uses the default_style.css if you do not specify a
skin in your cfform tag.

default_style.css
basic2_style.css

The basic_style with limited positioning changes for use with XSL files that have div-based formatting. Used
by the basiccss.xsl transform.

css_layout.css

Style specifications for laying out forms that use div-based formatting. Used by the basiccss.xsl transform.

colorname_style.css

Used by the color-formatted ColdFusion skins. Defines the same classes as basic_style.css, with additional
property specifications.

The ColdFusion XSL files and their corresponding CSS style sheets use classes extensively to format the form. The
basic.xsl file, for example, has only one element style; all other styles are class-based. Although the CSS files contain
specifications for all classes used in the XSL files, they do not always contain formatting information. The horizontal
class definition in basic_style.css, which is used for horizontal form groups, for example, is empty.
You can enhance the style of XML skinnable forms without changing the XSL transform by enhancing the style
sheets that ColdFusion provides.

613

Chapter 34: Using Ajax UI Components
and Features
You can use ColdFusion Ajax-based layout and form controls and other Ajax-based user interface capabilities to
create a dynamic application.
For information about how ColdFusion uses the Ajax framework in general, or how to use ColdFusion Ajax data and
programming capabilities, including binding to form data and managing JavaScript resources, see “Using Ajax Data
and Development Features” on page 647.
Contents

About Ajax and ColdFusion user interface features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613
Controlling Ajax UI layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615
Using menus and toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623
Using Ajax form controls and features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626

About Ajax and ColdFusion user interface features
Ajax (Asynchronous JavaScript and XML) is a set of web technologies for creating interactive web applications. Ajax
applications typically combine:

•

HTML and CSS for formatting and displaying information.

•

JavaScript for client-side dynamic scripting

•

Asynchronous communication with a server using the XMLHttpRequest function.

• XML or JSON (JavaScript Object Notation) as a technique for serializing and transferring data between the sever
and the client.
ColdFusion provides a number of tools that simplify using Ajax technologies for dynamic applications. By using
ColdFusion tags and functions, you can easily create complex Ajax applications.

ColdFusion Ajax features
ColdFusion provides two types of Ajax features:

•

Data and development features

•

User interface (UI) features

Data and development features

ColdFusion data and development features help you develop effective Ajax applications that use ColdFusion to
provide dynamic data. They include many features that you can use with other Ajax frameworks, including Spry.
The following data and development features are particularly important for use with form and layout tags:

ADOBE COLDFUSION 8 614
ColdFusion Developer’s Guide

• ColdFusion supports data binding in many tags. Binding allows form and display tags to dynamically display
information based on form input. In the simplest application, you display form data directly in other form fields, but
usually you pass form field data as parameters to CFC or JavaScript functions or CFM pages and use the results to
control the display.
• The cfajaximport tag specifies the location of the JavaScript and CSS files that a ColdFusion page imports or
to selectively import files required by specific tags. The ability to change the file location lets you support a wide
range of configurations and use advanced techniques, such as application-specific styles.
For more information about the data and development features and how to use them, see “Using Ajax Data and
Development Features” on page 647.
User Interface tags and features

Several ColdFusion user interface elements incorporate Ajax features. The tags and tag-attribute combinations can
be divided into the following categories:

•

Container tags that lay out or display contents

•

Forms tags that dynamically display data

•

A menu tag that lets you create menu bars and pull-down menus

•

User assistance features that provide tool tips and form completion

The following table lists the basic tags and attributes that display the Ajax-based features. For information on
additional forms-specific features, see “Using Ajax form controls and features” on page 626.
Tag/attribute

Description

Container tags
cfdiv

An HTML div region that can be dynamically populated by a bind expression. Forms
in this region submit asynchronously.

cflayout

A horizontal or vertical box, a tabbed region, or a set of bordered regions that can
include a top, bottom, left, right, and center regions.

cflayoutarea

An individual region within a cflayout area, such as the display that appears in a
tabbed layout when the user select a tab. Forms in this region submit asynchronously.

cfpod

An area of the browser window with an optional title bar and a body that contains
display elements. Forms in this region submit asynchronously.

cfwindow

A pop-up window within the browser. You can also use the
ColdFusion.Window.createWindow function to create a pop-up window. Forms
in this region submit asynchronously.

Forms tags
cfgrid format="html"

A dynamic, editable, sortable, data grid.

cfinput type="datefield"

An input control that users can fill by selecting a date from a pop-up calendar.

cftextarea richtext="yes"

A text area with a set of controls that let users format the displayed text.

cftree format="html"

A dynamic, editable, tree-format representation of data.

Menu tags
cfmenu

A menu bar or the root of a drop-down menu.

cfmenuitem

An individual item in a menu, or the root of a submenu.

ADOBE COLDFUSION 8 615
ColdFusion Developer’s Guide

Tag/attribute

Description

User assistance tags and attributes
cfinput type="text" autosuggest="bind
expression"

A drop-down autofill suggestion box. As the user types, a list appears with completion
suggestions based on the text the user has typed.

cftooltip tag, and the tooltip attribute on
cfinput, cfselect, cftextarea controls

A textual description of a control or region that appears when the user hovers the
mouse over the control or region.

In addition to the tags and attributes, ColdFusion provides a number of JavaScript functions that let you control and
manage the display. Many functions control the display of specific tags. For example, you can use JavaScript
functions to dynamically display and hide the window. There are also several utility tags, such as the
ColdFusion.getElementValue function that gets the value of a control attribute, or the ColdFusion.navigate
function that displays the results of a URL in a container tag. For a complete list of all ColdFusion Ajax JavaScript
functions, and detailed function descriptions, see “AJAX JavaScript Functions” on page 1246 in the CFML Reference.

Using ColdFusion Ajax UI features
ColdFusion Ajax UI features let you create data-driven pages that update dynamically without requiring multiple
HTML pages or page refreshes or non-HTML display tools such as Flash forms. Many UI features use data binding
to dynamically get data based on other data values: form field values, form control selections, and selections in Spry
data sets.
ColdFusion Ajax UI controls and features can be divided into two major categories:

•

Display layout

•

Data interaction

Display layout controls include the cflayout, cfpod, and cfwindow controls. Some of the data interaction features
include the HTML format cfgrid control, the cfmenu control, and dynamic autosuggest lists for text input controls.
Most display layout and data interaction features can use data binding to dynamically interact with the user.
ColdFusion Ajax UI features are based on the Yahoo User Interface Library and the Ext JavaScript Library. Also, the
cftextarea rich text editor is based on the FCKeditor text editor. In most situations, you require only ColdFusion
tags and functions (including JavaScript functions) to create and manage the interface; however, advanced developers can modify the library code, particularly the CSS styles, to customize the controls in more complex ways.

Controlling Ajax UI layout
The following layout tags let you dynamically control the display:

•

cfdiv

•

cflayout

•

cfpod

•

cfwindow

For information about how you can use these tags to submit form contents asynchronously, see “Using Ajax
containers for form submission” on page 626.

ADOBE COLDFUSION 8 616
ColdFusion Developer’s Guide

Using the cfdiv tag
The cfdiv tag is a general purpose container that lets you use a bind expression to specify its contents. It therefore
lets you dynamically refresh any arbitrary region on the page based on bind events. By default, the tag creates an
HTML div region, but it can create any HTML tag with body contents. Unlike other ColdFusion Ajax container tags,
you can use any type of bind expression to populate contents: CFC or JavaScript function, URL, or a string with bind
parameters. As a result, the cfdiv tag provides substantial flexibility in dynamically populating the page contents.
The cfdiv tag is also useful if you want a form to submit asynchronously, whether or not you use a bind expression
to populate the tag. If you submit a form that is inside a cfdiv tag (including in HTML returned by a bind
expression), the form submits asynchronously and the response from the form submission populates the cfdiv
region. (The cflayoutarea, cfwindow, and cfpod tags have the same behavior.) For example, you could have a page
with a form that includes a list of artists, and lets you add artists. If the form is in a cfdiv tag, when the user submits
the form, the entire page is not refreshed, only the region inside the cfdiv tag. For an example of using container
controls for asynchronous forms, see “Using Ajax containers for form submission” on page 626.
One use case for a cfdiv tag is an application where a cfgrid tag displays an employee list. Details of the selected
row in the grid are displayed inside a cfdiv tag with a bind expression that specifies the cfgrid in a bind parameter.
As users click through different employees on the grid, they get the employee details in the cfdiv region.
The following simple example shows how you can use the cfdiv tag to get data using a bind expression. It uses
binding to display the contents of a text input field in an HTML div region. Whenever the user enters text in the input
box and tabs out of it, or clicks on another region of the application, the div region displays the entered text.
The cfdiv tag.cfm file, the main application file, has the following contents.








 using a div




The divsource.cfm file that defines the contents of the div region has the following code:
Echoing main page input:


#url.InputText#

No input



Using layouts
The cflayout tag controls the appearance and arrangement of one or more child cflayoutarea regions. The
cflayoutarea regions contain display elements and can be arranged in one of the following ways:

•

Horizontally or vertically.

ADOBE COLDFUSION 8 617
ColdFusion Developer’s Guide

• In a free-form bordered grid (panel layout) with up to five regions: top, bottom, left. right, and center. You can
optionally configure the layout so that users can resize or collapse any or all of the regions, except the center region.
The center region grows or shrinks to take up any space that is not used by the other regions. You can also dynamically show or hide individual regions, or let users collapse, expand, or close regions.
• As a tabbed display, where selecting a tab changes the display region to show the contents of the tab’s layout area.
You can dynamically show and hide, and enable and disable tabs, and optionally let users close tabs.
You can configure a layout area to have scroll bars all the time, only when the area content exceeds the available
screen size, or never, and you can let layout area contents extend beyond the layout area. You can also nest layouts
inside layout areas to create complex displays.
You can define the layout area content in the cflayoutarea tag body, but you can also use a bind expression to
dynamically get the content by calling a CFC function, requesting a CFML page, or calling a JavaScript function.
ColdFusion provides a number of JavaScript functions for managing layouts, including functions to collapse,
expand, show, and hide border areas; and to create, enable, disable, select, show, and hide tabs. For a complete list of
functions, see “AJAX JavaScript Functions” on page 1246 in the CFML Reference.
The following example shows the use of a tabbed layout, including the use of JavaScript functions to enable and
disable a tab, and to show and hide a tab.








The First Tab

Here are the contents of the first tab.



The Second Tab

This is the content of the second tab.




Use these links to test selecting tabs via JavaScript:


Click here to select tab 1.


Click here to select tab 2.



Use these links to test disabling/enabling via JavaScript. Notice that you cannot disable
the currently selected tab.


Click here to enable tab 1.


ADOBE COLDFUSION 8 618
ColdFusion Developer’s Guide


Click here to disable tab 1.





For an example that uses a bordered layout with cfpod children, see the next section. For another example of a tab
layout, see the cflayoutarea tag in the CFML Reference. For an example of a bordered layout nested inside a layout
area of a vertical layout, see cflayout in the CFML Reference.
Styling layouts

The cflayout and cflayoutarea tags have style attributes. The cflayout tag style attribute controls the style
of the layout container, and sets default values for many, but not all, styles for the layout areas. For example, the color
and background color styles of the cflayout tag set the default text and background colors in the layout areas, but
the cflayout tag border style sets only the color of the border around the entire layout, not the layout area borders.
The cflayoutarea tag style attribute controls the style of the individual layout area and overrides any corresponding settings in the cflayout tag.
As is often the case with complex controls, the effects of layout and layout area styles can vary. For example, you
should often not specify the height style in the cflayout tag; instead, specify height styles on each of the
cflayoutarea tags.
The following simple example shows a tab layout with two layout areas. The layout has a light pink background color,
and the layout areas have 3 pixel-wide red borders.:


Layout area 1


Layout area 2



Using pods
The cfpod control creates a content region with a title bar and surrounding border. You can define the pod content
in the cfpod tag body, or you can use a bind expression to dynamically get the content from a URL. Pods are
frequently used for portlets in a web portal interface and for similar displays that are divided into independent,
possibly interactive, regions.
You control the pod header style and body style independently by specifying CSS style properties in the
headerStyle and bodyStyle attributes.

The following example uses multiple pods inside cflayoutarea tags to create a simple portal. The time pod gets the
current time from a CFML page. The contents of the other pods is defined in the cfpod bodies for simplicity. Each
pod uses the headerStyle and bodyStyle attributes to control the appearance.
The cfpodExample.cfm application has the following code:







ADOBE COLDFUSION 8 619
ColdFusion Developer’s Guide


Contents of a news feed would go here.




Contents of a sports feed would go here.





Contents of a news feed would go here.






In this example, the podweather.cfm page contains only the following line. A more complete example would dynamically get the weather from a feed and format it for display.
Partly Cloudy, 76 degrees

Using pop-up windows
ColdFusion HTML pop-up windows have the following characteristics:

•

They have title bars

•

They float over the browser window and can be placed at an arbitrary location over the window.

• They can be modal (users cannot interact with the main window when the pop-up window is displayed) or nonmodal (users can interact with both windows).
•

You can specify that the user can drag, close, or resize the window.

• You can create and show a window independently. After you create the window, you can use JavaScript functions
to show and hide it multiple times without having to create it again.
Displaying and hiding windows

You display a window in the following ways:

ADOBE COLDFUSION 8 620
ColdFusion Developer’s Guide

•

By using a ColdFusion cfwindow tag with an initShow attribute value of to create and show the window.

•

By using a ColdFusion cfwindow tag with an initShow attribute value of false and calling the

ColdFusion.Window.show JavaScript function to display it.

•

By by using ColdFusion.Window.create and ColdFusion.Window.show JavaScript functions.

You can hide a window that is currently showing by calling the ColdFusion.Window.hide function. You can use
the ColdFusion.Window.onShow and ColdFusion.Window.onhide functions to specify JavaScript functions to
run when a window shows or hides.
The following example shows how you can create, display, and hide a window. It also shows several of the configuration options that you can set, including whether the user can close, drag, or resize the window. When you run the
application, the cfwindow tag creates and shows Window 1. You can then hide it and reshow it. To show Window 2,
you must click the Create Window 2 button, followed by the Show Window 2 button. You can then hide and show it.
The following examples shows the main application page:








This content was defined in the cfwindow tag body.















ADOBE COLDFUSION 8 621
ColdFusion Developer’s Guide

The window2.cfm file with the contents of Window 2 has the following contents:


This content was loaded into window 2 from a URL.



Using the window show and hide events

You can use the onShow and onHide events that are triggered each time a window shows and hides to control your
application. To do so, call the ColdFusion.Window.onShow and ColdFusion.Window.onHide functions to specify
the event handlers. Both functions take the window name and the handler function as parameters. The event handler
functions can take a single parameter, the window name.
The following example displays an alert dialog when a window hides or shows. The alert message includes the
window name. The alert does not show when the window first appears, because the cfwindow tag uses the initShow
attribute to initially display the window. An alert dialog does appear when the user hides the window by clicking the
Toggle Window button or the close button on the window.






 Window contents



ADOBE COLDFUSION 8 622
ColdFusion Developer’s Guide






Controlling container contents
ColdFusion provides a variety of ways to set and change container tag contents:

• You can use bind expressions in the container tag source (or for cfdiv, bind) attribute. The container then
dynamically updates any time a bound control changes.
• You can call the ColdFuson.navigate function to change the container body to be the contents returned by a
specified URL. This function lets you specify a callback handler to do additional processing after the new content
loads, and also lets you specify an error handler.
The callback handler can be useful to provide information about a successful navigation operation. For example,
you could make a pod's title bar italic to indicate loading (just before the navigate call), and use the callback
handler to switch it back to normal once the navigate completes. Similarly, if a pod is shows pages from a book,
the callback handler could update a page number in a separate field once a page loads

•

You can use the special controlName_body variable to access and change the body contents for cfpod and
cfwindow controls. For example, you can use the controlName_body.innerHTML property to set the body HTML.
For cfpod and cfwindow tags, you can also use the controlName_title to get or set the control’s title bar contents.
These different techniques provide you with flexibility in writing your code. For example, the ColdFuson.navigate
function and the controlName_body variable provide similar functionality. However, with the controlName_body
technique, you must make explicit Ajax requests to get markup for the body, and the JavaScript functions in the
retrieved markup might not work properly. ColdFusion.navigate takes care of these issues. Therefore, you might
limit use of the controlName_body technique to simpler use cases.
The following example shows how you can use various techniques to change container contents. It consists of a main
page and a second windowcontent.cfm page with text that appears in a main page window when you click a button.
The main page has a cfpod control, two cfwindow controls, and the following buttons:

• The “Simple navigate” button calls a ColdFusion.navigate function to change the contents of the second
window.
• The “Change w2 body & title” button replaces the second window’s body and title innerHTML values directly to
specific strings.
• The “Change pod body” button changes the pod body innerHTML to the value of the second window’s title
innerHTML.
The following examples shows the main page:







This is a cfpod control.




This is a cfwindow control.


Click to navigate Window 2


This is a second cfwindow control.












The following examples shows the windowsource.cfm page:
This is markup from "windowsource.cfm"



Using menus and toolbars
The cfmenu and cfmenuitem tags let you create vertical menus and horizontal toolbars.

Defining menus
You define menus and toolbars as follows:

•

You use a single cfmenu tag to define the general menu characteristics.

ADOBE COLDFUSION 8 624
ColdFusion Developer’s Guide

•

You create a horizontal (toolbar) menu or vertical menu by specifying a cfmenu type attribute value of

horizontal or vertical (the default).

• Menus can have submenus, but only the top menu can be horizontal. All children of a horizontal menu are
vertical.
• The top-level menu shows initially, a submenu shows when the user moves the mouse over the menu root in the
parent menu.
•

You use cfmenuitem tags to specify individual menu items.

•

To create submenus, you nest cfmenuitem tags. The parent tag becomes the root of the submenu.

• All cfmenuitem tags, except tags for dividers, must have a display attribute, which defines the text to show on
the menu item, and can optionally have an image attribute.
•

A horizontal menu has dividers between all items. You put dividers in vertical menus by specifying a

cfmenuitem tag with a divider attribute.

• To make a menu item active, you specify a href attribute with a URL or a JavaScript function to call when the
user clicks the menu item.
The following example shows a simple horizontal menu with submenus that uses JavaScript to change the display
contents. When the user selects an end item in a menu, the text in the div block below the menu shows the path to
the selected menu.























Please select an item!



Styling menus
The cfmenu and cfmenuitem tags have several attributes that let you easily control the menu appearance. These
attributes consist of two types: basic and CSS style. Basic attributes, such as the cfmenu tag fontColor attribute,
control individual menu characteristics. CSS style attributes let you specify a CSS style specification for a whole
menu or part of a menu. The following information describes how the CSS style specifications interact and affect the
menu style. For descriptions of all style-related attributes, see the cfmenu and cfmenuitem descriptions in the CFML
Reference.
The cfmenu and cfmenuitem tags provide a hierarchy of CSS style attributes that affect different parts of the menu.
The following table describes these attributes in hierarchical order:
Attribute

Description

cfmenu attributes
menuStyle

Applies to the menu, including any parts of the menu that surround the menu items. If you do not
override this style in a cfmenu tag childStyle attribute or by specifying style information in the
cfmenuitem tags, this attribute controls the style of the top-level items.

childStyle

Applies to the items in the top level menu and all child menu items, including the children of submenus. This
attribute lets you use a single style specification for all menu items.

cfmenuitem attributes
style

Applies to the current menu item only. It is not overridden by the childStyle attribute.

menuStyle

Controls the overall style of any submenu of this menu item. This attribute controls the submenu of the
current menu item, but not to any child submenus of the submenu.

childStyle

Applies to all child menu items of the current menu item, including the children of submenus.

In addition to these styles, you must consider any style-related attributes, such as bgcolor, that you set on the
cfmenu tag.
When you design your menu, you should keep the following issues in mind:

• Keep font sizes at 20 pixels or smaller. Larger sizes can result in menu text in vertical menus exceeding the menu
boundaries.
• Consider how the style attributes interact. Because each menu and submenu consists of a surrounding menu area
and individual child items, you must particularly careful when you choose background colors. For example, if you
specify different background-color styles in the cfmenu tag’s menuStyle and childStyle attributes, the menu
items are one color and the surrounding menu area are a different color.
For an application that shows some of the effects of menu style attributes, see the example in the cfmenuitem tag in
the CFML Reference.
ColdFusion attributes provide most style options that you are likely to require. However, you can, if necessary,
modify the basic menu styles for all menus by editing the menu-related styles in the CSS files in the yui.css file. This
file is located by default in the web_root/CFID/scripts/ajax/resources/yui directory. For more information about
these styles, see the Yahoo! User Interface Library menu documentation.

ADOBE COLDFUSION 8 626
ColdFusion Developer’s Guide

Using Ajax form controls and features
ColdFusion HTML format forms and controls provide the following Ajax-based features:

•

The cfgrid, cfinput, cfselect, cftextarea, and cftree controls support binding to get control contents.

• ColdFusion functions support asynchronous submission of forms without refreshing the entire page. When a
form is in an Ajax container control, this is done automatically. Also, the ColdFusion.Ajax.SubmitForm JavaScript
function and Ajax proxy setForm function support manual asynchronous submissions.
•

The cfgrid and cftree tags provide HTML format grids and trees that do not require a Java applet or Flash.

•

The cftextarea control has a rich text editor option. The text editor is configurable.

• The cfinput tag supports a datefield type with an Ajax-based pop-up calendar from which user can select
the date.
• The cfinput tag with text type supports an autosuggest attribute that lets you dynamically supply a dropdown list of field completions based on the current user input.
• The cfinput, cfselect, and cftextarea tags support a tooltip attribute that specifies a pop-up tool tip to
display when the user moves the mouse over the control. The cftooltip tag displays a tool over any region of a page,
not just a form control.

Using Ajax form controls
ColdFusion Ajax-based form controls let you submit Ajax forms in your applications without refreshing the entire
page.
Using Ajax containers for form submission

The ColdFusion Ajax container tags, cfdiv, cflayoutarea, cfpod, and cfwindow, automatically submit any forms
that they contain asynchronously. When the form is submitted, the result returned by the action page replaces the
contents of the container, but has no effect on the rest of the page.
The following example shows this behavior in the submitSimple.cfm page:






This area is not refreshed when the form is submitted.




This form is replaced by the action page









ADOBE COLDFUSION 8 627
ColdFusion Developer’s Guide

In the following example, when you enter a name in the text input and click the Enter name button, the entered text
replaces the form on the page, but the rest of the page is not refreshed. This example shows the showName.cfm action
page:

The Name is : #Form.name#

Using the cfajaxproxy SetForm function

The SetForm function of the proxy object created by the cfajaxproxy tag causes the proxy to pass the form values
as arguments to the next CFC function that you call after the SetForm function. This way, you can pass the current
values of fields in a form to a CFC function, which can then do the necessary processing and return a result.
When you use the SetForm function, the following rules apply to the arguments in the called CFC function:

• The function does not need to specify the form fields in cfargument tags, and the function gets the field values
passed by name.
•

Form fields that have the same names as CFC arguments override the CFC argument values.

• If you do not specify form fields in the in cfargument tags, They do not necessarily immediately follow any
declared arguments when you use positional (array) notation to access them in the arguments structure.
• The arguments scope in the CFC function includes two fields that ColdFusion uses to control its behavior.
These fields are intended for internal use, and their names might change in future releases. Both field values are set
to true:
•

_CF_NODEBUG tells ColdFusion not to return debugging output in the call response.

• _CF_NOCACHE tells ColdFusion to send a no cache header on the response, which prevents the browser from
caching the response and ensures that every Ajax request results in a network call.
The following example shows how you could use a the SetForm tag to submit the contents of a login form. When
the user clicks the Login! button, the doLogin function calls the proxy setForm function and then the
AuthenticationSystem.cfc validateCredentials method. The validateCredentials method checks the
user’s password and if it is valid, returns true to the proxy. Because the proxy is synchronous (the default), the
doLogin method gets the returned value. If the value is true, it hides the login window; the user can then access the
page contents. If the return value is false, the doLogin function displays a message in the login window title bar.
The following examples shows the setForm.cfm application:





ADOBE COLDFUSION 8 628
ColdFusion Developer’s Guide


















This page is secured by a login.
You can see the window containing the login form.
The window is modal so the page cannot be accessed until you login.

Continue using the application!
Logout!





The following examples shows the AuthenticationSystem.cfc file:

















ADOBE COLDFUSION 8 629
ColdFusion Developer’s Guide

Using the ColdFusion.Ajax.submitForm function

You can use the ColdFusion.Ajax.submitForm function to submit form contents to a CFML page (or other active
page) at any time. For example, you could use this function to automatically save a partially completed form.
When you use this function, you pass it the name of the form to submit and the URL of the page that processes the
form. You can also specify the following optional parameters:

•

A callback function that handles the returned results

•

An error handler that takes two parameters, an HTTP error code and a message

•

The HTTP method (by default, POST)

•

Whether to submit the form asynchronously (by default, true)

The following proof of concept example uses the ColdFusion.Ajax.submitForm function to submit two form
fields to an asyncFormHandler.cfm page, which simply echoes the form values. The callback handler displays an
alert with the returned information.












Submit form



The asynchFormHandler.cfm page consists of a single line, as follows:
Echo: #form.mytext1# #form.mytext2#

ADOBE COLDFUSION 8 630
ColdFusion Developer’s Guide

Using the ColdFusion.navigate function to submit a form

The ColdFusion.navigate JavaScript function can submit a form to a URL and have the returned output appear
in a specified container control, such as a cfdiv, cflayout, cfpod, or cfwindow tag. This function lets you populate
a control other than the one that contains the form when the user submits the data. You can also use the function to
submit the form asynchronously when a user performs an action outside the form, such as clicking on a menu item.
For an example that uses this function, see the ColdFusion.navigate function in the CFML Reference.

Using HTML format grids
The ColdFusion HTML format cfgrid control lets you use a bind expression to dynamically populate the grid.
HTML format grids that use bind expressions are paged; as users navigate from page to page of the grid, the grid
dynamically gets the data for only the required page from the data source. You also use bind expressions when you
let users edit form contents, and other ColdFusion controls can bind to the grid. Also, HTML format grids provide
several JavaScript functions that you can use to manage and manipulate the grids.
You can also create a static HTML format grid by specifying a cfgrid tag that does not use a bind expression. With
static grids, all data is initially available.
Dynamically filling form data

HTML format grids can dynamically fill the grid data by using a bind attribute with a bind expression that calls a
CFC or JavaScript function, or a URL. The bind expression uses bind parameters to specify dynamic information
provided by the grid and the values of any other form field attributes.
You must pass the following bind parameters to the bind expression. If you omit any of the parameters in the
function call or URL, you get an error. These parameters send information about the grid and its state to the data
provider function. The data for these parameters is provided automatically. You do not set any values manually.
Parameter name

Description

cfgridpage

The number of the page for which to retrieve data.

cfgridpagesize

The number of rows of data in the page. The value of this parameter is the value of the pageSize attribute.

cfgridsortcolumn

The name of the column that determines the sorting order of the grid. This value is set only after the user clicks
on a column heading.

cfgridsortdirection

The direction of the sort, may be 'ASC' (ascending) or 'DESC' (descending). This value is set only after the user
clicks on a column heading.

Note: The cfgridsortcolumn and cfgridsortdirection parameters can be empty if the user or application has not
sorted the grid, for example, by clicking a grid column header.
For more information on binding and bind parameters, see “Using Ajax Data and Development Features” on
page 647 in the CFML Reference.
You can use optional parameters to specify additional information to pass to the called function. These parameters
provide data that the called function requires to determine the data to return. For example, if the function returns
the cities in a state, you would pass it the state name. Any or all of the optional function parameters can be bind
parameters. A state name, for example, could come from the selection in a states cfselect control.
If you do not want the grid to refresh automatically when other controls change, you can use the @none specifier on
all optional bind parameters. This prevents automatic updating of the grid based on the bound control values. You
use the ColdFusion.Grid.refresh JavaScript function to explicitly refresh the grid contents. For more information on this use of the @none specifier and explicitly refreshing the control, see “Specifying bind parameters” on
page 650.

ADOBE COLDFUSION 8 631
ColdFusion Developer’s Guide

If the grid supports user sorting of the data (the sort attribute is true), the function called by the bind expression
must return data in the desired sorted order, and must use the values of the cfgridsortcolumn and
cfgridsortdirection bind parameters to determine the order. Even if you do not allow user sorting, you must still
pass these parameters to the function; otherwise, you get an error. Also, your function or action page must handle
cases where these parameters are empty strings, because their values are not set until the user selects a column header
to sort the grid, or you call the JavaScript ColdFusion.Grid.sort function.
The format of the returned data depends on how you get the data:
Bind type

Return value

CFC

A ColdFusion structure. ColdFusion automatically converts the structure for return to the caller. Alternatively,
you can return a JSON representation of the structure.

URL

A JSON representation of a structure. No other body contents is allowed.

JavaScript

A JavaScript object.

When you specify a CFC in the bind attribute, use the queryConvertForGrid function to convert a query directly
into a structure that you can use as your CFC return value.
When you specify a CFML page in the bind attribute, use the queryConvertForGrid function to convert a query
into a structure, and then use the serializeJSON function to convert the structure into a JSON representation.
If you manually create a JavaScript object or its JSON representation, it must have two top-level keys:

• TOTALROWCOUNT: The total number of rows in the query data set being returned. This value is the total number
of rows of data in all pages in the grid, and not the number of rows in the current page.
•

QUERY: The contents of the query being returned. The QUERY value must also be an object with two keys:

•

COLUMNS: An array of the column names.

• DATA: A two-dimensional array, where the first dimension corresponds to the rows and the second
dimension corresponds to the field values, in the same order as the COLUMNS array.
Note: If a CFC manually creates a return structure, the QUERY value can be a ColdFusion query object; ColdFusion
automatically converts it for remote access.
The following example defines an object that a JavaScript bind function can return to provide the data for a cfgrid
tag:
var myobject =
{"TOTALROWCOUNT":6,"QUERY":{"COLUMNS":["EMP_ID","FIRSTNAME",
"EMAIL"],"DATA":[[1,"Carolynn","CPETERSON"],
[2,"Dave","FHEARTSDALE"], [3,"Linda","LSTEWART"],
[4,"Aaron","ASMITH"], [5,"Peter","PBARKEN"],
[6,"Linda","LJENNINGS"],]}};

The following example uses a bind expression and a CFC to populate a dynamic, paged, data grid. The CFML page
contains the following form:








ADOBE COLDFUSION 8 632
ColdFusion Developer’s Guide








The places.cfc file looks as follows. Notice that the query gets the full data set each time the function gets called. the
QueryConvertForGrid function selects and returns only the required page of data:







SELECT Emp_ID, FirstName, EMail
FROM Employees

order by #gridsortcolumn# #gridsortdirection#






The following example is equivalent to the previous one, but uses a URL bind expression in the main page and a
CFML page to return the data.
The main page contains the following form:














The following examples shows the getdata.cfm page:



SELECT Emp_ID, FirstName, EMail
FROM Employees

order by #sortcol# #sortdir#



ADOBE COLDFUSION 8 633
ColdFusion Developer’s Guide


#serializeJSON(QueryConvertForGrid(team, page, pageSize))#


If your database lets you specify SQL to retrieve only the required page of data in a query, you can optimize efficiency
by using such a query. Do not use the QueryConvertForGrid function. Instead, manually create the return structure
and return only the single page of data. Ensure that you set the TotalRowCount field to the number of rows in the
entire data set, not the number of rows in the returned page of data.
Using the bindOnLoad attribute

The bindOnLoad attribute causes a control to execute its bind expression immediately when it loads, and not wait
until the event that normally triggers the bind expression evaluation to occur. This way, the control can be filled with
an initial value. This attribute is false by default for all ColdFusion Ajax controls that have the attribute, except
cfdiv and cfgrid, for which it is true by default. Having a true bindOnLoad value on these controls ensures that
they are populated when they load.
When a control with a true bindOnLoad attribute is bound to a control that also binds when the page loads, the first
and second control load themselves at the onLoad page event. Then the first control loads itself again in response to
a change event from the second control when that control completes loading. So, the first control makes two Ajax
calls, whereas it should make only one, when the second control finished loading.
Because the cfinput, cfselect, and cftextarea control bindOnLoad attributes are false by default, you do not
encounter any problems if a cfgrid or cfdiv tag binds to any of these controls and you do not explicitly set the their
bindOnLoad attributes. However, if the control does set its bindOnLoad attribute to true, you should set the cfgrid
or cfdiv attribute to false to ensure that the control only fetches data when the control that it is bound to returns.
You can also get a double loading if a grid binds to a Spry data set. By default, the grid and data set load data at page
load, and then the grid loads data again in response to a selection change event from the data set when the it sets
focus to its first row. Set bindOnLoad to false to ensure that the grid fetches data only when it receives a selection
change event from the data set.
Dynamically editing grid contents

When you use a bind expression to get cfgrid data dynamically, you can also update the data source dynamically
with user input, without requiring the user to submit the form. You can use dynamic updating to update or delete
data in the data source. (To edit cfgrid data, select the contents of a field and type the new value; to delete a row,
select a field in the row and click the delete button at the bottom of the grid.)
You cannot insert new rows directly in a grid that uses a bind expression. To add rows, you must enter the data in a
form, and make sure the grid refreshes after the form has been submitted.
To update or delete data dynamically, do the following:

•

Specify selectmode="edit" in the cfgrid tag. This lets the user edit the grid.

• Specify an onChange attribute in the cfgrid tag. The attribute must use a bind expression to specify a CFC
method, JavaScript function, or URL of a page that updates the data source. The bind expression has the same format
as the bind expression described in “Dynamically filling form data” on page 630; however, it must take the following
bind parameters, which are automatically passed by the grid. These parameters send information about the grid and
its state to the onChange function.
Parameter name

Description

cfgridaction

The action performed on the grid. 'U' for update, or 'D' for delete.

ADOBE COLDFUSION 8 634
ColdFusion Developer’s Guide

Parameter name

Description

cfgridrow

A structure or JavaScript Object whose keys are the column names and values are the original values of
the updated or deleted row.

cfgridchanged

A structure or JavaScript Object with a single entry, whose key is the name of the column with the changed
value, and whose value is the new value of the field. If the grid action is delete, this structure exists but is
empty

When you update data dynamically, you can also use the onError attribute to specify the name of a JavaScript
function to handle any errors that result in a CFC or URL returning an HTTP error status. The method must take
two parameters: the HTTP error code and a text message that describes the error. The following example shows an
onError handler function:


The following example displays the members of a department and lets users edit the data in the fields. When the
focus leaves the edited field an onChange event triggers and the form calls the editData CFC function to update the
data source.















The getData function is identical to the getData function in “Dynamically filling form data” on page 630. This
example shows the editData function in the CFC:









ADOBE COLDFUSION 8 635
ColdFusion Developer’s Guide


update employees set #colname# =
'#value#'
where Emp_ID = #gridrow.Emp_ID#



delete from employees where emp_id = #gridrow.Emp_ID#





Binding controls to grid contents

You can bind the contents of a form control to the data in a grid field by specifying a bind parameter as the form
control bind attribute value. To do so, use the following syntax:


By default, each time the selected row in the grid changes, the bind parameter is reevaluated, and the control value
changes to the value of the specified column of selected grid cell.
Grid JavaScript functions

You can use the following JavaScript functions to manage an HTML format grid:
Function

Description

ColdFusion.Grid.getGridObject Gets the underlying Ext JS JavaScript library object.
ColdFusion.Grid.refresh

Manually refreshes a displayed grid.

ColdFusion.Grid.sort

Sorts the grid.

For more information, see the ColdFusion.Grid.getGridObject, ColdFusion.Grid.refresh, and
ColdFusion.Grid.sort functions in the CFML Reference.

Using HTML format trees
An HTML format cftree tag creates an Ajax-based tree data representation that you can populate from a query or
a bind expression. The behavior with a query is equivalent to that of applet or Flash format trees. Bind expressions
let you populate the tree based on the values of other controls or Spry data sets. Also, when you use a bind expression,
the tree loads dynamically, getting only the data required for the current display.
Populating the tree using a bind expression

You use the bind attribute and bind expressions to dynamically and incrementally load and display tree data as the
user navigates the tree. The child tree items do not exist until the parent node expands. This behavior avoids
prefilling a tree with large amounts of data, lets the tree children change dynamically (you can optionally get the
children each time the item expands), and can enhance application responsiveness.
For more information about binding and bind parameters, see “Binding data to form fields” on page 649.
Bind expressions in trees work in the following ways:

• If you use a bind expression, the cftree tag can have only a single cftreeitem tag. Therefore, the function or
URL called by the bind expression must be able to populate all levels of the tree.

ADOBE COLDFUSION 8 636
ColdFusion Developer’s Guide

• When a tree item expands, the CFC or JavaScript function or active page specified by the bind attribute returns
an array with the values for the item’s child nodes, and the dynamic tree code on the client constructs the child items
by using these values.
• When a control to which the tree is bound generates an event that the tree is listening for, the tree is refreshed.
For example, if the tree uses a bind expression that includes a select box as a bind parameter, the tree collapses to the
root nodes when the selected value in the select box changes.
When you use a bind expression to populate a cftree control, you must specify a CFC function, JavaScript function,
or URL, and must pass it the following bind parameters. If you omit either of the parameters from your function call
or URL, you get an error. These parameters provide information about the tree and its state, and are automatically
provided by the control.
Bind parameter

Description

{cftreeitempath}

Passes the path in the of the current (parent) node to the method, which will use it to generate the next node.

{cftreeitemvalue}

Passes the current tree item value (normally the value attribute)

The called function or URL cannot return nested arrays and structures, that is, it can only return a single level of
items.
When a function or URL is first called to populate the root-level tree items, the value passed in the
cftreeitemvalue variable is the empty string. Your bind function can test for an empty string to determine that it

is populating the root level of the tree.
The @none event specifier is also useful if you use the ColdFusion.Tree.refresh JavaScript function to manually
refresh the tree. When you call the Refresh function, the bind expression fetches data from all bind parameters,
including @none parameters. If you specify @none in all bind parameters that specify other controls, the tree does not
respond automatically to changes in the other controls, but it does pick up data from the bind parameters when you
use the ColdFusion.Tree.Referesh function to explicitly refresh the tree.
The format of the data that the function or URL in a bind expression must return depends on the type of bind
expression
Bind type

Return value

CFC

A ColdFusion array of structures. ColdFusion automatically converts the structure to JSON format when it
returns the result to the caller. Alternatively, you can return a JSON representation of the structure.

JavaScript

A JavaScript Array of Objects.

URL

A JSON representation of an array of structures. No other body content is allowed.

Each structure in the array of structures or objects defines the contents and appearance of the node for a child item.
Each structure must have a VALUE field, and can have the following fields. With the exception of LEAFNODE, these
structure keys correspond to cftreeitem attributes.

•

DISPLAY

•

EXPAND

•

HREF

•

IMG

•

IMGOPEN

•

LEAFNODE

•

TARGET

ADOBE COLDFUSION 8 637
ColdFusion Developer’s Guide

Note: If a CFC does not return a value field, you do not get an error, but the tree does not work properly.
The LEAFNODE structure element is only used in the bind response structures. It must be a Boolean value that
identifies whether the node is a leaf. If the value is true, the tree does not show a +/- expansion indicator in front of
the node, and users cannot expand the node.
If your bind expression specifies a JavaScript function, the function must use all-uppercase letters for the field names;
for example, use VALUE and DISPLAY, not value and display. ColdFusion uses all capital letters in the structure key
names. ColdFusion is case-insensitive, so CFCs can use lowercase letters for the field names; JavaScript is casesensitive, so the JavaScript function must match the uppercase field names.
If you use a URL to get the tree items from a CFML page, you can use the serializeJSON function to convert the
array to JSON format. If the array with the tree items is named itemsArray, for example, the following line specifies
the page output:
#serializeJSON(itemsArray)#

Example 1: a simple tree

The following simple example creates a simple hierarchical tree of unlimited depth, with one node per level. Each
node label (specified by the display attribute) identifies the node depth:
The following example shows the CFML page:






The following examples shows the maketree.cfc file with the getNodes method that is called when the user expands
a node:

















Handling leaf nodes

Code that returns the information for leaf nodes of the tree should always set the LEAFNODE structure field to true.
This prevents the tree from displaying a + expansion indicator in the tree leaf node tree entries and from attempting
to expand the node. The following example shows how you use the LEAFNODE field.

ADOBE COLDFUSION 8 638
ColdFusion Developer’s Guide

Example 2: a more complex tree with leaf node handling

The following tree uses the cfartgallery database to populate a tree where the top level is the art medium, the second
level is the artist, and the leaf nodes are individual works of art. When the user clicks on an art work, the application
shows the art image.
This example shows how to generate return values that are specific to the level in the tree and the parent value and
the use of the LEAFNODE return structure element.
In this application, the CFC return structure keys are specified in lowercase letters, and ColdFusion automatically
converts them to uppercase. Notice that the database contains entries only for the painting, sculpture, and photography categories, so just those top-level tree nodes have child nodes.
The following examples shows the main application page:













The following example shows the tree.cfc file:








ADOBE COLDFUSION 8 639
ColdFusion Developer’s Guide







SELECT mediaid, mediatype
FROM media










SELECT artists.lastname, artists.firstname, artists.artistid
FROM art, artists
WHERE art.mediaid = 
AND art.artistid = artists.artistid
GROUP BY artists.artistid, artists.lastname, artists.firstname










SELECT art.artid, art.artname, art.price, art.description,
art.largeimage, artists.lastname, artists.firstname
FROM art, artists
WHERE art.mediaid = 
AND art.artistid = artists.artistid
AND artists.artistid = 













ADOBE COLDFUSION 8 640
ColdFusion Developer’s Guide




Binding other controls to a tree

ColdFusion tags that use bind expressions can bind to the selected node of a tree by using the following formats:

•

{[form:]tree.node} retrieves the value of the selected tree node.

• {[form:]tree.path} retrieves the path of the selected tree node. If the completePath attribute value is true, the
bound path includes the root node.
The bind expression is evaluated each time a select event occurs on an item in the tree. If you specify any other
event in the bind parameter, it is ignored.
Tree JavaScript functions

You can use the following JavaScript functions to manage an HTML format tree:
Function

Description

ColdFusion.Tree.getTreeObject

Gets the underlying Yahoo User Interface Library TreeView JavaScript object.

ColdFusion.Tree.refresh

Manually refreshes a tree.

For more information, see the ColdFusion.Tree.getTreeObject and ColdFusion.Tree.refresh functions in
the CFML Reference.

Using the rich text editor
The ColdFusion rich text editor lets users enter and format rich HTML text by using an icon-driven interface based
on the open source FCKeditor Ajax widget. The editor includes numerous formatting controls, and icons for such
standard operations as searching, printing, and previewing text. This topic does not cover the text editor controls.
For detailed information on the editor icons and controls, see http://wiki.fckeditor.net/UsersGuide.
The following example shows a simple rich text editor. When a user enters text and clicks the Enter button, the application refreshes and displays the formatted text above the editor region.






#form.text01#










Note: If you use the rich text editor in your pages, you cannot configure your web server to have ColdFusion process files
with the .html or .htm extensions. The default HTML processor must handle pages with these extensions.

ADOBE COLDFUSION 8 641
ColdFusion Developer’s Guide

Configuring the rich text editor

You can customize the rich text editor in many ways. The cftextarea attributes support some basic customization
techniques. For more detailed information, see the FCKEditor website at http://wiki.fckeditor.net/.
Defining custom toolbars

You can use the following techniques to control the appearance of the toolbar:

•

Specify the toolbar name in the toolbar attribute

•

Create custom toolbars in the fckconfig.js file.

The editor has a single toolbar consisting of a set of active icons and fields, and separators. The toolbar attribute
lets you select the toolbar configuration. The attribute value specifies the name of a toolbar set, which you define in
a FCKConfig.ToolbarSets entry in the cf_webRoot/CFIDE/scripts/ajax/FCKEditor/fckconfig.js file.
The rich text editor comes configured with two toolbar sets: the Default set, which contains all supported editing
controls, and a minimal Basic set. By default, the editor uses the Default set. To create a custom toolbar named
BasicText with only text-editing controls, create the following entry in the fckconfig.js file, and specify
toolbar="BasicText" in the textarea tag.
FCKConfig.ToolbarSets["BasicText"] = [
['Source','DocProps','-','NewPage','Preview'],
['Cut','Copy','Paste','PasteText','PasteWord','-','Print','SpellCheck'],
['Undo','Redo','-','Find','Replace','-','SelectAll','RemoveFormat'],
['Bold','Italic','Underline'],
['Outdent','Indent'],
['JustifyLeft','JustifyCenter','JustifyRight','JustifyFull'],
'/',
['Style','FontFormat','FontName','FontSize'],
['TextColor','BGColor'],
['FitWindow','-','About']
];

This configuration defines a toolbar with two rows that contain a subset of the full tool set designed to support basic
text editing.
Follow these rules when you define a toolbar:

•

Start the definition with FCKConfig.ToolbarSets.

• Specify the toolbar name in double quotation marks and square brackets ([""]). You must use this name, case
correct, in the cftextarea tag toolbar attribute.
•

Follow the toolbar name with an equals sign (=).

•

Place all the toolbar controls inside a set of square brackets, and follow the definition with a semicolon (;).

•

Group controls in square brackets.

•

Put each entry in single quotation marks (') and separate the entries with commas (,).

•

Use the hyphen (-) character to specify a separator.

•

Use a forward slash (/) character to start a new row.

For a complete list of the valid toolbar entries, see the Default configuration in fckconfig.js.
Defining custom styles

You can add custom styles that users can chose in the Styles selector and apply to selected text. To create a custom
style, add a Style element to /CFIDE/scripts/ajax/FCKEditor/fckstyles.xml. The Style XML element has the
following format:

ADOBE COLDFUSION 8 642
ColdFusion Developer’s Guide

•

The name attribute specifies the name that appears in the Style selector.

•

The element attribute specifies the HTML element that surrounds the text.

•

Each Attribute child element defines the name and value of an attribute of the HTML tag.

For example, the following definition creates a style that makes the selected text bold and underlined:


You can use a custom XML file, instead of fckstyles.xml, to define your styles. If you do so, specify the filepath in the
stylesXML attribute.
Defining custom templates

The editor includes a set of basic templates that insert HTML formatting into the textarea control. For example,
the Image and Title template puts a placeholder for an image on the left of the area, and a title and text to the right
of the image. Then you can right-click the image area to specify the image source and other properties, and replace
the placeholder title and text.
You create your own templates by creating entries in cf_webRoot/CFIDE/scripts/ajax/FCKEditor/fcktemplates.xml
file. Each template XML entry has the following format:


The template title, image and description appear in the Templates dialog box that appears when the user clicks the
template icon on the rich text editor toolbar.
The following example template defines a title followed by text:


The name "Title and Text" and the template1.gif image appear in the template selection dialog box.
You can use a custom XML file, instead of fcktemplates.xml, to define your templates. If you do so, specify the file
path in the templatesXML attribute.
Defining custom skins

To create a custom skin that you can specify in the skin attribute, create a subdirectory of the
cf_webRoot/CFIDE/scripts/ajax/FCKeditor/editor/skins directory. The name of this subdirectory is the name that
you use to specify the skin in the skin attribute. The custom skin directory must contain an images subdirectory and
have the following files:

ADOBE COLDFUSION 8 643
ColdFusion Developer’s Guide

• fck_editor.css: Defines the main interface, including the toolbar, its items (buttons, panels, etc.) and the context
menu.
•

fck_dialog.css: Defines the basic structure of dialog boxes (standard for all dialogs).

• fck_strip.gif: Defines the Default toolbar buttons and context menu icons. It is a vertical image that contains all
icons placed one above the other. Each icon must correspond to a 16x16 pixels image. You can add custom images
to this strip.
•

images/toolbar.buttonarrow.gif: Defines the small arrow image used in the toolbar combos and panel buttons.

Place all other images used by the skin (those that are specified in the CSS files) in the images subfolder.
The most common way of customizing the skin is to make changes to the fck_editor.css and fck_dialog.css files. For
information on the skin format and contents, see the comments in those files.

Using the datefield input control
The HTML format cfinput control with a type value of datefield lets users select dates from a pop-up calendar
or enter the dates directly in the input box. When you use the control, you must keep the following considerations
in mind:

• To correctly display label text next to the control in both Internet Explorer and Firefox, you must surround the
label text in a 
 tag and put three 
 tags between each line.
• Consider specifying an overflow attribute with a value of visible in the cflayoutarea tag so that if the popup calendar exceeds the layout area boundaries, it appears completely.
• If you use a mask attribute to control the date format, it does not prevent the user from entering dates that do not
conform to the mask. The mask attribute determines the format for dates that users select in the pop-up calendar.
Also, if the user types a date in the field and opens the pop-up calendar, the calendar displays the selected date only
if the entered text follows the mask pattern. If you do not specify a mask attribute, the pop-up only matches the
default matching pattern.
• If the user types a date with a month name or abbreviation in the control, instead of picking a date from the
calendar, the selected date appears in the pop-up calendar only if both of the following conditions are true:
•

The month position and name format match the mask pattern.

•

The month name matches, case correct, the month names specified by the monthNames attribute, or, for an

mmm mask, their three-letter abbreviations.

• If the date mask specifies yy for the years, the pop-up calendar uses dates in the range 1951-2050, so if the user
enters 3/3/49 in the text field, the calendar displays March 3, 2049.
• If the user enters invalid numbers in a date, the pop-up calendar calculates a valid date that corresponds to the
invalid input. For example, if the user enters 32/13/2007 for a calendar with a dd/mm/yyyy mask, the pop-up
calendar displays 01/02/2008.
The following example shows a simple tabbed layout where each tab contains a form with several datefield controls.:










ADOBE COLDFUSION 8 644
ColdFusion Developer’s Guide

Date 1: 




Date 2: 




Date 3: 




Date 4: 










Date 1: 

(dd/mm/yyyy)



Date 2: 

(mm/dd/yyyy)



Date 3: 

(d/m/yy)



Date 4: 

(m/d/yy)









Note: In Internet Explorer versions prior to IE 7, this example might show the calendars for the first three fields in a page
behind the following input controls.

Using autosuggest text input fields
When you create a text input (type="text") in an HTML format form, you can use the autosuggest attribute to
specify a static or dynamic source that provides field completion suggestions as the user types. Use the
autosuggestMinLength attribute to specify the number of characters the user must type before first displaying any
suggestions.
Note: To put label text next to a cfinput control that uses an autosuggest attribute and have it display correctly in
both Internet Explorer and Firefox, you must surround the label text in an HTML div tag with a style="float:
left" attribute. Also if you have multiple controls, and put them on separate lines, follow the input controls with three

 tags, as in the following example. Otherwise, the label and control do not lay out properly.
 Name: 
 




The control can suggest entries from a static list of values. To use a static suggestion list, specify the list entries in the
autosuggest attribute, and separate the entries by the character specified by the delimiter attribute (by default, a
comma), as the following example shows:


ADOBE COLDFUSION 8 645
ColdFusion Developer’s Guide

In this example, if you type the character a (in uppercase or lowercase) in the cfinput control, the list of states that
start with A appears in a drop-down list. You navigate to a selection by using the arrow keys, and press Enter to select
the item.
You can also have the control suggest values from a dynamically generated suggestion list. To use a dynamic list,
specify a CFC function, JavaScript function, or URL in the autosuggest attribute. Use the autosuggestBindDelay
attribute to specify the minimum time between function invocations as the user types, and thereby limit the number
of requests that are sent to the server. If you use a dynamic list, the input field has an icon to its right that animates
while suggestions are fetched.
When you use a bind expression you must include a {cfautosuggestvalue} bind parameter in the function call
or URL parameters. This parameter binds to the user input in the input control and passes it to the function or page.
A CFC or JavaScript autosuggest function must return the suggestion values as a one-dimensional array or as a
comma-delimited list.
The HTTP response body from a URL must consist only of the array or list of suggestion values in JSON format. In
ColdFusion you can use the serializeJSON function to convert an array to JSON format. If an array with the
suggestions is named nodeArray, for example, the following line would specify the only output on a CFML page that
is called by using a bind expression with a URL:
#serializeJSON(nodeArray)#

You do not have to limit the returned data to values that match the cfautosuggestvalue contents, because the
client-side code displays only the values that match the user input. In fact, the called function or page does not even
have to use the value of the cfautosuggestvalue parameter that you pass to it. You should, however, use the
parameter if the returned data would otherwise be long.
The following example shows how you can a bind expression to populate autosuggest lists. The Last Name text box
displays an autosuggest list with all last names in the database that match the keys typed in the box. The First Name
text box uses binding to the Last Name text box to display only the first names that correspond to the last name and
the text entered in the box. The database query limits the responses to only include results that match the autosuggest
criteria, so the autosuggest list displays all the returned results, and the suggestions only match if the database entry
has a case-correct match.
To test this example with the cfdocexamples database, type S in the first box and the autosuggest list shows Smith
and Stewart. If you select Smith and enter A or J in the First Name box, you get a name suggestion.
The following example shows the application:





Last Name:





First Name:






The following example shows the suggestcfc.cfc file:

ADOBE COLDFUSION 8 646
ColdFusion Developer’s Guide








SELECT DISTINCT LASTNAME FROM Employees
WHERE LASTNAME LIKE 













SELECT FIRSTNAME FROM Employees
WHERE LASTNAME = 
AND FIRSTNAME LIKE 








647

Chapter 35: Using Ajax Data and
Development Features
Adobe ColdFusion supports Ajax features to use data dynamically in web pages.
For information on ColdFusion Ajax user interface capabilities, see “Using Ajax UI Components and Features” on
page 613.
Contents

About ColdFusion Ajax data and development features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647
Binding data to form fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
Managing the client-server interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656
Using Spry with ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
Specifying client-side support files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665
Using data interchange formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667
Debugging Ajax applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
Ajax programming rules and techniques. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671

About ColdFusion Ajax data and development features
Ajax (Asynchronous JavaScript and XML) is a set of web technologies for creating interactive web applications. Ajax
applications typically combine:

•

HTML and CSS for formatting and displaying information.

•

JavaScript for client-side dynamic scripting

•

Asynchronous communication with a server using the XMLHttpRequest function.

• XML or JSON (JavaScript Object Notation) as a technique for serializing and transferring data between the sever
and the client.
ColdFusion provides a number of tools that simplify using Ajax technologies for dynamic applications. By using
ColdFusion tags and functions, you can easily create complex Ajax applications.

ColdFusion Ajax features
ColdFusion provides data management and development, and user interface Ajax features.
Data and development features

ColdFusion data and development features help you develop effective Ajax applications that use ColdFusion to
provide dynamic data. They include many features that you can use with other Ajax frameworks, including Spry.

ADOBE COLDFUSION 8 648
ColdFusion Developer’s Guide

• ColdFusion supports data binding in many tags. Binding allows an application that uses form and display tags,
such as cfselect and cfwindow, to dynamically display information based on form input. In the simplest application, you display form data directly in other form fields, but usually you pass form field data as parameters to CFC
or JavaScript functions or URLs and use the results to control the display. Data binding uses events to automatically
update the display, typically when the bound input data changes. You can also use the
ColdFusion.Ajax.submitForm JavaScript function to get the current value of any bindable element.
• The cfajaxproxy tag creates a JavaScript proxy that represents a CFC on the server. It manages the communication between the client and server, and provides several functions to simplify and manage handling the communication and its results. This tag provides access to all remote functions in a CFC. It also lets applications, including
applications that use Ajax frameworks or widget sets such as Dojo or Backbase, easily access data from ColdFusion
servers.
• The cfsprydataset tag lets you use bind expressions to dynamically create and update Adobe Spry data sets.
Applications that use Spry framework elements, such as dynamic regions, can use this tag to populate the Spry
elements with information based on ColdFusion control input. This feature lets you easily intermix Spry and
ColdFusion controls.
• The cfajaximport tag specifies the location of the JavaScript and CSS files that a ColdFusion page imports. You
can also use this tag to selectively import files required by specific Ajax-based tags and functions. The ability to
change the file location lets you support a wide range of configurations and use advanced techniques, such as application-specific styles. Although ColdFusion can automatically determine and import the required files, sometimes
you must manually specify the information.
• ColdFusion provides several CFML functions that let you create and consume JSON format data on the server
and let you prepare data for use in HTML format cfgrid tags.
• You can display a floating logging window that shows client-side logging and debugging information.
ColdFusion Ajax features display information and error messages in this window, and several logging tags let you
display additional information, including the structure of complex JavaScript variables.
User interface features

•

Ajax-based HTML controls including the following:

•

Tree

•

Grid

•

Rich text editor

•

Date field

•

Autosuggest text input

•

Pop-up menus and menu bars.

•

Container tags that provide bordered, box, and tabbed layouts, pop-up windows, and pod regions.

•

A cfdiv container tag that enables asynchronous form submission and binding in HTML div and other regions.

•

Tooltips for specific controls and HTML regions.

For detailed information on using the UI features, see “Using Ajax UI Components and Features” on page 613.
ColdFusion Ajax tags

The following table lists ColdFusion Ajax-related tags and functions, including all tags that support Ajax-based
features. It does not include subtags that are used only in the bodies of the listed tags:

ADOBE COLDFUSION 8 649
ColdFusion Developer’s Guide

Data tags

UI tags

UI tags

Functions

cfajaximport

cfdiv

cfselect

AjaxLink

cfajaxproxy

cfgrid

cftextarea

AjaxOnLoad

cfsprydataset

cfinput

cftree

DeserializeJSON

cflayout

cftooltip

IsJSON

cfmenu

cfwindow

QueryConvertForGrid

cfpod

SerializeJSON

Binding data to form fields
Many ColdFusion Ajax features use binding to provide dynamic interactivity based on user input or changing data.
When you use binding, a bind expression gets evaluated, and the display gets updated based on new data each time
a specific event (onChange by default) occurs on a form control field specified by a bind parameter. This way, the
value of the tag that specifies the bind expression, and the display, get updated dynamically based on changing information, including user-entered form data. When you use binding the page contents updates, but the entire page is
not refreshed.
Note: When a bound window is not visible, or a tab is not selected, its contents is not updated when the controls it is
bound to change. When the tab or window is made visible, it is updated only if events have been received from the bound
controls while the control was not visible.
Depending on the specific ColdFusion tag, a bind expression can use bind parameter values directly or pass bind
parameter values as parameters to a CFC function, a JavaScript function, or an HTTP request and use the function
or request response to update the page. You can use the following as the data source for a bind expression:

•

•

ColdFusion form control attributes and values. You can bind to the following controls:

•

cfgrid

•

cfinput with checkbox, datefield, file, hidden, radio, or text types

•

cfselect

•

cftextarea

•

cftree

Spry data set elements

Note: You cannot use a bind expression to bind to controls in a dynamically loaded region. For example, you cannot bind
from a control on one page to a control in a layout area on that page if the cflayoutarea tag uses a source attribute
for its contents. However, a dynamically loaded region can bind to controls on the page that loads it, so the file specified
by the source attribute can use bind expressions that specify controls on the page that contains the cflayoutarea tag.
The results of the bind expression determine the value of the tag that uses the expression. For example, if you specify
a URL in a bind expression as the source attribute of a cfwindow control, the page specified by the URL must return
the full contents of the window.
For more examples, see “Using Ajax UI Components and Features” on page 613 and the reference pages for controls
that support binding.

ADOBE COLDFUSION 8 650
ColdFusion Developer’s Guide

Using bind expressions
To specify a bind expression, use one of the following formats:

•

cfc:componentPath.functionName(parameters)
Note: The component path cannot use a mapping. The componentPath value must be a dot-delimited path from
the web root or the directory that contains the current page.

•

javascript:functionName(parameters)

•

url:URL?parameters

•

URL?parameters

•

A string containing one or more instances of {bind parameter}, such as {firstname}.{lastname}@{domain}

In formats 1-4 the parameters normally include one or more bind parameters. The following table lists the tag
attributes that support bind expressions and the formats each can use:
Attribute

Tags

Supported formats

autosuggest

cfinput type="text"

1, 2, 3

bind

cfdiv, cfinput, cftextarea

1, 2, 3, 5

bind

cfajaxproxy, cfgrid, cfselect, cfsprydataset, cftreeitem

1, 2, 3

onChange

cfgrid

1, 2, 3

source

cflayoutarea, cfpod, cfwindow

4

The following examples show some of these uses:
bind="cfc:myapp.bookorder.getChoices({book})"
source="/myApp/innerSource/cityWindow.cfm?cityname={inputForm:city}

In these examples, {book} and {inputForm:city} specify bind parameters that dynamically get data from the book
and city controls, and the city control is in the inputForm form.
If a bind attribute specifies a page that defines JavaScript functions, the function definitions on that page must have
the following format:
functionName = function(arguments) {function body}

Function definitions that use the following format may not work:
function functionName (arguments) {function body}

However, Adobe recommends that you include all custom JavaScript in external JavaScript files and import them on
the application’s main page, and not write them in-line in code that you get using the source attribute. Imported
pages do not have this function definition format restriction.
Specifying bind parameters

A bind parameter specifies a form control value or other attribute, as in the following example:
bind="cfc:myapplication.bookSearch.getStores({form1:bookTitle})"

In this example, the bind parameter is form1:bookTitle and specifies the value attribute of the bookTitle field of the
form1 form.
Bind parameters have either of the following formats:
{[formName:]controlName[.attributeName][@event]}

ADOBE COLDFUSION 8 651
ColdFusion Developer’s Guide

{SpryDataSetName.fieldName}

The square brackets ([]) indicate optional contents and are not part of the parameter.
Note: To include a literal brace character in a bind expression, escape the character with a backslash, as \{, \}.
The formname value

The formname entry identifies the form that contains the control you are binding to. You must specify a form name
if multiple forms contain bind targets with the same names. To specify the form name, start the bind expression with
the form’s id attribute the name attribute if you did not specify an id attribute, and follow it with a colon (:). To
specify the book control that is in a form named inputForm, for example, use the following format:
bind="cfc:myapp.bookorder.getChoices({inputForm:book})"
The controlName value

To bind to a form field, the controlName value must be the value of the id or name attribute of the form control to
which you are binding. If a control has both an id and a name attribute, you can use either value.
You can bind to any ColdFusion form control, including cfgrid and cftree. You cannot bind to values in other
ColdFusion tags, such as cftable.
To bind to a Spry data set, specify the data set name in this part of the bind parameter.
You can bind to multiple radio buttons or check boxes by giving them the same name value. If all the radio buttons
in a radio button group have the same name value, the bind parameter represents the selected button. If multiple
check boxes have the same name value, the bind parameter represents the values of the selected controls in a commadelimited list. If you also specify a unique id attribute for each check box or radio button, you can specify an HTML
label tag for each button or check box and use the id value in the for attribute; in this case, users can select items
by clicking the label, not just the button or box.
If a cfselect control supports multiple selections, the bind expression returns the information about the selected
items in a comma-delimited list.
You can bind only to controls that are available in the DOM tree when the bind is registered. Binds are registered
when the page with the bind expression loads, either in the browser window or in a container tag. As a result, if you
have two cfdiv, layoutarea, cfpod, or cfwindow containers that you load by using a source (or for cfdiv tag,
bind) attribute, you cannot bind controls in one container to controls in the other, because one container cannot be
assured that the other is loaded when it loads. Similarly, elements on the main page cannot bind to elements on a
dynamically loaded container. To prevent this problem, you should define the bind target in line on the main page,
instead of using a source or bind attribute to retrieve the markup that contains the bind target. In other words, the
“master” form with fields that serve as sources of bind expressions should be loaded statically (on the main page),
and the “child” controls that depend on the data can be loaded dynamically, on a page that is specified in a source
or bind attribute.
The attributeName value

When you bind to a form control, by default, the bind expression represents the value attribute of the specified
control. If the bind target is a cfselect tag, the bind expression represents a comma delimited list of the values of
the selected items.
To bind to a different attribute, follow the control name or id with a period (.) and the attribute name. To pass the
checked attribute of a checkbox cfinput tag as a CFC parameter, for example, use an expression such as the

following:
bind="cfc:myapp.bookorder.useStatus({myForm:approved.checked"@click}"

ADOBE COLDFUSION 8 652
ColdFusion Developer’s Guide

Note: You can bind to the display text of a select box, instead of the value, by specifying an attribute name of innerHTML.
When you bind to a check box, use the @click event specifier to ensure that the bind expression is triggered in Internet
Explorer when the user selects or deselects the check box, not when the box loses focus.
Grids and trees do not have default bind attributes.

• You must always specify a grid target attribute by using the format {gridID.columnName}. The bind expression
gets the value of the specified column in the selected row.
• For trees, you must bind to a specific node in the tree. You can specify the node by using the node ID or an
explicit path to the node.
To bind to a Spry data set element or attribute, use standard Spry path notation. For example, specify an element
name.
The event value

By default, the bind expression function executes each time the control specified in the bind parameter has an
onChange event. To trigger updates on a different JavaScript event, end the bind expression with an at sign (@) and
the event name, without the “on” prefix. The following code, for example, executes the getChoices CFC each time the
user presses the mouse button while the pointer is over the book control:
bind="cfc:myapp.bookorder.getChoices({inputForm:book@mousedown})"

Note: To bind to a cfinput control with type attribute of button, you must specify a bind event setting, such as click.
The change event is the default event has no effect.
When you bind to a Spry data set, do not specify an event. The expression is evaluated when the selected row changes
in the data set, or when the data set reloads with new data.
You can also specify that a specific bind parameter never triggers bind expression reevaluation, by specifying @none
as the event. This is useful, for example, if a bind expression uses multiple bind parameters binding to different form
fields, and you want the bind expression to trigger changes only when one of the fields changes, not when the others
change. In this case, you would specify @none for the remaining fields, so events from those fields would not trigger
the bind. The following code shows this use:
bind="cfc:books.getinfo({iForm:book}, {iForm:author@none})"

The @none event specifier can also be useful when used with autosuggest text inputs, trees and grids, as follows:

• When you use an autosuggest text input, the bind expression is evaluated as a user types in text, and picks up
data from all bind parameters, including those with @none specified. Therefore, for autosuggest, you can specify
@none for all bind parameters, because there is no way for it to react to changes in the parameters.
• When you call the ColdFusion.Grid.refresh or ColdFusion.Tree.refresh function, the function fetches
data from all bind parameters when it evaluates the bind expression, including any parameters with @none specified.
If you specify @none for all bind parameters, the tree or grid might not respond to changes in other controls, but it
will get data from all the bind parameters each time you explicitly refresh it.
Using CFC functions in bind expressions

As with JavaScript functions, you can pass arguments to a CFC function specified in a bind expression positionally.
When you do this, the argument names in a CFC function definition do not have to be the same as the bind
parameter names, but the arguments in the bind expression must be in the same order as those in the CFC function
definition.

ADOBE COLDFUSION 8 653
ColdFusion Developer’s Guide

Alternatively, you can pass named CFC function arguments. Then, the bind expression and CFC function must use
the same names for the arguments, and the function does not have to define the arguments in the same order as they
are passed. To specify argument names in a bind expression, use a format such as the following, which uses two
named parameters, arg1 and arg2:
bind="cfc:mycfc.myfunction(arg1={myform:myfield1},arg2={myform:myfield2})"

Using binding in control attributes
When you use direct binding you specify a bind expression in a ColdFusion form or display control attribute. In the
simplest, form of binding you can use form fields, such as a name field, to fill other fields, such as an e-mail field, as
the following example. shows. When you enter a name or domain and tab to click in another field, the name is added
to the e-mail field.





First Name: 

Last Name: 

Domain: 

E-mail: 




The following example shows the results of binding to radio buttons and check boxes with the same name attribute
but different id attributes. Notice that because each control as a separate id value that is used in the label tags, you
can click the labels to select and deselect the controls.





Pick one:

Apples

Oranges

Mangoes






Pick as many as you like:

Apples

Oranges

Mangoes





ADOBE COLDFUSION 8 654
ColdFusion Developer’s Guide





Most applications call a CFC function, or JavaScript function, or use a URL to make an HTTP request (typically to
a CFML page), and pass bind parameters as the function or URL parameters.
The following example uses the same form as the first example in the preceding section, but uses a different bind
expression with the following features:

• It uses the keyup events of the name and domain fields to trigger binding. So the e-mail field gets updated each
time that you enter a letter in any of these fields.
• It calls a CFC, which uses only the first letter of the first name when forming the e-mail address, and forces the
domain name to be all lowercase.
The following example shows the bindapp.cfm page:





First Name: 

Last Name: 

Domain: 

E-mail: 




The following example shows the bindFcns.cfc CFC file:









Many of the examples in the documentation for ColdFusion Ajax features use binding, including more complex
forms of binding.

Using the cfajaxproxy tag to bind to display controls
The cfajaxproxy tag with a bind attribute makes any of the following elements dependent on one or more bound
ColdFusion Ajax controls:

•

A single CFC function

•

A single JavaScript function

•

An HTTP request; for example, the URL of a CFML page

The function or request executes whenever a specific event (by default, the onChange event) of the bound control
occurs.

ADOBE COLDFUSION 8 655
ColdFusion Developer’s Guide

Note: if you specify a bind attribute with a URL, the HTTP request includes a _CF_NODEBUG URL parameter.
ColdFusion checks this value, and when it is true, does not append to the response any debugging information that it
normally would send. This behavior ensures that JSON responses to Ajax requests do include any non-JSON (i.e.,
debugging information) text.
The cfajaxproxy tag includes the following attributes that determine how the proxy handles the data returned by
the function or the page:

• The onError function specifies code to handle an HTTP error return. You can use this attribute with a URL or
CFC bind.
• The onSuccess function handles a valid return from the function or page and updates the display as required
with the returned information.
Binding a function or request by using the cfajaxproxy tag enables you to perform a server-side action, such as
updating a database by using bind parameter values based on a user action in some control, and then invoke a
specific action or set of actions in one or more controls based on the server response. Because it uses an onSuccess
function to process the return from the server, this form of binding provides substantially more flexibility than a
CFML control bind parameter. This format also lets you use a control bind parameter for one kind of action, and
the cfajaxproxy tag for a different activity.
For example, you might have a form with an editable cfgrid control and a delete button that a user clicks to delete
a grid row. The application must have the following behaviors:

•

•

When the user clicks the delete button two things must happen:

•

The application must call a mycfc.deleteButton CFC function to delete the row from the database.

•

The grid must update to remove the deleted row.

When the user edits the grid content, the grid must call a mycfc.update function to update the database.

You can implement these behaviors by doing the following:

• In the cfgrid tag, specify a bind attribute that uses a bind expression to call a mycfc.update function each time
the user changes the grid contents.
•

In a cfajaxproxy tag, specify a bind attribute that calls the mycfc.deleterow CFC function, and specify an

onSuccess attribute that calls the ColdFusion.Grid.refresh function to update the displayed grid when the CFC

function returns successfully.
The following code snippets show how you could do this:

...


function test(x,y){
return "Hello, " + x + "!";

ADOBE COLDFUSION 8 656
ColdFusion Developer’s Guide

}
function callbackHandler(result){
alert("Bind expression evaluated. Result: \n" + result);
}











Getting bindable attribute values in JavaScript
You can use the ColdFusion.Ajax.submitForm function in your JavaScript code to get the current value of any
attribute of a bindable control. This technique is particularly useful for getting values for complex controls such as
cfgrid and cftree. For more information, see the ColdFusion.Ajax.submitForm function in the CFML
Reference.

Managing the client-server interaction
You can manage the client-server interaction in several ways:

• Use the cfajaxproxy tag to create a client-side JavaScript proxy for a CFC and its functions. You can then call
the proxy functions in client JavaScript code to access the server-side CFC functions.
• Use the cfsprydataset tag to dynamically populate a Spry data set from a URL or a CFC. You can then use the
data set to populate Spry dynamic regions. You can also use Spry data sets in bind expressions.
• Use the cfajaxproxy tag to bind fields of ColdFusion Ajax form controls as parameters to a specific CFC
function, JavaScript function, or HTTP request, and specify JavaScript functions to handle successful or error
results. The function is invoked each time the event determined by the bind expression occurs.
• Use ColdFusion Ajax-based UI tags, such as cftree or cfgrid that automatically get data from CFCs or URLs
by using data binding.
For Information on working with Spry, including how to use the cfsprydataset tag, see “Using Spry with
ColdFusion” on page 661. For detailed information on using binding, including how to use binding with ColdFusion
UI tags and the cfajaxproxy tag, see “Binding data to form fields” on page 649. For more information on using the
ColdFusion Ajax-based UI tags, see “Using Ajax UI Components and Features” on page 613.

Using ColdFusion Ajax CFC proxies
You can use the cfajaxproxy tag to create a client-side JavaScript proxy for a CFC and its functions. The proxy
object has the following characteristics:

• It provides a JavaScript function the corresponds to each CFC remote function. Calling these functions in your
client-side JavaScript code remotely calls the CFC functions on the server.

ADOBE COLDFUSION 8 657
ColdFusion Developer’s Guide

• It provides JavaScript support functions for controlling the communication, which specifies asynchronous result
and error handler callbacks, and sends form data to the server. For detailed information on these functions, see “CFC
proxy utility functions” on page 42 in the cfajaxproxy tag in the CFML Reference.
• It manages the interactions between the client and the CFC, including serializing and deserializing JavaScript
arrays and structures to and from JSON format for transmission over the web.
•

It ensures automatic serialization (into JSON format) and deserialization of CFC return values.

By using a ColdFusion Ajax proxy, any JavaScript code can call the proxied CFC functions. Thus, any Ajax application, not just one the uses ColdFusion Ajax UI elements, can use dynamic data provided by CFCs. Also, the proxy
provides access to all of the functions in a CFC, not just the single function that you can specify in a bind expression.
Creating a JavaScript CFC proxy

The cfajaxproxy tag with a cfc attribute generates a JavaScript proxy that represents a CFC on the web client.
Because a ColdFusion page that uses the cfajaxproxy tag is used as an Ajax client web page, the page typically starts
with the cfajaxproxy tag (or tags), and the remainder of the page consists of the HTML and JavaScript required to
control the display and perform the page logic on the client.
Note: Because JavaScript is case-sensitive, you must make sure that you match the case of the keys in any ColdFusion
structure or scope that you send to the client. By default, ColdFusion sets variable names and structure element names
to all-uppercase. (You can create structure element names with lowercase characters by specifying the names in
associative array notation, for example, myStruct["myElement"]="value".) The keys for the two arrays in the JSON
object that the ColdFusion SerializeJSON function generates to represent a query are COLUMNS and DATA, for
example, not columns and data.
For more information about creating and using CFC proxies, see the cfajaxproxy tag in the CFML Reference.
Configuring the CFC proxy

The proxy provides several JavaScript functions that you use to control the behavior of the proxy:

• You use the setAsyncMode and setSyncMode functions to control the call mode. By default, all calls to remote
CFC functions are asynchronous, the most common synchronization method for Ajax applications.
• You use the setCallbackHandler and setErrorHandler functions to specify the functions that handle the
results of successful and unsuccessful asynchronous calls.
Note: For error handling to work properly, you must select the Enable HTTP Status Codes option on the Server Settings
> Settings page of the ColdFusion Administrator.

• You use the setHTTPMethod function to control whether the call uses a GET HTTP request (the default) or a
POST request.
• You use the setForm function to prepare the proxy to send full form data to the remote function. This function
causes the proxy to pass each form field as a separate parameter to the CFC function.
• You use the setReturnFormat function to specify whether to return the result in JSON format (the default), in
WDDX format, or as plain text. You use the setQueryFormat function to specify whether to return a JSON format
query as an object with an array of column names and an array of row arrays, or as an object that corresponds to the
WDDX query format. These functions only effect the format of data returned by ColdFusion. Data sent from the
proxy to the server is always in JSON format.

ADOBE COLDFUSION 8 658
ColdFusion Developer’s Guide

Submitting data to a CFC

When you use an Ajax CFC proxy, you can send to the CFC function any client-side data that can be serialized to
JSON format, not just form data. However, the proxy cannot serialize DOM tree elements because they are wrappers
on native code. Therefore, you cannot use DOM tree elements directly as parameters to a CFC function that you call
by using an Ajax proxy. To ensure correct serialization to JSON for sending to the CFC, you must use basic JavaScript
types only: array, object, and simple types. Instead of using a DOM element directly, you can pass only the specific
element attributes that you require to the CFC function, either individually or in an array or object.
When you use the cfc attribute, you can submit form data to the CFC without refreshing the client page by calling
the proxy setForm function before you call a CFC proxy function in your JavaScript. The proxy function then passes
all field values of the specified form to the CFC function. In the CFC function Arguments scope, the argument names
are the form control ID attributes (or, by default, the name attributes) and the argument values are the control values.
Note: You cannot use the setForm function to submit the contents of file fields.
To pass the form parameters to your proxy function, you must invoke the proxy function immediately after you call
the setForm function. Subsequent proxy function invocations do not get the form parameters.
If you also pass arguments explicitly to the CFC, cfargument tags in the CFC function that specify the explicitly
passed arguments must precede any cfargument tags for the form fields. For example, you might have the following
submitForm JavaScript function:
function submitForm() {
var proxy = new remoteHandler();
proxy.setCallbackHandler(callbackHandler);
proxy.setErrorHandler(errorHandler);
proxy.setForm('myform');
proxy.setData('loggedIn');
}

In this example, the remoteHandler.cfc setData function should start as follows:



...

In this example, userName is the name of a form field. If the cfargument tag for userName preceded the
cfargument tag for the loggedIn explicitly passed variable, the CFC function would not get the value of loggedIn.
Your CFC function can omit cfargument tags for the form fields.

Example: Using an asynchronous CFC proxy
The following example uses a remote CFC method to populate a drop-down list of employees. When you select a
name from the list, it uses a call to the CFC method to get information about the employee, and displays the results.
The main application page has the following lines:









List of Employees:   











The following component, which gets the data from the data source, must be in a file named emp.cfc in the components subdirectory of the application directory. The CFC uses the cfdocexamples data source that is installed with
ColdFusion if you install the documentation.





select * from Employees

ADOBE COLDFUSION 8 661
ColdFusion Developer’s Guide


where Emp_ID = #empid#






Using Spry with ColdFusion
ColdFusion provides support for mixing native ColdFusion elements and Spry elements in a single application.

• ColdFusion tags can use Spry data sets directly in bind expressions. Therefore, a ColdFusion form element, such
as cfinput, can bind to a field in a dynamic Spry data set, and is updated each time the data set updates, including
when the user selects an item in a Spry control or dynamic region that the data set populates.
To bind to a Spry data set, specify the data set name followed by the path to the specific element that you bind
to, by using standard Spry path syntax. For example, if dsFilters is a Spry data set with a name column, the
{dsFilters.name} bind parameter binds to the value of the current row’s name column. The bind parameter
cannot specify an event; the bind expression is re-evaluated each time the selected row in the data set changes.
The following example shows the bind syntax:


ColdFusion includes the complete Spry 1.5 framework release in web_root/CFIDE/scripts/ajax/spry directory. For
more information, see the Adobe Labs Spry framework pages. For more information, see the cfsprydataset tag in
the CFML Reference.

Spry data set example
This example has the following behavior:
1

It uses a CFC function directly to populate a Spry XML data set, from an XML file.

ADOBE COLDFUSION 8 662
ColdFusion Developer’s Guide

2

It displays information from the Spry data in a Spry dynamic region list box.

It uses the selected item in the Spry data set to control the contents of a cfgrid control. The cfgrid bind
expression calls a CFC and passes it a parameter bound to the selected item in the Spry XML data set.

3

4 It creates a second Spry XML data set by using a cfsprydataset tag that binds to the selected item in the cfgrid
control and calls a CFC function.
5

It displays information from the second Spry data set in a second Spry dynamic region.

The example lets a user select the genre of books to display: all books, fiction, or nonfiction from a Spry list box
populated from the XML file. The selected genre determines the information displayed by a cfgrid control, and a
text input control shows the selected genre. The selected item in the cfgrid control determines the information that
is displayed in a second Spry dynamic region.
The application consists of the following files:

•

A roundtrip.cfm page with the display controls and related logic

•

A GridDataManager.cfc file with two functions:

•

•

A getFilter function that gets the XML for the spry data set

•

A getData function that gets the contents of the cfgrid control

•

A getProduct function that gets detailed information on the selected book

A Filters.xml file with the XML data for the spry data set

For this example to display images, you must also create an images subdirectory of your application directory that
contains images with the names specified by the BOOKIMAGE column of the cfbookclub database BOOKS table.
The roundtrip.cfm page












ADOBE COLDFUSION 8 663
ColdFusion Developer’s Guide











{dsFilters::description}
















ADOBE COLDFUSION 8 664
ColdFusion Developer’s Guide



{name}


{desc}




The gridDataManager.cfc file















select TITLE, GENRE from BOOKS

where GENRE = '#arguments.filter#'


order by #arguments.sortCol# #arguments.sortDir#

order by TITLE ASC










select TITLE, GENRE, BOOKIMAGE, BOOKDESCRIPTION from BOOKS
where TITLE = '#arguments.prodname#'






ADOBE COLDFUSION 8 665
ColdFusion Developer’s Guide



#BookDetails.TITLE#
#BookDetails.GENRE#
#BookDetails.BOOKIMAGE#
#BookDetails.BOOKDESCRIPTION#










The Filters.xml file



1

No Filter


2
Fiction
Look for Fiction


3
Non-fiction
Look for Nonfiction



Specifying client-side support files
By default, ColdFusion does the following:

• Gets all the client-side JavaScript, CSS, and other files required for Ajax-based features from the
web_root/CFIDE/scripts/ajax directory.
• For each application page, imports only the JavaScript files required for the tags that are explicitly included on
the page.
In some cases you must override these default behaviors.

ADOBE COLDFUSION 8 666
ColdFusion Developer’s Guide

Specifying a custom script or CSS location
In some situations, you cannot use the default location for the CFIDE directory, often because a hosting site blocks
access to it to prevent access to the ColdFusion Administrator. Then you must move the CFIDE/scripts directory, or
the subdirectories that you use in your applications, to a different location.
In other situations, you might have custom versions of some of the client-side files, such as the CSS files that specify
form control appearance, that apply only to certain applications.
In both situations, you must inform ColdFusion of the new location. You can specify the location of either or both
directories containing the following files:

•

All client-side resources required by the ColdFusion Ajax features

•

Only the CSS files required by the ColdFusion Ajax features

Specifying the client-side resource location

You can use any of the following techniques to control the location of the directory that contains the client-side
resources required by the ColdFusion Ajax features:

• If the ColdFusion client-side files required by all applications, including the files used by cfform tags are in a
single location, you can specify the directory in the ColdFusion Administrator > Server Settings > Settings page,
Default CFFORM ScriptSrc Directory field. The directory you specify and its subdirectories must have the same
structure and contents as the CFIDE/scripts directory tree.
• If the client-side files required for Ajax features on a specific page are in one location, you use the cfajaximport
tag scriptsrc attribute to specify the source directory. This tag overrides the setting in the administrator, and does
not affect the files used for standard cfform features.The directory you specify must have an ajax subdirectory with
the same structure and contents as the CFIDE/scripts/ajax directory tree.
• You can specify the client-side source directory for a specific form in the cfform tag scriptsrc attribute. This
setting overrides any cfajaximport tag setting for the form and its child controls. The directory you specify and its
subdirectories must have the same structure and contents as the CFIDE/scripts directory tree.
You must be careful if you require multiple resource locations for a single page. Each JavaScript file is imported only
once on a page, the first time it is required. Therefore, you cannot use different copies of one JavaScript file on the
same page.
To prevent problems, ColdFusion generates an error if you specify more than one scriptsrc attribute on a page.
Therefore, if multiple forms require custom client-side resource files, you must specify their location in a single
cfajaximport tag, not in scriptsrc attributes in the cfform tags.
Specifying the CSS file location

You can use the cfajaximport tag cssSrc attribute to specify the location of a directory that contains only the CSS
files that control the style of ColdFusion Ajax-based controls. This attribute overrides any scriptsrc value in determining the CSS file location. Therefore, you could use the CSS files in the scriptsrc directory tree for most pages,
and specify a cssSrc attribute on selected application pages that require a custom look.
For detailed information on how to use the scriptsrc and cssSrc attributes, and requirements for the contents of
the specified directory, see the cfajaximport tag in the CFML Reference.

Importing tag-specific JavaScript files
In the following situations, ColdFusion does not automatically import the JavaScript files that are required for Ajaxbased tags:

ADOBE COLDFUSION 8 667
ColdFusion Developer’s Guide

• If you use a ColdFusion Ajax-based tag on a page that you specify by using a source or bind attribute in a
container tag, such as cfdiv, cflayoutarea, cfpod, or window. You must put a cfajaximport tag on the page that
has the container tag and use the tags attribute to specify the Ajax feature tags that are on the other pages. (You do
not have to do this for any tags that are also used on the page with the source attribute.)
•

If you use a ColdFusion Ajax JavaScript function, such as ColdFusion.Window.create or

ColdFusion.navigate, on a page that does not otherwise import the required ColdFusion Ajax JavaScript

functions, you must use the cfajaximport tag to import the required JavaScript functions. If you are using a
function, such as coldFuson.navigate, that is not used for a specific control, you can omit any attributes; the
default behavior is to import the base functions that are not control-specific. If you are using a function such as
ColdFusion.Window.create, you must use the tags attribute and identify the associated control, for example,
cfwindow in the following line:


For detailed information on importing tag-specific JavaScript files, see the cfajaximport tag in the CFML
Reference.

Using data interchange formats
All complex data that is communicated over an HTTP connection must be serialized into a string representation that
can be transmitted over the web. Most commonly, web client applications use XML or JSON.
As a general rule, ColdFusion automatically handles all necessary serialization and deserialization when you use
ColdFusion Ajax features. The proxies that you create with the cfajaxproxy tag, and the bind expressions that call
CFC functions automatically request data in JSON format, and automatically deserialize JSON data to JavaScript
variables.
ColdFusion also provides the capability to create, convert, and manage data in web interchange formats. This can be
helpful, for example, if you use custom Ajax elements to get data from ColdFusion servers.
Also, you can use ColdFusion data serialization capability for any applications that must create or consume complex
data transmitted over an HTTP connection. You might want to make a web service or feed available in JSON format.
For example, many Yahoo! web services currently are accessible by using simple URLS that return data as JSON.
Note: For information on ColdFusion tags and functions for handling XML or WDDX data, see “Using XML and
WDDX” on page 865.

Controlling CFC remote return value data format
By default, CFC functions convert data that they return to remote callers to WDDX format. However, they can also
return the data in JSON format, or as plain string data. (XML objects are automatically converted to string representation when returning plain data.)
ColdFusion Ajax elements that request data from CFC functions, including bind expressions and the function
proxies generated by the cfajaxproxy tag, automatically generate a returnFormat parameter in the HTTP URL to
request JSON data from the CFC function.
You can control the CFC function return format in the following ways:

•

Use the returnFormat attribute on the cffunction tag.

•

Set a returnFormat parameter in the HTTP request that calls the CFC function.

ADOBE COLDFUSION 8 668
ColdFusion Developer’s Guide

• Use the CFC proxy setReturnFormat function. (You do this only if your client-side code requires non-JSON
format data, for example, XML or WDDX.)
If the requested return format is JSON and the function returns a query, ColdFusion serializes the query into a JSON
object in either of the following formats:

•

As a JSON object with two entries: an array of column names, and an array of column data arrays.
These entries are returned in the following situations:

•

By default

•

If you specify an HTTP URL parameter of queryFormat="row"

• If you use the cfajaxproxy tag and call the proxy object’s setReturnFormat function with a parameter
value of row
ColdFusion client-side binding and proxy code automatically converts this data into JavaScript that can be
consumed directly by HTML format grids.

• As a JSON object with three entries: the number of rows, an array of column names, and an object where each
key is a column name and each value is an array with the column data
These entries are returned in the following situations:

•

If you specify an HTTP URL parameter of queryFormat="column"

• If you use the cfajaxproxy tag and call the proxy object’s setQueryFormat function with a parameter value
of column
ColdFusion client-side binding and proxy code does not convert column format data into JavaScript that can be
consumed directly by HTML format grids. However, use this format with the cfajaxproxy tag, because you can
refer to the returned data by using the column names directly. For example, if a CFC function returns a query
with user data, you can get the user names in your JavaScript by specifying values such as userData.firstName[0]
and userData.lastName[0].
For more information, see the SerializeJSON function in the CFML Reference.

Using JSON
JSON (JavaScript Object Notation) is a lightweight JavaScript-based data interchange format for transmission
between computer systems. It is a much simpler format than XML or WDDX, and is an efficient, compact format for
transmitting data required for Ajax applications. ColdFusion Ajax bind expressions that use CFCs tell the CFC
function to send the data in JSON format by including a returnformat="json" parameter in the HTTP request,
and automatically handle the JSON-formatted result.
JSON represents objects by using { key : value , key : value... } notation, and represents arrays in standard [ value ,
value... ] notation. Values can be strings, numbers, objects, arrays, true, false, or null. Therefore, you can nest arrays
and objects inside each other. For a detailed specification of the JSON format, see www.JSON.org.
Although ColdFusion Ajax-based controls and the cffunction tag interoperate transparently, without you
converting anything to JSON format, other applications can take advantage of JSON format data. Many public feeds
are now available in JSON format. For example, the Yahoo! search interface can return a JSON data set, del.icio.us
provides JSON feeds showing your posts and tags, and Blogger feeds are available in JSON format. You don’t have to
use Ajax to display these feeds; you can use standard ColdFusion tags and functions to display the results.
The following CFML functions support using JSON format in server-side code:

•

DeserializeJSON

ADOBE COLDFUSION 8 669
ColdFusion Developer’s Guide

• SerializeJSON
• IsJSON
For more information about these functions and examples, see the CFML Reference.
The following example shows how to use ColdFusion JSON functions in a non-Ajax application. It does a Yahoo
search for references to "ColdFusion Ajax" and displays these results:

•

The total number of web pages found

•

The titles and summaries of the (by default 10) returned results. The title is a link to the web pageURL.







Results of search for "ColdFusion 8"
There were #myJSON.ResultSet.totalResultsAvailable# Entries.

Here are the first #myJSON.ResultSet.totalResultsReturned#.


#myJSON.ResultSet.Result[i].Title#
#myJSON.ResultSet.Result[i].Summary#



Debugging Ajax applications
ColdFusion provides a set of JavaScript functions that log information to a pop-up display window. ColdFusion also
logs many standard client-side activities to the window.

Displaying logging information
To display the logging window you must do the following:
1

Enable ColdFusion to send information to the logging window

2

Request logging window information in the main CFML page request.

Enabling logging output

To enable ColdFusion to send information to the logging window, you must do the following:

• Select the Enable Ajax Debug Log Window option on the ColdFusion Administrator > Debugging & Logging >
Debug Output Settings page. To view exception messages in the logging window, you must select the Enable Robust
Exception Information option on the Debug Output Settings page.
• Make sure that the IP address of the system where you will be doing the debugging is included on the ColdFusion
Administrator > Debugging & Logging > Debugging IP List page of the ColdFusion Administrator. By default this
list includes only 127.0.0.1.

ADOBE COLDFUSION 8 670
ColdFusion Developer’s Guide

Displaying logging information for a page

To display the logging window when you request a CFML page in the browser, specify an HTTP parameter of
cfdebug in the URL when you request a page, as in the following URL:
http://localhost:8500/myStore/products.cfm?cfdebug

After the debug log window appears, it continues running until you navigate to a new page in the browser. The
logging window includes options that let you filter the messages by either or both of the following criteria:

•

Severity

•

Category

You can select to display logging information at any combination of four levels of severity: debug, info, error, and
window. The specific logging function that you call determines the severity level.
The logging window always displays options to filter the output by using standard categories: bind, global, http,
LogReader, and widget. (For information on these categories, see “Standard ColdFusion logging messages” on
page 670.) It also displays a filter option for each custom category that you specify in a ColdFusion logging call.
ColdFusion does not limit the number of categories you create, but you should create only as many categories as you
require to debug your application effectively.

Logging information
You can call the following JavaScript functions to send information to the logger. In most cases, the function corresponds to a severity level, as follows:
Function

Severity

Purpose

ColdFusion.Log.debug

debug

A message that aids in debugging problems.

ColdFusion.Log.dump

debug

A representation of a single variable in a format similar to cfdump. This function can
display the structure and contents of JavaScript Array and Object variables.

ColdFusion.Log.error

error

Information about an error. Use this function only in error-handling code.

ColdFusion.Log.info

info

Information about properly operating code that can be useful in tracing and analyzing
the client-side code’s execution.

You cannot generate a window-level message. This level is reserved for messages generated by the log reader window,
including information about JavaScript errors in the log function calls.
When you call a logging function, you specify a message and a category.

•

The message can include JavaScript variables and HTML markup, such as bold text and line breaks.

• The category should be a short descriptive name. ColdFusion generates a check box option for each category to
filter the logging window output. This parameter is optional; the default value is global. You can specify a standard
ColdFusion category or a custom category.
To log information for a page, you must have a ColdFusion Ajax tag on the page, or use the cfajaximport tag. The
cfajaximport tag does not require any attributes to enable logging.

The following logging function generates an error level, Pod A category log message:
ColdFusion.Log.error("Invalid value:
" + arg.A, "Pod A");

Standard ColdFusion logging messages
ColdFusion automatically logs messages in the following categories:

ADOBE COLDFUSION 8 671
ColdFusion Developer’s Guide

Category

Description

global

(the default) Messages that are not logged from within the ColdFusion Ajax libraries, for example, initialization of
the logging infrastructure.

http

Information about HTTP calls and their responses, including the contents of HTTP requests and information on CFC
invocations and responses.

LogReader

Messages about the log display window.

bind

Bind-related actions such as evaluating a bind expression.

widget

Control-specific actions such as tree and grid creation.

Ajax programming rules and techniques
The following techniques can help you to prevent Ajax application errors, improve application security, and develop
more effective applications.

Preventing errors
The following rules and techniques can help you prevent errors in your applications:

• To ensure that your code works properly, make sure that all your pages, including dynamically loaded content
and pages that contain dynamic regions, have valid html, head, and body tags, and that all script tags are located
in the page head. This is particularly important for any page with ColdFusion Ajax tags and script tags, where it
ensures that the script code is processed and that code is generated in the correct order. It can also prevent problems
in some browsers, such as Internet Explorer.
• All JavaScript function definitions on pages that you include dynamically, for example by using a bind
expression, the ColdFusion.navigate function, or a form submission within a ColdFusion Ajax container tag,
must have the following syntax format:
functionName = function(arguments) {function body}

Function definitions that use the following format might not work:
function functionName (arguments) {function body}

However, Adobe recommends that you include all custom JavaScript in external JavaScript files and import them
on the application’s main page, and not write them in-line in code that you get dynamically. Imported pages do
not have this restriction on the function definition format.

• As a general rule, the id attributes or name attributes, when you do not specify id attributes, of controls should
be unique on the page, including on any pages that you specify in source attributes. Exceptions to this rule include
the following:
• You can use the same name attribute for all options in a radio button group. Bind expressions get information
about the selected button.
• You can use the same name attribute for check boxes in a group if you want a single bind expression to get
information about all selected controls in the group.
• If you have multiple similar forms on a page, you might have controls in each form with the same name or
ID. You specify the individual controls in bind expressions by including the form name in the bind parameter.

ADOBE COLDFUSION 8 672
ColdFusion Developer’s Guide

• Do not use an Application.cfc onRequestEnd function or onRequestEnd.cfm page that creates output in applications that use the cfajaxproxy tag or bind expressions that call CFC functions to get data. ColdFusion Ajax
features normally require that all returned data from the server be in JSON format; the onRequestEnd method
onRequestEnd.cfm page appends any output as non-JSON information to the end of the returned data.
• By default, all ColdFusion structure element names are in all uppercase characters. Therefore, your client-side
Ajax code, such as an onSuccess function specified by a cfajaxproxy tag, must use uppercase letters for the
returned object’s element names if you do not explicitly ensure that the element names are not all uppercase. (You
can create structure element names with lowercase characters by specifying the names in associative array notation,
for example, myStruct["myElement"]="value".)
• ColdFusion Ajax controls can throw JavaScript errors if badly formed HTML causes errors in the browser DOM
hierarchy order. One example of such badly formed HTML is a table that contains a cfform tag, which in turn
contains table rows. In this situation, you should put the table tag inside the cfform tag.
For browser-specific issues and other issues that might affect application appearance and behavior, see the
ColdFusion Release Notes on the Adobe website at www.adobe.com/go/prod_doc, and the ColdFusion Developer
Center on the Adobe website at www.adobe.com/go/prod_techarticles.

Improving security
ColdFusion includes several capabilities that help to ensure the security of Ajax application. Also, the ColdFusion
Administrator disables output to the client-side logging window by default (see “Enabling logging output” on
page 669).

• To prevent cross-site scripting, you cannot use remote URLs in code that executes on the client. For example, if
you use a URL such as http://www.myco.com/mypage.cfm in a cfwindow tag source attribute, the remote page does
not load in the window and the window shows an error message. If you must access remote URLs, you must do so
in CFML code that executes on the server, for example, by using a cfhttp tag on the page specified by a source
attribute.
• When a CFC function returns remote data in JSON format, by default, the data is sent without any prefix or
wrapper. To help prevent cross-site scripting attacks where the attacker accesses the JSON data, you can tell
ColdFusion to prefix the returned data with one or more characters. You can specify this behavior in several ways.
The value of an item in the following list is determined by the preceding item in this list:
a In the Administrator, enable the Prefix Serialized JSON option on Server Settings > Settings page (the default
value is false). You can also use this setting to specify the prefix characters. The default prefix is //, which is
the JavaScript comment marker that turns the returned JSON code into a comment from the browser’s
perspective. The // prefix helps prevent security breaches because it prevents the browser from converting the
returned value to the equivalent JavaScript objects.
b

Set the Application.cfc file This.secureJSON and This.secureJSONPrefix variable values, or set the

cfapplication tag secureJSON and secureJSONPrefix attributes.

c

Set the cffunction tag secureJSON attribute. (You cannot use the cffunction tag to set the prefix.)

As a general rule, you should use one of these techniques for any CFC or CFML page that returns sensitive data,
such as credit card numbers.
When you use any of these techniques, the ColdFusion Ajax elements that call CFC functions, including bind
expressions and the CFC proxies created by the cfajaxproxy tag, automatically remove the security prefix when
appropriate. You do not have to modify your client-side code.

ADOBE COLDFUSION 8 673
ColdFusion Developer’s Guide

• ColdFusion provides capabilities that help prevent security attacks where an unauthorized party attempts to
perform an action on the server, such as changing a password. You can use the following techniques to help make
sure that a request to a CFML page or remote CFC function comes from a ColdFusion Ajax feature, such as a bind
expression or CFC proxy, that is a valid part of your application:
• In the cffunction tag in a CFC function that returns data to an Ajax client, specify a verifyClient
attribute with a value of yes.
•

At the top of a CFML page or function that can be requested by a ColdFusion Ajax client, call the

VerifyClient ColdFusion function. This function takes no parameters.

The VerifyClient function and attribute tell ColdFusion to require an encrypted security token in each
request. To use this function, enable client management or session management in your application; otherwise,
you do not get an error, but ColdFusion does not verify clients.
Enable client verification only for code that responds to ColdFusion Ajax client code, because only the
ColdFusion Ajax library contains the client-side support code. Enabling client verification for clients other than
ColdFusion Ajax applications can result in the client application not running.
As a general rule, use this function for Ajax requests to the server to perform sensitive actions, such as updating
passwords. You should typically not enable client verification for public APIs that do not need protected, search
engine web services. Also, do not enable client verification for the top-level page of an application, because the
security token is not available when the user enters a URL in the browser address bar.

Programming effectively
The following recommendations can help improve or customize your ColdFusion Ajax application.

• Use the AjaxOnLoad function, which specifies a JavaScript function to run when the page loads, to perform any
initialization actions that are required for a page to function properly. You should use the AjaxOnLoad function to
call functions when a page is loaded in a container tag. One use for this function could be on a page that pops up a
login window if the user is not already logged in when it displays. You can use the AjaxOnLoad function to specify
a JavaScript function that determines the login status and pops up the window only if required.
• Use the following ColdFusion JavaScript functions to access the Ext JS or Yahoo YUI JavaScript library objects
that underlie border and tab style cflayout controls, cfwindow controls, and HTML format cfgrid and cftree
controls. Then you can use the raw object to modify the displayed control.
•

ColdFusion.Layout.getBorderLayout

•

ColdFusion.Grid.getGridObject

•

ColdFusion.Layout.getTabLayout

•

ColdFusion.Tree.getTreeObject

•

ColdFusion.Window.getWindowObject

For documentation on the objects and how to manage them, see the Ext documentation and the Yahoo toolkit
documentation.

674

Chapter 36: Using the Flash Remoting
Service
Using the Flash Remoting service of ColdFusion, ColdFusion developers can work together with Flash designers to
build dynamic Flash user interfaces for ColdFusion applications.
For a complete description of Flash Remoting capabilities, including how ColdFusion interacts with Flash Remoting,
see Using Flash Remoting MX 2004 and Flash Remoting ActionScript Dictionary in Flash Help. You can also access the
Flash Remoting documentation on the Flash Remoting Developer Center at www.adobe.com/devnet/mx/flashremoting.
Contents

About using the Flash Remoting service with ColdFusion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674
Configuring the Flash Remoting Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
Using the Flash Remoting service with ColdFusion pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679
Using Flash with CFCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
Using the Flash Remoting service with ColdFusion Java objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685
Handling errors with ColdFusion and Flash. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686

About using the Flash Remoting service with
ColdFusion
Using the Flash Remoting service of ColdFusion, ColdFusion developers can work together with Flash MX 2004
designers to build Flash user interfaces (UIs) for ColdFusion applications. Building Flash UIs requires the separation
of UI code from business logic code. You build user interface controls in Flash MX, and you build the business logic
in ColdFusion.
The following is a simplified representation of the relationship between Flash and ColdFusion:

ADOBE COLDFUSION 8 675
ColdFusion Developer’s Guide

Planning your Flash application
When you are planning ColdFusion application development with Flash UIs, remember the importance of
separating display code from business logic. Separating display code from business logic enables your ColdFusion
applications to interact with multiple client types, such as Flash applications, web browsers, and web services.
When you build ColdFusion applications for multiple clients, your ColdFusion pages and components return
common data types, including strings, integers, query objects, structures, and arrays. Clients that receive the results
can process the passed data according to the client type, such as ActionScript with Flash, or CFML with ColdFusion.
To use the Flash Remoting service with ColdFusion, you build ColdFusion pages and components or deploy Java
objects. In ColdFusion pages, you use the Flash variable scope to interact with Flash applications. ColdFusion
components (CFCs) natively support Flash interaction. The public methods of Java objects are also available to the
Flash Remoting service.
The Flash Remoting ActionScript API has been updated to comply with ActionScript 2.0. The ActionScript 2.0
version of the API consists of the following significant features:
Flash Remoting MX 2004 ActionScript 2.0 API Features
Enforcement of strict data typing, which requires you to declare the data types of variables and prohibits you from assigning different types
of data to them.
Enforcement of case sensitivity, which means that myvar and myVar are two different variables, though they were considered the same
variable with different spellings in ActionScript 1.0.
A new Service class, which lets you create a gateway connection and at the same time obtain a reference to a service and its methods. It
includes the connection property, which returns the connection and also lets you set credentials for authorization on the remote server.
Note: The NetServices class is still supported but has been deprecated in favor of the new Service and Connection classes
A new Connection class that helps you create and use Flash Remoting connections.
Note: The Connection class supersedes the former NetConnection class.

ADOBE COLDFUSION 8 676
ColdFusion Developer’s Guide

Flash Remoting MX 2004 ActionScript 2.0 API Features
A new PendingCall object returned on each call to a service method that is invoked using the Service object. The PendingCall object
contains the responder property, which you use to specify the methods to handle the results of the service call.
A new RelayResponder class, which specifies the methods to which the result and fault outcomes of a service call are relayed.
A RecordSet object that contains new properties (columnNames, items, and length), new methods (clear(), contains(),
editField(), getEditingData(), getIterator(), getLocalLength(), getRemoteLength(), isEmpty(), and sortItems()),
and the new modelChanged event.

For more information on the ActionScript 2.0 Flash Remoting API, see Flash Remoting ActionScript Dictionary
Help.

Configuring the Flash Remoting Gateway
The following parameters in the ColdFusion web.xml file point the Flash Remoting gateway to the gatewayconfig.xml file.

gateway.configuration.file
/WEB-INF/gateway-config.xml


whitelist.configuration.file
/WEB-INF/gateway-config.xml


whitelist.parent.node
gateway-config


Both the web.xml file and the gateway-config.xml file are located in the WEB-INF directory of your ColdFusion
server. As a general rule, there is no need to change these web.xml settings.
ColdFusion MX 7 and later versions of ColdFusion configure Flash gateways differently from previous ColdFusion
releases. Parameters that worked prior to this release are no longer supported, and you specify all configuration
parameters in the gateway-config.xml file. Also, the Flash gateway now supports a whitelist, which specifies which
remote sources can be accessed through the gateway. The two web.xml entries that identify the whitelist should
specify your gateway-config.xml file and gateway-config as the parent node.
You can modify the gateway-config.xml file to configure service adapters, add service names to the whitelist, change
the logging level, and specify how the gateway handles case sensitivity.
You can configure gateway features in the gateway-config.xml file as follows:

ADOBE COLDFUSION 8 677
ColdFusion Developer’s Guide

Feature

Description

service adapters

By default, the PageableResultSetAdapter, the ColdFusionAdapter, the CFCAdapter
(for ColdFusion components), and the CFSSASAdapter (for server-side ActionScript)
adapters are enabled in ColdFusion.
You can also enable the JavaBeanAdapter, JavaAdapter, EJBAdapter, ServletAdapter,
and CFWSAdapter (for web services) by removing their enclosing comment symbols
(). The following service adapter tags are defined as the default tag values:

flashgateway.adapter.resultset.PageableResultSetAdap
ter

coldfusion.flash.adapter.ColdFusionAdapter
coldfusion.flash.adapter.CFCAdapter
coldfusion.flash.adapter.CFSSASAdapter







ADOBE COLDFUSION 8 678
ColdFusion Developer’s Guide

Feature

Description

security

You can edit security settings in child tags of the  tag.
In the  tag, you can set the
flashgateway.security.LoginCommand implementation for performing local
authentication on a specific application server. By default, the  tag
is set to the following values:

flashgateway.security.JRunLoginCommand
JRun


In the  tag, you can enable stack traces. Stack traces are useful
for debugging and product support, but they should not be sent to the client in
production mode because they can expose internal information about the system. The
following  tag is the default tag:
false

The  tag specifies which remote sources can be accessed through the
gateway. The * character can be used as a wildcard to imply ALL matches. The
following  tag shows the default value:

*


When you deploy your application, ensure that you change this setting so that it specifies only the services that the gateway needs to access to run your application.
Remember that for ColdFusion based services, directories are treated as "packages"
and thus you specify a period delimited path from the web root to the directory or file
containing the services you will allow access to. An asterisk wildcard allows access to
all services in a particular directory. You can have multiple  tags.
The following whitelist allows access to the webroot/cfdocs/exampleapps/ directory,
which includes the flash1 through flash5 Flash Remoting example directories. It also
allows access to a webroot/BigApp/remoting directory and its children.

cfdocs.exampleapps.*
BigApp.remoting.*


logger level

You can set the level of logging between None, Error, Info, Warning, and Debug.
The following tag is the default logger level tag:
coldfusion.flash.ColdFusionLogger

redirect URL

In the  tag, you can specify a URL to receive HTTP requests that are
not sent with AMF data. By default, the  tag is set to
{context.root}, which is the context root of the web application:
{context.root}

case sensitivity

The  tag specifies how the gateway handles case sensitivity.
ActionScript 1.0 and ColdFusion use case insensitive data structures to store associative arrays, objects and structs. The Java representation of these data types requires a
case-insensitive Map, which the gateway achieves by forcing all keys to lowercase.
ActionScript 2.0 is case sensitive and requires a  tag value of false.
The following  tag is the default tag:
true

ADOBE COLDFUSION 8 679
ColdFusion Developer’s Guide

Using the Flash Remoting service with ColdFusion
pages
When you build a ColdFusion page that interacts with a Flash application, the directory name that contains the
ColdFusion pages translates to the service name that you call in ActionScript. The individual ColdFusion page
names within that directory translate to service functions that you call in ActionScript.
Note: Flash Remoting cannot interact with virtual directories accessed through a ColdFusion mapping.
In your ColdFusion pages, you use the Flash variable scope to access parameters passed to and from a Flash application. To access parameters passed from a Flash application, you use the parameter name appended to the Flash
scope or the Flash.Params array. To return values to the Flash application, use the Flash.Result variable. To set
an increment value for records in a query object to be returned to the Flash application, use the Flash.Pagesize
variable.
The following table shows the variables contained in the Flash scope:
Variable

Description

For more information

Flash.Params

Array that contains the parameters passed from the Flash application. See “Accessing parameters passed from
If you do not pass any parameters, Flash.params still exists, but it is Flash” on page 680.
empty.

Flash.Result

The variable returned from the ColdFusion page to the Flash applica- See “Returning results to Flash” on page 681.
tion that called the function.

Note: Because ActionScript performs automatic type conversion,
do not return a Boolean literal to Flash from ColdFusion. Return 1 to
indicate true, and return 0 to indicate false.
Flash.Pagesize

The number of records returned in each increment of a record set to See “Returning records in increments to
a Flash application.
Flash” on page 682.

The following table compares the ColdFusion data types and their ActionScript equivalents:
ActionScript data type

ColdFusion data type

Number (primitive data type)

Number

Boolean (primitive data type)

Boolean (0 or 1)

String (primitive data type)

String

ActionScript Object

Structure

ActionScript Object (as the only argument passed to a service
function)

Arguments of the service function. ColdFusion pages (CFM files): flash
variable scope, ColdFusion components (CFC files): named arguments

Null

Null (Asc() returns 0, which translates to not defined)

Undefined

Null (Asc() returns 0, which translates to not defined)

Ordered array

Array

Note: ActionScript array indexes start at zero (for example:
my_ASarray[0]).

Note: ColdFusion array indexes start at one (for example: my_CFarray[1]).

Named (or associative) array

Struct

ADOBE COLDFUSION 8 680
ColdFusion Developer’s Guide

ActionScript data type

ColdFusion data type

Date object

Date

XML object

XML document

RecordSet

Query object (when returned to a Flash application only; you cannot pass
a RecordSet from a Flash application to a ColdFusion application)

Also, remember the following considerations regarding data types:

• If a string data type on the server represents a valid number in ActionScript, Flash can automatically cast it to a
number if needed.
• To return multiple, independent values to the Flash application, place them in a complex variable that converts
to a Flash Object, Array, or Associative Array, that can hold all of the required data. Return the single variable and
access its elements in the Flash application.
For a complete explanation of using Flash Remoting data in ActionScript, see Using Flash Remoting MX 2004 Help.

Accessing parameters passed from Flash
To access variables passed from Flash applications, you append the parameter name to the Flash scope or use the
Flash.Params array. Depending on how the values were passed from Flash, you refer to array values using ordered
array syntax or structure name syntax. Only ActionScript objects can pass named parameters.
For example, if you pass the parameters as an ordered array from Flash, array[1] references the first value. If you
pass the parameters as named parameters, you use standard structure-name syntax like params.name.
You can use most of the CFML array and structure functions on ActionScript collections. However, the StructCopy
CFML function does not work with ActionScript collections. The following table lists ActionScript collections and
describes how to access them in ColdFusion:
Collection

ActionScript example

Notes

Strict array

var myArray:Array = new Array();
myArray[0] = "zero";
myArray[1] = "one";
myService.myMethod(myArray);

The Flash Remoting service converts the Array argument to a
ColdFusion array. All CFML array operations work as expected.



ADOBE COLDFUSION 8 681
ColdFusion Developer’s Guide

Collection

ActionScript example

Notes

Named or associative array

var myStruct:Array = new Array();
myStruct["zero"] = "banana";
myStruct["one"] = "orange";
myService.myMethod(myStruct);

Named array keys are not case-sensitive in ActionScript.

var myMxdArray:Array = new Array();
myMxdArray["one"] = 1;
myMxdArray[2] = true;

Treat this collection like a structure in ColdFusion. However,
keys that start with numbers are invalid CFML variable names.
Depending on how you attempt to retrieve this data, ColdFusion might throw an exception. For example, the following CFC
method throws an exception:

Mixed array







The following CFC method does not throw an exception:



Using an ActionScript object initializer for named arguments

myService.myMethod
({ x:1, Y:2, z:3 });

This notation provides a convenient way of passing named
arguments to ColdFusion pages. You can access these arguments in ColdFusion pages as members of the Flash scope:




Or, you can access them as normal named arguments of a CFC
method.

The Flash.Params array retains the order of the parameters as they were passed to the method. You use standard
structure name syntax to reference the parameters; for example:

SELECT ItemName, ItemDescription, ItemCost
FROM tblItems
WHERE ItemName EQ '#Flash.paramName#'


In this example, the query results are filtered by the value of Flash.paramName, which references the first parameter
in the passed array. If the parameters were passed as an ordered array from the Flash application, you use standard
structure name syntax; for example:


Note: ActionScript array indexes start at zero. ColdFusion array indexes start at one.

Returning results to Flash
In ColdFusion pages, only the value of the Flash.Result variable is returned to the Flash application. For more
information about supported data types between ColdFusion and Flash, see the data type table in “Using the Flash
Remoting service with ColdFusion pages” on page 679. The following procedure creates the service function
helloWorld, which returns a structure that contains simple messages to the Flash application.
Create a ColdFusion page that passes a structure to a Flash application
1 Create a folder in your web root, and name it helloExamples.
2

Create a ColdFusion page, and save it as helloWorld.cfm in the helloExamples directory.

ADOBE COLDFUSION 8 682
ColdFusion Developer’s Guide

3

Modify helloWorld.cfm so that the CFML code appears as follows:




In the example, two string variables are added to a structure; one with a formatted date and one with a simple
message. The structure is passed back to the Flash application using the Flash.Result variable.


4

Save the file.

Remember, the directory name is the service address. The helloWorld.cfm file is a method of the helloExamples
Flash Remoting service. The following ActionScript example calls the helloWorld ColdFusion page and displays the
values that it returns:
import mx.remoting.*;
import mx.services.Log;
import mx.rpc.*;
// Connect to helloExamples service and create the howdyService service object
var howdyService:Service = new Service(
"http://localhost/flashservices/gateway",
null,
"helloExamples",
null,
null );
// Call the service helloWorld() method
var pc:PendingCall = howdyService.helloWorld();
// Tell the service what methods handle result and fault conditions
pc.responder = new RelayResponder( this, "helloWorld_Result", "helloWorld_Fault" );
function helloWorld_Result(re:ResultEvent)
{
// Display successful result
messageDisplay.text = re.result.HELLOMESSAGE;
timeDisplay.text = re.result.TIMEVAR;
}
function helloWorld_Fault(fe:FaultEvent)
{
// Display fault returned from service
messageDisplay.text = fe.fault;
}

Note: Due to ActionScript's automatic type conversion, do not return a Boolean literal to Flash from ColdFusion. Return
1 to indicate true, and return 0 to indicate false.

Returning records in increments to Flash
ColdFusion lets you return record set results to Flash in increments. For example, if a query returns 20 records, you
can set the Flash.Pagesize variable to return five records at a time to Flash. Incremental record sets let you
minimize the time that a Flash application waits for the application server data to load.
Create a ColdFusion page that returns a incremental record set to Flash
1 Create a ColdFusion page, and save it as getData.cfm in the helloExamples directory.
2

Modify getData.cfm so that the code appears as follows:


ADOBE COLDFUSION 8 683
ColdFusion Developer’s Guide





SELECT *
FROM tblParks




In this example, if a single parameter is passed from the Flash application, the pagesize variable is set to the
value of the Flash.Params[1] variable; otherwise, the value of the variable is the default, 10. Next, a statement
queries the database. After that, the pagesize variable is assigned to the Flash.Pagesize variable. Finally, the
query results are assigned to the Flash.Result variable, which is returned to the Flash application.
3

Save the file.

When you assign a value to the Flash.Pagesize variable, you are specifying that if the record set has more than a
certain number of records, the record set becomes pageable and returns the number of records specified in the
Flash.Pagesize variable. For example, the following code calls the getData() function of the CFMService and
uses the first parameter to request a page size of 5:
import mx.remoting.*;
import mx.services.Log;
import mx.rpc.*;
// Connect to helloExamples service and create the CFMService service object
var CFMService:Service = new Service(
"http://localhost/flashservices/gateway",
null,
"helloExamples",
null,
null );
// Call the service getData() method
var pc:PendingCall = CFMService.getData(5);
// Tell the service what methods handle result and fault conditions
pc.responder = new RelayResponder( this, "getData_Result", "getData_Fault" );
function getData_Result(re:ResultEvent)
{
// Display successful result
DataGlue.bindFormatStrings(employeeData, re.result, "#PARKNAME#, #CITY#, #STATE#");
}
function getData_Fault(fe:FaultEvent)
{
// Display fault returned from service
trace("Error description from server: " + fe.fault.description);
}

In this example, employeeData is a Flash list box. The result handler, getData_Result, displays the columns
PARKNAME, CITY, and STATE in the employeeData list box. After the initial delivery of records, the RecordSet
ActionScript class assumes the task of fetching records. In this case, the list box requests more records as the user
scrolls the list box.
You can configure the client-side RecordSet object to fetch records in various ways using the
RecordSet.setDeliveryMode ActionScript function.

ADOBE COLDFUSION 8 684
ColdFusion Developer’s Guide

Using Flash with CFCs
CFCs require little modification to work with a Flash application. The tag names the method and contains the CFML
logic, the cfargument tag names the arguments, and the tag returns the result to the Flash application. The name of
the CFC file (*.cfc) translates to the service name in ActionScript.
Note: For CFC methods to communicate with Flash applications, you must set the cffunction tag’s access attribute
to remote.
The following example replicates the helloWorld function that was previously implemented as a ColdFusion page.
For more information, see “Using the Flash Remoting service with ColdFusion pages” on page 679.
Create a CFC that interacts with a Flash application
1 Create a CFC and save it as flashComponent.cfc in the helloExamples directory.
2

Modify the code in flashComponent.cfc so that it appears as follows:









In this example, the helloWorld function is created. The cfreturn tag returns the result to the Flash application.
3

Save the file.

The helloWorld service function is now available through the flashComponent service to ActionScript. The
following ActionScript example calls this function:
import mx.remoting.*;
import mx.services.Log;
import mx.rpc.*;
// Connect to the Flash component service and create service object
var CFCService:Service = new Service(
"http://localhost/flashservices/gateway",
null,
"helloExamples.flashComponent",
null,
null );
// Call the service helloWorld() method
var pc:PendingCall = CFCService.helloWorld();
// Tell the service what methods handle result and fault conditions
pc.responder = new RelayResponder( this, "helloWorld_Result", "helloWorld_Fault" );
function helloWorld_Result(re:ResultEvent)
{
// Display successful result
messageDisplay.text = re.result.HELLOMESSAGE;
timeDisplay.text = re.result.TIMEVAR;
}
function helloWorld_Fault(fe:FaultEvent)
{

ADOBE COLDFUSION 8 685
ColdFusion Developer’s Guide

// Display fault returned from service
messageDisplay.text = fe.fault;
}

In this example, the CFCService object references the flashComponent component in the helloExamples directory.
Calling the helloWorld function in this example executes the function that is defined in flashComponent.
For ColdFusion components, the component filename, including the directory structure from the web root, serves
as the service name. Remember to delimit the path directories with periods rather than backslashes.

Using the Flash Remoting service with ColdFusion Java
objects
You can run various kinds of Java objects with ColdFusion, including JavaBeans, Java classes, and Enterprise
JavaBeans. You can use the ColdFusion Administrator to add additional directories to the classpath.
Add a directory to ColdFusion classpath
1 Open the ColdFusion Administrator.
2

In the Server Settings menu, click the Java and JVM link.

3

Add your directory to the Class Path form field.

4

Click Submit Changes.

5

Restart ColdFusion.

When you place your Java files in the classpath, the public methods of the class instance are available to your Flash
movie.
For example, assume the Java class utils.UIComponents exists in a directory in your ColdFusion classpath. The
Java file contains the following code:
package utils;
public class UIComponents
{
public UIComponents()
{
}
public String sayHello()
{
return "Hello";
}
}

Note: You cannot call constructors with Flash Remoting. You must use the default constructor.
In ActionScript, the following javaService call invokes the sayHello public method of the utils.UIComponents
class:
import mx.remoting.*;
import mx.services.Log;
import mx.rpc.*;
// Connect to service and create service object
var javaService:Service = new Service(
"http://localhost/flashservices/gateway",
null,

ADOBE COLDFUSION 8 686
ColdFusion Developer’s Guide

utils.UIComponents",
null,
null );
// Call the service sayHello() method
var pc:PendingCall = javaService.sayHello();
// Tell the service what methods handle result and fault conditions
pc.responder = new RelayResponder( this, "sayHello_Result", "sayHello_Fault" );
function sayHello_Result(re:ResultEvent)
{
// Display successful result
trace("Result is: " + re.result);
}
function sayHello_Fault(fe:FaultEvent)
{
// Display fault returned from service
trace("Error is: " + fe.fault.description);
}

Note: For more information about using Java objects with ColdFusion, see “Using Java objects” on page 936

Handling errors with ColdFusion and Flash
To help with debugging, use tags in your ColdFusion page or component to return error messages to the Flash Player.
For example, the ColdFusion page, causeError.cfm, contains the code:








The second cfset tag in this example fails because it tries to divide by zero (0). The message attribute of the
cfthrow tag describes the error; ColdFusion returns this attribute to the Flash application.
To handle the error in your Flash application, create a fault handler similar to causeError_Fault in the following
example:
import mx.remoting.*;
import mx.services.Log;
import mx.rpc.*;
// Connect to service and create service object
var CFMService:Service = new Service(
"http://localhost/flashservices/gateway",
null,
"helloExamples",
null,
null );
// Call the service causeError() method
var pc:PendingCall = CFMService.causeError();
// Tell the service what methods handle result and fault conditions
pc.responder = new RelayResponder( this, "causeError_Result", "causeError_Fault" );
function causeError_Result(re:ResultEvent)

ADOBE COLDFUSION 8 687
ColdFusion Developer’s Guide

{
// Display successful result
messageDisplay.text = re.result;
}
function causeError_Fault(fe:FaultEvent)
{
// Display fault returned from service
trace("Error message from causeError is: " + fe.fault.description);
}

This example displays the trace message from the causeError_Fault function in the Flash Output panel. The
portion of the message that is contained in fe.fault.description is the portion of the message that is contained
in #cfcatch.message# in the causeError.cfm page.
Note: When you create a ColdFusion page that communicates with Flash, ensure that the ColdFusion page works before
using it with Flash.

688

Chapter 37: Using Flash Remoting Update
You can use Flash Remoting Update to create Rich Internet Applications in ColdFusion.
Contents

About Flash Remoting Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688
Installing Flash Remoting Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688
Using Flash Remoting Update. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688

About Flash Remoting Update
The Flash Remoting Update lets you create rich Internet applications using Adobe Flex Builder 2, with the advanced
data retrieval features of ColdFusion, such as the cfpop, cfldap, and cfquery tags. In addition, you can use Flash
Remoting Update to create Flash Forms and Flash applications that contain features, such as server call backs and
customized user interface.
You can use Flash Remoting Update with all configurations of ColdFusion (server, multiserver, and J2EE) on all the
platforms that ColdFusion supports.
To use Flash Remoting Update, you must have the following installed:

•

Flex Builder 2 or later

•

Flash Player 8.5 or later

•

ColdFusion MX 7.0.1 or later

Installing Flash Remoting Update
To install Flash Remoting Update:
1 Install ColdFusion.
2

If your ColdFusion server uses something other than port 8500, do the following:
a

Open the file \wwwroot\Web-INF\flex\flex-enterprise-services.xml.

b

Change the following to specify the port that you are using in the endpoint URL:


The destination “ColdFusion” is preconfigured in the flex-enterprise-services.xml with the wildcard * as the
source. To use the source attribute in MXML, you can use any destination by specifying the source="*" in flexenterprise-services.xml. If you specify a source other that “*” in flex-enterprise-services.xml, that source
definition overrides the source specified in the MXML.
Create a named resource for each CFC that you connect to
1 Edit the WEB-INF\flex\flex-enterprise-services.xml file by adding an entry for each CFC that you connect to,

for example:





dot_ path_to_CFC
true



The source attribute specifies the dot notation to the CFC from the web root (the classpath to the CFC).
2

Restart the ColdFusion server.

Use the CFC resource in your Flex Builder 2 project
1 For each Flex Builder 2 project, set the Flex compiler property by doing the following:
a

Select Project > Properties.

b

Select the Flex complier option.

c

Enter the following in the Additional Compiler Argument text box:
--services=C:\CFusion\wwwroot\WEB-INF\flex\flex-enterprise-services.xml

In the mxml file, you use the  tag to connect to your CFC named resource. With this
connection you can call any remote method on the CFC.

2

3 Use the destination attribute of the  tag to point to the name that you defined in the flexenterprise-services.xml file; for example:


4

Call a CFC method, for example, as the following example shows:


In this example, when a user presses a button, the Click event calls the CFC method getUsers.

ADOBE COLDFUSION 8 690
ColdFusion Developer’s Guide

5 Specify a handler for the return result of the CFC method call for the  tag, as the following
example shows.
private function my_CFC_handler( event:ResultEvent )
{
// Show alert with the value that is returned from the CFC.
mx.controls.Alert.show(ObjectUtil.toString(event.result));
}

691

Chapter 38: Using the LiveCycle Data
Services ES Assembler
To use Adobe ColdFusion as the back-end data manager for an Adobe Flex application, you use the Adobe LiveCycle
Data Services ES assembler that is provided with ColdFusion. You configure the LiveCycle Data Services ES
assembler and write an application that uses the assembler.
To use LiveCycle Data Services ES with ColdFusion, you should be familiar with ColdFusion components; accessing
and using data in ColdFusion applications; and using LiveCycle Data Services ES.
Contents

About ColdFusion and Flex. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
Application development and deployment process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693
Configuring a destination for the ColdFusion Data Service adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693
Writing the ColdFusion CFCs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697
Notifying the Flex application when data changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702
Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702
Enabling SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703
Data translation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704

About ColdFusion and Flex
The LiveCycle Data Services ES assembler lets you use ColdFusion components (CFCs) to provide the back-end data
management for a Flex application that uses the Data Management Service. You can run LiveCycle Data Services ES
as part of ColdFusion or remotely. If you are running LiveCycle Data Services ES as part of ColdFusion, LiveCycle
Data Services ES and ColdFusion communicate directly. If you are running LiveCycle Data Services ES remotely,
LiveCycle Data Services ES and ColdFusion communicate by using RMI. The following diagram shows how
ColdFusion and LiveCycle Data Services ES interact in both cases:

Note: To use the LiveCycle Data Services ES assembler, the Flex application must be running on Flex Data Services 2.0.1
or LiveCycle Data Services 2.5, although not every feature is supported in Flex Data Services 2.0.1.

ADOBE COLDFUSION 8 692
ColdFusion Developer’s Guide

The Flex server includes a ColdFusion Data Service adapter. The adapter processes changes to data to ensure that
data on the client is synchronized with back-end data and vice versa; it executes the sync, fill, count and get
operations, identifies conflicts, and passes results to LiveCycle Data Services ES.
ColdFusion includes the LiveCycle Data Services ES assembler; along with the ActionScript translator, it converts
the input arguments where necessary and translates the return values.
Note: If you install LiveCycle Data Services ES, ColdFusion does not map .SWF files. This means that all .SWF files are
served through the ColdFusion web application instead of the web server.
The following diagram shows the process that LiveCycle Data Services ES and ColdFusion use when a Flex application calls a method in a ColdFusion component:

1

A Flash client requests data that is handled by the LiveCycle Data Management Service adapter.

2

Flex calls a fill, sync, get, or count method in the Data Service.

3 The ColdFusion Data Service adapter sends the request to the LiveCycle Data Services ES assembler. If you are
running LiveCycle Data Services ES remotely, the adapter sends the request by using Java Remote Method
Invocation (Java RMI).
4 The LiveCycle Data Services ES assembler and the ActionScript translator convert ActionScript 3.0 data types to
the appropriate ColdFusion values.
5 The ColdFusion server invokes the fill, sync, get, or count method of the assembler CFC, which invokes the
appropriate methods in the DAO CFC.
6 The ColdFusion application creates an array of Value Objects or appropriate return value, which it sends to the
ColdFusion server.
7

The ColdFusion server sends the results to the LiveCycle Data Services ES assembler.

8 The LiveCycle Data Services ES assembler and the ActionScript translator convert ColdFusion values to the
appropriate ActionScript 3.0 data types, and then the assembler sends the results to the ColdFusion Data Service
adapter.
9

The ColdFusion Data Service adapter sends the results to the LiveCycle Data Management Service.

10 The LiveCycle Data Management Service passes the results to the Flash client.

Note: The RMI registry, which facilitates communication between the ColdFusion Data Service assembler and the
remote LiveCycle Data Management Service uses port 1099, which is the default port for Java RMI. You can change the
port number by adding -Dcoldfusion.rmiport=1234 to the Java JVM arguments on both the ColdFusion server and
the Flex server.

ADOBE COLDFUSION 8 693
ColdFusion Developer’s Guide

Application development and deployment process
The following is a typical process for developing and deploying a Flex application that uses the ColdFusion Data
Service adapter and LiveCycle Data Services ES assembler to manage back-end database tasks:
1

Design your application.

2 Create the Flex application, in which you define a DataService component in MXML or ActionScript. The
DataService component calls methods on a server-side Data Management Service destination to perform activities
such as filling client-side data collections with data from remote data sources and synchronizing the client and server
versions of data.
3 Configure a destination for the ColdFusion Data Service adapter so that the Flex application to connect to the
ColdFusion back-end application. For more information, see “Configuring a destination for the ColdFusion Data
Service adapter” on page 693.
4

Write your ColdFusion CFCs. For more information, see “Writing the ColdFusion CFCs” on page 697.

Note: To make creating the CFCs easier, ColdFusion includes wizards that you can use in Flex Builder. For more information, see “Using the ColdFusion Extensions for Eclipse” on page 1142.
5

Test your application by using Flex.

Configuring a destination for the ColdFusion Data
Service adapter
To provide the information necessary for the Flex application to connect to the ColdFusion back-end application,
you configure a destination. In the destination, you specify the ColdFusion Data Service adapter, the channels to use
to transport messages to and from the destination, the CFC that contains the fill, get, sync, and count methods,
and other settings.
To provide configuration information, you edit the following files:
1

services-config.xml
You specify channel definitions and enable ColdFusion-specific debugging output in the Flex console in this file.
You must also change the port numbers in the services-config.xml file for the RTMP channels if you run more
than one ColdFusion instance with the integrated LiveCycle Data Services ES.

2

data-management-config.xml
You specify adapters and destinations in this file.

To ensure that Flex recognizes the LiveCycle Data Services ES assembler and can transport messages to and from the
destination, by doing the following:

•

Specifying ColdFusion-specific channel definitions

•

Specifying the ColdFusion Data Service adapter

•

Specifying a destination

•

Enabling ColdFusion-specific debugging output

ADOBE COLDFUSION 8 694
ColdFusion Developer’s Guide

Specifying ColdFusion-specific channel definitions

LiveCycle Data Services ES transports messages to and from destinations over message channels that are part of the
Flex messaging system. When you configure a destination, you reference the messaging channels to use. To connect
to a ColdFusion back-end application, ensure that the services-config.xml file contains definitions for the cf-pollingamf channel and the cf-rtmp channel in the channels section. If you are running LiveCycle Data Services ES in
ColdFusion, the services-config.xml file is in the wwwroot\WEB-INF\flex directory and contains the channel
definitions by default. If you are running LiveCycle Data Services ES remotely, the services-config.xml file is located
in the C:\lcds\jrun4\servers\default\samples\WEB-INF\flex folder when you install Flex in the default location.
The channel definitions include the following:



true

false






20


false



Specifying the ColdFusion Data Service adapter

Flex provides adapters to connect to various back-end applications. To use the ColdFusion Data Service adapter, you
specify it in the data management configuration file by copying the following adapter-definition to the adapters
section of the data-management-config.xml file that is in the WEB-INF/flex folder of the server on which you want
to run the Flex application. If you are running LiveCycle Data Services ES in ColdFusion, the data-managementconfig.xml file contains the adapter definitions by default.
The adapter definition includes the following line:

Specifying a destination

A destination is the server-side service or object that you call. You configure Data Management destinations in the
data-management-config.xml file.
The destination contains the following elements:

ADOBE COLDFUSION 8 695
ColdFusion Developer’s Guide

Element

Description

destination id

The ID must be unique for each destination.

adapter

The name of the adapter to use. You use the ColdFusion adapter element for any ColdFusion specific
destinations.

channels

Use the ColdFusion configured channels that have the instantiate-types flag set to false.

component

The name or path of the assembler CFC.

scope

The scope, which can be application, session, or request. The application value specifies
that there is only one instance; request specifies that there is a new CFC for each call. ColdFusion does
not support session. (Do not confuse this setting with the ColdFusion variable scope; they are not
related.)

use-accessors

Whether the Value Object CFC has getters and setters. Set the value of use-accessors to true if
there are getters and setters in the Value Object CFC. However, if you set use-accessors to true and
there are no getters and setters in the value object CFC, ColdFusion sets the value of any property of
the value object CFC in the this scope. If your CFC does not have any getters and setters, you can
increase performance by setting this to false so that ColdFusion does not spend time looking for
these methods. The default value is true.

use-structs

Whether to translate ActionScript to CFCs. Set the value of use-structs to true if you don't require
any translation of ActionScript to CFCs. The assembler can still return structures to Flex, even if the
value is false. The default value is false.

hostname

The hostname or IP address of the ColdFusion host. If you are running LiveCycle Data Services as part
of ColdFusion you do not specify a hostname or IP address; however, if you are running LiveCycle Data
Services ES remotely, you must specify a hostname or IP address.

identity

The ID of the ColdFusion Data Management server as configured in the ColdFusion Administrator.
This is required only if you are accessing a ColdFusion server remotely using RMI and have more than
one instance of ColdFusion on a machine.

remote-password

Credentials to pass to the assembler CFC for all clients. It is generally preferable to use the ActionScript
setRemoteCredentials() API on the client.

method-access-invoke

The access level of the CFC, which can be public (including remote) or remote.

force-cfc-lowercase

Whether to make property names, query column names, and structure keys lowercase when
converting to ActionScript. Query column names must precisely match the case of the corresponding
ActionScript variables. The default value is false.

remote-username

force-query-lowercase
force-struct-lowercase
identity property

The property or list of properties that are the primary key in the database.

query-row-type

Optional. If the assembler fill method returns a query, you must define an ActionScript type for each
row in the query that the ArrayCollection returned.

fill-method

Whether to update the results of a fill operation after a create or update operation.

use-fill-contains

Optional. Whether the assembler has a fill-contains method. This method is used to determine
whether to refresh the fill. If the specified method returns true, the fill is re-executed after a create or
update operation. Set use-fill-contains to true only when auto-refresh is set to true. The
default value is false.

auto-refresh

Optional. Whether to refresh the fill after a create or update operation. The default value is true.

ordered

Optional. Whether order is important for this filled collection. Allows performance optimization when
order is not important. The default value is true.

The following code shows a sample destination:


ADOBE COLDFUSION 8 696
ColdFusion Developer’s Guide







samples.contact.ContactAssembler
request
true
false
localhost
default



remote


false
false
false



samples.contact.Contact






false
true
true




Enabling ColdFusion-specific debugging output

You enable ColdFusion-specific debugging output in the Flex console by adding the following  tag in the
 tag in the logging section in the services-config.xml file:
DataService.coldfusion

For more information, see “Configuring the Data Service” in Developing Flex Applications, which is included in the
Flex documentation.
Note: The ColdFusion Administrator lets you enable or disable LiveCycle Data Management support. If you are running
more than one instance of ColdFusion, you must use a unique ID to specify each instance of ColdFusion for which you
enable LiveCycle Data Management support. You do so by specifying the identity in the identity element in the datamanagement-config.xml file.

ADOBE COLDFUSION 8 697
ColdFusion Developer’s Guide

Writing the ColdFusion CFCs
When you create your ColdFusion CFCs, you can do one of the following:

•

Create an assembler CFC and a Value Object CFC.

•

Create an assembler CFC, a Data Access Object (DAO) CFC, and a Value Object CFC.

You put the database manipulation functionality directly in the methods in the assembler CFC and create a Value
Object CFC, which is a CFC that contains property definitions and related get and set methods.
To separate the lower level database functionality from the high-level Flex assembler operations, you create a Data
Access Object (DAO) CFC that contains the lower level database functionality. Using this approach, which is the
Bean/DAO methodology, requires that you put the fill, get, sync, and count methods in the assembler CFC. The
methods in the assembler CFC call methods in the DAO CFC that perform the lower level database functions such
as retrieving records. The DAO CFC creates Value Objects, which are CFCs that contain the values. A Value Object
is essentially a row in the result set.
The following diagram shows the two methodologies:

The LiveCycle Data Management Service recognizes the methods: fill, get, sync, and count. The fill method
retrieves records from a database and populates an array with the records. The get method retrieves a specific
record. The sync method lets you keep track of synchronization conflicts by accepting a change list, which is an array
of change objects. The count method returns a number that indicates how many records are in a result set. To
perform any of these database tasks, the Flex application calls the appropriate fill, get, sync, or count method in
the assembler CFC. You can also use a fillContains method, which checks whether to update the results of a fill.
For more information, see “Managing fills” on page 700.

Creating the fill method
The fill method retrieves records from a database and populates an array with the records. If you use the
Bean/DAO methodology, you create the lower level read method separately in the DAO CFC.
The fill method returns the results of a read operation. In the fill method, you create an array to hold the results
of the read, and then return the results of the read operation. The essential elements of a fill method appear as
follows:




ADOBE COLDFUSION 8 698
ColdFusion Developer’s Guide

You can return a Value Object CFC, a query, or an array of CFML structures. Using a query instead of a Value Object
CFC may improve performance. However, ColdFusion cannot handle nested results sets when you use a query. For
example, if one of the CFC properties you are returning from the fill method was populated with another complex
type such as another CFC type, ColdFusion cannot automatically convert a column in the query to an object with a
custom type. In this case, you return an array of CFCs, and the fill method or the read method in the DAO CFC
constructs the correct object.
You can use structures wherever you currently create a ColdFusion component in the Assembler. However, you still
receive CFC Value Objects from Flex. For example, the Change Objects that you receive in the sync method contain
CFCs, assuming you have a remote alias defined in the ActionScript type.
You can create Value Object CFCs in the get method. However, using the structure functionality, you can create and
return a structure instead of a CFC, because the structures are translated in exactly the same way as CFCs. You can
also return an array of structures from the fill method instead of an array of CFCs, for example, if you have to do
processing on your data and working with CFCs isn't fast enough. Generally, structures are faster than CFCs. You
also use structures when a member of the result object is a complex object. In this case, you create another structure
as the value of that key and provide the __type__ key for it.
You specify the returntype of the fill method as a Value Object CFC, a query, or an array:
1

Value Object:


2

Query:


3

Array of structures:


In addition to specifying the returntype of the fill function depending on whether you are using Value Objects, a
query, or an array of structures, you also do the following in the lower level read function:

•

Specify the returntype of the read function as the Value Object CFC, a query, or an array, for example:

• 

•

• 
• 
If you are using Value Objects:
•

Create the array to contain the Value Objects, as follows:


•

Loop through the query to create each Value Object based on each row of the query, for example:


obj = createObject("component",
"samples.contact.Contact").init();
obj.setcontactId(qRead.contactId);
obj.setfirstName(qRead.firstName);
obj.setlastName(qRead.lastName);
obj.setaddress(qRead.address);
obj.setcity(qRead.city);

ADOBE COLDFUSION 8 699
ColdFusion Developer’s Guide

obj.setstate(qRead.state);
obj.setzip(qRead.zip);
obj.setphone(qRead.phone);
ArrayAppend(ret, obj);



•

If you are using a query:

• Ensure that you configured the destination with the row type for the destination so that ColdFusion correctly
labels each rows in the query with the corresponding ActionScript type. Use the query-row-type element,
which is in the metadata section of the destination.
•

Specify the following in the fill method:








•

If you are using a DAO CFC, edit the read method to return a query instead of an array of CFCs.

•

Ensure that the query column names match the case of the properties in the ActionScript object. Use the

property-case settings in the destination to do so. Set the force-query-lowercase element to false so that

ColdFusion converts all column names to lowercase.

•

If you are using an array of structures:

•

Create the array to contain the Value Objects, as follows:


•

Loop through the query to create the structure that contains the results of the query, for example:


stContact = structNew();
stContact["__type__"] = "samples.contact.Contact";
stContact["contactId"] = qRead.contactId;
stContact["firstName"] = qRead.firstName;
stContact["lastName"] = qRead.lastName;
stContact["address"] = qRead.address;
stContact["city"] = qRead.city;
stContact["state"] = qRead.state;
stContact["zip"] = qRead.zip;
stContact["phone"] = qRead.phone;
ArrayAppend(ret, duplicate(stContact));



•

Use the "type" structure element to specify that the Value Object CFC is the type, for example:
stContact["_type_"] = "samples.contact.Contact";

• Use the associative array syntax, for example, contact["firstName"] to ensure that you match the case of
the ActionScript property. If you use the other syntax, for example, contact.firstName="Joan", ColdFusion
makes the key name uppercase.

ADOBE COLDFUSION 8 700
ColdFusion Developer’s Guide

Managing fills
To determine whether to refresh a fill result after an item is created or updated, you include a fillContains method
in the assembler and set both use-fill-contains and auto-refresh to true in the fill-method section of the
data-management-config.xml file. The following examples shows a fill-method section:

true
true
false


In this example, ordered is set to false because the fill result is not sorted by any criteria. However, if the fill result
is sorted, you set ordered to true. When an item changes in a fill result that is ordered, you must refresh the entire
fill result.
The fillContains method tells the Flex application whether it is necessary to run the fill again after an item in the
fill result has changed. The fillCcontains method returns a value that indicates how the fill should be treated for
that change. When the fillContains method returns true, the fill is executed after a create or update operation.
The following example shows the fillContains method signature:





The fillContains method has the following arguments:

•

fillArgs is a list of arguments to pass to the fill method.

•

item is the record to check to determine if it is in the result set.

•

isCreate indicates whether the record is new.

A sample fillContains method, which determines whether the fill arguments (part of the first or last name) are
in the Contact item passed to the function, is as follows:






















ADOBE COLDFUSION 8 701
ColdFusion Developer’s Guide





If you are running LiveCycle Data Services ES locally, you can determine whether a fill operation is a refresh or a
client triggered fill. You do so by calling the DataServiceTransaction.getCurrentDataServiceTransaction().isRefill()
method in your ColdFusion application as follows:

dst = CreateObject("java", "flex.data.DataServiceTransaction");
t = dst.getCurrentDataServiceTransaction();
isRefill = t.isRefill();


This does not work over RMI when ColdFusion and Flex are not in the same web application.

Creating the get method
The get method retrieves a specific record. The get method calls the lower level read method. If you use the
Bean/DAO methodology, as described in “Writing the ColdFusion CFCs” on page 697, you create the lower level
read method separately in the DAO CFC.
The following examples shows the essential elements of a get method:







The returntype of a get method can be any of the following:

•

The Value Object CFC

•

Any

•

An array

Creating the sync method
The sync method lets you keep track of synchronization conflicts by accepting a change list, which is an array of
change objects. In the sync method, you pass in an array of changes, loop over the array and apply the changes, and
then return the change objects, as follows:















ADOBE COLDFUSION 8 702
ColdFusion Developer’s Guide







Creating the count method
The count method returns a number that indicates how many records are in a result set. If you use the Bean/DAO
methodology, as described in “Writing the ColdFusion CFCs” on page 697, you create the lower level count method
separately in the DAO CFC.
The count method contains the following essential elements, without any error handling:





This count method calls a different count method in the DAO CFC, which contains the following essential
elements, without any error handling:





select COUNT(*) as totalRecords
from Contact




Notifying the Flex application when data changes
You use the LiveCycle Data Services ES event gateway type provided with ColdFusion, to have ColdFusion applications notify Flex when data that is managed by a destination has changed. You configure the LiveCycle Data Services
ES event gateway and write an application that uses the event gateway. For more information, see “Using the Data
Management Event Gateway” on page 1124.

Authentication
To authenticate users when using the LiveCycle Data Services ES assembler, you use the Flex
setRemoteCredentials() method on the DataService object. The credentials, which are in the FlexSession object,
are passed to the ColdFusion application, where you can use the cflogin tag to perform authentication. Alternatively, you can set credentials in the Flex destination, although this is not the recommended way to do so.
You can set the credentials by doing either of the following:

•

Specifying credentials in ActionScript

ADOBE COLDFUSION 8 703
ColdFusion Developer’s Guide

•

Specifying credentials in the Flex destination

Specifying credentials in ActionScript
To specify credentials in ActionScript, you use the setRemoteCredentials() method, as the following example
shows:
ds = new DataService(“mydest”);
ds.setRemoteCredentials(“wilsont”, “password”);

Specifying credentials in the Flex destination
To specify credentials in the Flex destination, you edit the data-management-config.xml file that is in the WEBINF/flex folder of the server on which you run the Flex application. In the properties element, you include the
remote-username and remote-password elements, as follows:






samples.contact.ContactAssembler
application
wilsont
password
...
/properties>


Enabling SSL
You encrypt communication between ColdFusion and Flex by enabling Secure Sockets Layer (SSL). Enabling SSL
only makes sense if you are running LiveCycle Data Services ES remotely. To use SSL, you must create a keystore file.
The keystore is a self-signed certificate. (You do not require a certificate signed by a Certificate Authority, although
if you do use one, you do not have to configure Flex as indicated in the following steps.) The information in the
keystore is encrypted and can be accessed only with the password that you specify. To create the keystore, you use
the Java keytool utility, which is included in your Java Runtime Environment (JRE).
To enable SSL, you do the following:

•

Create the keystore

•

Configure Flex

•

Enable SSL in the ColdFusion Administrator

Create the keystore
1 Generate the SSL server (ColdFusion) keystore file by using the keytool utility, with a command similar to the

following:
keytool -genkey -v -alias FlexAssembler -dname "cn=FlexAssembler" -keystore cf.keystore
-keypass mypassword -storepass mypassword

The following table describes the parameters of the keytool utility that you use:

ADOBE COLDFUSION 8 704
ColdFusion Developer’s Guide

Parameter

Description

-alias

The name of the keystore entry. You can use any name for this, as long as you are consistent when referring to it.

-dname

The Distinguished Name, which contains the Common Name (cn) of the server.

-keystore

The location of the keystore file.

-keypass

The password for your private key.

-storepass

The password for the keystore. The encrypted storepass is stored in ColdFuison configuration files.

-rfc

Generates the certificate in the printable encoding format.

-file

The name of the keystore file.

-v

Generates detailed certificate information.

Next, you place the certificate that you created in the file that the JVM uses to decide what certificates to trust. The
file in which you put the certificate, (usually named cacerts), is located in the JRE, under the lib/security folder.
Configure Flex
1 Export the keystore to a certificate by using the keytool utility, with a command similar to the following:
keytool -export -v -alias FlexAssembler -keystore cf.keystore -rfc -file cf.cer

2 Import the certificate into the JRE cacerts file for your server by using the keytool utility, with a command similar
to the following:
keytool -import -v -alias FlexAssembler -file cf.cer -keystore
C:\fds2\UninstallerData\jre\lib\security\cacerts

The previous example specifies the location of the keystore for LiveCycle Data Services ES with integrated JRun,
installed using the default settings. If you are using a different server, specify the location of the cacerts file for
the JRE that you are using. For example, if you are using JBoss, you specify the keystore location as
$JAVA_HOME/jre/lib/security/cacerts.

Enable SSL in the ColdFusion Administrator
1 In the ColdFusion Administrator, select Data & Services > Flex Integration, and specify the keystore file in the

Full Path to Keystore text box.
2

Specify the keystore password in the Keystore password text box.

3

Select the Enable RMI over SSL for Data Management option, and then click Submit Changes.
If you specify an invalid keystore file or password, ColdFusion does not enable SSL, and disables Flex Data
Management Support.

Data translation
The following table lists the ColdFusion data types and the corresponding Adobe Flash or ActionScript data type:

ADOBE COLDFUSION 8 705
ColdFusion Developer’s Guide

ColdFusion data type

Flash data type

String

String

Array

[] = Array

Struct

{} = untyped Object

Query

ArrayCollection

CFC

Class = typed Object (if a matching ActionScript class exists, otherwise the CFC becomes a generic
untyped Object (map) in ActionScript)

CFC Date

ActionScript Date

CFC String

ActionScript String

CFC Numeric

ActionScript Numeric

ColdFusion XML Object

ActionScript XML Object

706

Chapter 39: Using Server-Side
ActionScript
ColdFusion server configuration includes the Flash Remoting service, a module that lets Adobe Flash developers
create server-side ActionScript. These ActionScript files can directly access ColdFusion query and HTTP features
through two new ActionScript functions: CF.query and CF.http.
Contents

About server-side ActionScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
Connecting to the Flash Remoting service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709
Using server-side ActionScript functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709
Global and request scope objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
About the CF.query function and data sources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711
Using the CF.query function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712
Building a simple application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714
About the CF.http function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717
Using the CF.http function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718

About server-side ActionScript
ColdFusion includes a module called the Flash Remoting service that acts as a broker for interactions between Flash
and ColdFusion. Flash Remoting supports a range of object types, and lets you reference an ActionScript file that
lives on a ColdFusion server. You can partition data-intensive operations on the server, while limiting the amount of
network transactions necessary to get data from the server to the client.
Flash developers can create server-side ActionScript files to access ColdFusion resources; they do not have to learn
CFML (ColdFusion Markup Language). This ability lets you logically separate the Flash presentation elements of
your applications from the business logic. You have the option of creating ActionScript files that reside on the server
to partition this processing away from your client applications.
You have a very simple interface for building queries using server-side ActionScript, and an equally simple interface
for invoking these queries from your client-side ActionScript.

Client-side ActionScript requirements
On the client side, you only need a small piece of code that establishes a connection to the Flash Remoting service
and references the server-side ActionScript you want to use.
For example (notice the embedded comments):
// This #include is needed to connect to the Flash Remoting service
#include "NetServices.as"
// This line determines where Flash should look for the Flash Remoting service.
// Ordinarily, you enter the URL to your ColdFusion server.
// Port 8500 is the Flash Remoting service default.

ADOBE COLDFUSION 8 707
ColdFusion Developer’s Guide

NetServices.setDefaultGatewayUrl("http://mycfserver:8500");
// With the Flash Remoting service URL defined, you can create a connection.
gatewayConnnection = NetServices.createGatewayConnection();
// Reference the server-side ActionScript.
// In this case, the stockquotes script file lives in the web root of the
// ColdFusion server identified previously. If it lived in a subdirectory
// of the web root called "mydir," you would reference it
// as "mydir.stockquotes".
stockService = gatewayConnnection.getService("stockquotes", this);
// This line invokes the getQuotes() method defined in the stockquotes
// server-side ActionScript.
stockService.getQuotes("macr");
// Once the record set is returned, you handle the results.
// This part is up to you.
function getQuotes_Result ( result )
{
// Do something with results
}

Note: Client-side ActionScript does not support the two new server-side ActionScript functions, CF.query and
CF.http.

Server-side requirements
Creating ActionScript that executes on the server helps leverage your knowledge of ActionScript. It also provides
direct access to ColdFusion query and HTTP features. The CF.query and CF.http ActionScript functions let you
perform ColdFusion HTTP and query operations.
Note: On the server side, ActionScript files use the extension .asr.
For example, the following server-side ActionScript code builds on the client-side code shown previously:
// Filename: stockquotes.asr
// Here is the getQuotes method invoked in the client-side ActionScript.
// It accepts a single stock quote symbol argument.
function getQuotes(symbol)
{
// Query some provider for the specified stock quote and return the
// results. In this case, the getQuotesFromProvider method is
// defined elsewhere in this ActionScript code.
data = getQuotesFromProvider(symbol);
// Return the data to the client.
// Note: this example does not include any of the error checking
// logic you would normally use prior to returning the data.
return data;
}

The getQuotes function conducts the stock quote request and returns the results of the request to the client as a
RecordSet object.

Software requirements
To use server-side ActionScript files, you must have the following software installed:

•

Adobe Flash

ADOBE COLDFUSION 8 708
ColdFusion Developer’s Guide

•

ColdFusion

•

Flash Remoting Components

For more information about these products, go to www.adobe.com.

Location of server-side ActionScript files
You can place ActionScript files (*.asr) on the server anywhere below the web server’s root directory. To specify
subdirectories of the web root or a virtual directory, use package dot notation (use dots instead of slashes in a fully
qualified directory name). For example, in the following assignment code, the stockquotes.asr file is located in the
mydir/stock/ directory:
stockService = gatewayConnnection.getService("mydir.stock.stockquotes", this);

You can also point to virtual mappings, such as cfsuite.asr.stock.stockquotes where cfsuite is a virtual
mapping and asr.stock is subdirectories of that mapping.

Benefits
Server-side ActionScript lets your ActionScript engineers use their knowledge of ActionScript to write code for the
back end of their Flash applications, which can mean more meaningful levels of interactivity for your users. Your
Flash applications can share a library of server-side ActionScript functions, which means you can define functions
that are specifically tailored to your own business.
You could, for example, create a server-side ActionScript file that defines a whole library of SQL query methods.
With these query methods defined on the server side, your Flash designers only have to invoke the specific query
function they want to return data to their Flash movies. They do not have to write any SQL, and they do not have to
create a new query every time they need to retrieve data from a ColdFusion data source. It is a way of creating
reusable queries that your entire Flash design team can use.
Coding the ColdFusion query and HTTP operations in ActionScript is very straightforward. The CF.query and
CF.http functions provide a well-defined interface for building SQL queries and HTTP operations.
For example, the following is a typical server-side ActionScript function definition that returns query data:
// This function shows a basic CF.query operation using only
// arguments for data source name and for SQL.
function basicQuery()
{
mydata = CF.query({datasource:"customers",
sql:"SELECT * FROM myTable"});
return mydata;
}

What to do next
If you are already familiar with ActionScript, you only need to know a few things to get started:

• How to establish a connection with the Flash Remoting service using client-side ActionScript. See “Connecting
to the Flash Remoting service” on page 709
• How to reference server-side ActionScript functions and methods. See “Using server-side ActionScript
functions” on page 709.
• How to code the server-side CF.query and CF.http functions. See “Using the CF.query function” on page 712
and “Using the CF.http function” on page 718. Also see the reference pages for these functions in the CFML
Reference.

ADOBE COLDFUSION 8 709
ColdFusion Developer’s Guide

For additional information on using Flash Remoting, see “Using the Flash Remoting Service” on page 674 and Using
Flash Remoting.

Connecting to the Flash Remoting service
Before you can use functions defined in your server-side ActionScript files, you must connect the Adobe Flash movie
to the server-side Flash Remoting service.
Create a Flash Remoting service connection
1 Include the necessary ActionScript classes in the first frame of the Flash movie that will be using server-side

ActionScript functions.
a

Use the following command to include the NetServices class:

#include "NetServices.as"

b

(Optional) Use the following command to include the NetDebug class:

#include "NetDebug.as"

For more information about the NetDebug and RecordSet classes, see Using Flash Remoting.
2 Since the Flash Remoting service serves as a broker for calls to server-side ActionScript functions, you must
identify the Flash Remoting service URL as an argument in the NetServices.setDefaultGatewayUrl function.
For example:
NetServices.setDefaultGatewayURL("http://localhost:8500/flashservices")

You must specify a server hostname. The default port number for the Flash Remoting service is 8500.
3

Create the gateway connection using the NetServices.createGatewayConnection function; for example:
gatewayConnection = NetServices.createGatewayConnection();

Using server-side ActionScript functions
After you connect to the Flash Remoting service, you call functions that are defined in your server-side ActionScript
files, and return results.
Call a function
1 Create an instance of the server-side ActionScript file using the getService function. This function instantiates

the server-side ActionScript file as an object to be used on the client side. For example:
albumService = gatewayConnection.getService("recordsettest", this)

Where recordsettest represents the name of the server-side ActionScript file, without the file extension .asr.
2 Call a function defined in your server-side ActionScript object. Use dot notation to specify the object name
followed by the function name; for example:
albumService.getAlbum("The Color And The Shape", "1999");

Where albumService is the instance of the server-side ActionScript file and getAlbum is a function that passes
two arguments, "The Color and The Shape" and "1999".

ADOBE COLDFUSION 8 710
ColdFusion Developer’s Guide

Note: Arguments must occur in the order defined in the function declaration.
3

Handle the function results in ActionScript. See “Using the function results in ActionScript” on page 710.

Using the function results in ActionScript
To use the results returned by server-side ActionScript, you must create a corresponding results function. The results
function uses a special naming convention that ties it to the function that calls the server-side ActionScript. For
example, if you defined a client-side ActionScript function called basicCustomerQuery, you also must create a
results function called basicCustomerQuery_Result.
The results returned by server-side ActionScript functions differ somewhat depending on whether you are using
CF.http or CF.query :

• The CF.query function returns a record set, which you manipulate using methods available in the RecordSet
ActionScript class object. See “Using results returned by the CF.query function” on page 710.
• The CF.http function returns simple text strings through properties that you reference in your server-side
ActionScript. See “Using results returned by the CF.http function” on page 710.
Using results returned by the CF.query function

You use functions in the RecordSet ActionScript object to access the data returned in a CF.query record set; for
example, how many records are in the record set and the names of the columns. You can also use the RecordSet
functions to pull the query data out of the record set. To do so, you reference a specific row number in the record set
and use the getItemAt RecordSet function, as in the following example:
// This function populates a Flash text box with data in the first row
// of the record set under the "email" column name.
function selectData_Result ( result )
{
stringOutput.text = result.getItemAt(0)["email"];
_root.employeesView.setDataProvider(result);
}

In the example, the column name is referenced in the getItemAt function between square brackets [ ]. (In ActionScript, indexes start at 0, so getItemAt(0) returns the first row.)
For more information, see “Using the CF.query function” on page 712.
Using results returned by the CF.http function

The CF.http server-side ActionScript function returns data as simple text. You write server-side functions that
reference the properties available in the object returned by the CF.http function. These properties store the file
content of the retrieved file, HTTP status codes, the MIME type of the returned file, and so on. On the client side,
you create return functions to handle data returned by the CF.http function. You write these functions to handle
simple text data.
For more information, see “Using the CF.http function” on page 718.

Global and request scope objects
Global and request scope objects are implicitly available in all server-side ActionScript. The following table describes
these scope objects:

ADOBE COLDFUSION 8 711
ColdFusion Developer’s Guide

Scope name

Type

Description

config

Global

Initialization information for the server-side ActionScript adapter.
Class: javax.servlet.ServletConfig

application

Global

The context for the current web application. The context defines methods that provide, for
example, the MIME type of a file that can be used to write to a log file. There is one context
per web application.
Class: javax.servlet.ServletContext

request

Request

An object containing client request information. The object provides data, including parameter name and values, attributes, and an input stream.
Class: HttpServletRequest (subtype of javax.servlet.ServletRequest)

response

Request

An object to assist in sending a response to the client. It provides HTTP-specific functionality
in sending a response. Do not use the OutputStream or PrintWriter to send data back to the
client.
Class: HttpServletResponse (subtype of javax.servlet.ServletResponse)

For more information about these scope objects, see the documentation on the javax.servlet class at
http://java.sun.com.

About the CF.query function and data sources
You use the CF.query function to populate Flash movie elements with data retrieved from a ColdFusion data source.
To use the CF.query function you do the following:
Pull data into your Flash movie from a ColdFusion data source
1 Create a server-side ActionScript file that performs queries against a ColdFusion data source.
2 Write ActionScript code in your Flash movie that references your ActionScript file (.asr) on the ColdFusion
server.

You create server-side ActionScript to execute the query and return the data in a record set to the client—your Flash
movie. You can use methods in the RecordSet ActionScript object on the client to manipulate data in the record set
and present data in your Flash movie.
Note: Client-side ActionScript files use the .as extension. Server-side ActionScript files use the .asr (ActionScript remote)
extension.

Publishing dynamic data
You use the server-side ActionScript feature in ColdFusion to publish dynamic data. To do this, you write server-side
ActionScript files that perform queries against ColdFusion data sources. Before using ActionScript, you must understand how to do the following:

• Create database queries in the server-side ActionScript file using the CF.query ActionScript function. See
“Using the CF.query function” on page 712.
• Reference the server-side ActionScript file in your Flash movie. See “Connecting to the Flash Remoting service”
on page 709.
Using the CF.query function, you can do the following tasks:

ADOBE COLDFUSION 8 712
ColdFusion Developer’s Guide

•

Create user login interfaces that validate users against a ColdFusion data source.

•

Populate form elements and data grids with data from a ColdFusion data source.

•

Create banners that pull data (such as URLs or image file paths) out of a database.

The CF.query function can retrieve data from any supported ColdFusion data source (see “About ColdFusion data
sources” on page 712).

About ColdFusion data sources
For ColdFusion developers, the term data source can refer to a number of different types of structured data accessible
locally or across a network. You can query websites, Lightweight Directory Access Protocol (LDAP) servers, POP
mail servers, and documents in a variety of formats. For server-side ActionScript, a data source ordinarily means the
entry point to a ColdFusion database.
Your ColdFusion administrator can help you identify and configure data sources. To create ActionScript files that
successfully perform queries on ColdFusion data sources, you must know how the data source is identified by
ColdFusion, as well as any other parameters that affect your ability to connect to that database, such as whether a
user name and password are required to connect.
You use server-side ActionScript in ColdFusion to return record set data to a Flash client from a ColdFusion data
source. You specify the ColdFusion data source name and the SQL statement you execute on the data source as
arguments in the CF.query function in server-side ActionScript.
Typically, your server-side ActionScript handles the interaction with the ColdFusion data source, and returns a
record set to the Flash client through the Flash Remoting service.
For more detailed information about ColdFusion data sources, see Configuring and Administering ColdFusion.

Using the CF.query function
You use the CF.query function in your server-side ActionScript to retrieve data from a ColdFusion data source. This
function lets you perform queries against any ColdFusion data source.
Note: The CF.query function maps closely to the cfquery CFML tag, although it currently supports a subset of the
cfquery attributes.
Use the CF.query function to do the following:

•

Identify the data source you want to query.

•

Pass SQL statements to the data source.

•

Pass other optional parameters to the database.

For reference information about the CF.query function, see CF.query in the CFML Reference.

About CF.query function syntax
You can write the CF.query ActionScript function using either named arguments or positional arguments. The
named argument style is more readable, but it requires more code. Although the positional argument style supports
a subset of CF.query arguments, it allows a more compact coding style that is more appropriate for simple expressions of the CF.query function.

ADOBE COLDFUSION 8 713
ColdFusion Developer’s Guide

Using CF.query named argument syntax

The CF.query function accepts the following named arguments:
// CF.query named argument syntax
CF.query
({
datasource:"data source name",
sql:"SQL stmts",
username:"username",
password:"password",
maxrows:number,
timeout:milliseconds
})

Note: The named argument style requires curly braces {} to surround the function arguments.
Using CF.query positional argument syntax

Positional arguments support a subset of CF.query arguments, and you can create more efficient code. The
following is the syntax for the positional argument style:
// CF.query positional argument syntax
CF.query(datasource, sql);
CF.query(datasource, sql, maxrows);
CF.query(datasource, sql, username, password);
CF.query(datasource, sql, username, password, maxrows);

Note: When using positional arguments, do not use curly braces {}.

About the CF.query record set
The CF.query function returns a RecordSet object, which is an instance of the RecordSet class of objects. The
RecordSet class provides a wide range of functions for handling record set data.
You use methods in the RecordSet ActionScript class in your client-side ActionScript to change data returned in the
CF.query record set.

Currently, the following methods are available in the RecordSet class:
:

Method

Description

addItem

Appends a record to the end of the specified RecordSet

addItemAt

Inserts a record at the specified index

addView

Requests notification of changes in a RecordSet object’s state

filter

Creates a new RecordSet object that contains selected records from the original RecordSet object

getColumnNames

Returns the names of all the columns of the RecordSet

getItemAt

Retrieves a record from a RecordSet object

getItemID

Gets the unique ID corresponding to a record

getLength

Returns the total number of records in a RecordSet object

getNumberAvailable

Returns the number of records that have been downloaded from the server

isFullyPopulated

Determines whether a RecordSet object can be edited or manipulated

isLocal

Determines whether a RecordSet object is local or server-associated

ADOBE COLDFUSION 8 714
ColdFusion Developer’s Guide

Method

Description

removeAll

Removes all records from the RecordSet object

removeItemAt

Removes a specified record

replaceItemAt

Replaces the entire contents of a record

setDeliveryMode

Changes the delivery mode of a server-associated record set

setField

Replaces one field of a record with a new value

sort

Sorts all records by a specified compare function

sortItemsBy

Sorts all the records by a selected field

These functions are available for every RecordSet object returned by the CF.query function to the Flash client. You
invoke these functions as follows:
objectName.functionName();

For example, in the result function that you create to handle record set data returned by the CF.query function, you
can reference the database column names returned in the record set using the getColumnNames RecordSet function:
function selectData_Result ( result )
{
//result holds the query data; employeesView is a Flash list box
stringOutput.text = result.getColumnNames();
_root.employeesView.setDataProvider(result);
}

Building a simple application
The following procedure describes how to build a simple server-side ActionScript application. The example application, a corporate personnel directory, uses the NetServices object to connect to the personneldirectory serverside ActionScript. The personneldirectory server-side ActionScript retrieves data from a ColdFusion data source
and returns the results to the Flash application as a RecordSet object.
Note: The server-side ActionScript application that you create provides the back-end services in an application.
This example requires the following:

• A server-side ActionScript file named personneldirectory.asr that includes functions that interact with a
ColdFusion data source.
•

A client-side Flash movie in which the NetServices object is created.

Create the application
1 Write server-side ActionScript that performs the database query and returns data to the client through the Flash

Remoting service.
2

Create the Flash movie interface. See “Creating the Flash movie interface” on page 715.

3 Define a search function that sends user data to the Flash Remoting service. See “Submitting user data to the
Flash Remoting service” on page 716.
4

Define a result function that captures the results returned from the Flash Remoting service. See “” on page 716.

ADOBE COLDFUSION 8 715
ColdFusion Developer’s Guide

5 Ensure that the Flash movie has established a connection to the Flash Remoting service. See “Checking for a
Flash Remoting service connection” on page 717.

Writing the server-side ActionScript function
The example in this section creates a search function that performs a simple search operation against a ColdFusion
data source. This function accepts two arguments, firstName and lastName, and returns any records found that
match these arguments.
Create a server-side ActionScript function
1 Create a server-side ActionScript file that contains the following code:
//search takes firstName lastName arguments
function search(firstName, lastName)
{
searchdata = CF.query({datasource: "bigDSN",
sql:"SELECT * from personnel WHERE fname = firstName AND lname = lastName"{);
if (searchdata)
return searchdata;
else
return null;
}

2

Save the file as personneldirectory.asr.

Creating the Flash movie interface
The Flash movie interface example in this section consists of one frame with a variety of text boxes and a submit
button.
Create the Flash movie interface
1 In the Flash authoring environment, create a new Flash source file, and save it as pDirectory.fla.
2

Create two input text boxes. Name one text box variable lastName and the other firstName.

3

Create a dynamic text box, and name its variable status.

4

Insert a list box component, and name it dataView.

5

Insert a push button component.

6

Save your work.

The following image shows what the pDirectory Flash movie might look like:

ADOBE COLDFUSION 8 716
ColdFusion Developer’s Guide

Submitting user data to the Flash Remoting service
To send data to server-side ActionScript, you must create a function that passes the data from the Flash movie to
server-side ActionScript. The search function, applied at the frame level, collects the user-entered data from the
firstName and lastName text boxes and passes the data as function arguments to the directoryService object, which
is created when the Flash movie connects to the Flash Remoting service. For more information, see “Checking for a
Flash Remoting service connection” on page 717.
The following is a Flash ActionScript example:
#include "NetServices.as"
function search()
{
// The search() method is defined in the server-side AS file
directoryService.search(firstName.text, lastName.text);
dataView.setDataProvider(null);
status.text = "waiting...";
}
Reviewing the code

The following table describes the code and its function:
Code

Description

directoryService.search
(firstName.text, lastName.text);

Passes the contents of the firstName and lastName text boxes to server-side ActionScript.

dataView.setDataProvider
(null);

Clears the dataView list box component.

status.text = "waiting...";

Displays a message in the status text box while the record set is being retrieved from
server-side ActionScript.

Capturing Flash Remoting service results
When you create a function that calls a server-side ActionScript function, you must also create a function to handle
the data returned by server-side ActionScript. Define the function with the same name as the function making the
initial call, but you append _Result to the name.
For example, if you create a function called basicQuery to return query data, you also need to define a results
function to handle returned data; declare the results function as basicQuery_Result.
In the following example, the results function search_Result supplies the record set to the
dataView.setDataProvider function:
function search_Result(resultset)
{
dataView.setDataProvider(resultset);
status.text = (0+resultset.getLength())+" names found.";
}
Reviewing the code

The following table describes the code and its function:

ADOBE COLDFUSION 8 717
ColdFusion Developer’s Guide

Code

Description

function search_Result
(resultset)

The _Result suffix tells the Flash Remoting service to return the results of the search
function to this function.

dataView.setDataProvider
(resultset);

Assigns the results returned by the Flash Remoting service to the dataView list box.

status.text = (0+resultset.
getLength())+" names found.";

Displays the number of records returned by the Flash Remoting service.

Checking for a Flash Remoting service connection
To ensure that the Flash movie is connected to the Flash Remoting service, you use an if statement; for example:
if (inited == null)
{
inited = true;
NetServices.setDefaultGatewayUrl("http://localhost:8500/flashservices/
gateway");
gateway_conn = NetServices.createGatewayConnection();
directoryService = gateway_conn.getService(personneldirectory, this);
status.text = "Type into the text boxes, then click 'Search'";
}

In this example, the inited variable is evaluated for a value. If inited is null (not connected), the movie connects
to the Flash Remoting service using the NetServices object. For more information about connecting to the Flash
Remoting service, see “Connecting to the Flash Remoting service” on page 709.

About the CF.http function
You use the CF.http ActionScript function to retrieve information from a remote HTTP server using HTTP Get
and Post methods, as follows:

• Using the Get method, you send information to the remote server directly in the URL. This is common for a
one-way transaction in which the CF.http function retrieves an object, such as the contents of a web page.
•

The Post method can pass variables to a form or CGI program, and can also create HTTP cookies.

The most basic way to use the CF.http function is to use it with the Get method argument to retrieve a page from
a specified URL. The Get method is the default for the CF.http function.
The following server-side example retrieves file content from the specified URL:
function basicGet(url)
{
// Invoke with just the url argument. This is an HTTP GET.
result = CF.http(url);
return result.get("Filecontent");
}

The client-side example could look like the following:
#include "NetServices.as"
NetServices.setDefaultGatewayUrl("http://mycfserver:8500");
gatewayConnnection = NetServices.createGatewayConnection();
myHttp = gatewayConnnection.getService("httpFuncs", this);
// This is the server-side function invocation

ADOBE COLDFUSION 8 718
ColdFusion Developer’s Guide

url = "http://anyserver.com";
myHttp.basicGet(url);
// Create the results function
function basicGet_Result()
{
url = "http://anyserver.com
ssasFile.basicGet(url)
}

Using the CF.http function
The CF.http function returns an object that contains properties, also known as attributes. You reference these
attributes to access the contents of the file returned, header information, HTTP status codes, and so on. The
following table shows the available properties:
Property

Description

Text

A Boolean value indicating whether the specified URL location contains text data.

Charset

The charset used by the document specified in the URL.
HTTP servers normally provide this information, or the charset is specified in the charset parameter of the ContentType header field of the HTTP protocol. For example, the following HTTP header announces that the character
encoding is EUC-JP:
Content-Type: text/html; charset=EUC-JP

Header

Raw response header. The following is an example header :
HTTP/1.1 200 OK
Date: Mon, 04 Mar 2002 17:27:44 GMT
Server: Apache/1.3.22 (Unix) mod_perl/1.26
Set-Cookie: MM_cookie=207.22.48.162.4731015262864476;
path=/; expires=Wed, 03-Mar-04 17:27:44 GMT;
domain=.adobe.com
Connection: close
Content-Type: text/html

Filecontent

File contents, for text and MIME files.

Mimetype

MIME type. Examples of MIME types include text/html, image/png, image/gif, video/mpeg, text/css, and audio/basic.

responseHeader

Response header. If there is one instance of a header key, this value can be accessed as a simple type. If there is more
than one instance, values are put in an array in the responseHeader structure.

Statuscode

HTTP error code and associated error string. Common HTTP status codes returned in the response header include
the following:
400: Bad Request
401: Unauthorized
403: Forbidden
404: Not Found
405: Method Not Allowed

ADOBE COLDFUSION 8 719
ColdFusion Developer’s Guide

Referencing HTTP Post parameters in the CF.http function
To pass HTTP Post parameters in the CF.http function, you must construct an array of objects and assign this array
to a variable named params. The following arguments can only be passed as an array of objects in the params
argument of the CF.http function:
Parameter

Description

name

The variable name for data that is passed

type

Transaction type:

value

•

URL

•

FormField

•

Cookie

•

CGI

•

File

Value of URL, FormField, Cookie, File, or CGI variables that are passed

In the following example, the CF.http function passes HTTP Post parameters in an array of objects:
function postWithParamsAndUser()
{
// Set up the array of Post parameters. These are just like cfhttpparam tags.
params = new Array();
params[1] = {name:"arg2", type:"URL", value:"value2"};
url = "http://localhost:8500/";
// Invoke with the method, url, params, username, and password
result = CF.http("post", url, params, "karl", "salsa");
return result.get("Filecontent");
}

Using the CF.http Post method
You use the Post method to send cookie, form field, CGI, URL, and file variables to a specified ColdFusion page or
CGI program for processing. For POST operations, you must use the params argument for each variable that you
post. The Post method passes data to a specified ColdFusion page or an executable that interprets the variables being
sent, and returns data.
For example, when you build an HTML form using the Post method, you specify the name of the page to which
form data is passed. You use the Post method in the CF.http function in a similar way. However, with the CF.http
function, the page that receives the Post does not display anything. See the following example:
function postWithParams()
{
// Set up the array of Post parameters. These are just like cfhttpparam tags.
// This example passes formfield data to a specified URL.
params = new Array();
params[1] = {name:"Formfield1", type:"FormField", value:"George"};
params[2] = [name:"Formfield2", type:"FormField", value:"Brown"};
url = "http://localhost:8500/";
// Invoke CF.http with the method, url, and params
result = CF.http("post", url, params);

ADOBE COLDFUSION 8 720
ColdFusion Developer’s Guide

return result.get("Filecontent");
}

Using the CF.http Get method
You use the Get method to retrieve files, including text and binary files, from a specified server. You reference
properties of the object returned by the CF.http function to access things like file content, header information,
MIME type, and so on.
The following example uses the CF.http function to show a common approach to retrieving data from the web:
// Returns content of URL defined in url variable
// This example uses positional argument style
function get()
{
url = "http://www.adobe.com/software/coldfusion/";
//Invoke with just the url argument. Get is the default.
result = CF.http(url);
return result.get("Filecontent");
}

For more information about CF.http function properties, see CF.http in the CFML Reference.

721

Part 6: Working with Documents, Charts,
and Reports
This part contains the following topics:
Manipulating PDF Forms in ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723
Assembling PDF Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
Creating and Manipulating ColdFusion Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
Creating Charts and Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785
Creating Reports and Documents for Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810
Creating Reports with Report Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .818
Creating Slide Presentations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854

723

Chapter 40: Manipulating PDF Forms in
ColdFusion
You can use Adobe ColdFusion to manipulate PDF forms created in Adobe® Acrobat® Professional and Adobe®
LiveCycle™ Designer.
Contents

About PDF forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723
Populating a PDF form with XML data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724
Prefilling PDF form fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
Embedding a PDF form in a PDF document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
Extracting data from a PDF form submission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
Application examples that use PDF forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732

About PDF forms
ColdFusion 8 lets you incorporate interactive PDF forms in your application. You can extract data submitted from
the PDF forms, populate form fields from an XML data file or a database, and embed PDF forms in PDF documents
created in ColdFusion.
ColdFusion supports interactive forms created with Adobe Acrobat forms and with LiveCycle. In Adobe Acrobat 6.0
or earlier, you can create interactive Acroforms. Using Adobe LiveCycle Designer, which is provided with Adobe
Acrobat Professional 7.0 and later, you can generate interactive forms.
The type of form is significant because it affects how you manipulate the data in ColdFusion. For example, you
cannot use an XML data file generated from a form created in Acrobat to populate a form created in LiveCycle, and
vice versa, because the XML file formats differ between the two types of forms.
Forms created in Acrobat use the XML Forms Data Format (XFDF) file format. Forms created in LiveCycle use the
XML Forms Architecture (XFA) format introduced in Acrobat and Adobe Reader 6. For examples, see “Populating
a PDF form with XML data” on page 724. The file format also affects how you prefill fields in a form from a data
source, because you must map the data structure as well as the field names. For examples, see “Prefilling PDF form
fields” on page 725.
The use of JavaScript also differs based on the context. The JavaScript Object Model in a PDF file differs from the
HTML JavaScript Object Model. Consequently, scripts written in HTML JavaScript do not apply to PDF files. Also,
JavaScript differs between forms created in Acrobat and those created in LiveCycle: scripts written in one format do
not work with other.
ColdFusion 8 introduced several tags for manipulating PDF forms:

ADOBE COLDFUSION 8 724
ColdFusion Developer’s Guide

Tag

Description

cfpdfform

Reads data from a form and writes it to a file or populates a form with data from a data source.

cfpdfformparam

A child tag of the cfpdfform tag or the cfpdfsubform tag; populates individual fields in PDF forms.

cfpdfsubform

A child tag of the cfpdfform tag; creates the hierarchy of the PDF form so that form fields are filled properly. The cfpdfsubform tag contains one or more cfpdpformparam tags.

The following table describes a few of the tasks that you can perform with PDF forms:
Task

Tags and actions

Populate a PDF form with XML data

populate action of the cfpdf tag

Prefill individual fields in a PDF form with data from a data populate action of the cfpdfform tag with the cfpdfsubform and
source
cfpdfparam tags
Determine the structure of a PDF form

read action of the cfpdfform tag with the cfdump tag

Embed an interactive PDF form within a PDF document

populate action of the cfpdfform tag within the cfdocument tag.

Note: The cfpdfform tag must be at the same level as the
cfdocumentsection tags, not contained within them.
Write a PDF form directly to the browser

populate action of the cfpdfform tag with the destination attribute not

specified
Write PDF form output to an XML file

read action of the cfpdfform tag

Print a PDF form from ColdFusion

cfprint tag

Extract data from a PDF form submission

source="#PDF.Content#" for the read action of the cfpdfform tag

Write data extracted from a PDF form submission to a PDF source="#PDF.Content#" for the populate action of the cfpdfform tag,
file
and the destination attribute
Write data in a form generated in LiveCycle to an XDP file

source="#PDF.Content#" for the populate action of the cfpdfform tag,

and an XDP extension for the output file
Extract data from an HTTP post submission

cfdump tag determines the structure of the form data; map the form fields to

the output fields
Flatten forms generated in Acrobat (this does not apply to cfpdf action="write" flatten="yes"
forms generated in LiveCycle)
For more information, see “Flattening forms created in Acrobat” on page 747.
Merge forms generated in Acrobat or LiveCycle with other cfpdf action="merge"
PDF documents
For more information, see “Merging PDF documents” on page 746.

Populating a PDF form with XML data
Some applications submit PDF form data in an XML data file. For example, the e-mail submit option in forms
created in LiveCycle generates an XML data file and delivers it as an attachment to the specified e-mail address. This
is an efficient way to transmit and archive data because XML data files are smaller than PDF files. However, XML
files are not user-friendly: to view the file in its original format, the user has to open the PDF form template in
Acrobat and import the XML data file.

ADOBE COLDFUSION 8 725
ColdFusion Developer’s Guide

ColdFusion automates the process of reuniting XML data with the PDF form that generated it. To do this, you use
the populate action of the cfpdfform tag, specify the source, which is the PDF form used as a template, and specify
the XML data file that contains the information submitted by the person who completed the form. You also have the
option to save the result to a new file, which lets you save the completed forms in their original format (and not just
the form data). In the following example, ColdFusion populates the payslipTemplate.pdf form with data from the
formdata.xml data file and writes the form to a new PDF file called employeeid123.pdf:


For forms created in LiveCycle, you have the option to write the output to an XML Data Package (XDP) file rather
than a PDF file. For more information, see “Writing LiveCycle form output to an XDP file” on page 730.
Note: If you do not specify a destination, the populate action displays the populated PDF form in a browser window.
When you populate a form with an XML data file, ensure that the XML data is in the appropriate format. The format
of the XML data file differs based on whether it was generated from Acrobat or LiveCycle. Acrobat generates an XML
Forms Data Format (XFDF) file format. The following example shows the XFDF format:

- 
- 
- 
textvalue

- 
textvalue1




Forms created in LiveCycle require an XML Forms Architecture (XFA) format. The following example shows an XFA
format:

- 
- 
354325426
coldfusion
354325426.00
- 





Prefilling PDF form fields
ColdFusion lets you prefill individual form fields with data extracted from a data source. For example, you can run
a query to extract returning customer information from a data source based on a user name and password and
populate the related fields in an order form. The customer can complete the rest of the fields in the form and submit
it for processing. To do this, you must map the field names and the data structure of the PDF form to the fields in
the data source.
To determine the structure of the PDF form, use the read action of the cfpdfform tag, as the following example
shows:

ADOBE COLDFUSION 8 726
ColdFusion Developer’s Guide



Then use the cfdump tag to display the structure:


The result structure for a form created in Acrobat form might look something like the following example:
struct
firstName

[empty string]

lastName

[empty string]

department

[empty string]

...

...

To prefill the fields in ColdFusion, you add a cfpdfformparam tag for each of the fields directly under the
cfpdfform tag:




...


Forms created in LiveCycle from the standard blank forms contain a subform called form1. The result structure of a
form created in LiveCycle might look like the following example:
struct
form1

struct
txtfirstName

[empty string]

txtlastName

[empty string]

txtdepartment

[empty string]

...

...

To prefill the fields in ColdFusion, add a cfpdfsubform tag for form1 and a cfpdfformparam tag for each of the
fields to fill directly below the cfpdfsubform tag:





...



Note: In dynamic forms created in LiveCycle forms (forms saved as Dynamic PDF Form Files in LiveCycle Designer),
you have the option to mark how many times a record is repeated. Therefore, if no record exists for a subform, the
subform does not appear in the structure returned by the read action of the cfpdfform tag. You must view these forms
in LiveCycle Designer to see the hierarchy.

Nesting subforms
Although Acrobat forms do not contain subforms, some contain complex field names. For example an Acrobat form
might contain the following fields: form1.x.f1, form1.x.f2, form1.x.f3, and so on.

ADOBE COLDFUSION 8 727
ColdFusion Developer’s Guide

Because the cfpdfparam tag does not handle field names with periods in them, ColdFusion treats forms with
complex field names created in Acrobat the same way as subforms created in LiveCycle. Therefore, the result
structure of an Acrobat form with complex field names might look like the following example:
struct
form1

struct
x

struct
f1

[empty string]

f2

[empty string]

...

...

In ColdFusion, to prefill the fields in forms created in Acrobat, nest the field names as subforms:










Often, forms created in LiveCycle contain subforms within the form1 subform. For example, the following grant
application contains nested subforms:
struct
form1

struct
grantapplication

struct
page1

page2

struct
orgAddress

[empty string]

orgCity

[empty string]

orgState

[empty string]

...

...

struct
description

[empty string]

pageCount

[empty string]

...

...

To populate the fields in ColdFusion, map the structure by using nested cfpdfsubform tags:







...



ADOBE COLDFUSION 8 728
ColdFusion Developer’s Guide



...





Note: A PDF file can contain only one interactive form. Therefore, if a PDF file contains subforms, a Submit button
submits data for all the subforms simultaneously.

Embedding a PDF form in a PDF document
You can use the cfpdfform tag inside the cfdocument tag to embed an existing interactive PDF form in a PDF
document. This is useful to include additional information with a standard interactive form. For example, a company
might have a generic PDF form for maintaining employee information. You could reuse this form in different
contexts to ensure the employee information is current.
To create the static PDF pages, use the cfdocument tag and cfdocumentsection tags. Then use the cfpdfform tag
in the cfdocument tag to create an interactive form in the PDF document. When the user updates the form and
prints or submits it, all of the pages in the document, including the static PDF pages, are printed or submitted with
the form.
Note: You can embed only one interactive form in a PDF document; therefore, include only one cfpdfform tag in a
cfdocument tag. However, each cfpdfform tag can include multiple cfpdfsubform tags and cfpdfformparam tags.
Use at least one cfdocumentsection tag with the cfpdfform tag, but do not place the cfpdfform tag within the
cfdocumentsection tag. Instead, insure that the cfpdfform and cfdocumentsection tags are at the same level,
the following example shows:


This is the Header


This is the Footer


This is the first document section.








This is another section



The contents of the cfpdfform tag start on a new page. Any text or code directly after the cfdocument tag and before
the cfpdfform tag applies to the document sections but not to the interactive PDF form in the cfpdfform tag.

ADOBE COLDFUSION 8 729
ColdFusion Developer’s Guide

The headers and footers that are part of the embedded PDF form do not apply to the rest of the PDF document, and
the headers and footers that are defined in the cfdocument tag do not apply to the interactive form. However, header
and footer information defined in the cfdocumentitem tags resumes in the sections that follow the embedded form
and account for the pages in the embedded form.
Note: The read action of the cfpdfform tag is not valid when you embed a PDF form. Also, you cannot specify a destination in the cfpdfform tag. However, you can specify a filename in the cfdocument tag to write the PDF document
with the PDF form to an output file. If you do not specify a filename, ColdFusion displays the PDF form in the context
of the PDF document in the browser.

Extracting data from a PDF form submission
Data extraction differs based on how the PDF form is submitted. ColdFusion supports two types of PDF form
submission: HTTP post, which submits the form data, but not the form itself, and PDF, which submits the entire
PDF file.
One use for PDF submission is for archival purpose: because the form is submitted with the data, you can write the
output to a file. HTTP post submissions process faster because only the field data is transmitted, which is useful for
updating a database or manipulating specific data collected from the form, but you cannot write an HTTP post
submission directly to a file.
Note: Although forms created in LiveCycle Designer allow several types of submission, including XDP and XML,
ColdFusion 8 can extract data from HTTP post and PDF submissions only.
In LiveCycle Designer, the XML code for an HTTP post submission looks like the following example:


In LiveCycle Designer, the XML code for a PDF submission looks like the following example:


Note: Acrobat forms are submitted in binary format, not XML format.

Extracting data from a PDF submission
Use the following code to extract data from a PDF submission and write it to a structure called fields:



Use the cfdump tag to display the data structure, as follows:


Note: When you extract data from a PDF submission, always specify "#PDF.content#" as the source.
You can set the form fields to a variable, as the following example shows:


Use the populate action of the cfpdfform tag to write the output to a file. Specify "#PDF.content#" as the source.
In the following example, the unique filename is generated from a field on the PDF form:

ADOBE COLDFUSION 8 730
ColdFusion Developer’s Guide



Writing LiveCycle form output to an XDP file

For Acrobat forms, you can write the output to a PDF file only. For LiveCycle forms, you have the option to write the
output to an XDP file. The file extension determines the file format: to save the output in XDP format, simply use an
XDP extension in the destination filename, as the following example shows:


An XDP file is an XML representation of a PDF file. In LiveCycle Designer, an XDP file contains the structure, data,
annotations, and other relevant data to LiveCycle forms, which renders the form at run time.
ColdFusion XDP files contain the XDP XML code and the PDF image. Therefore, the file size is larger than a PDF
file. Only write PDF forms to XDP files if you must incorporate them into the LiveCycle Designer workflow on a
LiveCycle server.
Writing PDF output to an XML file

ColdFusion lets you extract data from a PDF form and write the output to an XML data file. To do this, you must
save the form output as a PDF file. (The cfpdfform tag source must always be a PDF file.)
To write the output of a PDF file to an XML file, use the read action of the cfpdfform tag, as the following example
shows:


To save disk space, you can delete the PDF file and maintain the XML data file. As long as you keep the blank PDF
form used as the template, you can use the populate action to regenerate the PDF file. For more information on
populating forms, see “Populating a PDF form with XML data” on page 724.

Extracting data from an HTTP post submission
For an HTTP post submission, use the cfdump tag with the form name as the variable to display the data structure,
as follows:


Note: When you extract data from an HTTP post submission, always specify the form name as the source. For example,
specify "#FORM.form1#" for a form generated from a standard template in LiveCycle.
Notice that the structure is not necessarily the same as the structure of the PDF file used as the template (before
submission). For example, the structure of a form before submission might look like the following example:
struct
form1

struct
txtDeptName

[empty string]

txtEMail

[empty string]

txtEmpID

[empty string]

txtFirstName

[empty string]

txtLastName

[empty string]

txtPhoneNum

[empty string]

ADOBE COLDFUSION 8 731
ColdFusion Developer’s Guide

After submission by using HTTP post, the resulting structure might look like the following example:
struct
FORM1

struct
SUBFORM

struct
HEADER

struct
HTTPSUBMITBUTTON1

[empty string]

TXTDEPTNAME

Sales

TXTFIRSTNAME

Carolynn

TXTLASTNAME

Peterson

TXTPHONENUM

(617) 872-9178

TXTEMPID

1

TXTEMAIL

carolynp@company

Note: When data extraction using the cfpdfform tag results in more than one page, instead of returning one structure,
the extraction returns one structure per page.
The difference in structure reflects internal rules applied by Acrobat for the HTTP post submission.
To extract the data from the HTTP post submission and update a database with the information, for example, map
the database columns to the form fields, as the following code shows:

UPDATE EMPLOYEES
SET FIRSTNAME = "#FORM1.SUBFORM.HEADER.TXTFIRSTNAME#",
LASTNAME = "#FORM1.SUBFORM.HEADER.TXTLASTNAME#",
DEPARTMENT = "#FORM1.SUBFORM.HEADER.TXTDEPTNAME#",
IM_ID = "#FORM1.SUBFORM.TXTEMAIL#",
PHONE = "#FORM1.SUBFORM.HEADER.TXTPHONENUM#"
WHERE EMP_ID = 


You can set a variable to create a shortcut to the field names, as the following code shows:


Use the cfoutput tag to display the form data:
Employee Information



ADOBE COLDFUSION 8 732
ColdFusion Developer’s Guide



Name:
#fields.txtfirstname# #fields.txtlastname#


Department:
#fields.txtdeptname#


E-Mail:
#fields.txtemail#

Phone:
#fields.txtphonenum#


Application examples that use PDF forms
The following examples show how you can use PDF forms in your applications.

PDF submission example
The following example shows how to populate fields in a PDF form created in LiveCycle Designer based on an
employee’s login information. When the employee completes the form and clicks the PDF Submit button, the entire
PDF form with the data is submitted to a second processing page where ColdFusion writes the completed form to a
file.
On the ColdFusion login page, an employee enters a user name and password:
Timesheet Login Form
Please enter your user name and password.



user name:



password:








On the first processing page, a query retrieves all of the information associated with the user name from the cfdocexamples database. The cfpdfform tag populates an associated PDF form created in LiveCycle Designer (called
timesheetForm.pdf) with the employee name, phone number, e-mail address, and department. ColdFusion displays
the populated form in the browser, where the employee can complete the form and submit it.


SELECT * FROM EMPLOYEES
WHERE EMAIL = 



ADOBE COLDFUSION 8 733
ColdFusion Developer’s Guide













When the user completes the timesheet form (by filling in the time period, projects, and hours for the week) and
clicks the Submit button, Acrobat sends the PDF file in binary format to a second ColdFusion processing page.
Note: In LiveCycle Designer, use the standard Submit button on the PDF form and specify “submit as: PDF” in the button
Object Properties. Also, ensure that you enter the URL to the ColdFusion processing page in the Submit to URL field.
The cfpdfform tag read action reads the PDF content into a result structure named fields. The cfpdfform tag
populate action writes the completed form to a file in the timesheets subdirectory.




Timesheet Completed
#empForm.txtempname#,
Thank you for submitting your timesheet for the week of
#DateFormat(empForm.dtmForPeriodFrom, "long")# through
#DateFormat(empForm.dtmForPeriodto, "long")#. Your manager,
#empForm.txtManagerName#, will notify you upon approval.

HTTP post example
The following example shows how to extract data from a PDF form submitted with HTTP post and use it to update
an employee database. The form was created in LiveCycle Designer.
On the ColdFusion login page, an employee enters a user name and password:

Employee Update Login Form
Please enter your user name and password.



user name:



password:








On the first processing page, a query retrieves all of the information associated with the user name from the cfdocexamples database. The cfpdfform tag populates an associated PDF form created in LiveCycle Designer (called
employeeInfoHTTP.pdf) with the employee name, phone number, e-mail address, and department. The form also
includes the employee ID as a hidden field. ColdFusion displays the populated form in the browser where the
employee can change personal information in the form and submit it.


SELECT * FROM EMPLOYEES
WHERE EMAIL = 



SELECT * FROM EMPLOYEES
WHERE EMAIL = 












When the employee updates the information in the form and clicks the HTTP post Submit button, Acrobat sends
the form data (but not the form itself) to a second ColdFusion processing page.
Note: In LiveCycle Designer, use the HTTP Submit button on the PDF form. Also, ensure that you enter the URL to the
ColdFusion processing page in the URL field of button Object Properties.
You must reproduce the structure, not just the field name, when you reference form data. To determine the structure
of the form data, use the cfdump tag.


UPDATE EMPLOYEES
SET FIRSTNAME = "#FORM1.SUBFORM.HEADER.TXTFIRSTNAME#",
LASTNAME = "#FORM1.SUBFORM.HEADER.TXTLASTNAME#",

ADOBE COLDFUSION 8 735
ColdFusion Developer’s Guide

DEPARTMENT = "#FORM1.SUBFORM.HEADER.TXTDEPTNAME#",
IM_ID = "#FORM1.SUBFORM.HEADER.TXTEMAIL#",
PHONE = "#FORM1.SUBFORM.HEADER.TXTPHONENUM#"
WHERE EMP_ID = 

Employee Information Updated
#FORM1.SUBFORM.HEADER.TXTFIRSTNAME#,
Thank you for updating your employee information in the employee database.

Embedded PDF form example
The following example shows how to embed an interactive PDF form in a PDF document created with the
cfdocument tag.
On the login page, an employee enters a user name and password:
Employee Login Form
Please enter your user name and password.



user name:



password:








On the processing page, a query populates an interactive PDF form from the cfdocexamples database. The interactive PDF form is embedded in a PDF document created with the cfdocument tag. The PDF document comprises
three sections: the cfdocumentsection tags define the first and last sections of the document; the cfpdfform tag
defines the second section embedded in the PDF document. Each section starts a new page in the PDF
document.The Print button on the PDF form prints the entire document, including the pages in the sections before
and after the interactive PDF form.

SELECT * FROM EMPLOYEES
WHERE EMAIL = 




Nondisclosure Agreement


Page #cfdocument.currentpagenumber#
of#cfdocument.totalpagecount#




ADOBE COLDFUSION 8 736
ColdFusion Developer’s Guide

Employee Nondisclosure Agreement
Please verify the information in the enclosed form. Make any of the necessary changes
in the online form and click the Print button. Sign and date the last page. Staple
the pages together and return the completed form to your manager.













I, #getEmpInfo.FIRSTNAME# #getEmpInfo.LASTNAME#, hereby attest
that the information in this document is accurate and complete.






Signature


Today's Date




Update PDF form example
The following example shows how ColdFusion lets you update a PDF form while retaining existing data. The application lets a user create an office supply request from a blank form created in LiveCycle or modify an existing supply
request. The user has the option to submit the completed form as an e-mail attachment.














ADOBE COLDFUSION 8 737
ColdFusion Developer’s Guide


Office Supply Request Form
Please choose the office supply request form that you would like to open. Choose New
Supply Request to create a new request.
























#fields.form1.txtRequester#,
Your changes have been recorded for supply request
#fields.form1.txtRequestNum#.
If the form is complete and you would like to submit it to
#fields.form1.txtContactName# for processing, click Submit.






If you would like to modify your request or choose another request,
click here.


Your request has been submitted.

ADOBE COLDFUSION 8 738
ColdFusion Developer’s Guide


Please review the attached PDF supply request form.



739

Chapter 41: Assembling PDF Documents
You can use Adobe ColdFusion to assemble PDF documents. You create a unified document from multiple source
files or pages from multiple files by using the cfpdf and cfpdfparam tags.
Contents

About assembling PDF documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
Using shortcuts for common tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
Using DDX to perform advanced tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
Application examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756

About assembling PDF documents
You use the cfpdf tag to assemble PDF documents in ColdFusion. The tag provides several actions for creating
unified output files from multiple sources, as the following table shows:
Action

Description

addWatermark

Adds a watermark image to one or more pages in a PDF document.

deletePages

Deletes one or more pages from a PDF document.

getInfo

Extracts information associated with the PDF document, such as the author, title, and creation date.

merge

Assembles PDF documents or pages from PDF source files into one output file.

processddx

Extends the cfpdf tag by providing a subset of Adobe® LiveCycle™ Assembler functionality. This is the default
action.

protect

Password-protects and encrypts a PDF document.

read

Reads a PDF document into a ColdFusion variable.

removeWatermark

Removes watermarks from specified pages in a PDF document.

setInfo

Sets the Title, Subject, Author, and Keywords for a PDF document,

thumbnail

Generates thumbnail images from specified pages in a PDF document.

write

Writes PDF output to a file. Also use to flatten forms created in Acrobat and linearize documents.

Note: You cannot use the cfpdf tag to create a PDF document from scratch. To create a PDF document from HTML
content, use the cfdocument tag. Also, you can use Report Builder to generate a report in PDF format. Instead of writing
a PDF document to file, you can specify a PDF variable generated as the source for the cfpdf tag.
All but one of the cfpdf tag actions provide shortcuts to common tasks; for example, with one line of code, you can
add a watermark image to one or more pages in an output file, merge all the PDF documents in a directory into a
single output file, or password-protect a PDF document. ColdFusion provides two ways to extend the functionality
of the cfpdf tag: the cfpdfparam tag and the processddx action.
You use the cfpdfparam tag only with the merge action of the cfpdf tag. The cfpdfparam tag gives you more
control over which files are included in the output file; for example you can merge pages from multiple files in
different directories.

ADOBE COLDFUSION 8 740
ColdFusion Developer’s Guide

The processddx action extends the cfpdf tag by providing a subset of Adobe LiveCycle Assembler functionality.
You use the processddx action to process Document Description XML (DDX) instructions explained in “Using
DDX to perform advanced tasks” on page 749. Using DDX instructions requires more coding, but it lets you perform
complex tasks, such as generating a table of contents and adding automatic page numbers.
Also, ColdFusion provides three functions for PDF file, DDX file, and PDF variable verification:
Function

Description

IsDDX

Determines whether a DDX file, pathname, and instructions are not null and are valid. Also verifies that the schema
used for the DDX instructions is supported by ColdFusion.

IsPDFFile

Determines whether a PDF source file, pathname, and version are valid and supported on the server running ColdFusion. Also verifies whether a PDF file is corrupted.

IsPDFObject

Determines whether a PDF object stored in memory is valid. Also verifies the contents of PDF variables generated
by the cfdocument and cfpdf tags.

The following table describes a few document assembly tasks that you can perform with ColdFusion:
Task

Action

Add a generated table of contents to a PDF document

cfpdf action="processddx" with the TableOfContents DDX element

Add automatic page numbers to a PDF document

cfpdf action="processddx" with the _PageNumber and
_LastPagenumber built-in keys. Valid only in the Header and Footer DDX

elements.
Add headers and footers to a PDF document

cfpdf action="processddx" with the Header and Footer DDX

elements
Add or remove watermarks

cfpdf action="processddx" with the Watermark and Background DDX

elements

cfpdf action="addWatermark" and cfpdf
action="removeWatermark"

Change the encryption algorithm for PDF documents

cfpdf action="protect" encrypt="encryption algorithm"

Change user permissions on a PDF document

cfpdf action="protect" newOwnerPassword="xxxxx"
permissions="comma-separated list"

Delete pages from a PDF document

cfpdf action="deletePages"

Extract text from a PDF document and export it to an XML cfpdf action="processddx" with the DocumentText DDX element
file
Flatten (remove interactivity from) forms created in
Acrobat

cfpdf action="write" flatten="yes"

Generate thumbnail images from PDF document pages

cfpdf action="thumbnail"pages="page numbers"

Linearize PDF documents for faster web display

cfpdf action="write" saveOption="linear"

Merge pages and page ranges from multiple documents in cfpdf action="merge" with multiple cfpdfparam tags
different locations into one PDF document
Merge PDF documents in a directory into one PDF document

cfpdf action="merge" directory="pathname"

ADOBE COLDFUSION 8 741
ColdFusion Developer’s Guide

Task

Action

Password-protect PDF documents

cfpdf action="protect" newUserPassword="xxxx"

Set the initial view for a PDF document

cfpdf action="processddx" with the InitialViewProfile DDX

element
Create different versions of a PDF document

Duplicate function to clone PDF variables

Using shortcuts for common tasks
You use the cfpdf tag actions to perform shortcuts to common PDF document assembly and manipulation.

Adding and removing watermark images
Use the addWatermark and removeWatermark actions to add and remove watermarks from PDF documents. You
can create a watermark and apply it to a PDF document in one of the following ways:

•

Use an image file as a watermark.

•

Specify a variable that contains an image file.

•

Specify a ColdFusion image.

•

Use the first page of a PDF document as a watermark.

Note: Also, you can use the Watermark or Background DDX elements with the processddx action to create a textstring watermark. For more information, see “Using DDX to perform advanced tasks” on page 749.
Using an image file as a watermark

The following example shows how to specify an image file as a watermark:


By default, ColdFusion centers the image on the page, sets the opacity of the image to 3 out of 10 (opaque), and
displays the image in the background of each page in the output file. In the following example, ColdFusion displays
the watermark in the foreground, offset 100 pixels from the left margin of the page and 100 pixels from the bottom
margin of the page. Because the opacity is set to 1, the image does not obscure the page content.


For a complete list of attributes and settings, see the cfpdf tag in the CFML Reference.
Using a variable that contains an image file

You can specify a variable that contains an image as a watermark. The following example shows how to create a form
from which the user can select an image:

Choosing a Watermark
Please choose the image you would like to use as a watermark.


ADOBE COLDFUSION 8 742
ColdFusion Developer’s Guide







Birch Forest



Lounging Woman


Celebration


Guitarist








The processing page uses the image selected from the form as the watermark for a PDF file:


The watermark has been added to your personalized checks.

Using a ColdFusion image as a watermark

You can specify a ColdFusion image as a watermark. You can extract an image from a database and manipulate the
image in memory, but you don’t have to write the manipulated image to a file. Instead, you can apply the manipulated
image as a watermark in a PDF document.
In the following example, the first ColdFusion page extracts images from a database and populates a pop-up menu
with the titles of the artwork:


SELECT ARTID, ARTNAME, LARGEIMAGE
FROM ART
ORDER BY ARTNAME



Please choose a title:







ADOBE COLDFUSION 8 743
ColdFusion Developer’s Guide

The action page generates a ColdFusion image from the selected file by using the cfimage tag. The
ImageScaleToFit function resizes the image and applies the bicubic interpolation method to improve the
resolution. To use the manipulated image as a watermark, specify the image variable, as the following example shows:









I'm sorry, no image exists for that title. Please click the Back button and try
again.


For more information on ColdFusion images, see “Creating and Manipulating ColdFusion Images” on page 763.
Creating a text image and using it as a watermark

You can use the ImageDrawText function to create a text image in ColdFusion and apply the image as a watermark,
as the following example shows:




















For more information on ColdFusion images, see “Creating and Manipulating ColdFusion Images” on page 763. For
an example of using DDX elements to create a text-string watermark, see “Adding text-string watermarks” on
page 754.

ADOBE COLDFUSION 8 744
ColdFusion Developer’s Guide

Using a PDF page as a watermark

Use the copyFrom attribute to create a watermark from the first page of a PDF file and apply it to another PDF
document. In the following example, ColdFusion creates a watermark from the first page of image.PDF, applies the
watermark to the second page of artBook.pdf, and writes the output to a new file called output.pdf:


In this example, image.pdf appears in the background of the second page of artBook.pdf. ColdFusion does not
change the size of the watermark image to fit the page. The page used as a watermark can contain text, graphics, or
both.
Removing watermarks

Use the removeWatermark action to remove a watermark from one or more pages in a PDF document. The
following example shows how to remove a watermark from the entire PDF document and write the document to a
new output file:


The following example shows how to remove a watermark from the first two pages of a PDF document and overwrite
the source document:


Because the source and the destination are the same and the overwrite attribute is set to yes, ColdFusion
overwrites the source file with the output file.

Deleting pages from a PDF document
Use the deletepages action to remove pages from a PDF document and write the result to a file. You can specify a
single page, a page range (for example, “81–97”), or a comma-separated list of pages to delete, as the following
example shows:


Protecting PDF files
Use the protect action to password-protect, set permissions, and encrypt PDF documents for security.
Setting passwords

ColdFusion supports two types of passwords: an owner password and a user password. An owner password controls
the ability to change the permissions on a document. When you specify an owner password, you set permissions to
restrict the operations users can perform, such as the ability to print a document, make changes to its content, and
extract content. The following code creates an owner password for a document:


To password-protect a document, set the user password. A user password controls the ability to open a document.
If you set a user password for a document, any person attempting to open the file is prompted to enter a password.
The following example sets the user password for a document:


ADOBE COLDFUSION 8 745
ColdFusion Developer’s Guide

In the previous example, no restrictions apply to the PDF document after the user enters the correct password. To
restrict usage and password-protect a document, add a user password and an owner password. Use the owner
password to set the permissions, as the following example shows:


In this example, a user must enter the password openSesame before opening the PDF form. All users can print the
document at any resolution, but only the owner can modify the document or change the permissions.
Encrypting PDF files

When you specify the protect action for a PDF file, ColdFusion encrypts the file with the RC4 128-bit algorithm
by default. Depending on the version of Acrobat running on the ColdFusion server, you can set the encryption to
protect the document contents and prevent search engines from accessing the PDF file metadata.
You can change the encryption algorithm by using the encrypt attribute. For a list of supported encryption
algorithms, see cfpdf in the CFML Reference.
The following example changes the password encryption algorithm to RC4 40-bit encryption:


To prevent ColdFusion from encrypting the PDF document, set the encryption algorithm to none, as the following
example shows:


To decrypt a file, provide the owner or user password and write the output to another file. The following code
decrypts the confidential.pdf file and writes it to a new file called myDocument.pdf:


Managing PDF document information
To retrieve information stored with a source PDF document, such as the creation date, the application used to create
the PDF document, and the name of the person who created the document, use the getInfo action. For a list of data
elements, see “PDF file information elements” on page 440 in the CFML Reference.

ADOBE COLDFUSION 8 746
ColdFusion Developer’s Guide

Use the setInfo action to specify information, such as the author, subject, title, and keywords associated with the
output file. This information is useful for archiving and searching PDF documents. PDF document information is
not displayed or printed with the document.
The following example shows how to set keywords for tax documents. The information is useful for assembling the
documents based on the tax filing requirements for different business types (Sole Proprietor, Partnership, and S
Corporation). Some business types share the same forms and documents. By setting the business type keywords for
each document, you can store the documents in one directory and search them based on keyword values. The
following code sets three keywords for the p535.pdf tax booklet:




When you use the setInfo action, ColdFusion overwrites any existing information for that key-value pair. In the
previous example, if the pc535.pdf document contained a keyword of “tax reference”, ColdFusion overwrites that
keyword with “Sole Proprietor, Partnership, S Corporation”.
To retrieve all of the information associated with the tax file, use the cfdump tag with the getInfo action, as the
following example shows:



To retrieve just the keywords for the PDF document, use this code:

#taxInfo.keywords#

Merging PDF documents
ColdFusion lets you merge PDF documents in the following ways:

•

Merge all of the PDF files in a specified directory.

•

Merge a comma-separated list of PDF files.

• Merge individual PDF files, and pages within those files, explicitly, even if the source files are stored in different
locations.
•

Merge the contents of a PDF variable generated by the cfdocument tag or a cfpdf tag

To merge the contents of a directory, use the merge action and specify the directory where the source PDF files are
located, as the following example shows:


By default, ColdFusion merges the source files in descending order by timestamp. You can control the order in which
the PDF files are added to the book by setting the order and ascending attributes. The following code merges the
files in ascending order according to the timestamp on the files:


By default, ColdFusion continues the merge process even if it encounters a file that is not a valid PDF document in
the specified directory. To override this setting, set the stopOnError attribute to yes, as the following example
shows:


ADOBE COLDFUSION 8 747
ColdFusion Developer’s Guide

You can merge a comma-separated list of PDF files. To do this, you must specify the absolute pathname for each file,
as the following example shows:


For more control over which files are added to the merged document, use the cfpdfparam tag with the cfpdf tag.
The cfpdfparam tag merges documents or pages from documents located in different directories into a single
output file. When you use the cfpdfparam tag, the PDF files are added to the output file in the order they appear in
the code. In the following example, the cover, title, and copyright pages are followed by the first five pages of the
introduction, then all of the pages in Chapter 1, and then the first page followed by pages 80–95 in Chapter 2:




Cover page
Please review the enclosed document for technical accuracy and completeness.













Because the keepbookmark attribute is set to yes, ColdFusion retains the bookmarks from the source documents in
the output file.
Note: You cannot use the cfpdf tag to create bookmarks in a PDF document.

Flattening forms created in Acrobat
Flattening forms involves removing the interactivity from the form fields. This is useful for displaying form data and
presenting it without allowing it to be altered. Use the write action to flatten PDF forms, as the following example
shows:

a href="http://localhost:8500/Lion/taxforms/flatForm.pdf">1040 form

Note: If you flatten a prefilled form created in Acrobat, ColdFusion flattens the form and removes the data from the form
fields. When you specify a form created in Acrobat as a source file for merge action of the cfpdf tag, ColdFusion
automatically flattens the form and removes data from the form fields, if the fields are filled in. ColdFusion does not
support flattening forms created in LiveCycle.

ADOBE COLDFUSION 8 748
ColdFusion Developer’s Guide

Linearizing PDF documents for faster web display
For efficient access of PDF files over the web, linearize PDF documents. A linearized PDF file is structured in a way
that displays the first page of the PDF file in the browser before the entire file is downloaded from the web server.
This means that linear PDF documents open almost instantly.
To linearize PDF documents, specify the saveOption attribute of the write action. The following example saves the
output file in linear format:


Note: Linearization can decrease performance when handling very large documents.

Generating thumbnail images from PDF pages
Use the thumbnail action to generate thumbnail images from PDF pages. If you specify only the source attribute
with the thumbnail action, ColdFusion automatically creates a directory relative to the CFM page called thumbnails
where it stores a generated JPEG image for each page in the document. The filenames are in the following format:
PDFdocumentName_page_n.JPG

For example, assume that the source file in the following example has 100 pages:


ColdFusion generates the following files and stores them in the thumbnails directory:
myBook_page_1.jpg
myBook_page_2.jpg
myBook_page_3.jpg
...
myBook_page_100.jpg

If you specify a destination, ColdFusion does not create the thumbnails directory and stores the files in the specified
directory instead. The following code generates a thumbnail image called myBook_page_1.jpg from the first page of
myBook.pdf and stores it in a directory called images, which is relative to the CFM page:


You change the prefix for the thumbnail filename and the change image file format to PNG or TIFF by specifying the
imagePrefix and format attributes. The following code generates a file called TOC_page_2.PNG from the second
page of myBook.pdf:


The following code generates thumbnails from a range of pages and changes the image background to transparent
(the default is opaque):


For an example of how to generate thumbnail images and link them to pages in the source PDF document, see the
cfpdf tag in the CFML Reference.

ADOBE COLDFUSION 8 749
ColdFusion Developer’s Guide

Using the Duplicate function to create versions of a PDF document
You can use the Duplicate function to clone PDF variables, which is an efficient way to create different versions of
a PDF document from a single source file. For example, you can customize PDF output based on your audience by
creating clones of a PDF variable and performing different actions on each clone. The following example shows how
to create a clone of a PDF document in memory, and create one version of the document with a watermark and
another version of the document where permissions are restricted:










Using DDX to perform advanced tasks
LiveCycle Assembler is a server-based application that processes DDX, a declarative markup language used to define
PDF output files.
The processddx action lets you process DDX instructions without installing LiveCycle Assembler. In addition to all
of the functionality available with the other cfpdf actions, you can use DDX instructions to perform advanced tasks,
such as adding a generated table of contents to a PDF document, adding headers and footers with automatic page
numbers, and creating groups of PDF documents to which you can apply formatting instructions.
ColdFusion does not provide complete LiveCycle Assembler functionality. For a list of DDX elements that you can
access from ColdFusion, see “Supported DDX elements” on page 442 in the CFML Reference.
For complete DDX syntax, see the Adobe LiveCycle Assembler Document Description XML Reference.

Using DDX instructions with ColdFusion
Although you can type DDX instructions directly in ColdFusion, typically you refer to an external DDX file. A DDX
file is basically an XML file with a DDX extension (for example, merge.ddx). You can use any text editor to create a
DDX file. The DDX syntax requires that you enclose the instructions within DDX start and end tags. In the following
example, the PDF element provides instructions for merging two PDF source files (Doc1 and Doc2) into a result file
(Out1):








ADOBE COLDFUSION 8 750
ColdFusion Developer’s Guide

In ColdFusion, you verify the source DDX file with the IsDDX function:



To implement the DDX instructions in ColdFusion, you create two structures: an input structure that maps the DDX
input instructions to the PDF source files, and an output structure that maps the DDX output instructions to a PDF
output file,
The following code maps two files called Chap1.pdf and Chap2.pdf to the Doc1 and Doc2 sources that you defined
in the DDX file:





The following code maps the output file called twoChaps.pdf to the Out1 result instruction that you defined in the
DDX file:




To process the DDX instructions, you use the processddx action of the cfpdf tag, in which you reference the DDX
file, the input structure, and the output structure, as the following example shows:


The name attribute creates a variable that you can use to test the success or failure of the action. If the action is
successful, ColdFusion generates an output file with the name and location specified in the output structure. The
following code returns a structure that displays a success, reason for failure, or failure message (if the reason is
unknown) for each output file, depending on the result:


The previous example performs the same task as the merge action in ColdFusion, as the following example shows:






In this situation, it makes more sense to use the merge action because it is easier. DDX is useful when you have to
perform tasks that you can’t perform with other actions in the cfpdf tag, or you require more control over specific
elements.

Adding a table of contents
You use DDX instructions to add a generated table of contents page to the PDF output file. Generating a table of
contents is useful if you are assembling documents from multiple sources. You can generate a table of contents that
contains active links to pages in the assembled PDF document. The following code shows how to create DDX
instructions to merge two documents and add a table of contents:



ADOBE COLDFUSION 8 751
ColdFusion Developer’s Guide









The TableOfContents element generates a table of contents from the PDF source elements that follow it. Order is
important: in the previous example, the table of contents appears on a separate page after the Title and before Doc 1
and Doc 2. The table of contents contains entries from Doc 1 and 2, but not from the title page, because the title page
precedes the table of contents in the order of instructions.
You do not reference the TableOfContents element on the corresponding ColdFusion page, as the following
example shows:














ColdFusion generates a table of contents from the DDX instructions and inserts it in the PDF document in the
location that you provided in the DDX file. By default, the table of contents contains active links to the top-level
bookmarks in the merged PDF document.
You can change the default TableOfContents settings in the DDX file, as the following example shows:


Use the maxBookmarkLevel attribute to specify the level of bookmarks included on the table of contents page. Valid
values are infinite or an integer. Use the bookmarkTitle attribute to add a bookmark to the table of contents page
in the output file. The includeInTOC attribute specifies whether the bookmark title is included on the table of
contents page.
For more information on the TableOfContents element, see the Adobe LiveCycle Assembler Document Description
XML Reference.

Adding headers and footers
To add headers and footers to a PDF document, specify the Header and Footer elements in the DDX file. The
following example specifies headers and footers for the PDF source called Doc2:








Right-justified header text


Left-justified header text







In this example, the Header and Footer elements apply only to Doc2 because they are contained within that PDF
source start and end tags; they do not apply to the table of contents or to the title page, which precede the Header
and Footer elements.

Formatting headers and footers
You use DDX instructions to perform the following tasks:

•

Add automatic page numbers to headers and footers

•

Use style profiles

•

Group documents in the PDF output file

Adding automatic page numbers

To add automatic page numbers, use the _PageNumber and _LastPagenumber built-in keys within the Header or
Footer elements. The following code shows how to create footers with right-justified automatic page numbers:


The first page of the output file is numbered “Page 1 of n”, and so on.
For more information on built-in keys, see the Adobe LiveCycle Assembler Document Description XML Reference.
Using style profiles

The previous example uses the StyledText element to define inline text formatting. To define styles that you can
apply by reference, use the StyleProfile element. Style profiles let you apply a set of styles to different elements in
the PDF output file. The following code shows how to define a style profile for the table of contents Header:




ADOBE COLDFUSION 8 753
ColdFusion Developer’s Guide


Table of Contents





To apply the style profile, refer to the StyleProfile name by using the styleReference attribute of the Header
element, as the following example shows:
















 color="red" font-weight="bold" font="Arial">Table of Contents





Grouping PDF documents

To apply a style profile to a group of documents in the output PDF file, use the PDFGroup element. The following
example shows how to create a group of chapters in the output file and apply a style profile to the Footer element
for all of the documents in the group:






...

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : Yes
Page Mode                       : UseOutlines
XMP Toolkit                     : Adobe XMP Core 4.0-c316 44.253921, Sun Oct 01 2006 17:14:39
Producer                        : Acrobat Distiller 8.1.0 (Windows)
Creator Tool                    : FrameMaker 7.2
Modify Date                     : 2007:07:09 19:21:36-07:00
Create Date                     : 2007:07:09 16:10:31Z
Metadata Date                   : 2007:07:09 19:21:36-07:00
Format                          : application/pdf
Title                           : ColdFusion Developer's Guide
Creator                         : Adobe Learning Resources
Document ID                     : uuid:0480659b-9214-4fcd-842e-fbb33a95dc13
Instance ID                     : uuid:4074836a-6d70-485e-8cce-1a8dcf3aaf56
Page Count                      : 1195
Author                          : Adobe Learning Resources