cffunction

Search
ColdFusion

ColdFusion

Open app

Description

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

History

ColdFusion (2018 release):  It is no longer necessary to set the access attribute to "remote" in case of a REST-based function.

ColdFusion 10: Added the attributes- restPath, httpMethod,  produces, and consumes.

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.

Category

Extensibility tags

See also

cfargument, cfcomponent, cfinterface, cfinvoke, cfinvokeargument, cfobject, cfproperty, cfreturn, SerializeJSON

 

Syntax

<cffunction
name = "method name"
access = "method access"
consumes="MIME types"
description = "function description"
displayName = "name"
httpMethod="GET|PUT|POST|DELETE"
hint = "hint text"
output = "yes|no"
produces="MIME type"
returnFormat = "not specified|JSON|plain|WDDX"
returnType = "data type"
roles = "securityRoles"
restPath="sub-resource path"
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. Methods are available to the CFC pages in the same 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.
restpath Optional String Specify to use a sub- resource path for the CFC. You can also include regular expressions in the path.

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

·         function

·         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 returntype 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 value that is returned is not a CFC with the specified name.
Note: If a function does not return a value and the returnType value is string , 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 Ajax programming rules and techniques 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 Ajax programming rules and techniques in the Developing ColdFusion Applications.

restPath

Optional

 

Specify to use a sub- resource path for the CFC.
The path is case-sensitive. Also, it is preferable to avoid special characters when you specify the path. You can include regular expressions in the path.
For details of the expressions that you can specify, see the attribute restPath in cfcomponent .

httpMethod

 

 

The HTTP method to use, must be one of the following:

·         GET: Requests information from the server. Any data that the server requires to identify the requested information must be in the URL or in {{cfhttp type="URL"}}tag.

·         POST: Sends information to the server for processing. Requires one or more cfhttpparam tags. Often used for submitting form-like data.

·         PUT: Requests the server to store the message body at the specified URL. Use this method to send files to the server.

·         DELETE: Requests the server to delete the specified URL.

·         HEAD: Identical to the GET method, but the server does not send a message body in the response. Use this method for testing hypertext links for validity and accessibility, determining the type or modification time of a document, or determining the type of server. If you have not specified HEAD, by default, GET method is called. However, message body is not sent in the response.

·         OPTIONS: A request for information about the communication options available for the server or the specified URL. This method enables the ColdFusion application to determine the options and requirements associated with a URL, or the capabilities of a server, without requesting any additional activity by the server. If you have not specified OPTIONS, then ColdFusion sends a response.
Overrides the value that you specify at component level.

produces

Optional

/

Comma-separated list of acceptable MIME types. Used to specify the MIME media type of representation a resource can produce, for example, {{produces= "text /plain ,text / html "}}If a resource can produce more than one MIME media type, the function chosen corresponds to the most acceptable media type as declared by the client.
If no value is specified, / is taken by default, which means, all MIME types are consumed. Overrides the value that you specify at the component level.

Note 
If MIME type is a wildcard, the results include any value.
For example, if you a make a http call with produces as '*/ xml ' and follow it up with a second http call with produces as '*/json', the results in the second http call might include the first call result as well. 

consumes

Optional

/

Comma-separated list of acceptable MIME types, for example consumes="text/plain,text/ html ".Used to specify which MIME media types of representation a resource can accept, or consume, from the client. This attribute overrides the same attribute at the component level.
If no value is specified, / is taken by default, which means, all MIME types are consumed. Adobe recommends that you avoid conflict scenarios while specifying the attributes produces and consumes. For example, avoid situations such as the following: In function 1, you specify produces as text/ xml and consumes as text/and in function 2, produces as text/ and consumes as text/ xml . Here, both the functions are valid for the request with accept = text/ xml and consumes as text/ xml .

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>

Example

<!--- component with attributes rest and restpath --->
<cfcomponent rest="true"
             restpath="/crudService">

    <!--- handle GET request (httpmethod),
          take argument in restpath(restpath={customerID}),
          return query data in json format(produces=text/json) ---> 
    <cffunction name="getHandlerJSON"
                access="remote"
                httpmethod="GET"
                restpath="{customerID}"
                returntype="query"
                produces="application/json">
                    
        <cfargument name="customerID"
                    required="true"
                    restargsource="Path"
                    type="numeric"/>
    
        <cfset myQuery = queryNew("id,name", 
                                  "Integer,varchar",
                                  [[1, "John"], [2, "Doe"]])>
        <cfquery dbtype="query"
                 name="resultQuery">
            select * from myQuery where id = #arguments.customerID#
        </cfquery>
        <cfreturn resultQuery>
    </cffunction>   
</cfcomponent>

Example

<cffunction name="getFullName" output="false" access="public" returnType="string">
    <cfargument name="firstName" type="string" required="false" default="" />
    <cfargument name="lastName" type="string" required="false" default="" />

    <cfset var fullName = arguments.firstName & " " & arguments.lastname />

    <cfreturn fullName />
</cffunction>

<cfset fullName = getFullName(firstName="John", lastName="Adams") />

<cfoutput>
    Good morning, #fullName#!
</cfoutput>

 Adobe

Get help faster and easier

New user?

Quick links

View all your plans Manage your plans
View quick links
Hide quick links

Legal Notices    |    Online Privacy Policy