Adobe ColdFusion 8

Defining functions by using the cffunction tag

The cffunction and cfargument tags let you define functions in CFML without using CFScript.

For information on ColdFusion components, see Building and Using ColdFusion Components. For more information on the cffunction tag, see the CFML Reference.

The cffunction tag function definition format

A cffunction tag function definition has the following format:

<cffunction name="functionName" [returnType="type" roles="roleList" 
        access="accessType" output="Boolean"]>
    <cfargument name="argumentName" [Type="type" required="Boolean"
        default="defaultValue">]
    <!--- Function body code goes here. --->
    <cfreturn expression>
</cffunction>

where square brackets ([]) indicate optional arguments. You can have any number of cfargument tags.

The cffunction tag specifies the name you use when you call the function. You can optionally specify other function characteristics, as the following table describes:

Attribute

Description

name

The function name.

returnType

(Optional) The type of data that the function returns. The valid standard type names are: any, array, binary, boolean, date, guid, numeric, query, string, struct, uuid, variableName, xml, and void. If you specify any other name, ColdFusion requires the argument to be a ColdFusion component with that name.

ColdFusion throws an error if you specify this attribute and the function tries to return data with a type that ColdFusion cannot automatically convert to the one you specified. For example, if the function returns the result of a numeric calculation, a returnType attribute of string or numeric is valid, but array is not.

roles

(Optional) A comma-delimited list of security roles that can invoke this method. If you omit this attribute, ColdFusion does not restrict user access to the function.

If you use this attribute, the function executes only if the current user is logged in using the cfloginuser tag and is a member of one or more of the roles specified in the attribute. Otherwise, ColdFusion throws an unauthorized access exception. For more information on user security, see Securing Applications.

output

(Optional) Determines how ColdFusion processes displayable output in the function body.

If you do not specify this option, ColdFusion treats the body of the function as normal CFML. As a result, text and the result of any cfoutput tags in the function definition body are displayed each time the function executes.

If you specify true or yes, the body of the function is processed as if it were in a cfoutput tag. ColdFusion displays variable values and expression results if you surround the variables and expressions with number signs (#).

If you specify false or no., the function is processed as if it were in a cfsilent tag. The function does not display any output. The code that calls the function is responsible for displaying any function results.

You must use cfargument tags for required function arguments. All cfargument tags must precede any other CFML code in a cffunction tag body. Therefore, put the cfargument tags immediately following the cffunction opening tag. The cfargument tag takes the following attributes:

Attribute

Description

name

The argument name.

type

(Optional) The data type of the argument. The type of data that is passed to the function. The valid standard type names are any, array, binary, boolean, date, guid, numeric, query, string, struct, uuid, and variableName. If you specify any other name, ColdFusion requires the argument to be a ColdFusion component with that name.

ColdFusion throws an error if you specify this attribute and the function is called with data of a type that ColdFusion cannot automatically convert to the one you specified. For example, if the argument type attribute is numeric, you cannot call the function with an array.

required

(Optional) A Boolean value that specifies whether the argument is required. If set to true and the argument is omitted from the function call, ColdFusion throws an error. The default value is false. The required attribute is not required if you specify a default attribute.

Because you do not identify arguments when you call a function, all cfargument tags that specify required arguments must precede any cfargument tags that specify optional arguments in the cffunction definition.

default

(Optional) The default value for an optional argument if no argument value is passed. If you specify this attribute, ColdFusion ignores the required attribute.

Note: The cfargument tag is not required for optional arguments. This feature is useful if a function can take an indeterminate number of arguments. If you do not use the cfargument tag for an optional argument, reference it by using its position in the Arguments scope array. For more information see Using the Arguments scope as an array.

Using a CFML tag in a user-defined function

The most important advantage of using the cffunction tag over defining a function in CFScript is that you can include CFML tags in the function. Thus, UDFs can encapsulate activities, such as database lookups, that require ColdFusion tags. Also, you can use the cfoutput tag to display output on the calling page with minimal coding.

Note: To improve performance, avoid using the cfparam tag in ColdFusion functions. Instead, use the cfset tag.

The following example function looks up and returns an employee's department ID. It takes one argument, the employee ID, and looks up the corresponding department ID in the cfdocexamples Employee table: 

<cffunction name="getDeptID" >
    <cfargument name="empID" required="true" type="numeric">
    <cfset var cfdocexamples="">
    <cfquery dataSource="cfdocexamples" name="deptID">
        SELECT Dept_ID
        FROM Employee
        WHERE Emp_ID = #empID#
    </cfquery>
    <cfreturn deptID.Dept_ID>
</cffunction>