Adobe ColdFusion 8

Tags

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

Tag syntax

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

<cfoutput>
    Hello #YourName#! <br>
</cfoutput>

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

<cfset YourName="Bob">

Note: The cfset tag differs from other tags in that it has neither a body nor arguments. Instead, the tag encloses an assignment statement that assigns a value to a variable. The cfset tag can also call a function without assigning a value to a result variable.

Sometimes, although the tag can have a body, you do not need to put anything in it because the attributes specify all the required information. You can omit the end tag and put a forward slash character before the closing (>) character, as in the following example:

<cfprocessingdirective pageencoding="euc-jp" />

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

<tagname attributeCollection="#structureName#">

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

<!--- Configure dynamic attribute variables. --->
<cfparam name="theURL" default="http://www.adobe.com">
<cfparam name="resolveURL" default="yes">

<!--- Code that dynamically changes values for attributes might go here. --->

<!--- Create an arguments structure using variables. --->
<cfset myArgs=StructNew()>
<cfset myArgs.url="#theURL#">
<!--- Include a user name and password only if they are available. --->
<cfif IsDefined("username")>
    <cfset myArgs.username="#username#">
</cfif>
<cfif IsDefined("password")>
    <cfset myArgs.password="#password#">
</cfif>
<cfset myArgs.resolveURL="#resolveURL#">
<cfset myArgs.timeout="2">

<!--- Use the myArgs structure to specify the cfhttp tag attributes. --->
<cfhttp attributeCollection="#myArgs#">
<cfoutput>
    #cfhttp.fileContent#
</cfoutput>

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

You can use the attributeCollection attribute in all tags except the following:

cfargument

cfelseif

cflogout

cfset

cfbreak

cffunction

cfloop

cfsilent

cfcase

cfif

cfparam

cfswitch

cfcatch

cfimport

cfprocessingdirective

cftry

cfcomponent

cfinterface

cfproperty

 

cfdefaultcase

cflogin

cfrethrow

 

cfelse

cfloginuser

cfreturn

 

Built-in tags

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

  • Manipulating variables
  • Creating interactive forms
  • Accessing and manipulating databases
  • Displaying data
  • Controlling the flow of execution on the ColdFusion page
  • Handling errors
  • Processing ColdFusion pages
  • Managing the CFML application framework
  • Manipulating files and directories
  • Using external tools and objects, including Verity collections, COM, Java, and CORBA objects, and executable programs
  • Using protocols, such as mail, http, ftp, and pop

The CFML Reference documents each tag in detail.

Custom tags

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

  • CFML custom tags that are ColdFusion pages
  • CFX tags that you write in a programing language such as Java or C++

Custom tags can encapsulate frequently used business logic or display code. These tags enable you to place frequently used code in one place and call it from many places. Custom tags also let you abstract complex logic into a single, simple interface. They provide an easy way to distribute your code to others; you can even distribute encrypted versions of the tags to prevent access to the tag logic.

You can access a variety of free and commercial custom tags on the Adobe developer's exchange (www.www.adobe.com/devnet/coldfusion/index.html). They perform tasks ranging from checking if Cookies and JavaScript are enabled on the client's browser to moving items from one list box to another. Many of these tags are free and include source code.

CFML custom tags

When you write a custom tag in CFML, you can take advantage of all the features of the ColdFusion language, including all built-in tags and even other custom tags. CFML custom tags can include body sections and end tags. Because they are written in CFML, you do not need to know a programming language such as Java. CFML custom tags provide more capabilities than user-defined functions, but are less efficient.

For more information on CFML custom tags, see Creating and Using Custom CFML Tags. For information about, and comparisons among, ways to reuse ColdFusion code, including CFML custom tags, user-defined functions, and CFX tags, see Creating ColdFusion Elements.

CFX Tags

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

For more information on CFX tags, see Building Custom CFXAPI Tags.