Macromedia COLFUSION MX 7-CFML REFERENCE User Manual

8.5 Mb
Loading...

COLDFUSION®MX7

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

3

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

4Contents

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

Describes system installation and basic configuration for Windows, Solaris,

ColdFusion MX

Linux, and HP-UX.

Configuring and

Part I describes how to manage the ColdFusion environment, including

Administering

connecting to your data sources and configuring security for your

ColdFusion MX

applications. Part II describes Verity search tools and utilities that you can

 

use for configuring the Verity K2 Server search engine, as well as creating,

 

managing, and troubleshooting Verity collections.

ColdFusion MX

Describes how to develop your dynamic web applications, including

Developer’s Guide

retrieving and updating your data, and using structures and forms.

Getting Started

Contains an overview of ColdFusion features and application development

Building

procedures. Includes a tutorial that guides you through the process of

ColdFusion MX

developing an example ColdFusion application.

Applications

 

CFML Reference

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

 

tags, functions, and variables.

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

5

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.

6Introduction:

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.

7

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_

CHAR_LENGTH

 

 

 

LENGTH

 

CHECK

CLOSE

COALESCE

COLLATE

COLLATION

COLUMN

COMMIT

CONNECT

CONNECTION

CONSTRAINT

CONSTRAINTS

CONTINUE

CONVERT

CORRESPONDING COUNT

CREATE

CROSS

CURRENT

CURRENT_DATE CURRENT_TIME

CURRENT_

CURRENT_

CURSOR

DATE

DAY

TIMESTAMP

USER

 

 

 

DEALLOCATE

DEC

DECIMAL

DECLARE

DEFAULT

DEFERRABLE

DEFERRED

DELETE

DESC

DESCRIBE

DESCRIPTOR

DIAGNOSTICS

DISCONNECT

DISTINCT

DOMAIN

DOUBLE

DROP

ELSE

END

END-EXEC

ESCAPE

EXCEPT

EXCEPTION

EXEC

EXECUTE

EXISTS

EXTERNAL

EXTRACT

FALSE

FETCH

FIRST

FLOAT

FOR

FOREIGN

FOUND

8Chapter 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_

TIMEZONE_

TO

 

 

HOUR

MINUTE

 

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

 

 

 

 

 

 

 

 

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 <CFSET 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:

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:

<cfset Caller.variable_name = "value">

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 name attribute:

queryname.CurrentRow queryname.RecordCount queryname.ColumnList

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 cferror generates an error page, the following error variables are available if type="request" or "exception".

Error.Diagnostics

Error.MailTo

Error.DateTime

Error.Browser

Error.GeneratedContent

Error.RemoteAddress

Error.HTTPReferer

Error.Template

Error.QueryString

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 for Error, if type = "Exception"; for example,

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

ColdFusion tag-specific variables

13

CFFILE ACTION=Upload variables

File variables are read-only. Use the CFFILE prefix to reference file variables; for example, 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

CFFTP error variables

When you use the cfftp stoponerror attribute, these variables are populated:

CFFTP.Succeeded

CFFTP.ErrorCode

CFFTP.ErrorText

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 action attribute. When you specify any of the following actions, cfftp returns a value:

GetCurrentDir

GetCurrentURL

ExistsDir

ExistsFile

Exists

CFFTP query object columns

When you use the cfftp tag with the listdir action, cfftp returns a query object, where queryname is the name attribute value, and row is the row number of each file or directory entry:

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

A 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[http_hd_key]

CFHTTP.StatusCode

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 attachmentpath, where queryname is the name attribute value:

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

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 name attribute value:

queryname.Entry queryname.Type queryname.Value

CFSEARCH variables

A 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

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:

<cfif CGI.varname IS NOT ""> CGI variable exists

<cfelse>

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 server supports user authentication, and the script is protected, the username the user has authenticated as. (Also available as AUTH_USER.)

If the HTTP server supports RFC 931 identification, this variable is set to the remote username retrieved from the server. Use this variable for logging only.

CONTENT_TYPE

For queries that have attached information, such as HTTP POST

 

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. It can be used to

 

take advantage of browser-side caching.

 

 

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

Defines an application name; activates client

 

tags

variables; specifies client variable storage

 

 

mechanism

cfargument

Extensibility tags

Creates a parameter definition within a

 

 

component definition; defines a function

 

 

argument

cfassociate

Application framework

Enables subtag data to be saved with a base tag

 

tags

 

cfbreak

Flow-control tags

Breaks out of a CFML looping construct

cfcache

Page processing tags

Caches ColdFusion pages

21

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,

Defines content type and filename of a file to be

 

Page processing tags

downloaded by current page

cfcookie

Variable manipulation

Defines and sets cookie variables, including

 

tags

expiration and security options

cfdefaultcase

Flow-control tags

Receives control if there is no matching cfcase

 

 

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,

Displays custom HTML error pages when errors

 

Application framework

occur

 

tags

 

cfexecute

Flow-control tags,

Executes developer-specified process on server

 

Extensibility tags

computer

cfexit

Flow-control tags

Aborts processing of executing CFML tag

cffile

File management tags

Performs typical file-handling tasks from within

 

 

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

Forms tags

Defines a grid row; used with cfgrid

cfgridupdate

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

 

 

POST operation; used with cfhttp

cfif

Flow-control tags

Creates IF-THEN-ELSE constructs

cfimport

Application framework

Imports JSP tag libraries into a CFML page

 

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

 

 

box, text entry box); used in cfform

cfinsert

Database manipulation

Inserts records in a data source

 

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

Ensures data integrity and synchronizes

 

tags

execution of CFML code

cflog

Data output tags,

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

Invokes a custom tag for use in a ColdFusion

 

tags

page

cfNTauthenticate

Security tags

Authenticates user information against an NT

 

 

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

Holds parameter information for stored

 

tags

procedure

cfprocresult

Database manipulation

Result set name that ColdFusion tags use to

 

tags

access result set of a stored procedure

cfproperty

Extensibility tags

Defines components

cfquery

Database manipulation

Passes SQL statements to a database

 

tags

 

cfqueryparam

Database manipulation

Checks data type of a query parameter

 

tags

 

24 Chapter 2: ColdFusion Tags

CFML tag

Category

Description

 

 

 

cfregistry

Other tags,

Reads, writes, and deletes keys and values in a

 

Variable manipulation

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

Saves generated content inside tag body in a

 

tags

variable

cfschedule

Variable manipulation

Schedules page execution; optionally, produces

 

tags

static pages

cfscript

Application framework

Encloses a set of cfscript statements

 

tags

 

cfsearch

Extensibility tags

Executes searches against data indexed in Verity

 

 

collections, using cfindex

cfselect

Forms tags

Creates a drop-down list box form element; used

 

 

in cfform tag

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

Database manipulation

Holds database connection information;

 

tags

identifies a stored procedure to execute

cfswitch

Flow-control tags

Evaluates passed expression; passes control to

 

 

matching cfcase tag

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,

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

Groups cfquery operations into one transaction;

 

tags

performs rollback processing

Tag summary 25

CFML tag

Category

Description

 

 

 

cftree

Forms tags

Creates tree control element; used in cfform

cftreeitem

Forms tags

Populates a tree control element in a form; used

 

 

with cftree

cftry

Exception handling tags, Catches exceptions in ColdFusion pages

 

Flow-control tags

 

cfupdate

Database manipulation

Updates rows in a database data source

 

tags

 

cfwddx

Extensibility tags

Serializes and de-serializes CFML data

 

 

structures to XML-based WDDX format

cfxml

Extensibility tags

Creates an XML document object

 

 

 

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

ColdFusion MX

 

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 language

 

 

attribute

 

 

 

 

 

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,

ColdFusion MX 7

 

porttypename, wsdlfile, and

 

 

bindingname attributes

 

 

 

 

 

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

ColdFusion MX 7

 

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"

 

 

 

 

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

 

 

 

 

currency value of type attribute

ColdFusion MX 7

30 Chapter 2: ColdFusion Tags

Tag

Attribute or value

Added in this ColdFusion

 

 

release

 

 

 

cfhttp

result attribute

ColdFusion MX 7

 

 

 

 

HEAD, PUT, DELETE, OPTIONS, and

ColdFusion MX 6.1

 

TRACE values of method attribute

 

 

 

 

 

multipart, getasbinary, proxyUser,

 

 

proxyPassword attributes

 

 

 

 

 

charset,firstrowasheaders

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

ColdFusion MX 7

 

categorytree attributes for update

 

 

and refresh actions

 

 

 

 

 

status attribute for Update,

 

 

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,

ColdFusion MX 6.1

 

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

 

 

 

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,

ColdFusion MX 7

 

query, overwrite attributes

 

 

 

 

cfreportparam

All

ColdFusion MX 7

32 Chapter 2: ColdFusion Tags

Tag

Attribute or value

Added in this ColdFusion

 

 

release

 

 

 

cfsearch

category, categoryTree, status,

ColdFusion MX 7

 

suggestions, contextPassages,

 

 

contextBytes,

 

 

contextHighlightBegin,

 

 

contextHighlightEnd,

 

 

previousCriteria attributes

 

 

 

 

 

natural, internet, and

 

 

internet_basic values of type

 

 

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

cachedirectory, timeout attributes

ColdFusion MX

 

 

 

cfcollection

map and repair options of the

ColdFusion MX 7

 

action attribute

 

 

 

 

cferror

monitor option of the exception

ColdFusion MX

 

attribute

 

 

 

 

cffile

system value for attributes

ColdFusion MX

 

attribute

 

 

 

 

 

temporary value for attributes

ColdFusion MX

 

attribute

 

 

 

 

cfform

passthrough attribute

ColdFusion MX 7

 

 

 

 

enableCAB attribute

ColdFusion MX

 

 

 

cfftp

agentname attribute

ColdFusion MX

 

 

 

cfgraph

All

ColdFusion MX

 

 

 

cfgraphdata

All

ColdFusion MX

 

 

 

cfgridupdate

connectString, dbName, dbServer,

ColdFusion MX

 

dbType, provider, providerDSN

 

 

attributes

 

 

 

 

cfinput

passthrough attribute

ColdFusion MX 7

 

 

 

cfinsert

connectString, dbName, dbServer,

ColdFusion MX

 

dbType, provider, providerDSN

 

 

attributes

 

 

 

 

cfldap

filterFile attribute

ColdFusion MX

 

 

 

cflog

date, thread, time attributes

ColdFusion MX

 

 

 

cfquery

connectString, dbName, dbServer,

ColdFusion MX

 

provider, providerDSN, sql

 

 

attributes

 

 

 

 

 

The following dbType attribute

ColdFusion MX

 

values:

(The value query is valid.)

 

dynamic, ODBC, Oracle73, Oracle80,

 

 

Sybase11, OLEDB, DB2

 

 

 

 

cfregistry

All, on UNIX only

ColdFusion MX

 

 

 

cfsearch

external, language attributes

ColdFusion MX

 

 

 

cfselect

passthrough attribute

ColdFusion MX 7

34 Chapter 2: ColdFusion Tags

Tag

Attribute or value

Deprecated as of this

 

 

ColdFusion release

 

 

 

cfservlet

All

ColdFusion MX

 

 

 

cfservletparam

All

ColdFusion MX

 

 

 

cfslider

img, imgStyle, grooveColor,

ColdFusion MX

 

refreshLabel, tickmarkimages,

 

 

tickmarklabels, tickmarkmajor,

 

 

tickmarkminor attributes

 

 

 

 

cfstoredproc

connectString, dbName, dbServer,

ColdFusion MX

 

dbtype, provider, providerDSN

 

 

attributes

 

 

 

 

cftextinput

All

ColdFusion MX 7

 

 

 

cfupdate

connectString, dbName, dbServer,

ColdFusion MX

 

dbtype, provider, providerDSN

 

 

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

All

ColdFusion MX

 

 

 

cfchart

rotated attribute

ColdFusion MX 7

 

 

 

cffile

attributes attribute value archive

ColdFusion MX

 

 

 

cfimpersonate

All

ColdFusion MX

 

 

 

cfindex

action attribute value optimize

ColdFusion MX

 

 

 

 

external attribute

 

 

 

 

cfinternaladminsecurity

All

ColdFusion MX

 

 

This tag did not appear in CFML

 

 

Reference.

 

 

 

cfldap

fileterConfig attribute

ColdFusion MX

 

 

 

cfnewinternaladminsecurity

All

ColdFusion MX

 

 

This tag did not appear in CFML

 

 

Reference.

 

 

 

cfsetting

catchExceptionsByPattern

ColdFusion MX

 

attribute

 

 

 

 

Tag changes since ColdFusion 5 35

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 cferror tag redirects output to a specified page.

If this tag does not contain a showError attribute value, processing stops when the tag is reached and ColdFusion returns the page contents up to the line that contains the cfabort tag.

When you use this tag with the showError attribute, but do not define an error page using cferror, page processing stops when the cfabort tag is reached. The message in showError displays to the client.

When you use this tag with the showError attribute and an error page using cferror, ColdFusion redirects output to the error page specified in the 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> <!--- first, set a variable --->

<cfset myVariable = 3>

<!--- now, perform a loop that increments this value ---> <cfloop from = "1" to = "4" index = "Counter">

<cfset myVariable = myVariable + 1> </cfloop>

<cfoutput>

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>

<!--- Reset the variable and show the use of cfabort. ---> <cfset myVariable = 3>

<!--- now, perform a loop that increments this value ---> <cfloop from = "1" to = "4" index = "Counter">

<!--- on the second time through the loop, cfabort ---> <cfif Counter is 2>

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

<cferror type="request" template="request_err.cfm">

<cfabort showerror="CFABORT has been called for no good reason">

<!--- Processing is stopped, and subsequent operations are not carried out.---> <cfelse>

<cfset myVariable = myVariable + 1> </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

Text to display if a page that contains a Java applet-based

 

 

Description

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>

param_n

Optional

 

Registered parameter for applet. Specify only to override

 

 

 

values for applet in ColdFusion Administrator.

 

 

 

 

 

Usage

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.

<cfform action = "index.cfm">

<cfapplet appletsource = "copytext" name = "copytext"> </cfform>

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

 

Name of application. Up to 64 characters.

 

Description

 

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

Lifespan of session variables.

 

 

Variables page

CreateTimeSpan function and values in days,

 

 

of ColdFusion

hours, minutes, and seconds, separated by

 

 

Administrator

commas.

applicationTimeout

Optional

Specified in

Lifespan of application variables.

 

 

Variables page

CreateTimeSpan function and values in days,

 

 

of ColdFusion

hours, minutes, and seconds, separated by

 

 

Administrator

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

Specifies whether to protect variables from

 

 

ColdFusion MX

cross-site scripting attacks

 

 

Administrator

none: do not protect variables

 

 

Enable Global

all: protect Form, URL, CGI, and Cookie

 

 

Script

 

variables

 

 

Protection

comma-delimited list of ColdFusion scopes:

 

 

 

 

setting

Protect variables in the specified scopes.

 

 

 

 

For more information, see Usage.

 

 

 

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 clientStorage = "cookie" or a data source name; you cannot specify "registry".

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 scriptProtect attribute to override the Administrator setting. You can also use the Application.cfc initialization code to set the protection value.

42 Chapter 2: ColdFusion Tags

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 cf_root/lib/ neo-security.xml file in the server configuration, or the cf_root/WEB-INF/cfusion/lib/neo- 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 cflock on page 270.

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>

<cfapplication name = "ETurtle"

sessionTimeout = #CreateTimeSpan(0, 0, 0, 60)# sessionManagement = "Yes">

<!--- Initialize session and application variables used by E-Turtleneck. ---> <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 scope = "Application" timeout = "30" type = "Exclusive"> <cfset application.number = application.number + session.numPurchased> </cflock>

</cfif>

<cfoutput>

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

</cfoutput>

<!--- End of Application.cfm --->

44 Chapter 2: ColdFusion Tags

cfargument

Description

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

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

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 default attribute.

 

 

 

true or "yes"

 

 

 

false or "no"

default

Optional

 

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

displayname

Optional

name

Meaningful only for CFC method parameters. A value to be

 

 

attribute

displayed when using introspection to show information about

 

 

value

the CFC.

hint

Optional

 

Meaningful only for CFC method parameters. Text to be

 

 

 

displayed when using introspection to show information about

the CFC. The hint attribute value follows the displayname attribute value in the parameter description line. This attribute can be useful for describing the purpose of the parameter.

Usage

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

<cffunction name="getDescription"> <!--- Identify argument --->

<cfargument name="Course_Number" type="numeric" required="true">

<!--- Use the argument to get a course description from the database ---> <cfquery name="Description" datasource="cfdocexamples">

SELECT Descript FROM Courses

WHERE Number = '#Course_Number#' </cfquery>

<!--- Specify the variable that the function returns ---> <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 AssocAttribs. To segregate subtag attributes (in a base tag that can have multiple subtags), specify a structure name, in the 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

<!--- Find the context. --->

<cfif thisTag.executionMode is "start"> <!--- Associate attributes. ---> <cfassociate baseTag = "CF_TAGBASE">

<!--- Define defaults for attributes. --->

<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

<cfbreak>

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

<!--- This shows the use of cfbreak to exit a loop when a condition is met.---> <!--- Select courses; use cfloop to find a condition; then break the loop. ---> <!--- Check that number is numeric. --->

<cfif IsDefined("form.course_number")> <cfif Not IsNumeric(form.course_number)>

<cfabort>

</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"> <select name="courseNum">

<cfoutput query="GetCourses">

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

<cfif IsDefined ("form.courseNum") IS "True">

<!--- Loop through query until value found, then use CFBREAK to exit query.---> <cfloop query="GetCourses">

<cfif GetCourses.course_number IS form.courseNum> <cfoutput>

<h4>Your Desired Course was found:</h4> <pre>#course_number# #descript#</pre>

</cfoutput>

<cfbreak>

cfbreak 49

<cfelse>

<br> Searching...

</cfif>

</cfloop>

</cfif>

50 Chapter 2: ColdFusion Tags

+ 1058 hidden pages