Making Client Access Easier: Web Services and Components

     

Making Client Access Easier: Web Services and Components

Web services, using Simple Object Access Protocol (SOAP), are the emerging standard for making application services available over the Internet.

The Dreamweaver/ColdFusion combination may be the easiest way currently available to create and deploy a Web service. Dreamweaver can also help you build HTML/CFML pages that consume (use) Web services.

In ColdFusion, a Web service is embodied in a ColdFusion component (CFC), a data structure containing functions that clients can call. Every CFC is not a Web service, but every Web service in ColdFusion is a CFC. First, we'll see how Dreamweaver can help you create and invoke a CFC. Then we'll look at Dreamweaver's features for creating a Web service.

For more on CFCs, see "Creating and Using ColdFusion Components (CFCs)," page 903 , in Chapter 33.

Creating a CFC

You can create a working CFC in Dreamweaver by choosing File, New, selecting Dynamic Page and ColdFusion Component, and clicking Create. The CFC contains one function, myFunction , which takes one argument, myArgument , and returns the string "foo" to the client.

NOTE

A function is a block of code embodying a procedure.

NOTE

An argument is a data object passed to a function.

It looks like this:

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

This code is meant to be used as a template for creating more useful CFCs. For example, as it stands, the function doesn't even do anything with the argument that is passed to it. However, creating a useful function would involve programming in CFML, which is not our focus here. Therefore, I'll use this component as an example. All you have to do to create the component is save the file you have just created. Dreamweaver automatically uses the extension .cfc . (In the examples that follow, the file is named myCFC.cfc .)

Invoking a Function in a CFC

After the CFC has been created, the next step is to create a page that invokes (calls) a function in the CFC. This is a simple two-step process:

1. Create a ColdFusion page: Select File, New to bring up the New Document dialog. In the Category column on the left, select Dynamic Page. In the Dynamic Page column on the right, select ColdFusion. Finally, click the Create button in the lower-right corner of the the New Document dialog.
   
   
2. Find the function on the Components panel in the Application panel group , and drag and drop the function into the document window. In the case of myCFC , there is just one function: myFunction .
   
   

The second step involves selecting CF Components in the drop-down menu at the top left of the Components panel, if it is not already selected. All the sites containing components will be listed. Expand the site that contains the component, and expand the component itself, so that you can see its functions. In Figure 13.24, for instance, the greendept site and the myCFC component are expanded, revealing the myFunction function.

Figure 13.24. The Components panel. Drag and drop a function from a CFC into the document window, and Dreamweaver auto-generates the code to invoke that function.

When that function is dragged into the document window, this code is automatically created:

 <cfinvoke  component="greendept.myCFC"  method="myFunction"  returnvariable="myFunctionRet">      <cfinvokeargument name="myArgument" value="enter_value_here"/> </cfinvoke> 

Substitute a value where Dreamweaver auto-generates enter_value_here . The value you enter gets passed to the function as an argument. In a real-world application, you would also make some use of the return value, myFunctionRet , in your Web page. One possible use is simply to display the return value ( "foo" ) by using cfoutput . You can do this at any point in the body of your document following the function invocation. For instructions, see the sidebar, "Using the Insert Bar to Create Instant CFML Tags."

Using the Insert Bar to Create Instant CFML Tags

The CFML category on the Insert bar allows you to create CFML tags by filling in values on dialogs. After you are familiar with the tags, the use of the dialogs is intuitive. For instance, to display the return value, myFunctionRet , you can use the following procedure:

1. On the Insert bar, select the CFML category.
   
   
2. Type myFunctionRet in the document window and select it.
   
   
3. Click the Surround with # button (the fourth button from the right). Dreamweaver auto-generates pound signs around myFunctionRet , making it a variable.
   
   
4. Leaving the selection highlighted, click the Out button (the third button from the left). Leave all the fields on the Tag Editor dialog blank and click OK. Dreamweaver auto-generates <cfoutput></cfoutput> tags around the selection.
   
   

This results in:

 <cfoutput>#myFunctionRet#</cfoutput> 

This will display the return value in the browser when the page is loaded.

Creating a Web Service CFC

Dreamweaver can auto-generate a CFC designed specifically for use as a Web service. A Web service CFC can be somewhat complex, and one has to understand those complexities to fully understand the Dreamweaver interface for creating a Web service CFC.

For more on Web Service CFCs, see "Creating and Using Web Service CFCs," page 904 , in Chapter 33.

In this section, however, I'll just illustrate the Dreamweaver workflow for creating a simple Web service CFC. Here's the procedure:

1. On the Components panel, with CF Components selected in the drop-down menu, click the plus sign to the right of the drop-down menu. The Create Component dialog appears (Figure 13.25). This dialog has four sections: Components, Properties, Functions, and Arguments. We'll just use Components and Functions here.
   
   

   Figure 13.25. The Components section of the Create Component dialog. The lower two parameters, Name and Component directory, are required. Others are optional.

   

   
   
2. In the Components section, the only required fields are the component name (the name of the CFC file) and the component directory. In Figure 13.25, there is also a Display Name, a name formatted for display to the end user .
   
   
3. In the Functions section (Figure 13.26), click the plus sign at the top. The word "Function" will appear in the Functions box and in the Name box.
   
   

   Figure 13.26. The Functions section of the Create Component dialog. You can add as many functions as you want. Access must be set to remote, so that remote clients can access the Web service. A Return type is also a requirement for the CFC to work as a Web service.

   

   
   
4. In the Name box, select the word "Function" and change it to the name of your function. Click the plus sign again, and the name will change in the Function box, as well. In Figure 13.26, the name was changed to getSiteName .
   
   
5. In the Access drop-down menu, select Remote. This enables remote clients to access your CFC via an HTTP URL.
   
   
6. Select an appropriate return type, depending on what type of value the function returns, such as a number, a date, or a string. You must select a return type!
   
   
7. Click OK. A Web service “ready CFC will be generated and opened for editing ( getSiteName.cfc in this case).
   
   

NOTE

Be sure to declare a return type. The CFC requires it to work as a Web service.

You can add as many functions as you want by repeating steps 3 and 4.

In general, CFCs generated using the Create Component dialog are used as templates, and fleshed out with more CFML coding to create a useful component. The getSiteName CFC needs a little bit of editing to be even minimally useful. Here's the completed code. Only the words "The Green Department" were added by hand. Everything else was generated by Dreamweaver.

 <!--- Generated by Dreamweaver MX 2004 7.0.2052   (Win32) - Mon Sep 15 19:26:23 GMT-0500  (Central Daylight Time) 2003 ---> <cfcomponent displayName="Get Site Name">      <cffunction name="getSiteName" access="remote" returnType="string" output="false">           <!--- getSiteName body --->           <cfreturn "The Green Department">      </cffunction> </cfcomponent> 

You can drag and drop the getSiteName function into the document window from the Components panel to create a page that invokes the function, as illustrated in the previous section with myCFC.

In addition, the getSiteName function is formatted to work as a Web service, with four parameters: name, access, returnType, and output. Nothing more needs to be done to the CFC to make it accessible as a Web service. However, on the client side you need to create a proxy and a page with code that invokes the getSiteName function. Dreamweaver makes both tasks straightforward, as demonstrated in the next section.

Consuming Web Services

As discussed in Chapter 32, the Web services architecture requires the client to consume the Web service via a proxy.

For an overview of the ColdFusion Web services architecture, see "Using Flash to Access the ColdFusion Server," page 878 , in Chapter 32.

Dreamweaver makes it easy to create the required proxy. Here's the procedure:

1. On the Components panel, select Web Services in the drop-down menu, if it is not already selected.
   
   
2. Click on the plus sign. The Add Using WSDL dialog appears.
   
   
3. Enter a URL. For most Web services, this will be the URL of a Web Service Description Language (WSDL) file. For instance, for the BabelFish translation service, the URL is http://www.xmethods.net/sd/2001/BabelFishService.wsdl. For a CFC, however, give the URL of the CFC, followed by ?wsdl. For instance, to add the getSiteName CFC as a locally accessible Web service, you use the following URL, as shown in Figure 13.27: http://localhost:8500/greendept/getSiteName.cfc?wsdl
   
   

   Figure 13.27. The Add Using WSDL dialog creates a proxy on the ColdFusion server, enabling clients to access the CFC as a Web service. The name of the service appears in the Components panel.

   

   
   If the CFC were deployed on the Internet, it might be specified like this: http://www.myDomain.com/greendept/getSiteName?wsdl
   
   
4. Click OK. The Web service proxy is created in the ColdFusion server, and the Web service (getSiteNameService in this case) appears in the Components panel.
   
   

After you have created the proxy, creating a page to access a Web service function is easy: Just drag and drop the function into the document window. Here's the auto-generated code for the getSiteName function:

 <cfinvoke  webservice="http://localhost:8500/greendept/getSiteName.cfc?wsdl"  method="getSiteName"  returnvariable="aString"> </cfinvoke> 

As before, you now have a return variable that you can use on your Web page. For instance, <cfoutput>#aString#</cfoutput> following the invocation displays the words "The Green Department".