In Part 1 of this two-part article (MXDJ, Vol. 2, issue 3) I showed how to invoke a Web service for the purpose of validating user input. Part 2 will delve a little deeper into the ColdFusion MX language structure specifically designed to handle XML result sets such as those returned from a Web service. The goal is to consume a Web service that will return headline news articles for a user-specified topic. When finished you will be able to add a live user-interactive newsfeed to your Web site.
This article will cover:
- XmlParse(): Returns an XML Document object
- XmlRoot property: Root element for an XML Document object
- XmlName property: Element name
- XmlChildren[1]: Referencing the first row in an array containing the child nodes for a specified element
- XMLSearch(): Search routine that returns an array of nodes that match a provided XPath expression
- Error trapping with <cftry> and <catch>
Choosing the Web ServiceOne resource for locating Web services is located at
www.xmethods.com, where you will find the Web service (
www.xmlme.com/WSCustNews.asmx?WSDL) that will be used for this article. This particular Web service returns a string that is in an XML format; other Web services may return different values. The Axis engine that is built into ColdFusion MX will deserialize these return values, creating a data type you can use.
Testing the Web Service
Now that the decision has been made as to what we want done and where to find the Web service that will provide the necessary information, the next step is testing the Web service. Testing will answer two questions.
- Does the Web service work?
- What is the Document Tree for the returned result set?
The easiest way to perform these tests is using the Dreamweaver MX Components tab that is located on the Application panel (see Image I). From this tab you can add information on a Web service, including a document tree. Click on the + button to open the "Add using WSDL" window (see Image II), enter the URL for the WSDL file, and click on the <OK> button.
A new entry will be added to the Component tab of the Application panel. Click on the new entry to view the document tree for the WSDL file (see Image III).
Using the file administrator, open a new document and drag-and-drop the new Web service into the new document as shown in Image IV.
You have now created the basic coding necessary for consuming the Web service. The code sample created by Dreamweaver MX shows one argument being passed to the Web service (topic), and the result set returned from the Web service will be stored in the aString variable. Replace "enter_value_here" with the word "Sacramento", which will provide a topic for the Web service to search on for the test.
The next step will be to add the coding to display the results returned from the Web service (see Image V). For displaying the results the XmlParse() function and <CFDUMP> tag are used. XmlParse() is a new function that accepts XML code as a string and returns an XML Document object that represents the various XML elements contained in the document. Image VI shows the results of the <CFDUMP>.
The User Interface
Now that the Web service has been selected and tested, the next step is to create an interface where the user can enter a topic of his or her choice and display the resulting headlines. The following list is a very simplified view of the desired process flow for the user interface.
- Display entry field for user to enter topic.
- Invoke Web service, passing user input as an argument and using a default value for topic if one is not provided.
- Display the result set if there are no errors.
- Display a message if there is an error.
The single most important variable in the completed form will be the topic being passed to the Web service as an argument. A default parameter, sTopic, will be created and a blank value assigned. This variable will control when the <CFINVOKE> tag is executed. The code will be executed only if sTopic has a value.
Another parameter will be the number of articles returned by the Web service, defaulting to zero. If the Web service returns a result set, this variable will be populated with a count of the number of headlines received.
<CFPARAM NAME="sTopic" DEFAULT="" />
<CFPARAM NAME="xCount" DEFAULT=0 />
With the default values out of the way the next step is to create the GUI. This will consist of a title, one label, an input field for the topic, and a submit button. This will be a rollover form so the CGI.SCRIPT_NAME variable is used to force the page to call itself on post (see Code I). Image VII shows the user input form for topic.
Consuming a Web service, just like accessing a database, should be treated as if there is a good chance the service will be unavailable, the return results are corrupted, or there are no results returned. With a database error you typically receive an error code that can be responded to. When you attempt to consume a Web service, the errors will vary and may be hard to account for. These potential problems are easily dealt with by placing the <CFINVOKE> code inside a <CFTRY>.
The entire code segment is placed inside a conditional statement that prevents the code from being executed unless the form has been submitted and a topic has been provided by the user (see Code II).
In Code II new properties (XmlRoot, XmlName, XmlChildren) and the XMLSearch() function have been introduced. The coding combination ensures that if the provider of the Web service changes the root or child element the program still has a good chance of retrieving the desired information without any modifications.
<cfset xRoot = MyXml.Xmlroot>
Retrieves information about the root element.
<cfset bNode = xRoot.XmlName>
Retrieves the name of the root element. In this case it is "moreovernews" (see Image VI).
<cfset cNode = xRoot.XmlChildren[1].XmlName>
Retrieves the name of the first child element. In this case it is "article" (see Image VI).
The combined results of these three <CFSET> calls provide the second parameter needed for the XMLSearch() function. This function will return an array containing the headlines received from the Web service.
The next line (<cfset xCount = arraylen(myNewsFeed)> ) returns a count of the number of elements (headlines) the XMLSearch() function found. This count will be used for a looping routine to display the result set and controlling whether or not the results code segment is executed.
The next step is to display the headlines to the user. The displaying of this code will be determined by the value of the xCount variable (see Code III). If the Web service returns a result set the value will be greater than zero and can be displayed (see Image VIII). A looping routine will be used to iterate over the result set, displaying the headline_text, source, and harvest_time elements. The url element will be used to create a hyperlink to view the entire story in a separate window (see Image VI).
Typically there are two types of problems with which a Web service will most likely return an error.
- A connection to the Web service cannot be made.
- The Web service does not know how to deal with the information provided as the argument (such as a topic where no headlines are found).
To handle these problems a <cfelseif> condition will be added to the code that displays the result set (see Image VIII). Code IV verifies that the form has been submitted and a topic was provided, but the xCount is equal to zero. If either of these problems are encountered a message will be displayed to the user (See Image IX).
Summary
Once you start working with the code presented in this article you will find that there are endless possibilities for creating new types of dynamic user-interactive Web pages. Companies such as Amazon.com and eBay have already started providing access to their engines via Web services that will greatly shorten development time. For example, with minimal programming, you can create fully operational e-commerce sites using another company's stock and their Web services.
In my next article you'll learn how to shorten your development time even more by taking this same Web service and applying an XSLT style sheet. Once it's applied, you'll find that your completed Web pages can be more dynamic and, with a few simple conditional statements, display the same information in an unlimited number of formats.
Subscribe to Adobe Flex Journal Email News Alerts
Subscribe via RSS
