Creating and consuming ColdFusion components and web services with Dreamweaver CS4

Note: This is an updated version of an article written in 2002 by Matt Brown.

Adobe ColdFusion 8 has numerous features that can help you create more powerful Internet applications than you ever have before. Among the most important capabilities made possible by these features are the ability to create components and the ability to consume web services. ColdFusion components (CFCs) are ColdFusion files that encapsulate application functionality and make that functionality available to browsers, other applications, Adobe Flash Players, and web services. They provide a simple and flexible way to maintain and reuse your code as you work, and they separate the logic from your pages. Adobe Dreamweaver CS4 makes it easy to create and consume components and web services using ColdFusion 8.

In this tutorial, you'll learn how to create simple ColdFusion components through manual coding in the Dreamweaver CS4 Code view and through the Dreamweaver CS4 Create Components dialog box. I'll show you how to consume the CFCs and how to consume a web service.

Web services are similar to CFCs in that they are applications into which you feed data and then receive some information. They allow you to add functionality to your site without having to create the back end for those pieces of your application. For example, if you were creating an online store and needed instant currency conversions, you could use web services. Or, you may want to be able to tell visitors 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 on the web that your applications can consume through ColdFusion 8.

Note: Due to the simple nature of the example CFC described in this article, and the introductory nature of the article itself, the example CFC does not use the var scope. The var scope prevents variables within CFC methods from leaking out and causing possible bugs. For more details on the var scope, see Creating user-defined functions.

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

To start creating a CFC, follow these steps:

1. Create a folder named myCFC in your ColdFusion 8 web root. You can either put the CFC and ColdFusion pages in a separate folder, like an asset, or in the same folder as the group of CFML pages that use the CFC. Regardless, Dreamweaver CS4 will locate them and make all CFCs in your defined site available to all other CFML pages in the website. You can store CFCs anywhere in your web root, but it is a best practice to keep them in a separate folder.
2. Open Dreamweaver CS4 and choose File > New.
3. In the New Document dialog box, select ColdFusion component as the Page Type. Click Create.
4. Choose File > Save. Save the CFC in the myCFC folder with the name TestCFC.cfc. Note that the file extension is CFC and not CFM.

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

Because you selected ColdFusion component when you chose the type of file to create, the CFC you created has the following code:

This is simply one large nested tag in a file with nothing else in it, but CFCs are much more. They can provide web services and can be used in any of your ColdFusion 8 and Adobe Flash applications. (For examples on how to use CFCs with Adobe Flash and Flash Remoting visit the ColdFusion 8 Developer Center.)

The cfcomponent tag denotes 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 that you want to move to a separate file to improve code maintainability. Inside the cffunction tag, you can process as much ColdFusion code as you like.

The cffunction tag has multiple attributes. Dreamweaver CS4 inserts three attributes by default:

• name: The name of the function needs to be unique in the CFC page so that you can call each function individually. As with JavaScript functions, there should be no spaces in the name.
• access: This determines who can access the component method by client type. Leave the access set to public, which means that any other CFML page on the ColdFusion server can access the CFC.
• returntype: This attribute gives data type validation for returned values. Leave this attribute in your code.

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

By default, when you create a CFC in Dreamweaver CS4, 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 it. This example will not use the cfargument tag, so you can delete it for now. I'll talk about how to use it in the next example. Within the cffunction tag, you will use the cfset tag to create a variable or variables that will hold the function result.

The following example creates a date for the CFC to return to the calling CFML page. To create it:

1. Open TestCFC.cfc if it is not already open in Dreamweaver CS4.
2. Change the cffunction name attribute to myDateFunction:

3. Place your cursor before the following line:

4. Press the Enter key to insert a line.
5. Create a cfset tag with a variable named mydate that creates a date, as follows:

6. Format the date created with the mydate variable in the previous step. Change the cfset for the variable myResult, so that it uses the dateformat() function to format the date.

In short, edit the following line:

Change it to:

Your function should now be coded as follows:

7. Save the TestCFC.cfc file.

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

1. After the closing cffunction tag, press the Enter key to insert a new line.
2. Start typing <cffunction>. As you type the tag, Dreamweaver's auto-complete feature displays tags for you to choose from. When you have typed <cffun you can see that the auto-complete feature selects the <cffunction> tag. Press the Enter key to select the cffunction tag and display it as code on your page.
3. Note that the cffunction tag is not complete. There is no closing bracket for it. This indicates that attributes are missing. Press the spacebar in the cffunction tag, and note that Tag Insight displays multiple attribute choices appropriate for the cffunction tag. You can press the Down Arrow key to select an attribute to enter for the tag. In this case, select the name attribute and press the Enter key. Note that the name="" attribute has been inserted in the cffunction tag, and your cursor is located between the quotes for the name attribute value.
4. Type myTextFunction as the name of your new function, and place your cursor after the closing quotation.
5. Press the spacebar and select the returntype attribute from the attribute list. Press the Enter key and insert the returntype attribute into the cffunction tag. Note that your cursor is located between the quotes for the returntype attribute value. Select string for the returntype attribute value.
6. Type a closing bracket (>) to close the cffunction tag. This will close the opening cffunction tag, and insert a closing </cffunction> tag.
7. Place your cursor between the <cffunction> and </cffunction> tags to enter your new function. Press the Enter key several times to create blank lines.
8. In the blank lines, type the following:

9. Press return. Your function should look like the following snippet:

10. Save your TestCFC.cfc file.

Now that you have created a simple CFC with two 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.

1. Ensure that you have a ColdFusion site defined in Dreamweaver CS4 on your machine.

   Note: For more details on how to set up a site in Dreamweaver, see Setting up a Dreamweaver site in Dreamweaver Help.

2. Create a new CFML page in Dreamweaver CS4. Select File > New. Select ColdFusion in the page type column.
3. Save your file as Test.cfm.
4. If you are not in Code view, switch to it. Note that you could insert CFCs into your page in Design view, but the code will not be displayed visually. This makes it difficult to call the CFC within your CFML code. It is preferable to create your CFC in Code view.
5. Choose Window > Components (or press Ctrl+F7). Alternatively, click the component tab in the palette if it is visible in your workspace already (see Figure 1).
6. If you don't see any components listed, click the Refresh button and the components will appear.

7. Under the entry for TestCFC, there are two functions. The first function, myDateFunction(), returns the date. The second function, myTextFunction(), prints "The date is: ".
8. Select myTextFunction(), and click the Insert button to insert a call to this function in your ColdFusion Page.
9. You should see code that looks like this:

10. Save your page and press F12 to preview your page in the browser.
11. The following displays in your browser, "The date is: "

When "The date is:" is displayed in your browser, 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 the 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 returns a value. This is the most common sort of CFC. Typically you will want to invoke your CFC, access the result, and present the information on your calling page. To do this, follow these steps:

1. Open the test.cfm page in Dreamweaver CS4.
2. Switch to Code view.
3. Enter a few blank lines after the closing cfinvoke tag.
4. In the Dreamweaver Components Palette, click the Refresh button. Select myDateFunction() from the TestCFC in the Components panel and click Insert.
5. The following code appears in test.cfm:

6. Note that the myDateFunction() function has an attribute named returnvariable. The returnvariable stores the result of the function. The previous function didn't actually return a result, but simply printed its output directly within the call. In this example, however, the result will be stored in a variable called myDateFunctionRet.
7. In Code view, insert a few blank lines after the second </cfinvoke> tag, and type the following line:

8. Verify that the whole file looks like the following:

9. Save the page and press F12 to preview your page in the browser. Your browser should display "The date is:" followed by the current date; for example, The date is: Oct-21-2008.

Now that 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 offer find and search capabilities on any number of pages, but maintain the code in only one place. If you need to change the code later, you only need to change it once, rather than on numerous ColdFusion pages. Additionally, you can access the functionality from other clients, such as Adobe Flash Player, through Adobe 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 CS4.

Create the CFC in Dreamweaver CS4

To create the CF follow these steps:

1. In Dreamweaver CS4 ensure that you are in the ColdFusion 8 web root Site Definition.
2. Click the Components tab. If you can't see the Components tab, choose Window > Components.
3. In the Components tab, click the plus (+) icon to create a new CFC through the Create Component dialog box.
   • In the dialog box, for the Display Name, type FindArtist. This is the component name that you'll reference when you call the CFC.
   • In the Name field, type FindArtist. This will be the name of the file in the file system.
   • For the Component directory, select the myCFC directory. It isn't necessary to keep all components in one place, since both Dreamweaver CS4 and ColdFusion 8 search for all the components in your site and make those available to you when you author anything in a ColdFusion site. However, it is a best practice to keep them all in the same place.

   Your screen should display the entries shown in Figure 2.

Note: The Component directory location will be different based on where you created your myCFC folder.

Leave the other fields empty. For more information on these fields, refer to the ColdFusion 8 documentation.

4. Click Functions under the Section area. From the Function view, click the plus (+) icon to add a function.
5. For the function name, type FindArtistSort. Select remote for the Access option, and select query for the Return Type (see Figure 3). You can select one of several return types depending on what you wish to return to the calling CFML page.

6. Click OK.

Dreamweaver CS4 creates the necessary framework for the CFC:

Now you're ready to add code to the function 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 retrieve artist information from the database and sort it. Second, you'll create a function to search for an artist 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.

1. Open FindArtist.cfc in Code view in Dreamweaver CS4.
2. Enter a few blank lines after the opening cffunction tag.
3. Enter the following code on the blank lines:

This query selects all of the information in the Artists table from the cfartgallery data source. The cfartgallery data source is part of the example applications that were installed with your copy of ColdFusion 8. The query checks whether an argument called LastName was passed into the method from the referring page.

If the referring page passed the LastName argument, the query uses the WHERE clause. The WHERE clause filters the query results, returning any last name that matches a combination of letters passed in the arguments.LastName variable. If the referring page does not pass LastName, the query returns a recordset for all the artists, sorted in ascending order by their last name.

4. Now you'll specify what the CFC returns to your ColdFusion page. Modify the cfreturn tag after the query and before the closing cffunction tag to:

The cfreturn tag will return the artistQuery so that you can loop through the returned data, as if the query were on a regular ColdFusion page.

5. Your FindArtist.cfc should look like this:

6. Save FindArtist.cfc.

Test 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 user will enter search criteria (in this case, just a last name). To do this, create a file named artistname1.cfm and save it in your ColdFusion web root. The file should have the following code:

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.

1. Choose File > New. In the New Document dialog box, select ColdFusion from the Page Type column and click Create.
2. Save the file to the ColdFusion 8 web root. Name the file artistname2.cfm.
3. From the Components palette, click Refresh and find the FindArtist.cfc you created. Click the CFC to expand its functions.
4. Click the FindArtistSort function and drag it into the body of your artistname2.cfm file.

   Your page should look like the following:

5. Save artistname2.cfm.

   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 Design view or Code view, whichever you prefer. For this example, I prefer to add the changes in Code view.

6. Insert a few blank lines after the closing cfinvoke tag and add the following code:

7. Save artistname2.cfm

Test your application

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

Figure 4 shows the form displayed in your browser.

Click the Submit button next to Return all artists. The action page displays an entire list of people from the database. Type al in the form field, and click the first Submit button. Notice that the action page still displays all the artists. Why? Your CFC method was built to accept the LastName argument, but the code never actually passed it. Modify the code to look for, and pass, the form value if it exists.

1. Open artistname2.cfm.
2. Before the cfinvoke tag, add this code:

3. Modify the cfinvoke tag to pass in the lastname value:

4. Add a cfelse tag after the cfinvoke.
5. You can now drag the FindArtistSort from the CFC in the components panel. Or you can cut and paste the cfinvoke tag above, but remove the lastname argument.
6. Your completed code should look like this:

7. Save your file and test the page again. Now the results will be filtered correctly if you enter a value in the input text field.

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.

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 weather information component that you can use in your pages without having to create the code or maintain it by getting separate daily temperatures for dozens of zip codes. 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. This is necessary to consume a remote web service.

Note: This section makes use of a Dreamweaver CS4 feature that is only available on Windows machines. You will not be able to introspect a web service on a Mac OS X machine. You can, of course, still use ColdFusion on Mac OS X and run code that makes use of web services. You just can't use the built-in Dreamweaver's tool to examine the web service.

1. Create a new ColdFusion document and save it as weathercalculator.cfm in your ColdFusion 8 web root.
2. Ensure that the Component Palette is visible in Dreamweaver CS4.
3. In the Component tab, select Web Services from the context menu. This panel lists all of the web services to which you have subscribed, and can therefore insert.
4. To subscribe to a web service, click the plus (+) button. In the Add Using WSDL dialog box, set the Proxy Generator to ColdFusion MX if it is not already selected. Click the globe icon and select xMethods from the context menu (see Figure 5).

5. This opens the xMethods website. At the xMethods website, you can choose from many services. For this example, select CDYNE Weather - FREE from xmethods.net.

   When you click the link in the list, it displays the service's details and instructions on using it. For this example, look for the WSDL URL, which is highlighted in yellow. (If you have trouble finding it, use the URL in Step 6.)

6. The following URL is listed at the end of the WSDL line on the page in yellow highlighting:

Copy and paste it into the WSDL dialog box as the URL of the WSDL file. ColdFusion uses this URL to access the web service.

7. Click OK. This adds the new web service to the Components Palette.
8. Click the getCityWeatherByZIP entry and drag it to the body of your page.
9. Your file should look like this:

10. Save weathercalculator.cfm.

Now that you have invoked the service, you need to pass a value for the cfinvokeargument tag, so the service has the zip code it needs to get weather information. You also need to display the temperature in the ColdFusion page.

1. In weathercalculator.cfm, switch to Code view. In the first cfinvokeargument tag, replace "enter_value_here" with #zip#. This passes the zip code that you're going to pass from the form calling this page on to the web service.
2. Enter a few blank lines after the closing cfinvoke tag and type the following:

3. Your page should look like the following:

4. The temperature value is returned as part of a structure of other information in the web service. You can expand the structs/WeatherReturn node for more details.
5. Save weathercalculator.cfm.

You have the page that references the web service and displays the return results. Now, create an HTML form that calls weathercalculator.cfm. Ensure that your field names in the HTML form match the value in the cfinvokeargument tag. Additionally, set the form action to post to weathercalculator.cfm. Your HTML form should have the following code:

Access your form from a browser. For the zip type 70508 (or your own zip code). Click Submit. Your form passes the value for zip to weathercalculator.cfm, which in turn invokes the web service using the form data. The web service processes and returns a structure in the variable aWeatherReturn. Weathercalculator.cfm displays the zip and the temperature.

Where to from here

You can get much more information about CFCs on the Adobe Developer Connection. Additionally, the ColdFusion 8 documentation, which is installed by default, also has information to help you get started with developing ColdFusion 8 applications.

For more information on web services, there are hundreds of resources. Some of my favorite resources include the following sites:

• XMethods (Lists many publicly available web services.)
• IBM web services (Requires free registration.)
• Microsoft web services (Has a list of UDDI services and resources.)
• www.webservices.org (Great resource for web services information and tutorials.)