cffunction ColdFusion 9 Documentation

Description

Defines a function that you can call in CFML. Required to define ColdFusion component methods.

History

ColdFusion 8:

Added returnformat, secureJSON, and verifyClient attributes
Added component as a valid value for the ReturnType attribute.

ColdFusion MX 7: Added the description attribute, and added the XML value to the returntype attribute.

ColdFusion MX: Added this tag.

Syntax

<cffunction 
    name = "method name" 
    access = "method access" 
    description = "function description" 
    displayName = "name" 
    hint = "hint text" 
    output = "yes|no" 
    returnFormat = "not specified|JSON|plain|WDDX" 
    returnType = "data type" 
    roles = "securityRoles" 
    secureJSON = "yes|no" 
    verifyClient = "no|yes">

Attributes

Attribute	Req/Opt	Default	Description
`name`	Required		A string; a component method that is used in the `cfcomponent` tag.
`access`	Optional	public	The client security context from which the method can be invoked. The following values are valid: `private`: available only to the component that declares the method and any components that extend the component in which it is defined. `package`: available only to the component that declares the method, components that extend the component, or any other components in the package. `public`: available to a locally executing page or component method. `remote`: available to a locally or remotely executing page or component method, or a remote client through a URL, Flash, or a web service. To publish the function as a web service, this option is required.
`description`	Optional		Supplies a short text description of the function.
`displayname`	Optional		Meaningful only for CFC method parameters. A value to be displayed in parentheses following the function name when using introspection to show information about the CFC.
`hint`	Optional		Meaningful only for CFC method parameters. Text to be displayed when using introspection to show information about the CFC. The `hint` attribute value follows the syntax line in the function description.
`output`	Optional	Function body is processed as standard CFML	Specifies under which conditions the function can generate HTML output. The following values are valid: `yes`: the entire function body is processed as if it were in a `cfoutput` tag. Variables names surrounded by number signs (#) are automatically replaced with their values. `no`: the function is processed as if it were within a `cfsilent` tag. If you do not specify this attribute, the function body is processed as standard CFML. Any variables must be in `cfoutput` tags.
`returnformat`		Return as WDDX or XML; see description.	The format in which to return values to a remote caller. This attribute has no effect on values returned to a local caller. The following values are valid: `json`: serialize the return value into JSON format before returning it remotely. `wddx`: serialize the return value into WDDX format before returning it remotely. `plain`: ensure that the return value is a type that ColdFusion can convert directly to a string, and return the string value without serialization. Valid types include all simple types, such as numbers, and XML objects. If the return value is a complex type, such as an array, or a binary value, ColdFusion generates an error. If you specify a `returntype` attribute, its value must be `any`, `boolean`, `date`, `guid`, `numeric`, `string`, `uuid`, `variablename`, or `XML`; otherwise, ColdFusion generates an error. By default, ColdFusion serializes all return types (including simple return types), except XML, into WDDX format, and returns XML data as XML text. You can also use `returnformat` as an HTTP request parameter when calling a remote CFC function. This parameter has the same effect as the `returnformat` attribute and overrides any `returnformat` attribute value specified in the `cffunction` tag.
`returnType`	Required for a web service; Optional, otherwise.	any	String; a type name; data type of the function return value: `any` `array` `binary` `boolean` `component`: the return value must be a ColdFusion component. `date` `guid`: the argument must be a UUID or GUID of the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where each x is a character that represents 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 that represents a hexadecimal number (0-9A-F). `variableName`: a string formatted according to ColdFusion variable naming conventions. `void`: does not return a value. `xml`: allows web service functions to return CFML 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. Note: If a function does not return a value and the `returnType` value is `numeric`, ColdFusion generates an error; ColdFusion does not generate an error for other types.
`roles`	Optional	"" (empty)	A comma-delimited list of ColdFusion security roles that can invoke the method. Only users who are logged in with the specified roles can execute the function. If this attribute is omitted, all users can invoke the method.
`secureJSON`	Optional	See Description	A Boolean value that specifies whether to add a security prefix in front of any value that the function returns in JSON-format in response to a remote call. The default value is the value of any `This.secureJSON` variable in the Application.cfc file or the `secureJSON` attribute of the `cfapplication` tag, or if there is no`secureJSON` application setting, the Prefix Serialized JSON setting in the Administrator Server Settings > Settings page, which defaults to `false`. For more information see Improving security in the Developing ColdFusion Applications.
`verifyClient`	Optional	no	A Boolean value that specifies whether to require remote function calls to include an encrypted security token. For use with ColdFusion AJAX applications only. For more information see Improving security in the Developing ColdFusion Applications.

Usage

The cffunction tag can define a function that you call in the same manner as a ColdFusion built-in function.

To define a ColdFusion component (CFC) method, use a cffunction tag.

The following example shows cffunction tag attributes for a simple CFC method that returns a ColdFusion Query object.

<cffunction 
    name="getEmployees"  
    access="remote"  
    returnType="query"  
    hint="This query returns all records in the employee database. It candrill-down or narrow the search, based on optional input parameters.">

For detailed information on using the cffunction tag for ColdFusion components, see Building and Using ColdFusion Components in the Developing ColdFusion Applications.

If you specify returnformat="json" and the function returns a query, ColdFusion serializes the query into a JSON Object with two entries, and array of column names, and an array of column data arrays. For more information see SerializeJSON.

If you specify a roles attribute, the function executes only if a user is logged in and belongs to one of the specified roles.

If you specify variableName for the returnType attribute, the function must return a string that is in ColdFusion variable name format; that is, the function must return a string that starts with a letter, underscore, or Unicode currency symbol, and consist of letters, numbers, and underscores (_), periods, and Unicode currency symbols, only. ColdFusion does not check whether the value corresponds to an existing ColdFusion variable.

Example

<cfcomponent> 
    <cffunction name="getEmp"> 
         <cfquery  
                name="empQuery" datasource="ExampleApps" > 
                SELECT FIRSTNAME, LASTNAME, EMAIL 
                FROM tblEmployees 
         </cfquery> 
         <cfreturn empQuery> 
    </cffunction> 
    <cffunction name="getDept"> 
        <cfquery name="deptQuery" datasource="ExampleApps" > 
         SELECT *     
         FROM tblDepartments     
         </cfquery> 
         <cfreturn deptQuery> 
    </cffunction> 
</cfcomponent>

cffunction