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.
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:
ManualDescription
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.
6Introduction:
CHAPTER 1
Reserved Words and Variables
This chapter provides information on Macromedia ColdFusion reserved words, and lists scope
variables.
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.
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 variables9
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.)
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:
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:
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.
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 variables17
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 variableDescription
SERVER_SOFTWAREName and version of the information server software answering
the request (and running the gateway). Format: name/version.
SERVER_NAMEServer's hostname, DNS alias, or IP address as it appears in self-
referencing URLs.
GATEWAY_INTERFACECGI specification revision with which this server complies. Format:
CGI/revision.
SERVER_PROTOCOLName and revision of the information protocol this request came in
with. Format: protocol/revision.
SERVER_PORTPort number to which the request was sent.
REQUEST_METHODMethod with which the request was made. For HTTP, this is Get,
Head, Post, and so on.
PATH_INFOExtra 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_TRANSLATEDTranslated version of PATH_INFO after any virtual-to-physical
mapping.
SCRIPT_NAMEVirtual path to the script that is executing; used for self-referencing
URLs.
QUERY_STRINGQuery information that follows the ? in the URL that referenced
this script.
REMOTE_HOSTHostname making the request. If the server does not have this
information, it sets REMOTE_ADDR and does not set
REMOTE_HOST.
REMOTE_ADDRIP address of the remote host making the request.
AUTH_TYPEIf 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_IDENTIf the HTTP server supports RFC 931 identification, this variable is
CONTENT_TYPEFor 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_LENGTHLength of the content as given by the client.
18Chapter 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 variableDescription
HTTP_REFERERThe referring document that linked to or submitted form data.
HTTP_USER_AGENTThe browser that the client is currently using to send the request.
Format: software/version library/version.
HTTP_IF_MODIFIED_SINCEThe 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_SUBJECTClient-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_ISSUERInformation 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_ENCODEDThe 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 variables19
20Chapter 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.
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.
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.
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.
TagAttribute or valueObsolete as of this
ColdFusion release
cfauthenticate
cfchart
cffile
cfimpersonate
cfindex
cfinternaladminsecurity
cfldap
cfnewinternaladminsecurity
cfsetting
AllColdFusion MX
rotated
attributes
attributeColdFusion MX 7
attribute value archive ColdFusion MX
AllColdFusion MX
action
external attribute
attribute value optimizeColdFusion MX
AllColdFusion MX
This tag did not appear in CFML Reference.
fileterConfig
attributeColdFusion MX
AllColdFusion MX
This tag did not appear in CFML Reference.
catchExceptionsByPattern
ColdFusion MX
attribute
Tag changes since ColdFusion 535
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.
and cfexit” in Chapter 2, “Elements of CFML,” in ColdFusion MX Developer’s Guide
Attributes
AttributeReq/OptDefault Description
showErrorOptionalError 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>
36Chapter 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>
cfabort37
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.
• 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
AttributeReq/Opt DefaultDescription
appletSource Required Name of registered applet
nameRequired Form variable name for applet
heightOptional Height of applet, in pixel
widthOptional Width of applet, in pixels
vSpaceOptionalSpace above and below applet, in pixels
hSpaceOptionalSpace on left and right of applet, in pixels
38Chapter 2: ColdFusion Tags
AttributeReq/Opt DefaultDescription
alignOptional Alignment:
• Left
• Right
• Bottom
• Top
• TextTop
• Middle
• AbsMiddle
• Baseline
• AbsBottom
notSupported OptionalSee
Description
param_nOptional 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>
cfapplet39
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"
• 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.
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.
cfapplication41
AttributeReq/OptDefaultDescription
setDomainCookiesOptionalno• 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.
scriptProtectOptionalDetermined 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.
42Chapter 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
type OptionalanyString; 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.
cfargument45
AttributeReq/Opt DefaultDescription
requiredOptional noNote: 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"
defaultOptionalIf no argument is passed, specifies a default argument value.
default attribute.
displayname Optional
hintOptional 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>
46Chapter 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
AttributeReq/OptDefaultDescription
baseTagRequiredBase tag name.
dataCollectionOptionalAssocAttribsStructure 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">
...
cfassociate47
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.
48Chapter 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")>
<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.--->
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.
• 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.)
cfcache51
Attributes
AttributeReq/OptDefaultDescription
actionOptionalcache• 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".
directoryOptionalcf_root/cache Absolute path of cache directory.
timespanOptionalPage is
flushed only
when
cfcache
action
"flush" is
=
executed
expireURLOptionalFlush 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=*".
usernameOptionalA username. Provide this if the page requires
authentication at the web server level.
passwordOptional A password. Provide this if the page requires
authentication at the web server level.
portOptionalThe 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.
protocolOptionalThe 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.
52Chapter 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.--->
<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>
cfcache53
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
AttributeReq/OptDefaultDescription
nameRequiredThe name of the calendar.
heightOptionalDetermined by
Flash
widthOptionalDetermined by
Flash
selectedDateOptionalNone (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
54Chapter 2: ColdFusion Tags
AttributeReq/OptDefaultDescription
startRangeOptionalThe start of a range of dates that are disabled. Users
cannot select dates from this date through the date
specified by the
endRange attribute.
endRangeOptionalThe end of a range of dates that are disabled. Users
cannot select dates from the date specified by the
startRange attribute through this date.
disabledOptionalnot disabledDisables 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).
maskOptionalMM/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 Optional0Integer in the range 0-6 specifying the first day of
the week in the calendar: 0 indicates Sunday; 6
indicates Saturday.
dayNamesOptionalS, 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.
monthNamesOptionalJanuary,
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
styleOptional 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.
enabledOptionalYesFlash only: Boolean value specifying whether the
control is enabled. A disabled control appears in
light gray. This is the inverse of the disabled
attribute.
cfcalendar55
AttributeReq/OptDefaultDescription
visibleOptionalYesFlash only: Boolean value specifying whether to
show the control. Space that would be occupied by
an invisible control is blank.
tooltipOptional Flash only: Text to display when the mouse pointer
hovers over the control.
onChangeOptional ActionScript that runs when the user selects a date.
Usage
The cfcalendar tag displays a calendar month, showing the month, the year, a grid of the days
of the month, and headings for the days of the week. The calendar contains forward and back
arrow buttons to let you change the month and year that are displayed.
If you include a value for the
selectedDate attribute, that date is highlighted in green and
determines the month and year that display initially. Changing the month and year display does
not change the selected date. A user can change the selected date by clicking a different date on
the calendar. The
onChange attribute can specify an ActionScript event handler function that
runs when the user selects a date.
The current date is highlighted in reverse (that is, a white number on a black background). If the
selected date is in a different month or year, however, the current date does not appear unless you
move to it by clicking the forward or back arrows.
The
mask attribute lets you specify the format of the selected date that is returned to the
application.
You can use the keyboard to access and select dates from a
cfcalendar control:
• Use the Up, Down, Left, and Right Arrow keys to change the selected date.
• Use the Home and End keys to reach the first and last enabled date in a month, respectively.
• Use the Page Up and Page Down keys to reach the previous and next month, respectively.
Note: The cfcalendar tag is not supported in XML format forms.
Example
This example produces a 200-pixel by 150-pixel calendar with a Flash haloBlue skin. It displays
abbreviated month names and two-character days of the week. It initially displays today’s date as
determined by the
back to the current page, which displays the submitted information.
selectedDate attribute. When you click the Save button, the form submits
The example also has three
that displays on the calendar and a blocked-out date range. The initial blocked-out date is a fourday period immediately preceding today’s date.
Note: This example must be modified to work in locales that do not use mm/dd/yyyy date formats. To
do so, use the
appropriate for your locale, such as dd/mm/yyyy.
<!--- Set initial selected and blocked-out dates.--->
<cfparam name="Form.startdate" default="#dateformat(now()-5, 'mm/dd/yyyy')#">
56Chapter 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
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
AttributeReq/OptDefaultDescription
valueRequiredThe 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.
delimiterOptional, (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":
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.
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.
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">
cfcatch61
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.
62Chapter 2: ColdFusion Tags
Advanced Exception types
You can specify the following advanced exception types in the type attribute:
<!--- 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>
64Chapter 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#">
cfcatch65
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
• 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
AttributeReq/OptDefaultDescription
backgroundColorOptionalColor 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"
chartHeightOptional240Chart height; integer number of pixels.
chartWidthOptional320Chart width; integer number of pixels.
dataBackgroundColorOptionalwhiteColor 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.
fontOptionalarial 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.
cfchart67
AttributeReq/OptDefaultDescription
fontBoldOptionalnoWhether to make the text bold:
• yes
• no
fontItalicOptional noWhether to make the text italicized:
• yes
• no
fontSizeOptional11Font size; integer.
foregroundColorOptionalblackColor 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.
formatOptionalflashFile format in which to save the graph:
• flash
• jpg
• png
gridlinesOptional10, including
top and bottom
Number of grid lines to display on the value
axis, including axis; positive integer.
labelFormatOptionalnumberFormat for y-axis labels:
• number
• currency
• percent
• date
markerSizeOptional (Automatic)Size of data point marker in pixels; integer.
nameOptionalPage 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.
pieSliceStyleOptionalslicedApplies to the
value
pie.
cfchartseries type attribute
• solid: displays pie as if unsliced.
• sliced: displays pie as if sliced.
rotatedOptionalnoWhether to rotate the chart 90 degrees:
• yes
• no
scaleFromOptionalDetermined by
scaleToOptionalDetermined by
68Chapter 2: ColdFusion Tags
Y-axis minimum value; integer.
data
Y-axis maximum value; integer.
data
AttributeReq/OptDefaultDescription
seriesPlacementOptionaldefault 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
show3DOptionalyesWhether to display the chart with three-
dimensional appearance:
• yes
• no
showBorderOptionalnoWhether to display a border around the
chart:
• yes
• no
showLegendOptionalyesWhether to display the legend if the chart
contains more than one data series:
• yes
• no
showMarkersOptionalyes Whether to display markers at data points in
line, curve, and scatter graphs:
• yes
• no
showXGridlinesOptionalnoWhether to display x-axis gridlines:
• yes
• no
showYGridlinesOptionalyesWhether to display y-axis gridlines:
• yes
• no
sortXAxisOptionalnoWhether to display column labels in
alphabetic order along the x-axis:
• yes:
• no
Ignored if the
xAxisType attribute is scale.
styleOptionalXML file or string to use to specify the style
of the chart.
titleOptionalTitle of the chart.
tipbgcolorOptionalwhiteBackground 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.
cfchart69
AttributeReq/OptDefaultDescription
tipStyleOptionalmouseOverDetermines 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
urlOptionalURL 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
xAxisTitleOptionalTitle that appears on the x-axis; text.
xAxisTypeOptionalcategoryWhether 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.
xOffsetOptional0.1Number 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.
yAxisTitleOptionalTitle of the y-axis; text.
70Chapter 2: ColdFusion Tags
AttributeReq/OptDefaultDescription
yAxisTypeOptionalcategoryCurrently has no effect, as the y-axis is
always used for data values.
yOffsetOptional0.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 nameRGB 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
cfchart71
Color nameRGB 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>
72Chapter 2: ColdFusion Tags
<h1>Employee Salary Analysis</h1>
<!--- Bar graph, from Query of Queries --->
<cfchart format="flash"
xaxistitle="Department"
yaxistitle="Salary Average">
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
AttributeReq/OptDefaultDescription
itemRequired Data point name; string.
valueRequired 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
74Chapter 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">
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.
76Chapter 2: ColdFusion Tags
Attributes
AttributeReq/OptDefaultDescription
colorlistOptionalSets 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
itemColumnRequired 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
markerStyleOptionalrectangleSets the icon that marks a data point for two-
dimensional line, curve, and scatter graphs:
• rectangle
• triangle
• diamond
• circle
• letter
• mcross
• snow
• rcross
paintStyleOptionalplainSets 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.
queryOptionalName of the ColdFusion query from which to get data
to graph.
seriesColorOptionalColor of the main element (such as the bars) of a chart.
seriesLabelOptional 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.
cfchartseries77
AttributeReq/OptDefaultDescription
typeRequiredSets the chart display style:
• bar
• line
• pyramid
• area
• horizontalbar
• cone
• curve
• cylinder
• step
• scatter
• pie
valueColumnRequired if
query
attribute is
specified
dataLabelStyle OptionalNoneSpecifies 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>
78Chapter 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">
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.
AttributeReq/OptDefaultDescription
headerRequiredColumn header text. To use this attribute, you must also use the
cftable colHeaders attribute.
widthOptional20Column 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.
alignOptionalleftColumn alignment:
• left
• right
• center
textRequiredDouble-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.
80Chapter 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. --->
• 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.
82Chapter 2: ColdFusion Tags
Attributes
Attribute Req/OptDefaultDescription
actionRequired; 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.
pathSee UsageAbsolute 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\".
languageSee UsageEnglishAlthough 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.
nameSee UsageName for the query results returned by the
categorylist actions.
list and
categories See UsagenoUsed 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.
cfcollection83
The following table shows the dependence relationships among this tag’s attribute values:
<!------------------------------------------------------------------------(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\
<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>
cfcollection87
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">
Chapter 10, “Building and Using ColdFusion Components” in ColdFusion MX
Developer’s Guide
88Chapter 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
AttributeReq/OptDefaultDescription
extendsOptionalName of parent component from which to inherit
methods and properties.
outputOptionalComponent
body
displayable
text is
processed
as standard
CFML
styleOptionalrpcSpecifies whether a CFC used for web services uses
namespaceOptionalclassnameSpecifies 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".
serviceportnameOptionalSpecifies 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".
cfcomponent89
AttributeReq/OptDefaultDescription
porttypenameOptionalSpecifies 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
bindingnameOptionalSpecifies 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
wsdlfileOptionalA properly formatted WSDL file to be used instead of
WSDL generated by ColdFusion MX.
This attribute applies only when
displaynameOptionalA 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.
hintOptionalText 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:
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.
• 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.
92Chapter 2: ColdFusion Tags
Attributes
AttributeReq/OptDefaultDescription
typeOptional 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"
deleteFileOptionalnoApplies 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.
fileOptionalName 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.
cfcontent93
AttributeReq/OptDefaultDescription
variableOptionalName 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
resetOptionalyesIf 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
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
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.
94Chapter 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. --->
<!--- 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. --->
<!--- 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. --->
• 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/OptDefaultDescription
nameRequired 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.
valueOptionalValue to assign to cookie variable. Must be a string or variable that
can be stored as a string.
expiresOptionalExpiration 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).
cfcookie97
Attribute Req/OptDefaultDescription
secureOptionalIf 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
pathOptionalURL, 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.
domainRequired 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:
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>
98Chapter 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>
cfcookie99
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">
100Chapter 2: ColdFusion Tags
Loading...
+ hidden pages
You need points to download manuals.
1 point = 1 manual.
You can buy points or you can get point for every manual you upload.