ColdFusion Article

Table of contents

In this tutorial, you'll learn how to create simple ColdFusion Components (CFCs) through manual coding in the Dreamweaver MX code view and through the Dreamweaver MX Create Components Dialog. You will see how to consume them, and how to consume a .Net web service.

Web services are similar to CFCs in that they are applications into which you feed data and then receive some information back. They allow you to add functionality to your site without having to create the back end for those pieces of your application. For instance, if you were creating an online store and needed to have instant currency conversions, you could use web services. Or, you may want to be able to tell someone how far they are from your location. Or, you may want to be able to access the Federal Express package tracking system. There are a wide variety of services available for consumption on the web through ColdFusion MX.

Prerequisites
For this tutorial, you are going to need to have the following installed and running on your computer:

Creating a simple CFC through code
The simplest form of a CFC is simply some ColdFusion code that you have abstracted to a separate ColdFusion page, that you can invoke from other ColdFusion pages. One simple application is to create the footer or copyright information for a particular page. You could do this same thing a number of ways in ColdFusion without CFCs, as developers have done in the past, but this is an easy example to apply CFCs.

To start creating a CFC, use the following steps:

In Dreamweaver, view the code. You may need to click Show Code View.

Since you chose "ColdFusion Component" when you chose which type of file to create, the CFC you created has the following code:

 <cfcomponent>
    <cffunction name="myFunction" access="public"  returntype="string">
       <cfargument name="myArgument"  type="string" required="true">
       <cfset myResult="foo">
       <cfreturn myresult>
    </cffunction>
 </cfcomponent> 

Although this has the simplicity of one large nested tag in a file with nothing else in it, CFCs are much more. They can provide web services and can be used in any of your ColdFusion MX and Macromedia Flash MX applications. Read more about how to use CFCs with Macromedia Flash MX and Flash Remoting in the other articles in the ColdFusion MX Application Developer Center.

The cfcomponent tag indicates the CFC much like the HTML tag indicates the beginning and end of an HTML page.

The cffunction tag indicates the functionality of the component. There can be multiple cffunction tags in a single component. When you invoke the CFC from your ColdFusion page, you can call any one of the functions. This is especially useful if you have sets of related functionality when you want to remove to a separate file for maintainability of the code. Inside the cffunction tag, you can process as much ColdFusion code as you like.

The cffunction tag has five attributes. Dreamweaver MX inserts three attributes as a default:

Note: For more information about the cffunction tag in CFCs, refer to the CFML documentation installed with ColdFusion MX.

By default, when you create a CFC in Dreamweaver MX, it adds the cfargument tag, sets a result, and returns the result in a variable.

The cfargument tag informs the function that the CFML page calling the function is passing information to the function. This example will not use the cfargument tag, so you can delete it for now. We are going to talk about how to use that in the next example. Within the cffunction tag, you will use the cfset tag to creates a variable or variables that will hold the function result.

This example will create a date for the CFC to return to the calling CFML page:

You could test this CFC now, but before you do, you'll add another function to the CFC. By doing this, you can call either or both functions from the ColdFusion calling page:

Using your CFC
Now that you have created a simple CFC with a couple of functions, you are ready to use it. Calling a CFC is easy. In the ColdFusion page where you want to call the CFC, use the cfinvoke tag. In the cfinvoke tag, you can call individual functions inside of the CFC, and you can specify the name of the return variable that is returned from the CFC.

You have successfully called a CFC from your page. You have called some content that does not reside in the calling page. This is simple because the information is in a separate file. When test.cfm page is processed, the ColdFusion Application Server processes the myTextFunction() function in TestCFC.cfc and inserts it in the calling page (test.cfm), where the <cfinvoke> tag is located.

The other function in TestCFC, myDateFunction(), requires a little more work to display because it creates the date. This is the most common sort of CFC. Typically you will want your CFC to perform a function, access the result, and present the information on your calling page. The instructions for doing so are below:

Passing Variables into a CFC
Once you have created a simple CFC, you may want to create a CFC that provides a more functionality. In this example, you'll build a CFC that finds an employee and lists the results a few different ways. This CFC will enable you to to save find and search capabilities on any number of pages, but only generate the code in one place. If you need to change the code later, you only need to change it in one place, rather than on numerous ColdFusion pages. Additionally, you can access the functionality from other clients, such as Macromedia Flash MX through Macromedia Flash Remoting.

In the previous steps, you manually created a CFC. This time, you'll create them using the new Components and Web Services interface in Dreamweaver MX.

Creating the CFC in Dreamweaver MX

<!--- Generated by Dreamweaver MX 6.0.1681 [en] (Win32) - Tue Apr 09 18:51:44   
      GMT-0700 (Pacific Daylight Time) 2002 --->

  <cfcomponent displayName="FindEmployee">
     <cffunction name="FindEmployeeSort" 
                 access="remote" 
                 returnType="query"    
                 output="false">
     </cffunction>
  </cfcomponent>

Dreamweaver MX created the necessary framework for the CFC. Now you're ready to add code to the function, and to make it do something. In this case, you'll create a query that you can access in a few different ways. First, you'll call all the employee's information from the database and sort it. Second, you'll want to create a function where you can search for an employee by name. By using a CFC, you can call the query from any ColdFusion pages or application on your ColdFusion server. You can even add more features to the query over time, if necessary.

Testing your CFC
To test the CFC, create an HTML form and a CFML action page. Your CFML action page will call the CFC.

Create an HTML form where the end-user will enter a search criteria (in this case, a last name). Create a file named employeename1.cfm and save it in your ColdFusion webroot. The file should have the following code:

 <html>
   <head>
   <title>employeename1</title>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   </head>

<body>
   <!---First form: This form submits the end-user's search criteria--->
   <form name="form1" method="post" action="employeename2.cfm">
   <p>Search for employee: 
   <input type="text" name="LastName">
   </p>
   <p>
   <input type="submit" name="Submit" value="Submit">
   </p>
   </form>

<!---Second form: This form submits no search criteria--->
   <form name="form2" method="post" action="employeename2.cfm">
   <p>Return all employees: <input type="submit" name="Submit2"
      value="Submit"></p>
   </form>
   
   </body>
   </html>

Now that you have created a form that passes information to your CFML action page (and your CFC), you'll create the action page that invokes the CFC and displays the result.

Now, you have a page that calls the CFC, and the CFC works, but you'll need to add code to display the results that are returned. Add the code in the Design view mode or the Code view mode, whichever you prefer. For this example, it is preferable to add the changes within the Code view mode.

Testing your application
Now you have a small ColdFusion application and you are ready to test it. Browse to http://localhost:8500/employeename1.cfm (please change this URL based on the port number where you're running ColdFusion MX, and where your file, employeename1.cfm, is located in your ColdFusion MX webroot).

The following form displays in your browser:

Click the second Submit button, next to "Return all employees." The action page displays an entire list of people from the database. Enter"al" in the form field, and click the first Submit button. The action page displays only people with "al" in their last name.

This one CFC allows you to get as many different result sets as you like. The advantage is that you can keep all of your database logic in one place in your application and not on each individual ColdFusion page. If you need to change the query, or add new functionality, you do it all in one file instead of several ColdFusion pages.

Consuming a web service
Web services are similar to CFCs in that they are encapsulated functionality that you can access in your website. For this example, you'll create a currency exchange calculator that you can use in your pages without having to create the code or maintain it by getting the daily exchange rates for hundreds of currencies. Simply create a form and pass the variables to a web service, and then use the cfoutput tag to insert the returned values into your page.

Before you start, ensure that you have a live connection to the web. It is necessary to consume a web service.

Now that you have invoked the service, you need to pass values for the cfinvokeargument tag, so the service has data to process in the currency conversion. Below, you'll create a way to display the rate in the ColdFusion page.

You have the page that references the web service and displays the return results. Now, create an HTML form that calls currencycalculator.cfm. Ensure that your field names in the HTML form match the values in the cfinvokeargument tags. Additionally, set the form action to go to currencycalculator.cfm. Your HTML form would have the following code:

<html>
  <head>
  <title>Untitled Document</title>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  </head>

<body>
   <form name="form1" method="post" action="currencycalculator.cfm">
   <p>Currency 1: 
   <input type="text" name="currency1">
   <br>
   Currency 2: 
   <input type="text" name="currency2">
   </p>
   <p>
   <input type="submit" name="Submit" value="Submit">
   </p>
   </form>
</body>
</html>

Browse your form from a browser. For currency 1, enter "newzealand," and for currency 2, enter "usa." Click Submit. Your form passes the values for currency1 and currency2 to currencycalculator.cfm. Currencycalculator.cfm invokes the web service and receives the form data. The web service processes and returns a number in the variable named "aRate." Currencycalculator.cfm displays the currencies and rate.

You could use additional math functions and operations in ColdFusion to easily convert the money amounts instead of returning the rate for different countries.

Try out your currency conversion application with a few of the following countries for the currencies, such as china, germany, france, dijibouti, swaziland and canada.

Where to get more information about CFCs and web services
You can get a lot of information about CFCs on the Macromedia DevNet. Additionally, the ColdFusion MX documentation, which is installed by default, also has information to help you get started with developing ColdFusion MX applications.

For more information on web services, there are hundreds of resources. Some preferable resources are as follows: