|
cffunction
DescriptionDefines
a function that you can call in CFML. Required to define ColdFusion component
methods.
HistoryColdFusion
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 nosecureJSON 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.
|
UsageThe 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>
|