Creating ColdFusion Components


ColdFusion Components (often referred to as CFCs) are plain text files, just like any other ColdFusion files. They may be created manually or by using the interactive screens in Dreamweaver MX.

File Naming

ColdFusion Components are special files and are named using an extension of .cfc. This extension distinguishes ColdFusion Components from other ColdFusion files (which have a .cfm extension).

File Location

Unlike Custom Tags, which have a specific storage location on the server, CFCs can be in any directory under the Web root. CFCs that are used throughout an application can be stored in directories designated for just that purpose; more focused or specific CFCs can be stored in the directory in which they are to be used.

Custom Tags were covered in Chapter 28, "Custom Tags," and Chapter 29, "Advanced Custom Tags."


CFC Tags

CFCs are created using a series of CFML tags as described below.

NOTE

ColdFusion Components are created using the same tags used to create User Defined Functions.


The <cfcomponent> Tag

ColdFusion Components are defined using a pair of <cfcomponent> tags. <cfcomponent> must be the first tag in a .cfc file, and </cfcomponent> must be the last. All component code must be placed in between those tags, like this:

 <cfcomponent>  ... </cfcomponent> 

<cfcomponent> supports the use of two optional attributes, as listed in Table 31.1:

Table 31.1. <cfcomponent> Attributes

ATTRIBUTE

DESCRIPTION

extends

Specifies the name of a component to be inherited (reviewed later in this chapter).

output

Turns on or off output display: if yes, component output is permitted; if no, then it is not.


TIP

As a general rule, CFCs should never generate output, so output="no" is recommended.


The <cffunction> Tag

Within the <cfcomponent> and </cfcomponent> tags, the individual functions are defined using pairs of <cffunction> tags. A CFC must contain one or more functions. Functions are declared like this:

 <cfcomponent>  <cffunction name="Get">  ...  </cffunction>  <cffunction name="Set">  ...  </cffunction> </cfcomponent> 

Every function must be named using a name attribute, as seen in the above code snippet. <cffunction> attributes are shown in Table 31.2:

Table 31.2. <cffunction> Attributes

ATTRIBUTE

DESCRIPTION

access

The access level, used to control access based on the origin of a request (as described later in this chapter). Valid values are package, private, public, and remote.

name

The function name, which must be unique within the CFC.

output

Turns on or off output display: if yes, function output is permitted; if no, then it is not.

returntype

The data type returned by the function; it must be one of the types listed below (default is any).

roles

List of roles that can invoke this function (described later in this chapter).


CFC functions usually return results. The data type of the result can be specified in the returntype attribute, and must be one of the following values:

  • any

  • array

  • binary

  • boolean

  • date

  • guid

  • numeric

  • query

  • string

  • struct

  • uuid

  • variableName

  • void

  • xml

  • a component name

TIP

It is recommended that the returntype always be specified.


NOTE

CFC functions are sometimes referred to as "methods."


The <cfargument> Tag

CFC functions can accept parameters (or arguments). Each function parameter is defined using a <cfargument> tag, like this:

 <cfcomponent>   <cffunction name="Get">   <cfargument name="id">   ...   </cffunction> </cfcomponent> 

Every argument must be named using a name attribute, as seen in the above code snippet. The complete list of <cfargument> attributes is shown in Table 31.3:

Table 31.3. <cfargument> Attributes

ATTRIBUTE

DESCRIPTION

default

The default value, used if argument is not specified.

name

The required argument name, must be unique within the function.

required

Flag indicating whether or not an argument is required.

type

Optional argument data type, used to perform type validation. It must be one of the types listed below.


Arguments can accept any type of data, but to perform data validation, type may be used to specify one of the following data types:

  • any

  • array

  • binary

  • boolean

  • date

  • guid

  • numeric

  • query

  • string

  • struct

  • uuid

  • variableName

  • xml

  • a component name

TIP

It is recommended that the type always be specified.


Within CFC code, arguments are accessed by their names (with or without a prefix), so the argument specified in the code snippet above could be accessed as #id# or #ARGUMENTS.id#. In addition, ARGUMENTS can be accessed as an array, so id (being the first argument) can be accessed as #arguments[1]#.

Arguments must be specified before any function processing. If <cfargument> is used after any other tag, an error will be thrown.

NOTE

The order of <cfargument> tags is unimportant if CFCs are invoked using tags. But if they are invoked using functions, or as Web Services, then order is very important. As such, order arguments appropriately (required ones first, group related arguments) to ensure that your CFC will be usable in as many scenarios as possible.


The <cfreturn> Tag

CFC functions return data via the <cfreturn> tag. <cfreturn> takes the value to be returned as an attribute, as seen here:

 <cfcomponent>   <cffunction name="Get">    <cfargument name="id">    <cfset result="">    ...    <cfreturn result>   </cffunction> </cfcomponent> 

Generally each function should have a single <cfreturn> (just one exit point),and it should be the last line of code in the function.

TIP

Functions can return a single result only; to return multiple values, use a complex data type (like a structure or an array or a query).




Macromedia ColdFusion MX 7 Certified Developer Study Guide
Macromedia ColdFusion MX 7 Certified Developer Study Guide
ISBN: 0321330110
EAN: 2147483647
Year: 2004
Pages: 389
Authors: Ben Forta

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net