MACROMEDIA COLFUSION MX 7-CFML, COLFUSION MX 7 Reference

COLDFUSION®MX 7

CFML Reference

Trademarks

1 Step RoboPDF, ActiveEdit, ActiveTest, Authorware, Blue Sky Software, Blue Sky, Breeze, Breezo, Captivate, Central, ColdFusion, Contribute, Database Explorer, Director, Dreamweaver, Fireworks, Flash, FlashCast, FlashHelp, Flash Lite, FlashPaper, Flex, Flex Builder, Fontographer, FreeHand, Generator, HomeSite, JRun, MacRecorder, Macromedia, MXML, RoboEngine, RoboHelp, RoboInfo, RoboPDF, Roundtrip, Roundtrip HTML, Shockwave, SoundEdit, Studio MX, UltraDev, and WebHelp are either registered trademarks or trademarks of Macromedia, Inc. and may be registered in the United States or in other jurisdictions including internationally. Other product names, logos, designs, titles, words, or phrases mentioned within this publication may be trademarks, service marks, or trade names of Macromedia, Inc. or other entities and may be registered in certain jurisdictions including internationally.

This product includes code licensed from RSA Data Security.

Third-Party Information

This guide contains links to third-party websites that are not under the control of Macromedia, and Macromedia is not responsible for the content on any linked site. If you access a third-party website mentioned in this guide, then you do so at your own risk. Macromedia provides these links only as a convenience, and the inclusion of the link does not imply that Macromedia endorses or accepts any responsibility for the content on those third-party sites.

Copyright © 1999–2005 Macromedia, Inc. All rights reserved. U.S. Patents Pending. This manual may not be copied, photocopied, reproduced, translated, or converted to any electronic or machine-readable form in whole or in part without written approval from Macromedia, Inc. Notwithstanding the foregoing, the owner or authorized user of a valid copy of the software with which this manual was provided may print out one copy of this manual from an electronic version of this manual for the sole purpose of such owner or authorized user learning to use such software, provided that no part of this manual may be printed out, reproduced, distributed, resold, or transmitted for any other purposes, including, without limitation, commercial purposes, such as selling copies of this documentation or providing paid-for support services. Part Number ZCF70M600

Acknowledgments

Project Management: Randy Nielsen

Writing: Hal Lichtin, Randy Nielsen

Editing: Linda Adler, Noreen Maher

Production Management: Patrice O’Neill,

Media Design and Production: John Francis, Adam Barnett

First Edition: January 2005

Macromedia, Inc. 600 Townsend St.

San Francisco, CA 94103

CONTENTS

INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

CHAPTER 1: Reserved Words and Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Reserved words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Scope-specific built-in variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Custom tag variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

ColdFusion tag-specific variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Standard CGI variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

CGI environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

CHAPTER 2: ColdFusion Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Tags by function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Tag changes since ColdFusion 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

CHAPTER 3: ColdFusion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449

Functions by category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452

Function changes since ColdFusion 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457

CHAPTER 4: ColdFusion MX Flash Form Style Reference . . . . . . . . . . . . . . . . 933

Styles valid for all controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 934

Styles for cfform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936

Styles for cfformgroup with horizontal or vertical type atributes . . . . . . . . . . . . . 936

Styles for box-style cfformgroup elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937

Styles for cfformgroup with accordion type attribute . . . . . . . . . . . . . . . . . . . . . . 938

Styles for cfformgroup with tabnavigator type attribute. . . . . . . . . . . . . . . . . . . . 939

Styles for cfformitem with hrule or vrule type attributes . . . . . . . . . . . . . . . . . . . 939

Styles for cfinput with radioButton, checkbox, button, image,

or submit type attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 940

Styles for cftextarea tag and cfinput with text, password,

or hidden type attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 941

Styles for cfselect with size attribute value of 1. . . . . . . . . . . . . . . . . . . . . . . . . . . 941

Styles for cfselect with size attribute value greater than 1 . . . . . . . . . . . . . . . . . . . 942

Styles for cfcalendar tag and cfinput with dateField type attribute . . . . . . . . . . . . 942

Styles for the cfgrid tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 943

Styles for the cftree tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 943

CHAPTER 5: Application.CFC Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945

Application variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945

Method summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 946

CHAPTER 6: ColdFusion MX Event Gateway Reference . . . . . . . . . . . . . . . . . . 963

Gateway development interfaces and classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 963

CFML CFEvent structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004

IM gateway methods and commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004

SMS Gateway CFEvent structure and commands . . . . . . . . . . . . . . . . . . . . . . . 1042

CHAPTER 7: ColdFusion C++ CFX Reference . . . . . . . . . . . . . . . . . . . . . . . . . 1055

C++ class overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055

Deprecated class methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1056

CCFXException class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1056

CCFXQuery class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1058

CCFXRequest class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1062

CCFXStringSet class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1072

CHAPTER 8: ColdFusion Java CFX Reference . . . . . . . . . . . . . . . . . . . . . . . . 1075

Class libraries overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075

Custom tag interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1076

Query interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1077

Request interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1082

Response interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1087

Debugging classes reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1090

CHAPTER 9: WDDX JavaScript Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091

JavaScript object overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091

WddxSerializer object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1092

WddxRecordset object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1095

CHAPTER 10: ColdFusion ActionScript Functions. . . . . . . . . . . . . . . . . . . . . . 1101

4 Contents

INTRODUCTION

CFML Reference is your primary ColdFusion Markup Language (CFML) reference. Use this manual to learn about CFML tags and functions, ColdFusion expressions, and using JavaScript objects for WDDX in Macromedia ColdFusion MX 7. It also provides detailed references for Java and C++ CFX interfaces.

About Macromedia ColdFusion MX documentation

The ColdFusion MX 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 MX

Configuring and Administering ColdFusion MX

ColdFusion MX Developer’s Guide

Getting Started Building ColdFusion MX Applications

CFML Reference Provides descriptions, syntax, usage, and code examples for all ColdFusion

CFML Quick Reference A brief guide that shows the syntax of ColdFusion tags, functions, and

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

Part I describes how to manage the ColdFusion environment, including connecting to your data sources and configuring security for your 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.

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

Contains an overview of ColdFusion features and application development procedures. Includes a tutorial that guides you through the process of developing an example ColdFusion application.

tags, functions, and variables.

variables.

Viewing online documentation

All ColdFusion MX documentation is available online in HTML and Adobe Acrobat Portable Document Format (PDF) files. Go to the documentation home page for ColdFusion MX on the Macromedia website: www.macromedia.com.

6 Introduction:

CHAPTER 1

Reserved Words and Variables

This chapter provides information on Macromedia ColdFusion reserved words, and lists scope variables.

Contents

Reserved words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Scope-specific built-in variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

ColdFusion tag-specific variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

CGI environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Reserved words

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.

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

custom tag page name with cf_.

• Built-in function names, such as Now or Hash

• Scope names, such as Form or Session

• 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

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

Reserved words in forms

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.

• _integer

• _float

• _range

• _date

• _time

• _eurodate

Reserved words in queries

The following table lists SQL keywords that are reserved in ColdFusion queries of queries. This list includes all reserved words in the SQL standard, and should be avoided in variables used in all queries. Do not use these keywords as variable names in any queries.

Note: Many database management systems have additional reserved words that you cannot use as variable names in queries to their databases. For a detailed list, see your DBMS documentation.

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

CHECK CLOSE COALESCE COLLATE COLLATION

COLUMN COMMIT CONNECT CONNECTION CONSTRAINT

CONSTRAINTS CONTINUE CONVERT CORRESPONDING COUNT

CREATE CROSS CURRENT CURRENT_DATE CURRENT_TIME CURRENT_

TIMESTAMP

DEALLOCATE DEC DECIMAL DECLARE DEFAULT

DEFERRABLE DEFERRED DELETE DESC DESCRIBE

DESCRIPTOR DIAGNOSTICS DISCONNECT DISTINCT DOMAIN

DOUBLE DROP ELSE END END-EXEC

CURRENT_ USER

CURSOR DATE DAY

CHAR_LENGTH

ESCAPE EXCEPT EXCEPTION EXEC EXECUTE

EXISTS EXTERNAL EXTRACT FALSE FETCH

FIRST FLOAT FOR FOREIGN FOUND

8 Chapter 1: Reserved Words and Variables

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

RIGHT ROLLBACK ROWS SCHEMA SCROLL

SECOND SECTION SELECT SESSION SESSION_USER

SET SIZE SMALLINT SOME SPACE

SQL SQLCODE SQLERROR SQLSTATE SUBSTRING

SUM SYSTEM_USER TABLE TEMPORARY THEN TIME TIMESTAMP TIMEZONE_

HOUR

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

TIMEZONE_ MINUTE

Scope-specific built-in variables

ColdFusion returns variables, such as those returned in a cfdirectory or cfftp operation. A variable is usually referenced by scoping it according to its type: naming it according to the code context in which it is available; for example, Session.varname, or Application.varname. For more information on ColdFusion scopes, see Chapter 3, “Using ColdFusion Variables” in ColdFusion

MX Developer’s Guide

Scope-specific built-in variables 9

You use the cflock tag to limit the scope of CFML constructs that modify shared data structures, files, and CFXs, to ensure that modifications occur sequentially. For more information, see

cflock on page 270, and Chapter 15, “Using Persistent Data and Locking” in ColdFusion MX

Developer’s Guide.

Variable scope

ColdFusion supports the Variables scope. Unscoped variables created with the

cfset tag acquire

the Variables scope by default. For example, the variable created by the statement

linguist = Chomsky>

can be referenced as #Variables.linguist#

Caller scope

History

ColdFusion MX: The Caller scope is accessible as a structure. (In earlier releases, it was not.)

Client variables

The following client variables are reserved:

Client.CFID Client.CFToken Client.HitCount Client.LastVisit Client.TimeCreated Client.URLToken

Server variables

Use the Server prefix to reference server variables, as follows:

<CFSET

Server.ColdFusion.ProductName Server.ColdFusion.ProductVersion Server.ColdFusion.ProductLevel Server.ColdFusion.SerialNumber Server.ColdFusion.SupportedLocales Server.ColdFusion.AppServer Server.ColdFusion.Expiration Server.ColdFusion.RootDir Server.OS.Name Server.OS.AdditionalInformation Server.OS.Version Server.OS.BuildNumber

Application and session variables

To enable application and session variables, use the

cfapplication tag or Application.cfc.

Reference them as follows:

Application.myvariable Session.myvariable

To ensure that modifications to shared data occur in the intended sequence, use the cflock tag. For more information, see

cflock on page 270.

10 Chapter 1: Reserved Words and Variables

The predefined application and session variables are as follows:

Application.ApplicationName Session.CFID Session.CFToken Session.URLToken

Custom tag variables

A ColdFusion custom tag returns the following variables:

ThisTag.ExecutionMode ThisTag.HasEndTag ThisTag.GeneratedContent ThisTag.AssocAttribs[index]

A custom tag can set a Caller variable to provide information to the caller. The Caller variable is set as follows:

The calling page can access the variable with the cfoutput tag, as follows:

<cfoutput>#variable_name#</cfoutput>

Request variable

Request variables store data about the processing of one page request. Request variables store data in a structure that can be passed to nested tags, such as custom tags, and processed once.

To provide information to nested tags, set a Request variable, as follows:

<CFSET Request.field_name1 = "value"> <CFSET Request.field_name2 = "value"> <CFSET Request.field_name3 = "value"> ...

Each nested tag can access the variable with the cfoutput tag, as follows:

<CFOUTPUT>#Request.field_name1#</CFOUTPUT>

Form variable

ColdFusion supports the Form variable FieldNames. FieldNames returns the names of the fields on a form. You use it on the action page associated with a form, as follows:

Form.FieldNames

ColdFusion tag-specific variables

Some ColdFusion tags return data as variables. For example, the cffile tag returns file size information in the FileSize variable, referenced as CFFILE.FileSize.

The following tags return data that can be referenced in variables:

cfcatch cfdirectory cferror

ColdFusion tag-specific variables 11

cffile cfftp cfhttp cfindex cfldap cfpop cfquery cfregistry cfsearch cfstoredproc

ColdFusion query variables

A ColdFusion tag that returns a query object supports the following variables, where queryname is the value of the

queryname.CurrentRow queryname.RecordCount queryname.ColumnList

name attribute:

CFCATCH variables

Within a

cfcatch block, the active exception properties can be accessed as the following

variables:

CFCATCH.Type CFCATCH.Message CFCATCH.Detail CFCATCH.ErrNumber CFCATCH.NativeErrorCode CFCATCH.SQLState CFCATCH.LockName CFCATCH.LockOperation CFCATCH.MissingFileName CFCATCH.TagContext CFCATCH.ErrorCode CFCATCH.ExtendedInfo

Within a cfcatch block, database exception properties can be accessed as the following variables:

CFCATCH.QueryError CFCATCH.SQL CFCATCH.Where CFCATCH.Datasource

Within a cfcatch block, undefined variable exception properties can be accessed as the following variable:

CFCATCH.Name

Within a cfcatch block, syntax and parsing exception properties can be accessed as the following variables:

CFCATCH.TokenText CFCATCH.Snippet CFCATCH.Column CFCATCH.KnownColumn

12 Chapter 1: Reserved Words and Variables

CFCATCH.Line CFCATCH.KnownLine

CFDIRECTORY variables

The

cfdirectory tag, with action=list, returns a query object as follows, where queryname is

the

name attribute value:

queryname.Name queryname.Size queryname.Type queryname.DateLastModified queryname.Attributes queryname.Mode

CFERROR variables

When

type="request" or "exception".

Error.Diagnostics Error.MailTo Error.DateTime Error.Browser Error.GeneratedContent Error.RemoteAddress Error.HTTPReferer Error.Template Error.QueryString

cferror generates an error page, the following error variables are available if

The following error variables are available if type="validation".

Error.ValidationHeader Error.InvalidFields Error.ValidationFooter

Any cfcatch variable that applies to exception type can be accessed within the Error scope, as follows:

Error.Type Error.Message Error.Detail Error.ErrNumber Error.NativeErrorCode Error.SQLState Error.LockName Error.LockOperation Error.MissingFileName Error.TagContext Error.ErrorCode Error.ExtendedInfo

Note: You can substitute the prefix

CFERROR.Diagnostics, CFERROR.Mailto, or CFERROR.DateTime.

CFERROR for Error, if type = "Exception"; for example,

ColdFusion tag-specific variables 13

CFFILE ACTION=Upload variables

File variables are read-only. Use the

CFFILE.ClientDirectory. The File prefix is deprecated in favor of the CFFILE prefix.

CFFILE.AttemptedServerFile CFFILE.ClientDirectory CFFILE.ClientFile CFFILE.ClientFileExt CFFILE.ClientFileName CFFILE.ContentSubType CFFILE.ContentType CFFILE.DateLastAccessed CFFILE.FileExisted CFFILE.FileSize CFFILE.FileWasAppended CFFILE.FileWasOverwritten CFFILE.FileWasRenamed CFFILE.FileWasSaved CFFILE.OldFileSize CFFILE.ServerDirectory CFFILE.ServerFile CFFILE.ServerFileExt CFFILE.ServerFileName CFFILE.TimeCreated CFFILE.TimeLastModified

CFFILE prefix to reference file variables; for example,

CFFTP error variables

When you use the

CFFTP.Succeeded CFFTP.ErrorCode CFFTP.ErrorText

cfftp stoponerror attribute, these variables are populated:

CFFTP ReturnValue variable

Some

cfftp file and directory operations provide a return value, in the variable

CFFTP.ReturnValue. Its value is determined by the results of the specify any of the following actions,

GetCurrentDir GetCurrentURL ExistsDir ExistsFile Exists

cfftp returns a value:

action attribute. When you

CFFTP query object columns

When you use the

queryname is the name attribute value, and row is the row number of each file or directory entry:

cfftp tag with the listdir action, cfftp returns a query object, where

queryname.Name[row] queryname.Path[row] queryname.URL[row] queryname.Length[row]

14 Chapter 1: Reserved Words and Variables

queryname.LastModified[row] queryname.Attributes queryname.IsDirectory queryname.Mode

CFHTTP variables

cfhttp get operation can return text and binary files. Files are downloaded and the contents

stored in a variable or file, depending on the MIME type, as follows:

CFHTTP.FileContent CFHTTP.MimeType CFHTTP.Header CFHTTP.ResponseHeader CFHTTP.StatusCode

[http_hd_key]

CFLDAP variables

The

cfldap action=query tag returns information about the LDAP query, as follows:

queryname.CurrentRow queryname.RecordCount queryname.ColumnList

CFPOP variables

The

cfpop tag returns the following result columns, depending on the action attribute value and

the use of other attributes, such as

queryname.Date queryname.From queryname.Body queryname.Header queryname.MessageNumber queryname.ReplyTo queryname.Subject queryname.CC queryname.To queryname.CurrentRow queryname.RecordCount queryname.ColumnList queryname.Attachments queryname.AttachmentFiles

attachmentpath, where queryname is the name attribute value:

CFQUERY and CFSTOREDPROC variables

The

cfquery tag returns information about the query in this variable:

CFQUERY.ExecutionTime

The cfquery tag uses the query name to scope the following data about the query:

queryname.CurrentRow queryname.RecordCount queryname.ColumnList

ColdFusion tag-specific variables 15

The cfstoredproc tag returns the following variables:

CFSTOREDPROC.ExecutionTime CFSTOREDPROC.StatusCode

CFREGISTRY variables

The

cfregistry tag returns a query record set that you can reference after executing the GetAll

action, as follows, where queryname is the

queryname.Entry queryname.Type queryname.Value

CFSEARCH variables

cfsearch operation returns the following variables, where searchname is the name attribute

value:

searchname.URL searchname.Key searchname.Title searchname.Score searchname.Custom1 and Custom2 searchname.Summary searchname.RecordCount searchname.CurrentRow searchname.RecordsSearched searchname.ColumnList

name attribute value:

Standard CGI variables

The CGI variables that are available for your use vary with the web server and configuration. This section lists the CGI 1.1 variables that some web servers create when a CGI script is called. Some of the following variables may not be available.

Request

CGI.AUTH_TYPE CGI.CONTENT_LENGTH CGI.CONTENT_TYPE CGI.METHOD CGI.PATH_INFO CGI.PATH_TRANSLATED CGI.QUERY_STRING CGI.REMOTE_ADDR CGI.REMOTE_HOST CGI.REMOTE_USER CGI.REQUEST_METHOD CGI.SCRIPT_NAME

16 Chapter 1: Reserved Words and Variables

Server

CGI.GATEWAY_INTERFACE CGI.SERVER_NAME CGI.SERVER_PORT CGI.SERVER_PROTOCOL CGI.SERVER_SOFTWARE

Client

CGI.CERT_ISSUER CGI.CERT_SUBJECT CGI.CLIENT_CERT_ENCODED CGI.HTTP_ACCEPT CGI.HTTP_IF_MODIFIED_SINCE CGI.HTTP_USER_AGENT

The CERT_ISSUER, CERT_SUBJECT, CLIENT_CERT_ENCODED variables are available only when you use client certificates.

CGI environment variables

When a browser makes a request to a server, the web server and the browser create environment variables. In ColdFusion, these variables are referred to as CGI environment variables. They take the CGI prefix regardless of whether the server uses a server API or CGI to communicate with the ColdFusion server.

Environment variables contain data about the transaction between the browser and the server, such as the IP Address, browser type, and authenticated username. You can reference CGI environment variables for a given page request anywhere in the page. CGI variables are read-only.

Note: The environment variables available to applications depend on the browser and server software.

Testing for CGI variables

Because some browsers do not support some CGI variables, ColdFusion always returns True when it tests for the existence of a CGI variable, regardless of whether the browser supports the variable. To determine if the CGI variable is available, test for an empty string, as shown in the following example:

CGI variable exists

CGI variable does not exist

</cfif>

CGI environment variables 17

CGI server variables

The following table describes common CGI environment variables that the server creates (some of these are not available with some servers):

CGI server variable Description

SERVER_SOFTWARE Name and version of the information server software answering

the request (and running the gateway). Format: name/version.

SERVER_NAME Server's hostname, DNS alias, or IP address as it appears in self-

referencing URLs.

GATEWAY_INTERFACE CGI specification revision with which this server complies. Format:

CGI/revision.

SERVER_PROTOCOL Name and revision of the information protocol this request came in

with. Format: protocol/revision.

SERVER_PORT Port number to which the request was sent.

REQUEST_METHOD Method with which the request was made. For HTTP, this is Get,

Head, Post, and so on.

PATH_INFO Extra path information, as given by the client. Scripts can be

accessed by their virtual pathname, followed by extra information at the end of this path. The extra information is sent as PATH_INFO.

PATH_TRANSLATED Translated version of PATH_INFO after any virtual-to-physical

mapping.

SCRIPT_NAME Virtual path to the script that is executing; used for self-referencing

URLs.

QUERY_STRING Query information that follows the ? in the URL that referenced

this script.

REMOTE_HOST Hostname making the request. If the server does not have this

information, it sets REMOTE_ADDR and does not set REMOTE_HOST.

REMOTE_ADDR IP address of the remote host making the request.

AUTH_TYPE If the server supports user authentication, and the script is

protected, the protocol-specific authentication method used to validate the user.

REMOTE_USER AUTH_USER

REMOTE_IDENT If the HTTP server supports RFC 931 identification, this variable is

CONTENT_TYPE For queries that have attached information, such as HTTP POST

If the server supports user authentication, and the script is protected, the username the user has authenticated as. (Also available as AUTH_USER.)

set to the remote username retrieved from the server. Use this variable for logging only.

and PUT, this is the content type of the data.

CONTENT_LENGTH Length of the content as given by the client.

18 Chapter 1: Reserved Words and Variables

CGI client variables

The following table describes common CGI environment variables the browser creates and passes in the request header:

CGI client variable Description

HTTP_REFERER The referring document that linked to or submitted form data.

HTTP_USER_AGENT The browser that the client is currently using to send the request.

Format: software/version library/version.

HTTP_IF_MODIFIED_SINCE The last time the page was modified. The browser determines

whether to set this variable, usually in response to the server having sent the LAST_MODIFIED HTTP header. take advantage of browser-side caching.

It can be used to

CGI client certificate variables

ColdFusion makes available the following client certificate data. These variables are available when running Microsoft IIS 4.0 or Netscape Enterprise under SSL if your web server is configured to accept client certificates.

CGI client certificate variable Description

CERT_SUBJECT Client-specific information provided by the web server. This data

typically includes the client's name, e-mail address, and so on; for example:

O = "VeriSign, Inc.", OU = VeriSign Trust Network, OU =

"www.verisign.com/repository/RPA Incorp. by Ref.,LIAB.LTD(c)98", OU = Persona Not Validated, OU = Digital ID Class 1 - Microsoft, CN = Matthew Lund, E = mlund@macromedia.com

CERT_ISSUER Information about the authority that provided the client certificate;

for example:

O = "VeriSign, Inc.", OU = VeriSign Trust Network, OU =

"www.verisign.com/repository/RPA Incorp. By Ref.,LIAB.LTD(c)98", CN = VeriSign Class 1 CA Individual Subscriber-Persona Not Validated

CLIENT_CERT_ENCODED The entire client certificate binary, base-64 encoded. This data is

typically of interest to developers, so they can integrate with other software that uses client certificates.

CGI environment variables 19

20 Chapter 1: Reserved Words and Variables

CHAPTER 2

ColdFusion Tags

ColdFusion Markup Language (CFML) includes a set of tags that you use in Macromedia ColdFusion MX 7 pages to interact with data sources, manipulate data, and display output. CFML tag syntax is similar to HTML element syntax.

This chapter contains categorized and alphabetical lists of the tags followed by the detailed tag descriptions.

Contents

Tag summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Tags by function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Tag changes since ColdFusion 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Tag descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Tag summary

The following table briefly describes CFML tags:

CFML tag Category Description

cfabort Flow-control tags Stops the processing of a ColdFusion page at

the tag location

cfapplet Forms tags Embeds Java applets in a cfform tag

cfapplication Application framework

tags

cfargument Extensibility tags Creates a parameter definition within a

cfassociate Application framework

tags

cfbreak Flow-control tags Breaks out of a CFML looping construct

cfcache Page processing tags Caches ColdFusion pages

Defines an application name; activates client variables; specifies client variable storage mechanism

component definition; defines a function argument

Enables subtag data to be saved with a base tag

CFML tag Category Description

cfcalendar Forms tags Provides a calendar from which to select a date

cfcase Flow-control tags Used with the cfswitch and cfdefaultcase tags cfcatch Exception handling tags,

Catches exceptions in ColdFusion pages

Flow-control tags

cfchart Data output tags Generates and displays a chart

cfchartdata Data output tags Defines chart data points

cfchartseries Data output tags Defines style in which chart data displays

cfcol Data output tags Defines table column header, properties

cfcollection Extensibility tags Administers Verity collections

cfcomponent Extensibility tags Creates and defines a component object cfcontent Data output tags,

Page processing tags

cfcookie Variable manipulation

tags

cfdefaultcase Flow-control tags Receives control if there is no matching cfcase

Defines content type and filename of a file to be downloaded by current page

Defines and sets cookie variables, including expiration and security options

tag value

cfdirectory File management tags Performs typical directory-handling tasks from

within a ColdFusion application

cfdocument Data output tags Creates PDF or FlashPaper output from a text

block containing CFML and HTML

cfdocumentitem Data output tags Specifies action items, such as header, footer,

and page break, for a PDF or FlashPaper document

cfdocumentsection Data output tags Divides a PDF or FlashPaper document into

sections

cfdump Debugging tags,

Outputs variables for debugging

Variable manipulation tags

cfelse Flow-control tags Creates IF-THEN-ELSE constructs

cfelseif Flow-control tags Creates IF-THEN-ELSE constructs cferror Exception handling tags,

Application framework

Displays custom HTML error pages when errors

occur

tags

cfexecute Flow-control tags,

Extensibility tags

cfexit Flow-control tags Aborts processing of executing CFML tag

cffile File management tags Performs typical file-handling tasks from within

Executes developer-specified process on server

computer

ColdFusion application

22 Chapter 2: ColdFusion Tags

CFML tag Category Description

cfflush Data output tags,

Flushes currently available data to client

Page processing tags

cfform Forms tags Builds input form; performs client-side input

validation

cfformgroup Forms tags Groups form control into a containing object

cfformitem Forms tags Adds text and dividing rules to Flash forms cfftp Forms tags,

Permits FTP file operations

Extensibility tags, Internet Protocol tags

cffunction Extensibility tags Defines function that you build in CFML

cfgrid Forms tags Displays tabular grid control, in cfform tag

cfgridcolumn Forms tags Used in cfform; defines columns in a cfgrid

cfgridrow

cfgridupdate

Forms tags Defines a grid row; used with cfgrid

Forms tags Directly updates ODBC data source from edited

grid data

cfheader Data output tags,

Generates HTTP headers

Page processing tags

cfhtmlhead Page processing tags Writes text and HTML to HEAD section of page

cfhttp Internet Protocol tags Performs GET and POST to upload file or post

form, cookie, query, or CGI variable directly to

server

cfhttpparam Internet Protocol tags Specifies parameters required for a cfhttp

cfif

cfimport Application framework

Flow-control tags Creates IF-THEN-ELSE constructs

POST operation; used with

Imports JSP tag libraries into a CFML page

cfhttp

tags

cfinclude Flow-control tags Embeds references to ColdFusion pages

cfindex Extensibility tags Creates Verity search indexes

cfinput Forms tags Creates an input element (radio button, check

cfinsert

Database manipulation

box, text entry box); used in

Inserts records in a data source

cfform

tags

cfinvoke Extensibility tags Invokes component methods from a ColdFusion

page or component

cfinvokeargument Extensibility tags Passes a parameter to a component method or a

web service

cfldap Internet Protocol tags Provides access to LDAP directory servers

cflocation Flow-control tags Controls execution of a page

Tag summary 23

CFML tag Category Description

cflock Application framework

tags

cflog Data output tags,

Ensures data integrity and synchronizes

execution of CFML code

Writes a message to a log file

Other tags

cflogin Security tags Defines a container for user login and

authentication code

cfloginuser Security tags Identifies an authenticated user to ColdFusion

cflogout Security tags Logs the current user out

cfloop Flow-control tags Repeats a set of instructions based on

conditions

cfmail Internet Protocol tags Assembles and posts an e-mail message

cfmailparam Internet Protocol tags Attaches a file or adds a header to an e-mail

message

cfmailpart Internet Protocol tags Contains one part of a multi-part mail message

cfmodule Application framework

tags

cfNTauthenticate Security tags Authenticates user information against an NT

Invokes a custom tag for use in a ColdFusion

page

domain

cfobject Extensibility tags Creates COM, component, CORBA, Java, and

web service objects

cfobjectcache Database manipulation

Flushes the query cache

tags

cfoutput Data output tags Displays the output of a database query or other

operation

cfparam Variable manipulation

Defines a parameter and its default value

tags

cfpop Internet Protocol tags Gets and deletes messages from POP mail

server

cfprocessingdirective Data output tags Suppresses white space and other output

cfprocparam Database manipulation

tags

cfprocresult Database manipulation

tags

cfproperty Extensibility tags Defines components

cfquery Database manipulation

Holds parameter information for stored

procedure

Result set name that ColdFusion tags use to

access result set of a stored procedure

Passes SQL statements to a database

tags

cfqueryparam Database manipulation

tags

24 Chapter 2: ColdFusion Tags

Checks data type of a query parameter

CFML tag Category Description

cfregistry Other tags,

Variable manipulation

Reads, writes, and deletes keys and values in a

Windows system registry

tags

cfreport Exception handling tags Embeds a ColdFusion Report Builder or Crystal

Reports report

cfreportparam Exception handling tags Passes an input parameter to a ColdFusion

Report Builder report

cfrethrow Exception handling tags Rethrows currently active exception

cfreturn Extensibility tags Returns results from a component method

cfsavecontent Variable manipulation

tags

cfschedule Variable manipulation

tags

cfscript Application framework

Saves generated content inside tag body in a

variable

Schedules page execution; optionally, produces

static pages

Encloses a set of cfscript statements

tags

cfsearch Extensibility tags Executes searches against data indexed in Verity

cfselect

collections, using

Forms tags Creates a drop-down list box form element; used

cfform tag

cfindex

cfset Variable manipulation

Defines a variable

tags

cfsetting Other tags,

Defines and controls ColdFusion settings

Variable manipulation tags

cfsilent Data output tags,

Suppresses CFML output within tag scope

Page processing tags

cfslider Forms tags Creates slider control; used in cfform

cfstoredproc

cfswitch Flow-control tags Evaluates passed expression; passes control to

cftable Data output tags Builds a table in a ColdFusion page

cftextarea Forms tags Puts a multiline text box in a form cfthrow Exception handling tags,

Database manipulation tags

Holds database connection information;

identifies a stored procedure to execute

matching

cfcase tag

Throws a developer-specified exception

Flow-control tags

cftimer Debugging tags Displays execution time for a block of code

cftrace Debugging tags Displays and logs application debugging data

cftransaction Database manipulation

tags

Groups cfquery operations into one transaction;

performs rollback processing

Tag summary 25

CFML tag Category Description

cftree Forms tags Creates tree control element; used in cfform

cftreeitem

cftry

cfupdate Database manipulation

cfwddx Extensibility tags Serializes and de-serializes CFML data

cfxml Extensibility tags Creates an XML document object

Forms tags Populates a tree control element in a form; used

with

cftree

Exception handling tags, Flow-control tags

tags

Catches exceptions in ColdFusion pages

Updates rows in a database data source

structures to XML-based WDDX format

Tags by function

The following tables list Tags by their function or purpose.

Application framework tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Database manipulation tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Data output tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Debugging tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Exception handling tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Extensibility tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

File management tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Flow-control tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Forms tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Internet Protocol tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Page processing tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Security tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Variable manipulation tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Other tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Application framework tags

cfapplication cfimport cfscript

cfassociate cflock

cferror cfmodule

26 Chapter 2: ColdFusion Tags

Database manipulation tags

cfinsert cfprocresult cfstoredproc

cfobjectcache cfquery cftransaction

cfprocparam cfqueryparam cfupdate

Data output tags

cfchart cfdocumentitem cfoutput

cfchartdata cfdocumentsection cfprocessingdirective

cfchartseries cfflush cfreport

cfcol cfheader cfreportparam

cfcontent cflog cfsilent

cfdocument cfoutput cftable

Debugging tags

cfdump cftimer cftrace

Exception handling tags

cfcatch cfrethrow cftry

cferror cfthrow

Extensibility tags

cfchart cffunction cfreportparam

cfchartdata cfindex cfreturn

cfchartseries cfinvoke cfsearch

cfcollection cfinvokeargument cfwddx

cfcomponent cfobject cfxml

cfexecute cfproperty

cfftp cfreport

File management tags

cfdirectory cffile cfftp

Tags by function 27

Flow-control tags

cfabort cfexecute cfrethrow

cfbreak cfexit cfswitch

cfcase cfif cfthrow

cfdefaultcase cfinclude cftry

cfelse cflocation

cfelseif cfloop

Forms tags

cfapplet cfgrid cfselect

cfcalendar cfgridcolumn cfslider

cfform cfgridrow cftextarea

cfformgroup cfgridupdate cftree

cfformitem cfinput cftreeitem

Internet Protocol tags

cfftp cfldap cfmailpart

cfhttp cfmail cfpop

cfhttpparam cfmailparam

Page processing tags

cfcache cfheader cfprocessingdirective

cfcontent cfhtmlhead cfsetting

cfflush cfinclude cfsilent

Security tags

cflogin cflogout

cfloginuser cfNTauthenticate

Variable manipulation tags

cfcookie cfregistry cfset

cfdump cfsavecontent cfsetting

cfparam cfschedule

28 Chapter 2: ColdFusion Tags

Other tags

cflog cfregistry

Tag changes since ColdFusion 5

The following tables list Tags, attributes, and values that have changed since ColdFusion 5.0 and indicate the specific release in which the change was made.

New tags, attributes, and values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Deprecated tags, attributes, and values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Obsolete tags, attributes, and values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

New tags, attributes, and values

This table lists tags, attributes, and attribute values that have been added since the ColdFusion MX release:

Tag Attribute or value Added in this ColdFusion

release

cfapplication scriptProtect ColdFusion MX 7

loginStorage ColdFusion MX 6.1

cfargument xml value of type attribute ColdFusion MX 7

All ColdFusion MX

cfcache cachedirectory, timespan

attributes

cfcalendar All ColdFusion MX 7

cfchart style , title attributes ColdFusion MX 7

xAxisType, yAxisType attributes ColdFusion MX 6.1

All ColdFusion MX

cfchartdata All ColdFusion MX

cfchartseries datalabelstyle attribute ColdFusion MX 7

column value of type attribute

All ColdFusion MX

cfcollection categories attribute ColdFusion MX 7

New values of the attribute

language

ColdFusion MX

list and categoryList values of action attribute

name attribute ColdFusion MX

Tag changes since ColdFusion 5 29

Tag Attribute or value Added in this ColdFusion

release

cfcomponent style, namespace, serviceportname,

porttypename, wsdlfile, and bindingname attributes

ColdFusion MX 7

Extended functionality for the hint and

displayname attributes when

publishing document-literal style web services

All ColdFusion MX

cfcontent variable attribute ColdFusion MX 7

cfdirectory recurse attribute for list and

delete actions

cfdocument All ColdFusion MX 7

cfdocumentitem All ColdFusion MX 7

cfdocumentsection All ColdFusion MX 7

cfexecute variable attribute ColdFusion MX 6.1

cffile result attribute for upload action ColdFusion MX 7

fixnewline attribute for action="append" and action="write"

ColdFusion MX 7

cfform name

and action attributes are

ColdFusion MX 7

optional

accessible, format, height, width , method, onError, preloader, scriptsrc, skin, style, timeout, wMode attributes

onReset event

cfformgroup All ColdFusion MX 7

cfformitem All ColdFusion MX 7

cfftp result attribute ColdFusion MX 7

cffunction description attributes ColdFusion MX 7

All ColdFusion MX

cfgrid format attribute and support for

ColdFusion MX 7

Flash and XML output

enabled, onChange, style, tooltip, visible attributes (Flash format

only)

cfgridcolumn mask attribute ColdFusion MX 7

30 Chapter 2: ColdFusion Tags

currency value of

type attribute ColdFusion MX 7

Tag Attribute or value Added in this ColdFusion

release

cfhttp result attribute ColdFusion MX 7

HEAD, PUT, DELETE, OPTIONS, and TRACE values of method attribute

multipart, getasbinary, proxyUser, proxyPassword attributes

charset,firstrowasheaders

ColdFusion MX 6.1

ColdFusion MX

attributes

cfhttpparam header and body values of type

ColdFusion MX 6.1

attribute

encoded, mimeType attributes

cfimport All ColdFusion MX

cfindex custom3, custom4, category, and

categorytree attributes for update

and

refresh actions

status attribute for Update,

ColdFusion MX 7

Refresh, Delete, Purge actions

New values of the

language

attribute

cfinput height and width attributes (all

ColdFusion MX 7

except checkbox and radiobutton)

bind attribute (text and password)

label attribute (all but radiobutton,

image, reset, and submit)

mask attribute (text only)

validateAt attribute (all but

radiobutton, image, reset, and submit)

datefield, button, file, hidden, image, reset, and submit values of type attribute

daynames and monthnames attributes

(

type="datefield" only)

boolean, email, guid, maxlength noblanks, range, submitOnce, URL, USdate, and uuid values of the

validate attribute

tooltip, visible, and enabled

attributes (Flash forms only)

src attribute (image only)

Tag changes since ColdFusion 5 31

Tag Attribute or value Added in this ColdFusion

release

cfinvoke servicePort attribute for web

ColdFusion MX 7

services

All ColdFusion MX

cfinvokeargument omit attribute ColdFusion MX 7

All ColdFusion MX

cfldap returnAsBinary attribute ColdFusion MX 7

cflogin All ColdFusion MX

cfloginuser All ColdFusion MX

cflogout All ColdFusion MX

cfmail spoolEnable attribute ColdFusion MX

charset, failto, replyTo, userName, password, wrapText attributes

cfmailparam contentID, dispositionattributes ColdFusion MX 7

type attribute ColdFusion MX 6.1

cfmailpart All ColdFusion MX 6.1

cfNTauthenticate All ColdFusion MX 7

ColdFusion MX 6.1

cfobject All ColdFusion MX

cfobjectcache All ColdFusion MX

cfparam min, max, pattern attributes ColdFusion MX 7

creditcard, email, eurodate, float, integer, range, regex, regular_expression, ssn, social_security_number, time, URL, USdate, XML, zipcode attributes of

the

type attribute

cfprocessingdirective pageEncoding attribute ColdFusion MX

cfproperty All ColdFusion MX

cfquery result attribute ColdFusion MX 7

cfreturn All ColdFusion MX

cfreport template, format, name, filename,

query, overwrite attributes

cfreportparam All ColdFusion MX 7

ColdFusion MX 7

32 Chapter 2: ColdFusion Tags

Tag Attribute or value Added in this ColdFusion

release

cfsearch category, categoryTree, status,

suggestions, contextPassages, contextBytes, contextHighlightBegin, contextHighlightEnd, previousCriteria attributes

natural, internet, and internet_basic values of type

ColdFusion MX 7

attribute

cfselect selected attribute can take a list ColdFusion MX 7

enabled, group, height, label, onKeyUp, onKeyDown, onMouseUp, onMouseDown, onChange, onClick, queryPosition, tooltip, visible,

and

width attributes

cfsetting requestTimeOut attribute ColdFusion MX

cfstoredproc result attribute ColdFusion MX 7

cftextarea All ColdFusion MX 7

cfthrow object attribute ColdFusion MX

cftimer All ColdFusion MX 7

cftree format, onChange, style attributes ColdFusion MX 7

cftrace All ColdFusion MX

cfxml All ColdFusion MX

Tag changes since ColdFusion 5 33

Deprecated tags, attributes, and values

The following tags, attributes, and attribute values are deprecated. Do not use them in ColdFusion applications. They might not work, and might cause an error, in releases later than ColdFusion MX.

Tag Attribute or value Deprecated as of this

ColdFusion release

cfcache

cfcollection

cferror

cffile

cfform

cfftp

cfgraph

cfgraphdata

cfgridupdate

cfinput

cachedirectory

map

and repair options of the

action attribute

monitor

option of the exception

, timeout attributes ColdFusion MX

ColdFusion MX 7

ColdFusion MX

attribute

system

value for attributes

ColdFusion MX

attribute

temporary value for attributes

ColdFusion MX

attribute

passthrough

enableCAB attribute ColdFusion MX

agentname

attribute ColdFusion MX 7

attribute ColdFusion MX

All ColdFusion MX

connectString dbType, provider, providerDSN

, dbName, dbServer,

ColdFusion MX

attributes

passthrough

attribute ColdFusion MX 7

cfinsert

cfldap

cflog

cfquery

cfregistry

cfsearch

cfselect

34 Chapter 2: ColdFusion Tags

connectString dbType, provider, providerDSN

, dbName, dbServer,

ColdFusion MX

attributes

filterFile

date

, thread, time attributes ColdFusion MX

connectString provider, providerDSN, sql

attribute ColdFusion MX

, dbName, dbServer,

ColdFusion MX

attributes

The following values:

dynamic, ODBC, Oracle73, Oracle80, Sybase11, OLEDB, DB2

dbType attribute

ColdFusion MX (The value

query is valid.)

All, on UNIX only ColdFusion MX

external

passthrough

, language attributes ColdFusion MX

attribute ColdFusion MX 7

Tag Attribute or value Deprecated as of this

ColdFusion release

cfservlet

cfservletparam

cfslider

cfstoredproc

All ColdFusion MX

img

, imgStyle, grooveColor,

refreshLabel, tickmarkimages, tickmarklabels, tickmarkmajor, tickmarkminor attributes

connectString dbtype, provider, providerDSN

, dbName, dbServer,

ColdFusion MX

attributes

cftextinput

cfupdate

All ColdFusion MX 7

connectString dbtype, provider, providerDSN

, dbName, dbServer,

ColdFusion MX

attributes

Obsolete tags, attributes, and values

The following tags, attributes, and attribute values are obsolete. Do not use them in ColdFusion applications. They do not work, and might cause an error, in releases later than ColdFusion 5.

Tag Attribute or value Obsolete as of this

ColdFusion release

cfauthenticate

cfchart

cffile

cfimpersonate

cfindex

cfinternaladminsecurity

cfldap

cfnewinternaladminsecurity

cfsetting

All ColdFusion MX

rotated

attributes

attribute ColdFusion MX 7

attribute value archive ColdFusion MX

All ColdFusion MX

action

external attribute

attribute value optimize ColdFusion MX

All ColdFusion MX

This tag did not appear in CFML Reference.

fileterConfig

attribute ColdFusion MX

All ColdFusion MX

This tag did not appear in CFML Reference.

catchExceptionsByPattern

ColdFusion MX

attribute

Tag changes since ColdFusion 5 35

CHAPTER 2

ColdFusion Tags

cfabort

Description

Stops the processing of a ColdFusion page at the tag location. ColdFusion returns everything that was processed before the tag. The tag is often used with conditional logic to stop processing a page when a condition occurs.

Category

Flow-control tags

Syntax

<cfabort

showError = "error_message">

See also

cfbreak

, cfexecute, cfexit, cfif, cflocation, cfloop, cfswitch, cfthrow, cftry; “cfabort

and cfexit” in Chapter 2, “Elements of CFML,” in ColdFusion MX Developer’s Guide

Attributes

Attribute Req/Opt Default Description

showError Optional Error to display, in a standard ColdFusion error page, when tag

executes.

Usage

When you use the cfabort and cferror tags together, the cfabort tag halts processing immediately; the

If this tag does not contain a and ColdFusion returns the page contents up to the line that contains the

When you use this tag with the

cferror, page processing stops when the cfabort tag is reached. The message in showError

cferror tag redirects output to a specified page.

showError attribute value, processing stops when the tag is reached

cfabort tag.

showError attribute, but do not define an error page using

displays to the client.

When you use this tag with the ColdFusion redirects output to the error page specified in the

showError attribute and an error page using cferror,

cferror tag.

Example

This example shows the use of cfabort to stop processing. In the second example, where cfabort is used, the result never displays.

<h3>Example A: Let the instruction complete itself</h3>  <cfset myVariable = 3>  <cfloop from = "1" to = "4" index = "Counter">

</cfloop>

36 Chapter 2: ColdFusion Tags

<p>The value of myVariable after incrementing through the loop #Counter# times

is:

#myVariable#

</cfoutput>

<h3>Example B: Use cfabort to halt the instructions with showmessage attribute

and cferror</h3>  <cfset myVariable = 3>  <cfloop from = "1" to = "4" index = "Counter">

<!--- Take out the cferror line to see cfabort error processed by CF error

page --->

</cfif> </cfloop>

<cfoutput> <p> The value of myVariable after incrementing through the loop#counter# times

is: #myVariable# </cfoutput>

cfabort 37

cfapplet

Description

This tag references a registered custom Java applet. To register a Java applet, in the ColdFusion Administrator, click Extensions > Java Applets.

Using this tag within a

cfform tag is optional. If you use it within cfform, and the method

attribute is defined in the Administrator, the return value is incorporated into the form.

Category

Forms tags

Syntax

<cfapplet

appletSource = "applet_name"

name = "form_variable_name"

height = "height_in_pixels"

width = "width_in_pixels"

vSpace = "space_above_and_below_in_pixels"

hSpace = "space_on_each_side_in_pixels"

align = "alignment_option"

notSupported = "message_to_display_for_nonJava_browser"

param_1 = "applet_parameter_name"

param_2 = "applet_parameter_name"

param_n = "applet_parameter_name">

See also

cfform, cfformgroup, cfformitem, cfgrid, cfinput, cfobject, cfselect, cfservlet, cfslider, cftextarea, cftree

History

ColdFusion MX:

• Removed the requirement that you use this tag within a cfform tag.

• Changed the behavior when this tag is used within a cfform tag; if the method attribute is

defined in the Administrator, the return value of the applet’s method is incorporated into the

form.

Attributes

Attribute Req/Opt Default Description

appletSource Required Name of registered applet

name Required Form variable name for applet

height Optional Height of applet, in pixel

width Optional Width of applet, in pixels

vSpace Optional Space above and below applet, in pixels

hSpace Optional Space on left and right of applet, in pixels

38 Chapter 2: ColdFusion Tags

Attribute Req/Opt Default Description

align Optional Alignment:

• Left

• Right

• Bottom

• Top

• TextTop

• Middle

• AbsMiddle

• Baseline

• AbsBottom

notSupported Optional See

Description

param_n Optional Registered parameter for applet. Specify only to override

Usage

Text to display if a page that contains a Java applet-based cfform control is opened by a browser that does not support Java or has Java support disabled. For example:

notSupported = "<b>Browser must support Java to view ColdFusion Java Applets</b>" Default: <b>Browser must support Java to<br> view ColdFusion Java

Applets!</b>

values for applet in ColdFusion Administrator.

You can specify the applet method attribute only in the Administrator, Java Applets view. For other attributes, you can accept the default values in the Administrator view, or specify values in this tag and override the defaults.

If Java applet components are stored in a JAR file, enter the filename in the ColdFusion Administrator, Java Applets window, Archive text box. For more information, see “Embedding Java applets” in Chapter 27, “Building Dynamic Forms with cfform Tags” in ColdFusion MX

Developer’s Guide

Example

<p>cfapplet lets you reference custom Java applets that have been

registered using the ColdFusion Administrator. <p>To register a Java applet, open the ColdFusion Administrator and

click "Applets" link under "extensions" section. <p>This example applet copies text that you type into a form. Type

some text, and then click "copy" to see the copied text.

cfapplet 39

cfapplication

Description

Defines the scope of a ColdFusion application; enables and disables storage of Client variables; specifies the Client variable storage mechanism; enables Session variables; and sets Application variable timeouts.

Category

Application framework tags

Syntax

<cfapplication

name = "application_name"

loginStorage = "cookie" or "session"

clientManagement = "yes" or "no"

clientStorage = "datasource_name" or "Registry" or "Cookie"

setClientCookies = "yes" or "no"

sessionManagement = "yes" or "no"

sessionTimeout = #CreateTimeSpan(days, hours, minutes, seconds)#

applicationTimeout = #CreateTimeSpan(days, hours, minutes, seconds)#

setDomainCookies = "yes" or "no"

scriptProtect = "none", "all", or list>

See also

cfassociate

, cferror, cflock, cfmodule; Chapter 5, “Application.CFC Reference,” on

page 945; Chapter 13, “Designing and Optimizing a ColdFusion Application” and Chapter 37,

“Integrating J2EE and Java Elements in CFML Applications,” in ColdFusion MX Developer’s

Guide

History

ColdFusion MX 7: Added scriptProtect attribute

ColdFusion MX 6.1: Added

loginStorage attribute

ColdFusion MX:

• Changed how persistent scopes are available: Server, Session, and Application scope variables

are stored in memory as structures. In earlier releases, only Session and Application scope

variables were stored this way. You cannot access the UDF function scope as a structure.

• Changed the algorithm for setting the CFTOKEN variable value: if the registry key

UUIDToken is a non-zero value, ColdFusion uses a number constructed from the UUID plus

a random number. Otherwise, ColdFusion sets the CFTOKEN variable default value using a

positive random integer. (In earlier releases, ColdFusion always used a number constructed

from the UUID plus a random number.)

40 Chapter 2: ColdFusion Tags

Attributes

Attribute Req/Opt Default Description

name See

Description

Name of application. Up to 64 characters.

For Application and Session variables: Required.

For Client variables: Optional

loginStorage Optional cookie • cookie: store login information in the Cookie

scope.

• session: store login information in the Session scope.

clientManagement Optional no • yes: enables client variables.

• no

clientStorage Optional registry How client variables are stored:

• datasource_name: in ODBC or native data source. You must create storage repository in the Administrator.

• registry: in the system registry.

• cookie: on client computer in a cookie.

Scalable. If client disables cookies in the browser, client variables do not work.

setClientCookies Optional yes • yes: enables client cookies.

• no: ColdFusion does not automatically send CFID and CFTOKEN cookies to client browser; you must manually code CFID and CFTOKEN on the URL for every page that uses Session or Client variables.

sessionManagement Optional no • yes: enables session variables.

• no

sessionTimeout Optional Specified in

Variables page of ColdFusion Administrator

applicationTimeout Optional Specified in

Variables page of ColdFusion Administrator

Lifespan of session variables. CreateTimeSpan function and values in days, hours, minutes, and seconds, separated by commas.

Lifespan of application variables. CreateTimeSpan function and values in days, hours, minutes, and seconds, separated by commas.

cfapplication 41

Attribute Req/Opt Default Description

setDomainCookies Optional no • yes: uses domain cookies for CFID and

CFTOKEN cookies and for all Client variables when using cookies for client variable storage. Required for applications running on clusters.

• no: uses host-specific cookies for CFID, CFTOKEN, and all client variable cookies.

scriptProtect Optional Determined by

ColdFusion MX Administrator Enable Global Script Protection setting

Usage

Specifies whether to protect variables from cross-site scripting attacks

• none: do not protect variables

• all: protect Form, URL, CGI, and Cookie

variables

• comma-delimited list of ColdFusion scopes: Protect variables in the specified scopes.

For more information, see Usage.

This tag is typically used in the Application.cfm file, to set defaults for a ColdFusion application.

Note: You can also set the application defaults in the Application.cfc file. For more information, see

“Application variables” on page 945.

This tag enables application variables, unless they are disabled in the ColdFusion Administrator. The Administrator setting also overrides the

sessionManagement attribute. For more

information, see Configuring and Administering ColdFusion MX.

If ColdFusion is running on a cluster, you must specify source name; you cannot specify

"registry".

clientStorage = "cookie" or a data

ColdFusion generates an error if the application name is longer than 64 characters.

The CFTOKEN variable is 8 bytes in length. Its range is 10000000 —99999999.

Note: If you specify ClientStorage=cookie, any Client scope variables set following a cfflush tag are not saved in the Client browser.

Protecting variables from cross-site scripting attacks

The ScriptProtect attribute lets you protect one or more variable scopes from cross-site scripting attacks, where a client attempts to get your application to send malicious code back to a user’s browser. In these attacks, user input (for example, from form fields or from URL variables) sets a CF variable which is destined for user output. The submitted data includes malicious code, such as JavaScript or an applet or object reference, which then executes on the user’s system.

Note: The ColdFusion MX Administrator Settings page Enable Global Script Protection option determines the default script protection setting. You can use the the Administrator setting. You can also use the Application.cfc initialization code to set the protection value.

42 Chapter 2: ColdFusion Tags

scriptProtect attribute to override

The ColdFusion MX cross-site scripting protection operation is done when ColdFusion MX processes the application settings at the beginning of a request. Thus, it can process the URL, and Cookie, CGI, and Form variables in a user’s request. By default, it replaces occurrences of the following tag names with the text InvalidTag: object, embed, script, applet, and meta. It allows these names in plain text, replaces the words if they are used as tag names.

You can specify any or all ColdFusion scopes for protection, but only the Form, URL, CGI, and Cookie scopes have variables that are often provided by unknown sources. Also, protecting a scope requires additional processing. For these reasons, the

all attribute value applies protection

to only the four scopes.

The script protection mechanism applies a regular expression that is defined in the neo-security.xml file in the server configuration, or the

cf_root/WEB-INF/cfusion/lib/neo-

cf_root/lib/

security.xml file in the J2EE configuration to the variable value. You can customize the patterns that ColdFusion replaces by modifying the regular expression in the CrossSiteScriptPatterns variable.

Locking server, application, and session variables

When you set or update variables in the server, application, and session scopes, use the cflock tag with the

scope attribute set to the following value:

• For server variables, specify "server"

• For application variables, specify "application"

• For session variables, specify "session"

In some cases, you should also lock code that reads variables in these scopes. For information about locking scopes, see

Example

<!--- This example shows how to use cflock to prevent race conditions during

data updates to variables in Application, Server, and Session scopes. ---> <h3>cfapplication Example</h3> <p>cfapplication defines scoping for a ColdFusion application and enables or

disables application and/or session variable storage. This tag is placed in

a special file called Application.cfm that automatically runs before any

other CF page in a directory (or subdirectory) where the Application.cfm

file appears.</p>

cflock on page 270.

<cfparam name="application.number" default="1"> <cfparam name="session.color" default= ""> <cfparam name="session.size" default="">

<cfif IsDefined("session.numPurchased") AND

IsNumeric(trim(session.cartTotal))>

cfapplication 43

<!--- Use the application scope for the application variable to prevent race

condition. This variable keeps track of total number of turtlenecks sold. --

</cflock> </cfif>

<cfoutput> E-Turtleneck is proud to say that we have sold #application.number# turtlenecks

to date. </cfoutput>

44 Chapter 2: ColdFusion Tags

cfargument

Description

Creates a parameter definition within a component definition. Defines a function argument. Used within a

Category

Extensibility tags

Syntax

<cfargument

name="string"

type="data type"

required="yes" or "no"

default="default value"

displayname="descriptive name"

hint="extended description">

See also

cfcomponent, cffunction, cfinvoke, cfinvokeargument, cfobject, cfproperty, cfreturn

Attributes

cffunction tag.

Attribute Req/Opt Default Description

name Required String; an argument name.

type Optional any String; a type name; data type of the argument.

• any

• array

• binary

• boolean

• date

• guid: the argument must be a UUID or GUID of the form

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where each x is a character representing a hexadecimal number (0-9A-F).

• numeric

• query

• string

• struct

• uuid: the argument must be a ColdFusion UUID of the form

xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx where each x is a character representing a hexadecimal number (0-9A-F).

• variableName: a string formatted according to ColdFusion variable naming conventions.

• xml: XML objects and XML strings

• a component name: if the type attribute value is not one of

the preceding items, ColdFusion treats it as the name of a ColdFusion component. When the function executes, it generates an error if the argument that is passed in is not a CFC with the specified name.

cfargument 45

Attribute Req/Opt Default Description

required Optional no Note: All arguments are required when invoked as a web

service, irrespective of how they are defined.

Specifies whether the parameter is required to execute the component method. The parameter is not required if you specify a

• true or "yes"

• false or "no"

default Optional If no argument is passed, specifies a default argument value.

default attribute.

displayname Optional

hint Optional Meaningful only for CFC method parameters. Text to be

Usage

name

attribute value

Meaningful only for CFC method parameters. A value to be displayed when using introspection to show information about the CFC.

displayed when using introspection to show information about the CFC. The attribute value in the parameter description line. This attribute can be useful for describing the purpose of the parameter.

hint attribute value follows the displayname

This tag must be in a cffunction tag, before any other tags in the cffunction tag body.

Arguments that are passed when a method is invoked can be accessed from the method body in the following ways:

• With shorthand syntax: #myargument#

(This example accesses the argument myargument.)

• Using the arguments scope as an array: #arguments[1]#

(This example accesses the first defined argument in the cffunction.)

• Using the arguments scope as a struct: #arguments.myargument#

(This example accesses the argument myargument in the array.)

Example

<!--- This example defines a function that takes a course number parameter

and returns the course description. --->

<cfargument name="Course_Number" type="numeric" required="true">  <cfquery name="Description" datasource="cfdocexamples">

SELECT Descript FROM Courses

WHERE Number = '#Course_Number#' </cfquery>  <cfreturn Description.Descript>

</cffunction>

46 Chapter 2: ColdFusion Tags

cfassociate

Description

Allows subtag data to be saved with a base tag. Applies only to custom tags.

Category

Application framework tags

Syntax

<cfassociate

baseTag = "base_tag_name"

dataCollection = "collection_name">

See also

cfapplication, cferror, cflock, cfmodule

; “High-level data exchange” in Chapter 11,

“Creating and Using Custom CFML Tags,” in ColdFusion MX Developer’s Guide.

Attributes

Attribute Req/Opt Default Description

baseTag Required Base tag name.

dataCollection Optional AssocAttribs Structure in which base tag stores subtag data.

Usage

Call this tag within a subtag, to save subtag data in the base tag.

When ColdFusion passes subtag attributes back to the base tag, it saves them in a structure whose default name is multiple subtags), specify a structure name, in the

AssocAttribs. To segregate subtag attributes (in a base tag that can have

dataCollection attribute. The structure is

appended to an array whose name is thistag.collectionName.

Within the custom tag code, the attributes passed to the tag by using the

attributeCollection

attribute are saved as independent values, with no indication that they are grouped into a structure by the custom tag’s caller. Therefore, in the called tag, if you assign a value to a specific attribute, it replaces the value passed in the

attributeCollection attribute that you used when

calling the subtag.

Example

<cfif thisTag.executionMode is "start">  <cfassociate baseTag = "CF_TAGBASE">

<cfparam name = "attributes.happy" default = "yes"> <cfparam name = "attributes.sad" default = "no"> ...

cfassociate 47

cfauthenticate

Description

This tag is obsolete. Use the newer security tools; see “Conversion functions” on page 453 and Chapter 16, “Securing Applications” in ColdFusion MX Developer’s Guide.

History

ColdFusion MX: this tag is obsolete. It does not work in ColdFusion MX and later releases.

48 Chapter 2: ColdFusion Tags

cfbreak

Description

Used within a cfloop or cfswitch tag. Breaks out of a loop or switch block.

Category

Flow-control tags

Syntax

See also

cfabort

, cfexecute, cfif, cflocation, cfloop, cfswitch, cfthrow, cftry; “cfloop and

cfbreak” in Chapter 2, “Elements of CFML,” in ColdFusion MX Developer’s Guide

Example

<cfif IsDefined("form.course_number")>

</cfif> </cfif> <cfquery name="GetCourses" datasource="cfdocexamples">

SELECT *

FROM Courses

ORDER by course_number </cfquery>

<p> This example uses CFLOOP to cycle through a query to find a value. (In our example, a list of values corresponding to courses in the Snippets datasource). When the conditions of the query are met, CFBREAK stops the loop. <p> Please enter a Course Number, and hit the "submit" button: <form action="cfbreak.cfm" method="POST">

<option value="#course_number#">#course_number#

</cfoutput> </select> <input type="Submit" name="" value="Search on my Number">

</form> <!--- If the courseNum variable is not defined,

don't loop through the query.--->

<h4>Your Desired Course was found:</h4>

<pre>#course_number# #descript#</pre> </cfoutput> <cfbreak>

cfbreak 49

</cfif>

</cfloop>

</cfif>

<br> Searching...

50 Chapter 2: ColdFusion Tags

cfcache

Description

Stores a copy of a page on the server and/or client computer, to improve page rendering performance. To do this, the tag creates temporary files that contain the static HTML returned from a ColdFusion page.

Use this tag if it is not necessary to get dynamic content each time a user accesses a page.

You can use this tag for simple URLs and for URLs that contain URL parameters.

Category

Page processing tags

Syntax

<cfcache

action = "action" directory = "directory_name" timespan = "value" expireURL = "wildcarded_URL_reference" username = "username" password = "password" port = "port_number"

protocol = "protocol">

See also

cfflush, cfheader, cfhtmlhead, cfsetting, cfsilent

History

ColdFusion MX:

• Deprecated the cachedirectory and timeout attributes. They might not work, and might

cause an error, in later releases.

• Added the timespan attribute.

• Changed how pages are cached: the default action attribute value, cache, caches a page on

the server and the client. (In earlier releases, this option cached a page only on the server.)

• Changed the source of the protocol and port values: the default protocol and port values

are now taken from the current page URL. (In earlier releases, they were respectively.)

"http" and "80",

• Changed how session state is handled when caching a page: this tag can cache pages that

depend on session state, including pages that are secured with a ColdFusion login. (In earlier releases, the session state was cleared when caching the page, causing authentication to be lost.)

• Changed how files are cached: this tag uses a hash() of the URL for the filename to cache a file.

(In earlier releases, ColdFusion used the cfcache.map file.)

cfcache 51

Attributes

Attribute Req/Opt Default Description

action Optional cache • cache: server-side and client-side caching.

• flush: refresh cached page(s).

• clientcache: browser-side caching only. To cache a

personalized page, use this option.

• servercache: server-side caching only. Not recommended.

• optimal: same as "cache".

directory Optional cf_root/cache Absolute path of cache directory.

timespan Optional Page is

flushed only when

cfcache

action "flush" is

executed

expireURL Optional Flush all

cached pages

The interval until the page is flushed from the cache.

• A decimal number of days. For example:

■

- ".25", for one-fourth day (6 hours)

■

- "1", for one day

■

- "1.5", for one and one half days

• A return value from the example,

"#CreateTimeSpan(0, 6, 0, 0)#".

CreateTimeSpan function; for

Used with action = "flush". A URL reference. ColdFusion matches it against the mappings in the specified cache directory. Can include wildcards. For example:

"*/view.cfm?id=*".

username Optional A username. Provide this if the page requires

authentication at the web server level.

password Optional A password. Provide this if the page requires

authentication at the web server level.

port Optional The current

page port

Port number of the web server from which the URL is requested. In the internal call from

cfcache to cfhttp,

ColdFusion resolves each URL variable in the page; this ensures that links in the page remain functional.

protocol Optional The current

page protocol

Protocol that is used to create URL from cache.

• http://

• https://

Usage

Use this tag in pages whose content is not updated frequently. Taking this action can greatly improve the performance of your application.

The output of a cached page is stored in a file on the client browser and/or the ColdFusion server. Instead of regenerating and downloading the output of the page each time it is requested, ColdFusion uses the cached output. ColdFusion regenerates and downloads the page only when the cache is flushed, as specified by the

action=flush

To enable a simple form of caching, put a top of a page. Each time the specified time span passes, ColdFusion flushes (deletes) the copy of the page from the cache and caches a new copy for users to access.

52 Chapter 2: ColdFusion Tags

timespan attribute, or by invoking cfcache

cfcache tag, specifying the timespan attribute, at the

You can specify client-side caching or a combination of client-side and server-side caching (the default), using the action attribute. The advantage of client-side caching is that it requires no ColdFusion resources; the browser stores pages in its own cache, improving performance. The advantage of combination caching is that it optimizes server performance; if the browser does not have a cache of the page, the server can get data from its own cache. (Macromedia recommends that you do not use server-side only caching. Macromedia recommends that you use combination caching.)

If a page contains personalized content, use the

action = "clientcache" option to avoid the

possibility of caching a personalized copy of a page for other users.

Debug settings have no effect on generating a cached file,

cfcache uses cfsetting showDebugOutput = "no".

cfcache unless the application page enables debugging. When

The cfcache tag evaluates each unique URL, including URL parameters, as a distinct page, for caching purposes. For example, the output of http://server/view.cfm?id=1 and the output of http://server/view.cfm?id=2 are cached separately.

The

cfcache tag uses the cfhttp tag to get the contents of a page to cache. If there is an HTTP

error accessing the page, the contents are not cached. If a ColdFusion error occurs, the error is cached.

For more information, see “Caching ColdFusion pages that change infrequently” in Chapter 13, “Optimizing ColdFusion applications,” in ColdFusion MX Developer’s Guide.

Example

<h3>This is a test of some simple output</h3>

<cfoutput> This page was generated at #now()#<br> </cfoutput>

<cfparam name = "URL.x" default = "no URL parm passed" > <cfoutput>The value of URL.x = # URL.x #</cfoutput>

cfcache 53

cfcalendar

Description

Puts an interactive Macromedia Flash format calendar in an HTML or Flash form. Not supported in XML format forms. The calendar lets a user select a date for submission as a form variable.

Category

Forms tags

Syntax

<cfcalendar

name = "name of calendar" height = "height" width = "width" selectedDate = "date" startRange = "first disabled date" endRange = "last disabled date" disabled = "true", "false", or no attribute value mask = "character pattern" dayNames = "days-of-the-week labels" monthNames = "month labels" visible = "Yes" or "No" enabled = "Yes" or "No" tooltip = "Tip text"

onChange = "actionscript to invoke">

See also

cfform

, cfgrid, cfinput, cfselect, cfslider, cftextarea, cftree; “About Flash form

styles” in Chapter 29, “Creating Forms in Macromedia Flash” in ColdFusion MX Developer’s Guide.

History

ColdFusion MX 7: Added tag.

Attributes

Attribute Req/Opt Default Description

name Required The name of the calendar.

height Optional Determined by

Flash

width Optional Determined by

Flash

selectedDate Optional None (Flash

shows the current month)

The vertical dimension of the calendar specified in pixels.

The horizontal dimension of the calendar specified in pixels.

The date that is initially selected. It is highlighted in a color determined by the form skin. Must be in mm/ dd/yyyy or dd/mm/yyyy format, depending on the current locale. (Use the locale, if necessary.)

setlocale tag to set the

54 Chapter 2: ColdFusion Tags

Attribute Req/Opt Default Description

startRange Optional The start of a range of dates that are disabled. Users

cannot select dates from this date through the date specified by the

endRange attribute.

endRange Optional The end of a range of dates that are disabled. Users

cannot select dates from the date specified by the

startRange attribute through this date.

disabled Optional not disabled Disables all user input, making the control read-only.

To disable input, specify attribute or

disabled="Yes" (or any ColdFusion

disabled without an

positive boolean value, such as True). To enable input, omit the attribute or specify

disabled="No" (or

any ColdFusion negative boolean value, such as False).

mask Optional MM/DD/YYYY A pattern that specifies the format of the submitted

date. Mask characters are:

• D = day; can use 0–2 mask characters

• M = month; can use 0–4 mask characters

• Y = year; can use 0, 2, or 4 characters

• E = day in week; can use 0–4 characters

• Any other character = put the character in the

specified location

For more information on masking, see “Masking

input data” in the

cfinput reference page.

firstDayOfWeek Optional 0 Integer in the range 0-6 specifying the first day of

the week in the calendar: 0 indicates Sunday; 6 indicates Saturday.

dayNames Optional S, M, T, W, Th,

F, S

A comma-delimited list that sets the names of the weekdays displayed in the calendar. Sunday is the first day and the rest of the weekday names follow in the normal order.

monthNames Optional January,

February,

A comma-delimited list of the month names that are

displayed at the top of the calendar. March, April, May, June, July, August, September, October, November, December

style Optional Flash ActionScript style or styles to apply to the

calendar. For more information, see Chapter 29,

“Setting styles and skins in Flash forms” in

ColdFusion MX Developer’s Guide.

enabled Optional Yes Flash only: Boolean value specifying whether the

control is enabled. A disabled control appears in

light gray. This is the inverse of the disabled

attribute.

cfcalendar 55

Attribute Req/Opt Default Description

visible Optional Yes Flash only: Boolean value specifying whether to

show the control. Space that would be occupied by

an invisible control is blank.

tooltip Optional Flash only: Text to display when the mouse pointer

hovers over the control.

onChange Optional ActionScript that runs when the user selects a date.

Usage

The cfcalendar tag displays a calendar month, showing the month, the year, a grid of the days of the month, and headings for the days of the week. The calendar contains forward and back arrow buttons to let you change the month and year that are displayed.

If you include a value for the

selectedDate attribute, that date is highlighted in green and

determines the month and year that display initially. Changing the month and year display does not change the selected date. A user can change the selected date by clicking a different date on the calendar. The

onChange attribute can specify an ActionScript event handler function that

runs when the user selects a date.

The current date is highlighted in reverse (that is, a white number on a black background). If the selected date is in a different month or year, however, the current date does not appear unless you move to it by clicking the forward or back arrows.

The

mask attribute lets you specify the format of the selected date that is returned to the

application.

You can use the keyboard to access and select dates from a

cfcalendar control:

• Use the Up, Down, Left, and Right Arrow keys to change the selected date.

• Use the Home and End keys to reach the first and last enabled date in a month, respectively.

• Use the Page Up and Page Down keys to reach the previous and next month, respectively.

Note: The cfcalendar tag is not supported in XML format forms.

Example

This example produces a 200-pixel by 150-pixel calendar with a Flash haloBlue skin. It displays abbreviated month names and two-character days of the week. It initially displays today’s date as determined by the back to the current page, which displays the submitted information.

selectedDate attribute. When you click the Save button, the form submits

The example also has three that displays on the calendar and a blocked-out date range. The initial blocked-out date is a fourday period immediately preceding today’s date.

Note: This example must be modified to work in locales that do not use mm/dd/yyyy date formats. To do so, use the appropriate for your locale, such as dd/mm/yyyy.

<cfparam name="Form.startdate" default="#dateformat(now()-5, 'mm/dd/yyyy')#">

56 Chapter 2: ColdFusion Tags

LSDateFormat function in place of the DateFormat function and a mask that is

dateField controls that let the user change the initial selected date

<cfif isDefined("Form.submitit")>

<cfoutput><b>You selected #Form.selectedDate#</b><br><br></cfoutput>

</cfif>

<b>Please select a date on the calendar and click Save.</b><br> <br> <cfform name="form1" format="Flash" skin="haloBlue" width="375" height="350" >

<cfcalendar name="selectedDate"

selectedDate="#Form.selectdate#" startRange="#Form.startdate#" endRange="#Form.enddate#" mask="mmm dd, yyyy" dayNames="SU,MO,TU,WE,TH,FR,SA" monthNames="JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC" style="rollOverColor:##FF0000" width="200" height="150" >

<cfinput type="dateField" name="startdate" label="Block out starts"

width="100" value="#Form.startdate#">

<cfinput type="dateField" name="enddate" label="Block out ends" width="100"

value="#Form.enddate#">

<cfinput type="dateField" name="selectdate" label="Initial date" width="100"

value="#Form.selectdate#" >

</cfform>

cfcalendar 57

cfcase

Description

Used only inside the cfswitch tag body. Contains code to execute when the expression specified in the

Category

Flow-control tags

Syntax

<cfcase

See also

cfswitch tag has one or more specific values.

value = "value or delimited set of values"

delimiters = "delimiter characters">

cfdefaultcase

, cfswitch; “cfswitch, cfcase, and cfdefaultcase” in Chapter 2, “Elements of

CFML,” in ColdFusion MX Developer’s Guide

Attributes

Attribute Req/Opt Default Description

value Required The value or values that the expression attribute of the

cfswitch tag must match. To specify multiple matching

values, separate the values with the character. The value or values must be simple constants or constant expressions, not variables.

delimiter Optional , (comma) Specifies the delimiter character or characters that

separate multiple values to match. If you specify multiple delimiter characters, you can use any of them to separate the values to be matched.

Usage

delimiter

The contents of the cfcase tag body executes only if the expression attribute of the cfswitch tag evaluates to a value specified by the

value attribute. The contents of the cfcase tag body can

include HTML and text, and CFML tags, functions, variables, and expressions. You do not have to explicitly break out of the

cfcase tag, as you do in some languages.

One

cfcase tag can match multiple expression values. To do this, separate the matching values

with the delimiter character, which is the comma by default. For example the following line matches "red", "blue", or "green":

You can use the delimiter attribute to specify one or more delimiters to use in place of the comma. For example, the following line matches "cargo, live", "cargo, liquid", and "cargo, solid":

Example

The following example displays a grade based on a 1-10 score. Several of the cfcase tags match more than one score. For simplicity, the example sets the score to 7.

58 Chapter 2: ColdFusion Tags

</cfswitch> <cfoutput>

Your grade is #grade#

</cfoutput>

cfcase 59

cfcatch

Description

Used inside a cftry tag. Together, they catch and process exceptions in ColdFusion pages. Exceptions are events that disrupt the normal flow of instructions in a ColdFusion page, such as failed database operations, missing include files, and developer-specified events.

Category

Exception handling tags

Syntax

Exception processing code here

</cfcatch>

See also

cftry

, cferror, cfrethrow, cfthrow, onError; Chapter 14, “Handling Errors,” in ColdFusion

MX Developer’s Guide

History

ColdFusion MX:

• Changed SQLSTATE value behavior: the SQLSTATE return value in a cfcatch tag depends

on the database driver type:

■ Type 1 (JDBC-ODBC bridge): the value is the same as in ColdFusion 5

■ Type 4 (100% Java, no native methods): the value might be different

If your application depends on SQLSTATE values for flow control, the application might produce unexpected behavior with ColdFusion MX.

• Changed the behavior of this tag when type="any": it is not necessary, when you include a

cfcatch tag with type="any", to do so in the last cfcatch tag in the block, to ensure that all

other tests are executed before it. ColdFusion finds the best-match

cfcatch block.

• Changed the behavior of the cfscript tag: it includes try and catch statements that are

equivalent to the

cftry and cfcatch tags.

• Changed object modification: you cannot modify the object returned by cfcatch.

• Changed thrown exceptions: the cfcollection, cfindex, and cfsearch tags can throw the

SEARCHENGINE exception. In earlier releases, an error in processing these tags threw only an UNKNOWN exception.

60 Chapter 2: ColdFusion Tags

Attributes

Attribute Req/Opt Default Description

type Optional Any • application: catches application exceptions

• database: catches database exceptions

• template: catches ColdFusion page exceptions

• security: catches security exceptions

• object: catches object exceptions

• missingInclude: catches missing include file exceptions

• expression: catches expression exceptions

• lock: catches lock exceptions

• custom_type: catches the specified custom exception type

that is defined in a

• searchengine: catches Verity search engine exceptions

• any: catches all exception types

Usage

cfthrow tag

You must code at least one cfcatch tag within a cftry block. Put cfcatch tags at the end of a

cftry block. ColdFusion MX tests cfcatch tags in the order in which they appear. This tag

requires an end tag.

type="any", ColdFusion MX catches exceptions from any CFML tag, data source, or external

object. To get the exception type use code such as the following:

#cfcatch.type#

Applications can use the cfthrow tag to throw developer-defined exceptions. Catch these exceptions with any of these

type options:

• "custom_type"

• "Application"

• "Any"

The custom_type type is a developer-defined type specified in a cfthrow tag. If you define a custom type as a series of strings concatenated by periods (for example, "

MyApp.BusinessRuleException.InvalidAccount"), ColdFusion MX can catch the custom

type by its character pattern. ColdFusion MX searches for a a matching exception type, starting with the most specific (the entire string), and ending with the least specific.

For example, you could define a type as follows:

If you have the following cfcatch tag, it will handle the exception:

Otherwise, if you have the following cfcatch tag, it will handle the exception:

cfcatch tag in the cftry block with

Finally, if you have the following cfcatch tag, it will handle the exception:

cfcatch 61

You can code cfcatch tags in any order to catch a custom exception type.

If you specify the

Application type in the cfthrow tag that defines them.

The

cfinclude, cfmodule, and cferror tags throw an exception of type = "template".

An exception that is thrown within a immediately encloses the with the

The

cfcatch variables provide the following exception information:

type = "Application", the cfcatch tag catches only custom exceptions that have

cfcatch block cannot be handled by the cftry block that

cfcatch tag. However, you can rethrow the currently active exception

cfrethrow tag.

cfcatch variable Content

cfcatch.type

cfcatch.message

cfcatch.detail

Type: Exception type, as specified in cfcatch.

Message: Exception's diagnostic message, if provided; otherwise, an empty string; in the

cfcatch.message variable.

Detailed message from the CFML interpreter or specified in a

cfthrow tag. When the exception is generated by ColdFusion (and

not

cfthrow), the message can contain HTML formatting and can

help determine which tag threw the exception.

cfcatch.tagcontext

An array of tag context structures, each representing one level of the active tag context at the time of the exception.

cfcatch.NativeErrorCode

Applies to type = "database". Native error code associated with exception. Database drivers typically provide error codes to diagnose failing database operations. Default: -1.

cfcatch.SQLState

cfcatch.Sql

cfcatch.queryError

cfcatch.where

cfcatch.ErrNumber

cfcatch.MissingFileName

cfcatch.LockName

cfcatch.LockOperation

cfcatch.ErrorCode

cfcatch.ExtendedInfo

Applies to type = "database". SQLState associated with exception. Database drivers typically provide error codes to help diagnose failing database operations. Default: -1.

Applies to type = "database". The SQL statement sent to the data source.

Applies to type ="database". The error message as reported by the database driver.

Applies to type = "database". If the query uses the cfqueryparam tag, query parameter name-value pairs.

Applies to type = "expression". Internal expression error number.

Applies to type = "missingInclude". Name of file that could not be included.

Applies to type = "lock". Name of affected lock (if the lock is unnamed, the value is

"anonymous").

Applies to type = "lock". Operation that failed (Timeout, Create Mutex, or Unknown).

Applies to type = "custom". String error code.

Applies to type = "application" and "custom". Custom error message; information that the default exception handler does not display.

62 Chapter 2: ColdFusion Tags

Advanced Exception types

You can specify the following advanced exception types in the type attribute:

ColdFusion advanced exception type

COM.Allaire.ColdFusion.CFEXECUTE.OutputError

COM.Allaire.ColdFusion.CFEXECUTE.Timeout

COM.Allaire.ColdFusion.FileException

COM.Allaire.ColdFusion.HTTPAccepted

COM.Allaire.ColdFusion.HTTPAuthFailure

COM.Allaire.ColdFusion.HTTPBadGateway

COM.Allaire.ColdFusion.HTTPBadRequest

COM.Allaire.ColdFusion.HTTPCFHTTPRequestEntityTooLarge

COM.Allaire.ColdFusion.HTTPCGIValueNotPassed

COM.Allaire.ColdFusion.HTTPConflict

COM.Allaire.ColdFusion.HTTPContentLengthRequired

COM.Allaire.ColdFusion.HTTPContinue

COM.Allaire.ColdFusion.HTTPCookieValueNotPassed

COM.Allaire.ColdFusion.HTTPCreated

COM.Allaire.ColdFusion.HTTPFailure

COM.Allaire.ColdFusion.HTTPFileInvalidPath

COM.Allaire.ColdFusion.HTTPFileNotFound

COM.Allaire.ColdFusion.HTTPFileNotPassed

COM.Allaire.ColdFusion.HTTPFileNotRenderable

COM.Allaire.ColdFusion.HTTPForbidden

COM.Allaire.ColdFusion.HTTPGatewayTimeout

COM.Allaire.ColdFusion.HTTPGone

COM.Allaire.ColdFusion.HTTPMethodNotAllowed

COM.Allaire.ColdFusion.HTTPMovedPermanently

COM.Allaire.ColdFusion.HTTPMovedTemporarily

COM.Allaire.ColdFusion.HTTPMultipleChoices

COM.Allaire.ColdFusion.HTTPNoContent

COM.Allaire.ColdFusion.HTTPNonAuthoritativeInfo

COM.Allaire.ColdFusion.HTTPNotAcceptable

COM.Allaire.ColdFusion.HTTPNotFound

COM.Allaire.ColdFusion.HTTPNotImplemented

cfcatch 63

ColdFusion advanced exception type

COM.Allaire.ColdFusion.HTTPNotModified

COM.Allaire.ColdFusion.HTTPPartialContent

COM.Allaire.ColdFusion.HTTPPaymentRequired

COM.Allaire.ColdFusion.HTTPPreconditionFailed

COM.Allaire.ColdFusion.HTTPProxyAuthenticationRequired

COM.Allaire.ColdFusion.HTTPRequestURITooLarge

COM.Allaire.ColdFusion.HTTPResetContent

COM.Allaire.ColdFusion.HTTPSeeOther

COM.Allaire.ColdFusion.HTTPServerError

COM.Allaire.ColdFusion.HTTPServiceUnavailable

COM.Allaire.ColdFusion.HTTPSwitchingProtocols

COM.Allaire.ColdFusion.HTTPUnsupportedMediaType

COM.Allaire.ColdFusion.HTTPUrlValueNotPassed

COM.Allaire.ColdFusion.HTTPUseProxy

COM.Allaire.ColdFusion.HTTPVersionNotSupported

COM.Allaire.ColdFusion.POPAuthFailure

COM.Allaire.ColdFusion.POPConnectionFailure

COM.Allaire.ColdFusion.POPDeleteError

COM.Allaire.ColdFusion.Request.Timeout

COM.Allaire.ColdFusion.SERVLETJRunError

COMCOM.Allaire.ColdFusion.HTTPConnectionTimeout

Example

<h3>cftry Example</h3>  <cftry>

<cfquery name = "TestQuery" dataSource = "cfdocexamples">

SELECT *

FROM EMPLOYEEAS </cfquery>   <cfcatch type = "Database">

<h3>You've Thrown a Database <b>Error</b></h3>

<p>#cfcatch.message#</p>

64 Chapter 2: ColdFusion Tags

</cfoutput> </cfcatch>

</cftry>

<p>Caught an exception, type = #CFCATCH.TYPE# </p> <p>The contents of the tag stack are:</p> <cfdump var="#cfcatch.tagcontext#">

cfcatch 65

cfchart

Description

Generates and displays a chart.

Category

Data output tags, Extensibility tags; “Controlling chart appearance” in Chapter 31, “Creating

Charts and Graphs,” in ColdFusion MX Developer’s Guide

Syntax

Syntax 1

<cfchart

style = "XML string or filename">

</cfchart>

Syntax 2

<!--- This syntax uses the attributes of the cfchart tag to specify the chart

style. ---> <cfchart

backgroundColor = "Hex value or Web color"

chartHeight = "integer number of pixels"

chartWidth = "integer number of pixels"

dataBackgroundColor = "Hex value or Web color"

font = "font name"

fontBold = "yes" or "no"

fontItalic = "yes" or "no"

fontSize = "integer font size"

foregroundColor = "Hex value or Web color"

format = "flash" or "jpg" or "png"

gridlines = "integer number of lines"

labelFormat = "number, currency, percent, date"

markerSize = "integer number of pixels"

name = "String">

pieSliceStyle = "solid, sliced"

scaleFrom = "integer minimum value"

scaleTo = "integer maximum value"

seriesPlacement = "default, cluster, stacked, percent"

show3D = "yes" or "no"

showBorder = "yes" or "no"

showLegend = "yes" or "no"

showMarkers = "yes" or "no"

showXGridlines = "yes" or "no"

showYGridlines = "yes" or "no"

sortXAxis = "yes" or "no"

tipBGColor = "hex value or web color"

tipStyle = "MouseDown, MouseOver, none"

title = "title of chart"

url = "onClick destination page"

xAxisTitle = "title text"

xAxisType = "scale or category"

xOffset = "number between -1 and 1"

yAxisTitle = "title text"

yAxisType = "scale or category"

yOffset = "number between -1 and 1"

</cfchart>

66 Chapter 2: ColdFusion Tags

See also

cfchartdata

History

, cfchartseries

ColdFusion MX 7:

• Added style and title attributes.

• Added support for eight-digit hexadecimal values to specify RGB color and transparency.

• Removed the rotated attribute.

• Renamed the column chart type to be horizontalbar chart type.

ColdFusion MX 6.1:

• Added the xAxisType and yAxisType attributes.

• Changed interpolation behavior: the tag now interpolates data points on line charts with

multiple series.

ColdFusion MX: Added this tag.

Attributes

Attribute Req/Opt Default Description

backgroundColor Optional Color of the area between the data

background and the chart border, around labels and around the legend.

Hexadecimal value or supported named color; see the name list in Usage. For a hexadecimal value, use the form or "##xxxxxxxx", where x = 0-9 or A-F; use two number signs or none.

"##xxxxxx"

chartHeight Optional 240 Chart height; integer number of pixels.

chartWidth Optional 320 Chart width; integer number of pixels.

dataBackgroundColor Optional white Color of area around chart data.

Hexadecimal value or supported named color; see the name list in Usage.

For a hexadecimal value, use the form

"##xxxxxx" or "##xxxxxxxx", where x = 0-9 or

A-F; use two number signs or none.

font Optional arial Name of text font:

• arial

• times

• courier

• arialunicodeMS. This option is required, if

you are using a double-byte character set on UNIX, or using a double-byte character set in Windows with a file type of Flash.

cfchart 67

Attribute Req/Opt Default Description

fontBold Optional no Whether to make the text bold:

• yes

• no

fontItalic Optional no Whether to make the text italicized:

• yes

• no

fontSize Optional 11 Font size; integer.

foregroundColor Optional black Color of text, grid lines, and labels.

Hexadecimal value or supported named color; see name list in Usage.

For a hexadecimal value, use the form

"##xxxxxx" or "##xxxxxxxx", where x = 0-9 or

A-F; use two number signs or none.

format Optional flash File format in which to save the graph:

• flash

• jpg

• png

gridlines Optional 10, including

top and bottom

Number of grid lines to display on the value axis, including axis; positive integer.

labelFormat Optional number Format for y-axis labels:

• number

• currency

• percent

• date

markerSize Optional (Automatic) Size of data point marker in pixels; integer.

name Optional Page variable name; string. Generates the

the graph as binary data and assigns it to the specified variable. Suppresses chart display. You can use the

name value in the cffile tag

to write the chart to a file.

pieSliceStyle Optional sliced Applies to the

value

pie.

cfchartseries type attribute

• solid: displays pie as if unsliced.

• sliced: displays pie as if sliced.

rotated Optional no Whether to rotate the chart 90 degrees:

• yes

• no

scaleFrom Optional Determined by

scaleTo Optional Determined by

68 Chapter 2: ColdFusion Tags

Y-axis minimum value; integer.

data

Y-axis maximum value; integer.

data

Attribute Req/Opt Default Description

seriesPlacement Optional default Relative positions of series in charts that

have more than one data series.

• default: ColdFusion determines relative positions, based on graph types

• cluster

• stacked

• percent

show3D Optional yes Whether to display the chart with three-

dimensional appearance:

• yes

• no

showBorder Optional no Whether to display a border around the

chart:

• yes

• no

showLegend Optional yes Whether to display the legend if the chart

contains more than one data series:

• yes

• no

showMarkers Optional yes Whether to display markers at data points in

line, curve, and scatter graphs:

• yes

• no

showXGridlines Optional no Whether to display x-axis gridlines:

• yes

• no

showYGridlines Optional yes Whether to display y-axis gridlines:

• yes

• no

sortXAxis Optional no Whether to display column labels in

alphabetic order along the x-axis:

• yes:

• no

Ignored if the

xAxisType attribute is scale.

style Optional XML file or string to use to specify the style

of the chart.

title Optional Title of the chart.

tipbgcolor Optional white Background color of tips. Applies only to

Flash format graph files. Hexadecimal value or supported named

color; see the name list in the Usage section. For a hexadecimal value, use the form

"##xxxxxx", where x = 0-9 or A-F; use two

number signs or none.

cfchart 69

Attribute Req/Opt Default Description

tipStyle Optional mouseOver Determines the action that opens a pop-up

window to display information about the current chart element.

• mouseDown: display if the user positions the cursor at the element and clicks the mouse. Applies only to Flash format graph files. (For other formats, this option functions the same as

mouseOver.)

• mouseOver: displays if the user positions the cursor at the element

• none: suppresses display

url Optional URL to open if the user clicks item in a data

series; the

onClick destination page.

You can specify variables within the URL string; ColdFusion passes current values of the variables.

•

$VALUE$: the value of the selected row. If

none, the value is an empty string.

$ITEMLABEL$: the label of the selected item.

•

If none, the value is an empty string.

•

$SERIESLABEL$: the label of the selected

series. If none, the value is an empty string.

For example:

“somepage.cfm?item=$ITEMLABEL$&series=$

SERIESLABEL$&value=$VALUE$

• "javascript:...": executes a client-side script

xAxisTitle Optional Title that appears on the x-axis; text.

xAxisType Optional category Whether the x-axis indicates data or is

numeric:

• category: The axis indicates the data category. Data is sorted according to the

sortXAxis attribute.

• scale: The axis is numeric. All

item attribute values must be numeric. The

cfchartdata

x-axis is automatically sorted numerically.

xOffset Optional 0.1 Number of units by which to display the chart

as angled, horizontally. Applies if

show3D="yes". The number can be between

-1 and 1, where "-1" specifies 90 degrees left

and "1" specifies 90 degrees right.

yAxisTitle Optional Title of the y-axis; text.

70 Chapter 2: ColdFusion Tags

Attribute Req/Opt Default Description

yAxisType Optional category Currently has no effect, as the y-axis is

always used for data values.

yOffset Optional 0.1 Number of units by which to display the chart

as angled, vertically. Applies if The number can be between -1 and 1, where "-1" specifies 90 degrees left and "1" specifies 90 degrees right.

Usage

show3D="yes".

The cfchart tag defines a container in which a graph displays: its height, width, background color, labels, and so on. The bar, line, pie, and so on. The

cfchartseries tag defines the chart style in which data displays:

cfchartdata tag defines a data point.

Data is passed to the

cfchartseries tag in the following ways:

• As a query

• As data points, using the cfchartdata tag

For the

font attribute value ArialUnicodeMS, the following rules apply:

• In Windows, to permit Flash charts (type = "flash") to render a double-byte character set,

you must select this value.

• On UNIX, for all type values, to render a double-byte character set, you must select this value.

• If this value is selected, the fontBold and fontItalic attributes have no effect.

The following table lists W3C HTML 4 named color value or hexadecimal values that the attribute accepts:

Color name RGB value

Aqua ##00FFFF

Black #000000

Blue ##0000FF

Fuchsia ##FF00FF

color

Gray ##808080

Green ##008000

Lime ##00FF00

Maroon ##800000

Navy ##000080

Olive ##808000

Purple ##800080

Red ##FF0000

Silver ##C0C0C0

cfchart 71

Color name RGB value

Teal ##008080

White ##FFFFFF

Yellow ##FFFF00

For all other color values, you must enter the hexadecimal value. You can enter a six-digit value, which specifies the RGB value, or an eight-digit value, which specifies the RGB value and the transparency. The first two digits of an eight-digit hexadecimal value specify the degree of transparency, with FF indicating opaque and 00 indicating transparent. Values between 00 and FF are allowed.

For more color names that are supported by popular browsers, go to www.w3.org/TR/css3-color

You can specify whether charts are cached in memory, the number of charts to cache, and the number of chart requests that ColdFusion can process concurrently. To set these options in the ColdFusion Administrator, select Server Settings > Charting.

Example

<cfquery name="GetSalaries" datasource="cfdocexamples"> SELECT Departmt.Dept_Name, Employee.Dept_ID, Employee.Salary FROM Departmt, Employee WHERE Departmt.Dept_ID = Employee.Dept_ID </cfquery>

<cfquery dbtype = "query" name = "DataTable"> SELECT Dept_Name, AVG(Salary) AS avgSal, SUM(Salary) AS sumSal FROM GetSalaries GROUP BY Dept_Name </cfquery>

<cfloop index = "i" from = "1" to = "#DataTable.RecordCount#"> <cfset DataTable.sumSal[i] = Round(DataTable.sumSal[i]/1000)*1000> <cfset DataTable.avgSal[i] = Round(DataTable.avgSal[i]/1000)*1000> </cfloop>

72 Chapter 2: ColdFusion Tags

<h1>Employee Salary Analysis</h1>  <cfchart format="flash" xaxistitle="Department" yaxistitle="Salary Average">

</cfchartseries> </cfchart>

cfchart 73

cfchartdata

Description

Used with the cfchart and cfchartseries tags. This tag defines chart data points. Its data is submitted to the

Category

Data output tags, Extensibility tags

Syntax

<cfchartdata

item = "text"

value = "number">

See also

cfchartseries tag.

cfchart

, cfchartseries; Chapter 31, “Creating Charts and Graphs,” in ColdFusion MX

Developer’s Guide

ColdFusion MX: Added this tag.

Attributes

Attribute Req/Opt Default Description

item Required Data point name; string.

value Required Data point value; number or expression.

Example

74 Chapter 2: ColdFusion Tags

</cfquery>

<h1>Employee Salary Analysis</h1>  <cfchart format="flash" xaxistitle="Department" yaxistitle="Salary Average">

</cfchartseries> </cfchart>

cfchartdata 75

cfchartseries

Description

Used with the cfchart tag. This tag defines the chart style in which the data displays: bar, line, pie, and so on.

Category

Data output tags, Extensibility tags

Syntax

<cfchartseries

colorlist = "list"> itemColumn="queryColumn" markerStyle="style" paintStyle="plain, raise, shade, light" query="queryName" seriesColor="Hex value or Web color" seriesLabel="Label Text" type="type" valueColumn="queryColumn" dataLabelStyle="style"

</cfchartseries>

See also

cfchart

, cfchartdata; Chapter 31, “Creating Charts and Graphs,” in ColdFusion MX

Developer’s Guide

History

ColdFusion MX 7: Added the dataLabelStyle attribute and the horizontalbar chart type.

ColdFusion MX 6.1: Changed interpolation behavior: the tag now interpolates data points on line charts with multiple series.

ColdFusion MX: Added this tag.

76 Chapter 2: ColdFusion Tags

Attributes

Attribute Req/Opt Default Description

colorlist Optional Sets colors for each data point. Applies if the

cfchartseries type attribute is pie, pyramid, area, horizontalbar, cone, cylinder, or step.

Comma-delimited list of hexadecimal values or supported, named web colors; see the name list and information about six- and eight-digit hexadecimal values in the

cfchart Usage section.

For a hexadecimal value, use the form

"##xxxxxxxx", where x = 0-9 or A-F; use two number

signs or none.

"##xxxxxx" or

itemColumn Required if

query

attribute is

Name of a column in the query specified in the

attribute; contains the item label for a data point to graph.

query

specified

markerStyle Optional rectangle Sets the icon that marks a data point for two-

dimensional line, curve, and scatter graphs:

• rectangle

• triangle

• diamond

• circle

• letter

• mcross

• snow

• rcross

paintStyle Optional plain Sets the paint display style of the data series:

• plain: solid color.

• raise: the appearance of a button.

• shade: gradient fill, darker at the edges.

• light: a lighter shade of color; gradient fill.

query Optional Name of the ColdFusion query from which to get data

to graph.

seriesColor Optional Color of the main element (such as the bars) of a chart.

seriesLabel Optional Text of the data series label

For a pie chart, the color of the first slice. Hexadecimal value or supported named color; see the

name list and information about six- and eight-digit hexadecimal values in the Usage section for the

cfchart tag.

For a hexadecimal value, use the form

"##xxxxxxxx", where x = 0-9 or A-F; use two number

"##xxxxxx" or

signs or none.

cfchartseries 77

Attribute Req/Opt Default Description

type Required Sets the chart display style:

• bar

• line

• pyramid

• area

• horizontalbar

• cone

• curve

• cylinder

• step

• scatter

• pie

valueColumn Required if

query

attribute is specified

dataLabelStyle Optional None Specifies the way in which the color is applied to the

Usage

Name of a column in the query specified in the

attribute; contains data values to graph.

item in the series:

• none: nothing is printed.

• value: the value of the datapoint.

• rowLabel: the row's label.

• columnLabel: the column's label.

• pattern: combination of column label, value, and

aggregate information, such as columnLabel value for the percentage of total graph; for example, Sales 55,000 20% of 277,000.

query

For a pie chart, ColdFusion sets pie slice colors as follows:

• If the seriesColor attribute is omitted, ColdFusion automatically determines the colors of

the slices.

• If the seriesColor attribute is specified, ColdFusion automatically determines the colors of

the slices after the first one, starting with the specified color for the first slice.

Example

78 Chapter 2: ColdFusion Tags

<h1>Employee Salary Analysis</h1>  <cfchart format="flash" xaxistitle="Department" yaxistitle="Salary Average">

cfchartseries 79

cfcol

Description

Defines table column header, width, alignment, and text. Used within a cftable tag.

Category

Data output tags

Syntax

<cfcol

header = "column_header_text" width = "number_indicating_width_of_column" align = "left" or "right" or "center"

text = "column_text">

See also

cfcontent

, cfoutput, cftable; “Performing file operations with cfftp” in Chapter 40,

“Interacting with Remote Servers,” in ColdFusion MX Developer’s Guide

History

ColdFusion MX: Added the ability to construct dynamic cfcol statements.

Attribute Req/Opt Default Description

header Required Column header text. To use this attribute, you must also use the

cftable colHeaders attribute.

width Optional 20 Column width. If the length of data displayed exceeds this value,

data is truncated to fit. To avoid this, use an HTML If the surrounding

width specifies the percent of the table width and it does not

truncate text; otherwise, characters.

align Optional left Column alignment:

• left

• right

• center

text Required Double-quotation mark-delimited text; determines what to

display. Rules: same as for hyperlinks, image references, and input controls.

cftable tag includes the htmltable attribute,

width specifies the number of

cfoutput sections. You can embed

table tag.

Usage

At least one cfcol tag is required within the cftable tag. You must put cfcol and cftable tags adjacent in a page. The only tag that you can nest within the cannot nest

To d i sp l ay th e

colHeader attribute. If you specify either attribute without the other, the header does not display.

cftable tags.

cfcol header text, you must specify the cfcol header and the cftable

No error is thrown.

80 Chapter 2: ColdFusion Tags

cftable tag is the cfcol tag. You

Example

<!--- This example shows the use of cfcol and cftable to align

information returned from a query. --->  <cfquery name = "GetEmployees" dataSource = "cfdocexamples">

SELECT Emp_ID, FirstName, LastName, EMail, Phone, Department

FROM Employees </cfquery> <html> <body> <h3>cfcol Example</h3>

<!--- Uses the HTMLTable attribute to display cftable as an HTML

table, rather than PRE formatted information ---> <cftable

query = "GetEmployees"

startRow = "1" colSpacing = "3"

HTMLTable colheaders>

<!--- Each cfcol tag sets the width of a column in the table,

the header information, and the text/CFML for the cell. --->

<cfcol header = "<b>ID</b>"

align = "Left" width = 2 text = "#Emp_ID#">

<cfcol header = "<b>Name/Email</b>"

align = "Left" width = 15 text = "<a href = ’mailto:#Email#’>#FirstName# #LastName#</A>">

<cfcol header = "<b>Phone Number</b>"

align = "Center" width = 15 text = "#Phone#">

</cftable>

cfcol 81

cfcollection

Description

Creates and administers Verity search engine collections.

Category

Extensibility tags

Syntax

<cfcollection

action = "action"

collection = "collection_name"

path = "path_to_verity_collection"

language = "language"

name = "queryname"

categories = "yes" or "no">

See also

cfexecute, cfindex, cfobject, cfreport, cfsearch, cfwddx

History

ColdFusion MX 7:

• Removed reference to external collections.

• Deprecated the map and repair options of the action attribute. They might not work, and

might cause an error, in later releases.

• Added categories attribute and categorylist action.

• Added CATEGORIES, SIZE, DOCCOUNT, and LASTMODIFIED to list of variables

returned by the

list action.

• Marked as obsolete the MAPPED, ONLINE, and REGISTERED variables returned by the

list action.

ColdFusion MX:

• Changed the requirements for the action attribute: it is now required.

• Added the action attribute list value. It is the default.

• Changed the requirements for the action attribute value map: it is not necessary to specify the

action attribute value map. (ColdFusion detects collections and creates maps collections as

required.)

• Changed acceptable collection naming: this tag accepts collection names that include spaces.

• Changed Verity operations behavior: ColdFusion supports Verity operations on Acrobat PDF

files.

• Changed thrown exceptions: this tag can throw the SEARCHENGINE exception.

82 Chapter 2: ColdFusion Tags

Attributes

Attribute Req/Opt Default Description

action Required; see

Usage

list • categorylist: retrieves categories from the collection and

indicates how many documents are in each one. Returns a structure of structures in which the category representing each substructure is associated with a number of documents. For a category in a category tree, the number of documents is the number at or below that level in the tree.

• create: registers the collection with ColdFusion.

■

If the collection is present: creates a map to it.

■

If the collection is not present: creates it.

• delete: unregisters a collection and deletes its directories.

• list: returns a query result set, named from the

name

attribute value, of the attributes of the collections that are registered by ColdFusion.

• map: creates a map to a collection. If the action is

create

and the collection already exists, Coldfusion also creates a map to the collection.

• optimize: optimizes the structure and contents of the collection for searching; recovers space. Causes collection to be taken offline, preventing searches and indexing.

• repair: deprecated. Does nothing.

collection See Usage • A collection name. The name can include spaces.

path See Usage Absolute path to a Verity collection.

To map an existing collection, specify a fully qualified path to the collection (not including the collection name); for example,

"C:\MyCollections\".

language See Usage English Although English is the default language, Englishx, a more

advanced English locale, is also provided. For a list of options, see Usage.

Requires the appropriate (European or Asian) Verity Locales language pack.

name See Usage Name for the query results returned by the

categorylist actions.

list and

categories See Usage no Used only for creating a collection:

• yes: this collection includes support for categories.

• no: this collection does not support categories.

Usage

With this tag you can create, register, and administer a Verity collection that was created by ColdFusion or by a Verity application.

cfcollection 83

The following table shows the dependence relationships among this tag’s attribute values:

This attribute is required, optional, or

For this action attribute value:

list create map optimize repair delete categorylist

unnecessary (blank):

collection

path

language

name

Category

Extensibility tags

Syntax

<cfcomponent

extends ="anotherComponent" output = "yes" or "no" style = "rpc" or "document" namespace = "default service namespace" serviceportname = "port element name" porttypename = "porttype element name" bindingname = "binding element name" wsdlfile = "path to hard-coded wsdl file" displayname = "text string">

hint = "text string">

variable declarations

...

</cffunction>

...

</cffunction>

</cfcomponent>

See also

cfargument, cffunction, cfinvoke, cfinvokeargument, cfobject, cfproperty, cfreturn,

Chapter 10, “Building and Using ColdFusion Components” in ColdFusion MX

Developer’s Guide

88 Chapter 2: ColdFusion Tags

History

ColdFusion MX 7:

• Added support for publishing document-literal style web services.

• Added the style, namespace, serviceportname, porttypename, wsdlfile, and

bindingname attributes.

• Extended functionality for the hint and displayname attributes when publishing document-

literal style web services.

ColdFusion MX: Added this tag.

Attributes

Attribute Req/Opt Default Description

extends Optional Name of parent component from which to inherit

methods and properties.

output Optional Component

body displayable text is processed as standard CFML

style Optional rpc Specifies whether a CFC used for web services uses

namespace Optional classname Specifies the namespace used in the WSDL when

Specifies whether constructor code in the component can generate HTML output; does not affect output in the body of

• yes: Constructor code is processed as if it were within a by number signs (#) are automatically replaced with their values.

• no: Constructor code is processed as if it were within a

• If you do not specify this attribute, constructor code is processed as standard CFML. Any variables must be in

RPC-encoded style or document-literal style:

• rpc: RPC-encoded style

• document: document-literal style

using the CFC as a document-literal style web service. If you don’t specify this attribute, ColdFusion MX derives the value from the CFC class name.

This attribute applies only when

cffunction tags in the component.

cfoutput tag. Variable names surrounded

cfsilent tag.

cfoutput tags.

style="document".

serviceportname Optional Specifies the

name attribute of the port element in the

WSDL. If you don’t specify this attribute, ColdFusion MX derives the value from the CFC class name.

This attribute applies only when

style="document".

cfcomponent 89

Attribute Req/Opt Default Description

porttypename Optional Specifies the name attribute of the porttype element in

the WSDL. If you don’t specify this attribute, ColdFusion MX derives the value from the CFC class name.

This attribute applies only when

bindingname Optional Specifies the

the WSDL. If you don’t specify this attribute, ColdFusion MX derives the value from the CFC class name.

This attribute applies only when

wsdlfile Optional A properly formatted WSDL file to be used instead of

WSDL generated by ColdFusion MX.

This attribute applies only when

displayname Optional A string to be displayed when using introspection to

show information about the CFC. The information appears on the heading, following the component name.

If the

style attribute is set to document,

ColdFusion MX uses the

name attribute of the service element in the WSDL.

hint Optional Text to be displayed when using introspection to

show information about the CFC. The hint attribute value appears below the component name heading. This attribute can be useful for describing the purpose of the parameter.

binding attribute of the port element in

displayname attribute as the

style="document".

If the

style attribute is set to document,

Usage

ColdFusion MX uses the of the

documentation element of the service in the

WSDL.

hint attribute as the content

If you specify the extends attribute, the data and methods of the parent component are available to CFC methods as if they were parts of the current component. If the managerCFC component extends the employeeCFC component, and the employeeCFC component has a getEmployeeName method, you can call this method using the managerCFC, as follows:

<cfinvoke component="managerCFC" method="getEmployeeName"

returnVariable="managerName" EmployeeID=#EmpID#>

This tag requires an end tag.

If you specify

style="document", ColdFusion MX publishes the CFC as a document-literal style

web service. For more information, see “Publishing document-literal style web services” in Chapter 36, “Using Web Services” in ColdFusion MX Developer’s Guide.

90 Chapter 2: ColdFusion Tags

Example

<cfquery name="empQuery" datasource="cfdocexamples" > SELECT FIRSTNAME, LASTNAME, EMAIL FROM tblEmployees </cfquery> <cfreturn empQuery>

</cffunction>

<cfquery name="deptQuery" datasource="cfdocexamples" > SELECT * FROM tblDepartments </cfquery> <cfreturn deptQuery>

</cffunction>

</cfcomponent>

cfcomponent 91

cfcontent

Description

Does either or both of the following:

• Sets the MIME content encoding header for the current page; if the encoding information

includes a character encoding, sets the character encoding of generated output.

• Sends the contents of a file, or of a variable that contains binary data, as the page output.

To restrict this tag, use the Sandbox Security feature of the ColdFusion MX Administrator. For more information, see the Administrator online Help.

Category

Data output tags

Syntax

<cfcontent

type = "file_type" deleteFile = "yes" or "no" file = "filename" variable = "variablename"

reset = "yes" or "no">

See also

cfcol, cfheader, cfhttp, cfoutput, cftable

History

ColdFusion MX 7: Added the variable attribute.

92 Chapter 2: ColdFusion Tags

Attributes

Attribute Req/Opt Default Description

type Optional The MIME content type of the page, optionally followed by a

semicolon and the character encoding. By default, ColdFusion sends pages as text/html content type in the UTF-8 character encoding.

The content type determines how the browser or client interprets the page contents.

The following are some of the content type values you can use:

• text/html

• text/plain

• application/x-shockwave-flash

• application/msword

• image/jpeg

The following list includes commonly used character encoding values:

• utf-8

• iso-8859-1

• windows-1252

• us-ascii

• shift_jis

• iso-2022-jp

• euc-jp

• euc-kr

• big5

• euc-cn

• utf-16

For example: type = "text/html" type = "text/html; charset=ISO-8859-1"

deleteFile Optional no Applies only if you specify a file with the

file attribute.

• yes: deletes the file on the server after sending its contents to the client.

• no: leaves the file on the server.

file Optional Name of file whose contents will be the page output. The file

name must start with a drive letter and a colon, or a forward or backward slash. When using ColdFusion in a distributed configuration, the

file attribute must refer to a path on the

system on which the web server runs. When you use this attribute, any other output on the current CFML page is ignored; only the contents of the file are sent to the client.

cfcontent 93

Attribute Req/Opt Default Description

variable Optional Name of a ColdFusion MX binary variable whose contents can

be displayed by the browser, such as the contents of a chart generated by the a

cffile action="readBinary" tag. When you use this

attribute, any other output on the current CFML page is ignored; only the contents of the file are sent to the client.

cfchart tag or a PDF or Excel file retrieved by

reset Optional yes If you specify a

effect; otherwise, it does the following:

• yes: discards output that precedes call to

• no: preserves output that precedes call to cfcontent. In this

case, all output is sent with the specified type.

Usage

file or variable attribute, this attribute has no

cfcontent

To set the character encoding (character set) of generated output, including the page HTML, use code such as the following:

When ColdFusion processes an HTTP request, it determines the character encoding to use for the data it returns in the HTTP response. By default, ColdFusion returns character data using the Unicode UTF-8 format, regardless of the value of an HTML the

cfcontent tag to override the default character encoding of the response. For example, to tell

ColdFusion MX to return the page using Japanese EUC character encoding, use the

meta tag in the page. You can use

type

attribute, as follows:

If you call the cfcontent tag from a custom tag, and you do not want the tag to discard the current page when it is called from another application or custom tag, set

reset = "no".

If a file delete operation is unsuccessful, ColdFusion throws an error.

Do not use this tag after the

cfflush tag on a page, it will have no effect or ColdFusion will

throw an error.

The following tag can force most browsers to display a dialog box that asks users whether they want to save the contents of the file specified by the by the

filename value. If the user selects to open the file, most browsers open the file in the

cfcontent tag using the filename specified

related application, not the browser window.

<cfheader name="Content-Disposition" value="attachment;

filename=filename.ext">

Some file types, such as PDF documents, do not use executable code and can display directly in most browsers. To request the browser to display the file directly, use a

cfheader tag similar to

the following:

You can use any value for the filename part of the filename attribute, but the ext part must be the standard Windows extension for the file type.

94 Chapter 2: ColdFusion Tags

For file types that might contain executable code, such as Microsoft Excel documents, most browsers always ask before opening the document. For these file types, the inline content disposition specification requests the browser to display the file directly if the user selects to open the file.

For more information on character encodings, see the following web pages:

• www.w3.org/International/O-charset.html provides general information on character

encodings and the web, and has several useful links.

• www.iana.org/assignments/character-sets is a complete list of character sets names used on the

Internet, maintained by the Internet Assigned Numbers Authority.

• java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.html lists the character encodings that

Java, and therefore ColdFusion, can interpret. This list uses Java internal names, not the IANA character encoding names that you use in the ColdFusion attributes and parameters. ColdFusion MX 6.0 Updater 3 uses JDK 1.3. CFMX

6.1 uses JDK 1.4.2; for encoding support, see http://java.sun.com/j2se/1.4.2/docs/guide/intl/

encoding.doc.html.

For a complete list of media types used on the Internet, see www.iana.org/assignments/

media-types/.

Example

SetEncoding charset parameter and other

<cfcontent type = "text/html"

file = "C:\CFusionMX7\wwwroot\cfdocs\dochome.htm"

deleteFile = "no">

<p>This example shows how the Reset attribute changes output for text.</p> <p>reset = "Yes": 123 <BR> <cfcontent type = "text/html" reset = "Yes">456</p> <p>This example shows how the Reset attribute changes output for text.</p> <p>reset = "No": 123 <BR> <cfcontent type = "text/html" reset = "No">456</p>

cfcontent 95

<cfheader name="Content-Disposition" value="inline; filename=temp.doc"> <cfcontent type="application/msword" file="c:\temp\Cable.doc"

deletefile="yes">

<table border="2"> <tr><td>Month</td><td>Quantity</td><td>$ Sales</td></tr> <tr><td>January</td><td>80</td><td >$245</td></tr> <tr><td>February</td><td>100</td><td>$699</td></tr> <tr><td>March</td><td>230</td><td >$2036</td></tr> <tr><td>Total</td><td>=Sum(B2..B4)</td><td>=Sum(C2..C4)</td></tr> </table>

96 Chapter 2: ColdFusion Tags

cfcookie

Description

Defines web browser cookie variables, including expiration and security options.

Category

Forms tags, Variable manipulation tags

Syntax

<cfcookie

name = "cookie_name" value = "text" expires = "period" secure = "yes" or "no" path = "url"

domain = ".domain">

See also

cfdump, cfparam, cfregistry, cfsavecontent, cfschedule, cfset

History

ColdFusion MX 6.1:

• Changed the expires attribute: it now accepts a date time object.

• Cookie names can include all ASCII characters except commas, semicolons, or whitespace

characters.

Attributes

Attribute Req/Opt Default Description

name Required Name of cookie variable. ColdFusion converts cookie names to

all-uppercase. Cookie names set using this tag can include any printable ASCII characters except commas, semicolons or white space characters.

value Optional Value to assign to cookie variable. Must be a string or variable that

can be stored as a string.

expires Optional Expiration of cookie variable.

• The default: the cookie expires when the user closes the browser, that is, the cookie is "session only".

• A date or date/time object (for example, 10/09/97)

• A number of days (for example, 10, or 100)

• now: deletes cookie from client cookie.txt file (but does not

delete the corresponding variable the Cookie scope of the active page).

• never: The cookie expires in 30 years from the time it was created (effectively never in web years).

cfcookie 97

Attribute Req/Opt Default Description

secure Optional If browser does not support Secure Sockets Layer (SSL)

security, the cookie is not sent. To use the cookie, the page must be accessed using the https protocol.

• yes: Variable must be transmitted securely.

• no

path Optional URL, within a domain, to which the cookie applies; typically a

directory. Only pages in this path can use the cookie. By default, all pages on the server that set the cookie can access the cookie.

path = "/services/login" To specify multiple URLs, use multiple If you specify path, you must also specify

cfcookie tags.

domain.

domain Required if

path

attribute is specified. Optional otherwise

Usage

Domain in which cookie is valid and to which cookie content can

be sent from the user’s system. By default, the cookie is only available to the server that set it. Use this attribute to make the cookie available to other servers.

Must start with a period. If the value is a subdomain, the valid domain is all domain names that end with this string. This attribute sets the available subdomains on the site upon which the cookie can be used.

For a

domain value that ends in a country code, the specification

must contain at least three periods; for example,

".mongo.state.us". For top-level domains, two periods are

required; for example, You cannot use an IP address as a domain.

".mgm.com".

If this tag specifies that a cookie is to be saved beyond the current browser session, the client browser writes or updates the cookie in its local cookies file. Until the browser is closed, the cookie resides in browser memory. If the

expires attribute is not specified, the cookie is not

written to the browser cookies file.

If you use this tag after the

cfflush tag on a page, ColdFusion does not send the cookie to the

browser; however, the value you set is available to ColdFusion in the Cookie scope during the browser session.

Note: You can also create a cookie that expires when the current browser session expires by using the cfset tag or a CFScript assignment statement to set a variable in the Cookie scope, as in

Cookie.mycookie="sugar">. To get a cookie’s value, refer to the cookie name in the Cookie scope, as

<cfif Cookie.mycookie is "oatmeal">.

You can use dots in cookie names, as the following examples show:

To access cookies, including cookies that you set and all cookies that are sent by the client, use the Cookie scope. For example, to display the value of the person.name cookie set in the preceding code, use the following line:

<cfoutput>#cookie.person.name#</cfoutput>

98 Chapter 2: ColdFusion Tags

<cfset

Example

<cfquery name = "GetAolUser" dataSource = "cfdocexamples">

SELECT EMail, FromUser, Subject, Posted

FROM Comments </cfquery> <html> <body> <h3>cfcookie Example</h3>

<!--- If the URL variable delcookie exists, set cookie expiration date

to NOW ---> <cfif IsDefined("url.delcookie") is True>

<cfcookie name = "TimeVisited"

value = "#Now()#"

expires = "NOW"> <cfelse>

<!--- Otherwise, loop through list of visitors; stop when you match

the string aol.com in a visitor’s e-mail address. ---> <cfloop query = "GetAolUser">

</cfif> </cfloop>

</cfif> </cfif>  <cfif IsDefined("Cookie.LastAOLVisitor") is "True">

<p>The last AOL visitor to view this site was

<cfoutput>#Cookie.LastAOLVisitor#</cfoutput>, on

<cfoutput>#DateFormat(COOKIE.TimeVisited)#</cfoutput>  <p><a href = "cfcookie.cfm?delcookie = yes">Hide my tracks</A> <cfelse>

<p>No AOL Visitors have viewed the site lately. </cfif>

cfcookie 99

cfdefaultcase

Description

Used only inside the cfswitch tag body. Contains code to execute when the expression specified in the

Category

Flow-control tags

Syntax

See also

cfswitch tag does not match a of the value specified by a cfcase tag.

cfcase

, cfswitch; “cfswitch, cfcase, and cfdefaultcase” in Chapter 2, “Elements of CFML,” in

ColdFusion MX Developer’s Guide

History

ColdFusion MX: Changed placement requirements: this tag does not have to follow all cfcase tags in the

Usage

cfswitch tag body.

The contents of the cfdefaultcase tag body is executes if the expression attribute of the

cfswitch tag does not match any of the values specified by the cfcase tags in the cfswitch tag

body. The contents of the

cfdefaultcase tag body can include HTML and text, and CFML

tags, functions, variables, and expressions.

You can specify only one

cfdefaultcase tag at any position within a cfswitch statement; it is not required to be the last

cfdefaultcase tag within a cfswitch tag. You can put the

item, but it is good programming practice to put it last.

Example

<!--- The following example displays a grade based on a 1-10 score.

Several of the cfcase tags match more than one score.

For simplicity, the example sets the score to 7. ---> <cfset score="7"> <cfswitch expression="#score#">

</cfcase> <cfcase value="9;8" delimiters=";">

</cfcase> <cfcase value="7;6" delimiters=";">

</cfcase> <cfcase value="5;4;" delimiters=";">

</cfcase> <cfdefaultcase>

100 Chapter 2: ColdFusion Tags

MACROMEDIA COLFUSION MX 7-CFML, COLFUSION MX 7 Reference

Specifications and Main Features

Frequently Asked Questions

User Manual