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
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
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.
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.
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.
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_
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
TO
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:
<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
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
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 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
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
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:
<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 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
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,
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
in
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
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
All ColdFusion MX
img
, imgStyle, grooveColor,
refreshLabel, tickmarkimages, tickmarklabels, tickmarkmajor, tickmarkminor attributes
connectString dbtype, provider, providerDSN
, dbName, dbServer,
ColdFusion MX
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> <!--- 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
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.
<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
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.
<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
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. --->
<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 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
<!--- 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>
</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
<!--- This example produces as many cached files as there are URL parameter permutations. You can see that the page is cached when the timestamp doesn't change.--->
<cfcache timespan="#createTimeSpan(0,0,10,0)#"> <body>
<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 four­day 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.
<!--- Set initial selected and blocked-out dates.---> <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
<cfparam name="Form.enddate" default="#dateformat(now()-1, 'mm/dd/yyyy')#"> <cfparam name="Form.selectdate" default="#dateformat(now(), 'mm/dd/yyyy')#">
<!--- If the form has been submitted, display the 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#" >
<cfinput type="Submit" name="submitit" value="Save" width="100">
</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":
<cfcase value="red,blue,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":
<cfcase value="cargo, live;cargo, liquid-cargo, solid" delimiters=";-">
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
<cfset score="7"> <cfswitch expression="#score#">
<cfcase value="10">
<cfset grade="A"> </cfcase> <cfcase value="9;8" delimiters=";">
<cfset grade="B"> </cfcase> <cfcase value="7;6" delimiters=";">
<cfset grade="C"> </cfcase> <cfcase value="5;4;" delimiters=";">
<cfset grade="D"> </cfcase> <cfdefaultcase>
<cfset grade="F"> </cfdefaultcase>
</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
<cfcatch type = "exceptiontype">
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.
If
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:
<cfthrow type = "MyApp.BusinessRuleException.InvalidAccount">
If you have the following cfcatch tag, it will handle the exception:
<cfcatch type = "MyApp.BusinessRuleException.InvalidAccount">
Otherwise, if you have the following cfcatch tag, it will handle the exception:
cfcatch tag in the cftry block with
<cfcatch type = "MyApp.BusinessRuleException">
Finally, if you have the following cfcatch tag, it will handle the exception:
<cfcatch type = "MyApp">
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
<!--- cfcatch example, using TagContext to display the tag stack. ---> <h3>cftry Example</h3> <!--- Open a cftry block. ---> <cftry>
<!--- Note misspelled tablename "employees" as "employeeas". ---> <cfquery name = "TestQuery" dataSource = "cfdocexamples">
SELECT *
FROM EMPLOYEEAS </cfquery> <!--- Other processing goes here. ---> <!--- Specify the type of error for which we search. ---> <cfcatch type = "Database">
<!--- the message to display. --->
<h3>You've Thrown a Database <b>Error</b></h3>
<cfoutput>
<!--- The diagnostic message from ColdFusion MX. ---> <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
<!--- This syntax uses an XML file or string to specify the chart style. --->
<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
<!---The following example analyzes the salary data in the cfdocexamples database and generates a bar chart showing average salary by department. The body of the cfchartseries tag includes one cfchartdata tag to include data that is not available from the query. --->
<!--- Get the raw data from the database. ---> <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>
<!--- Use a query of queries to generate a new query with ---> <!--- statistical data for each department. ---> <!--- AVG and SUM calculate statistics. ---> <!--- GROUP BY generates results for each department. ---> <cfquery dbtype = "query" name = "DataTable"> SELECT Dept_Name, AVG(Salary) AS avgSal, SUM(Salary) AS sumSal FROM GetSalaries GROUP BY Dept_Name </cfquery>
<!--- Reformat the generated numbers to show only thousands. ---> <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> <!--- Bar graph, from Query of Queries ---> <cfchart format="flash" xaxistitle="Department" yaxistitle="Salary Average">
<cfchartseries type="bar" query="DataTable" itemcolumn="Dept_Name" valuecolumn="avgSal">
<cfchartdata item="Facilities" value="35000">
</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
<!--- The following example analyzes the salary data in the cfdocexamples database and generates a bar chart showing average salary by department. The body of the cfchartseries tag loops over a cfchartdata tag to include data available from the query. --->
<!--- Get the raw data from the database. ---> <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>
<!--- Use a query of queries to generate a new query with ---> <!--- statistical data for each department. ---> <!--- AVG and SUM calculate statistics. ---> <!--- GROUP BY generates results for each department. ---> <cfquery dbtype = "query" name = "DataTable"> SELECT Dept_Name, AVG(Salary) AS avgSal, SUM(Salary) AS sumSal FROM GetSalaries GROUP BY Dept_Name
74 Chapter 2: ColdFusion Tags
</cfquery>
<!--- Reformat the generated numbers to show only thousands. ---> <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>
<h1>Employee Salary Analysis</h1> <!--- Bar graph, from Query of Queries. ---> <cfchart format="flash" xaxistitle="Department" yaxistitle="Salary Average">
<cfchartseries type="bar" itemcolumn="Dept_Name" valuecolumn="avgSal">
<cfloop query="DataTable"> <cfchartdata item="#DataTable.Dept_Name#" value="#DataTable.avgSal#"> </cfloop>
</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
<!--- The following example analyzes the salary data in the cfdocexamples database and generates a bar chart showing average salary by department. --->
<!--- Get the raw data from the database. ---> <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>
78 Chapter 2: ColdFusion Tags
<!--- Use a query of queries to generate a new query with ---> <!--- statistical data for each department. ---> <!--- AVG and SUM calculate statistics. ---> <!--- GROUP BY generates results for each department. ---> <cfquery dbtype = "query" name = "DataTable"> SELECT Dept_Name, AVG(Salary) AS avgSal, SUM(Salary) AS sumSal FROM GetSalaries GROUP BY Dept_Name </cfquery>
<!--- Reformat the generated numbers to show only thousands. ---> <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>
<h1>Employee Salary Analysis</h1> <!--- Bar graph, from Query of Queries ---> <cfchart format="flash" xaxistitle="Department" yaxistitle="Salary Average">
<cfchartseries type="bar" query="DataTable" itemcolumn="Dept_Name" valuecolumn="avgSal" /> </cfchart>
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. ---> <!--- query selects information from cfdocexamples data source. ---> <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
categories
Required Required Required Required Required Required
Required Required
Optional Optional
Required Required
The following examples illustrate the structures returned by the
CATEGORIES
blue 10
green 3
magenta 3
purple 2
categorylist action:
CATEGORYTREES
a/ 10
a/b 10
a/b/c 10
a/b/c/subdir 3
list action returns the following information in a result set that contains one row per
The collection:
Column Contents
CATEGORIES yes: the collection has category support enabled.
no: the collection does not have category support enabled.
CHARSET The character set of the collection.
CREATED The date and time that the collection was created.
DOCCOUNT The number of documents in this collection.
EXTERNAL yes: the collection is external.
no: the collection is not external.
Not Found: the collection is registered but is not available in the defined path .
LANGUAGE The locale setting of the collection.
This information is not available for K2Server collections.
84 Chapter 2: ColdFusion Tags
Column Contents
LASTMODIFIED The date and time that the collection was last changed.
MAPPED Obsolete
NAME The name of the collection.
ONLINE Obsolete
PATH Absolute path to the collection.
REGISTERED Obsolete
SIZE The size of the collection, expressed in kilobytes.
The ColdFusion MX Administrator Verity > Collections page displays the information that is returned when you use the
list attribute.
If the Verity Server is not running when the
list action is executed, the tag throws an error.
To determine whether a collection exists, use code, such as the following, to execute a query of queries:
<cfcollection action="list" name="myCollections" >
<cfquery name="qoq" dbtype="query">
select * from myCollections where myCollections.name = 'myCollectionName'
</cfquery>
<cfif qoq.recordcount GT 0>
<!--- Collection exists ---> <cfdump var = #qoq#>
</cfif>
To get a result set with values for all the collections that are registered with the Verity server, use code such as the following:
<cfcollection action="list" name="myCollections"> <cfoutput query="myCollections">
#name#<br>
</cfoutput>
To add content to a collection, use cfindex. To search a collection, use cfsearch.
The language attribute of this tag supports the following options:
Asian Language Pack
Japanese Korean Chinese Traditional Chinese
Multilanguage Language Pack
Unicode
Western European Language Pack
Bokmal Finnish Italian Spanish
Danish French Nynorsk Swedish
Dutch German Portuguese
cfcollection 85
Eastern European/Middle Eastern Language Pack
Arabic Greek Polish Turkish
Bulgarian Hebrew Russian
Czech Hungarian Russian2
The default location of Verity collections is as follows:
Server configuration:
Windows: C:\CFusionMX7\verity\collections
UNIX system: /opt/coldfusionmx7/verity/collections
J2EE configuration: webapp_root/WEB-INF/cfusion/verity/collections
Example
<!------------------------------------------------------------------------­(coll_actn.cfm) Check for server platform and use its default Verity Collection directory. If you did not install ColdFusion MX in the default directory, or if you use the J2EE configuration, or if your webroot is not C:\CFusionMX7\wwwroot, you might need to change the path in this example. For example, for JRun4 the path might be C:\JRun4\Verity\Collections\
---------------------------------------------------------------------------> <cfif Find("Windows", Server.OS.Name)>
<cfset collPath = "C:\JRun4\Verity\Collections\">
<cfelse>
<cfset collpath = "/opt/coldfusionmx7/verity/collections/">
</cfif>
<!-------------------------------------------------------------------------­Process form input and do the requested cfcollection operation.
--------------------------------------------------------------------------->
<cfif IsDefined("form.CollectionName") AND IsDefined("form.CollectionAction")>
<cfif form.CollectionName is not "">
<cfswitch expression="#FORM.CollectionAction#"> <cfcase value="Create"> <cfcollection action="CREATE" collection="#FORM.CollectionName#"
path="#collPath#" categories="yes">
<h3>Collection created.<br>
Use CFINDEX to populate it.</h3> </cfcase> <cfcase value="Repair"> <cfcollection action="REPAIR" collection="#FORM.CollectionName#"> <h3>Collection repaired.</h3> </cfcase> <cfcase value="Optimize"> <cfcollection action="OPTIMIZE" collection="#FORM.CollectionName#"> <h3>Collection optimized.</h3> </cfcase> <cfcase value="Delete"> <cfcollection action="DELETE" collection="#FORM.CollectionName#"> <h3>Collection deleted.</h3>
86 Chapter 2: ColdFusion Tags
</cfcase> </cfswitch>
<cfelse> <h3>Please enter a name for your collection</h3> </cfif>
</cfif>
<!-------------------------------------------------------------------­(coll_form.cfm) Form to specify the collection name and action
coll_form.cfm
--------------------------------------------------------------------->
<form action="coll_actn.cfm" method="POST" > <select name="CollectionAction">
<option value="Create">Create this collection <option value="Optimize">Optimize this collection <option value="Repair">Repair this collection <option value="Delete">Delete this collection
</select>
<p><strong>Collection on which to act</strong><br> Use the default value or enter your own Collection name<br> <input type="Text" name="CollectionName" value="My_coll"></p>
<input type="Submit" name="" value="alter or create my collection"> </form>
cfcollection 87
cfcomponent
Description
Creates and defines a component object; encloses functionality that you build in CFML and enclose within methods. Code within the body of this tag, other than
cffunction tags. This tag contains one or more cffunction tags that define
cffunction tags, is executed when the
component is instantiated.
A component file has the extension CFC and is stored in any directory of an application.
A component method is invoked in the following ways:
Within the cfinvoke tag in a ColdFusion page
Within a URL that calls a CFC file and passes a method name as a URL parameter
Within the cfscript tag
As a web service
From Flash code
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>
<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".
style="document".
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
<cfcomponent>
<cffunction name="getEmp">
<cfquery name="empQuery" datasource="cfdocexamples" > SELECT FIRSTNAME, LASTNAME, EMAIL FROM tblEmployees </cfquery> <cfreturn empQuery>
</cffunction>
<cffunction name="getDept">
<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:
<cfcontent type="text/html; charset=ISO-8859-1">
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:
<cfcontent type="text/html; charset=EUC-JP">
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:
<cfheader name="Content-Disposition" value="inline; filename=name.ext">
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
<!--- CFCONTENT Example 1 This example shows the use of cfcontent to return the contents of the CF Documentation page dynamically to the browser. You might need to change the path and/or drive letter depending on how ColdFusion is installed on your system. Notice that the graphics do not display and the hyperlinks do not work, because the html page uses relative filename references. The root of the reference is the ColdFusion page, not the location of the html page. --->
SetEncoding charset parameter and other
<cfcontent type = "text/html"
file = "C:\CFusionMX7\wwwroot\cfdocs\dochome.htm"
deleteFile = "no">
<!--- CFCONTENT EXAMPLE 2 This example shows how the Reset attribute changes text output. Notice how the first text section ("This example shows how the Reset attribute changes output for text reset = "Yes":123) does NOT print out to the screen. --->
<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 EXAMPLE 3 This example triggers a download of an Excel file. The user will be prompted with an option to save the file or open it in the browser. --->
<cfheader name="Content-Disposition" value="inline; filename=acmesales03.xls">
<cfcontent type="application/vnd.ms-excel" file="c:\temp\acmesales03.xls">
cfcontent 95
<!--- CFCONTENT EXAMPLE 4 This example triggers a download of a Word document then deletes the original from the "temp" directory. The user will be prompted with an option to save the file or open it in the browser. --->
<cfheader name="Content-Disposition" value="inline; filename=temp.doc"> <cfcontent type="application/msword" file="c:\temp\Cable.doc"
deletefile="yes">
<!--- CFCONTENT EXAMPLE 5 This example causes the browser to treat the HTML table as Excel data. Excel interprets the table format. Because Excel can include executable code, the browser prompts the user whether to save the file or open it in a browser. --->
<cfheader name="Content-Disposition" value="inline; filename=acmesalesQ1.xls"> <cfcontent type="application/vnd.msexcel">
<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
in
<cfif Cookie.mycookie is "oatmeal">.
You can use dots in cookie names, as the following examples show:
<cfcookie name="person.name" value="wilson, john"> <cfset cookie.person.lastname="Santiago">
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
<!--- This example shows how to set/delete a cfcookie variable. ---> <!--- Select users who have entered comments into a sample database. ---> <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 FindNoCase("aol.com", Email, 1) is not 0>
<cfcookie name = "LastAOLVisitor" value = "#Email#" expires = "NOW" >
</cfif> </cfloop> <!--- If the timeVisited cookie is not set, set a value. --->
<cfif IsDefined("Cookie.TimeVisited") is False>
<cfcookie name = "TimeVisited" value = "#Now()#" expires = "10">
</cfif> </cfif> <!--- Show the most recent cookie set. ---> <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> <!--- Use this link to reset the cookies. ---> <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
<cfdefaultcase>
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 value="10">
<cfset grade="A">
</cfcase> <cfcase value="9;8" delimiters=";">
<cfset grade="B">
</cfcase> <cfcase value="7;6" delimiters=";">
<cfset grade="C">
</cfcase> <cfcase value="5;4;" delimiters=";">
<cfset grade="D">
</cfcase> <cfdefaultcase>
<cfset grade="F">
100 Chapter 2: ColdFusion Tags
Loading...