Building ColdFusion components

Just like ColdFusion pages, you store component files in a domain accessible by your web server and ColdFusion. Unlike ColdFusion pages, you save component files with the CFC suffix, such as componentName.cfc.

Save your component files in one of the following locations:

Directories accessible from the web server, which includes the web root and web server virtual directories.
Directories accessible from ColdFusion mappings.
Subdirectories of custom tag roots.

Note: For more information about saving components and component naming conventions, see "Using component packages".

All ColdFusion variable scopes are available to components, including Session, Client, Server, and Application. In addition, the This scope is available during component method execution.

You use the cfcomponent and cffunction tags to create ColdFusion components. By itself, the cfcomponent tag does not provide functionality. Rather, the cfcomponent tag provides an envelope that describes the functionality that you build in CMFL and enclose in cffunction tags.

Syntax for the cfcomponent tag

<cfcomponent extends="anotherComponent">

The following table displays the tag attribute, data type, and description:

Attribute

Type

Required

Description

For more information

extends

string

no

Name of parent component.

See "Using component inheritance".

Attribute	Type	Required	Description	For more information
extends	string	no	Name of parent component.	See "Using component inheritance".

Note: The cfcomponent tag is optional.

Syntax for the cffunction tag

<cffunction name="methodName" returnType="dataType" 
  roles="securityRoles" access="methodAccess" output="yes/no">

The following table displays the tag attribute, data type, and description:

Attribute

Type

Required

Description

For more information

name

string

yes

Name of component method

See "Defining component methods".

returnType

string

no

Data type validation for returned values.

See "Returning values from component methods".

roles

string

no

Assigns component method to ColdFusion security roles.

"Building secure ColdFusion components".

access

string

no

Restricts component method access by client type.

See "Building secure ColdFusion components"

output

Boolean

no

Suppresses component method output

See "Building secure ColdFusion components".

Attribute	Type	Required	Description	For more information
name	string	yes	Name of component method	See "Defining component methods".
returnType	string	no	Data type validation for returned values.	See "Returning values from component methods".
roles	string	no	Assigns component method to ColdFusion security roles.	"Building secure ColdFusion components".
access	string	no	Restricts component method access by client type.	See "Building secure ColdFusion components"
output	Boolean	no	Suppresses component method output	See "Building secure ColdFusion components".

The following example creates a component with two methods:

<cfcomponent>

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

In the example, two cffunction tags define two component methods, getEmp and getDept. When invoked, the component methods query the ExampleApps database. The cfreturn tag returns the query results to the client. For more information, see "Invoking component methods".

Defining component methods

Component method definitions exist between opening and closing cffunction tags. To separate the component method code from the component file, use the cfinclude tag to call the page that contains the component method code.

To create a component method:

Create a new ColdFusion component, and save it as tellTime.cfc in a directory below your web-root directory.

Modify the code so that it appears as follows:

<cfcomponent>
  <cffunction name="getLocalTime">
    <cfscript>
      serverTime=now();
      localStructure=structNew();
      localStructure.Hour=DatePart("h", serverTime);
      localStructure.Minute=DatePart("n", serverTime);
    </cfscript>
    <cfoutput>
      #localStructure.Hour#:#localStructure.Minute#
    </cfoutput>  
  </cffunction>
</cfcomponent>

In the example, the cfscript and cfoutput statements execute during component method processing.

Save your work.

By placing the method execution code in a separate file, template methods separate execution and markup code from the component method definitions.

To create component method using the cfinclude tag:

Open the tellTime.cfc file, and modify the code so that it appears as follows:
```
<cfcomponent>
  <cffunction name="getLocalTime">
    <cfinclude template="getTime.cfm">
  </cffunction>
</cfcomponent>
```
In the example, the getLocalTime method definition calls the getTime.cfm file with the cfinclude tag.
Save your work.
Create a ColdFusion page, and save it as getTime.cfm in the same directory as tellTime.cfc.
Modify getTime.cfm so that the code appears as follows:
```
<cfscript>
  serverTime=now();
  localStruct=structNew();
  localStruct.Hour=DatePart("h", serverTime);
  localStruct.Minute=DatePart("n", serverTime);
</cfscript>
<cfoutput>#localStruct.Hour#:#localStruct.Minute#</cfoutput>
```
In the example, a CFScript statement uses the now() and DatePart() functions to populate a structure with hour and minute values. The values are then displayed with the cfoutput tag. Notice that no value is returned to the client. Instead, the getTime method displays the variable.
Save your work.