Using the WebServiceConnector with SOAP Web Services

Simple Object Access Protocol (SOAP) is another protocol for web services. It uses XML to request information from the web service in a SOAP message. It receives an XML document in response. SOAP messages can be sent using HTTP and even by email. Flash only supports HTTP-based SOAP messages.

To consume a web service, a SOAP message containing the request is sent to a receiver. The receiver processes the request and acts upon it, usually running a remote method in a web application. The method returns the results to the requester in XML format.

Web Services Description Language (WSDL) is an XML-based language that describes how to access the web service. The WDSL document for a web service lists the methods or functions that a web service can perform. It specifies how to make the request and what information youll need to provide. You should consult the WDSL document before you start working with SOAP web services. Luckily, Flash does this for you automatically.

For example, the WSDL file for Google web services lists three methods: doGetCachedPage , doSpellingSuggestion , and doGoogleSearch . You can see the details of these methods if you visit http://api.google.com/GoogleSearch.wsdl. Later in this chapter, youll see how the WebServiceConnector component finds these methods automatically.

Using SOAP in Flash

Flash Professional can work natively with SOAP requests . You can use the WebServiceConnector component to query a WDSL file and generate a SOAP request for you. You can also script the WebServiceConnector class.

Each WebServiceConnector component can work with only one operation at the web service. The connector can call the same operation more than once. You need to add extra WebServiceConnector components if youre calling more than one operation in your application.

Using the WebServiceConnector

The WebServiceConnector is available in Flash Professional. Like the other data components, it has no visual appearance in a compiled Flash movie. When you drag the WebServiceConnector to a movie, Flash displays the icon shown in Figure 9-9.

Figure 9-9: The WebServiceConnector component icon

Configuring the WebServiceConnector

You configure the WebServiceConnector using the Component Inspector panel. To begin, enter the settings in the Parameters tab of the panel. Figure 9-10 shows the panel.

Figure 9-10: The WebServiceConnector parameters

Table 9-1 provides a summary of the parameters in this tab.

Table 9-1: The settings listed in the Parameters tab of the Component Inspector
Parameter	Purpose
WSDLURL	Specifies the path to the WSDL document for the web service.
operation	Contains the name of the remote procedure or method specified within the WSDL.
multipleSimultaneousAllowed	Specifies whether to allow multiple connections. If you set this property to false , when you are triggering one XMLConnector, you cant trigger others.
suppressInvalidCall	Sets the behavior for invalid data parameters. If you set the value to true , the component wont be triggered if the parameters are invalid.

You start by entering the URL for the WSDL document. You can either type the URL or copy and paste it from another location. If youve entered the URL previously, you can also select it from a drop-down list. If Flash finds a valid WSDL document at the URL, it will populate the operation setting with all available procedures for the web service. This may take a few seconds.

Figure 9-11 shows the operations available after entering the Google WSDL URL http://api.google.com/GoogleSearch.wsdl. Google provides three operations through its web services: doGetCachedPage , doSpellingSuggestion , and doGoogleSearch .

Figure 9-11: The operations available from the Google WSDL document

After youve selected the operation, you dont normally need to change the last two settings in the Parameters tab, multipleSimultaneousAllowed and suppressInvalidCall .

Once youve selected an operation, the Schema tab of the Component Inspector will identify any parameters required by the web service as well as show you the structure of the results. Figure 9-12 shows the Schema tab after selecting the doGoogleSearch operation.

Figure 9-12: The Schema tab available after selecting an operation

The params section identifies information required by Google, and the results section provides the structure for the returned results. You can find out more information about each element by viewing the settings below the structure pane.

Binding the params

Often, youll need to enter different parameters each time you call the web service. You can achieve this by binding the params to UI components such as TextInputs. For example, in the case of the Google search, the q parameter represents the search query, so you could bind it to a TextInput component. Click the Add binding or + button in the Schema tab and select a parameter, as shown in Figure 9-13.

Figure 9-13: Adding a parameter binding

Set the direction to in since the component is sending the value in to the parameter. Then select the UI component that will supply the value for this parameter. In Figure 9-14, weve selected the text property of the search_txt component.

Figure 9-14: Selecting a component for the binding

You can also specify a fixed value for parameters that wont vary. You might do this if you need to send a developer token or ID with your request. Again, youd add a binding and set the direction to in . Instead of selecting a component, check the Use constant value check box and enter the value. Figure 9-15 shows a binding with a constant value of 10.

Figure 9-15: Entering a constant value for the binding

Bear in mind that storing a developer token or ID value within Flash is not very secure. If you are concerned about security, a better approach is to request the value from a server-side file or load the token with the page hosting the Flash movie.

Triggering the web services call

Before you receive the results from your request, you must trigger the call to the web service. As with the XMLConnector, you can use the Behaviors panel to generate the ActionScript, or you can add the code yourself.

When you work with web services, youll often add the trigger to a button instance. Select the instance and bring up the Behaviors panel with the SHIFT-F3 shortcut key. Click the Add Behavior button and select Data Trigger Data Source . Figure 9-16 shows how to add this Behavior.

Figure 9-16: Adding a Behavior panel to trigger the WebServiceConnector

Youll need to select the component to trigger from the Trigger Data Source dialog box, as shown in Figure 9-17. You can insert either a Relative or an Absolute path to the WebServiceConnector component. I normally choose a relative path in case I need to rearrange my movie timelines later.

Figure 9-17: Selecting the Data Source component to trigger

In the case of a button instance, Flash will add the following code:

 on (click) {   // Trigger Data Source Behavior    // Macromedia 2003   this._parent.WSCInstanceName.trigger(); }

You could also type this ActionScript yourself or enter an onRelease event handler, as shown in this code snippet:

 buttonInstance.onRelease = function():Void {   WSCInstanceName.trigger(); }

This code would work where the Button and WebServiceConnector components are in the same timeline.

Binding the results

Once youve triggered the component, youll be able to bind the results of your web service request to one or more UI components. Click the Add binding button in the Bindings tab of the Component Inspector and select one of the resulting elements. Figure 9-18 shows the selection of an Array element.

Figure 9-18: Adding a binding for the results

Youll need to set the direction for the binding to out and select a UI component. If you want to bind the results to a data-aware UI component such as the List, ComboBox, or DataGrid, youll probably want to select an element with an Array datatype. You can bind the Array to the dataProvider for the UI component and use a Rearrange Fields formatter to determine which element to use for the label and data properties. Figure 9-19 shows the Bound To dialog box.

Figure 9-19: Binding to the dataProvider of a List component

If the results array has multiple child elements, youll see all of the children in the UI component. In the case of a List or ComboBox component, youll probably need to use a Rearrange Fields formatter so you have more control over which values display.

Select this formatter from the drop-down list in the formatter setting of the Bindings tab. The Rearrange Fields formatter allows you to specify the label and data properties for a List-based component using the names from the results schema. Click the magnifying glass within the formatter options setting and enter the values.

Figure 9-20 shows a sample Rearrange Fields dialog box. The label comes from the title field and the data associated with each item comes from the URL field, so Ive used the setting data=URL;label=title .

Figure 9-20: Setting the Rearrange Fields formatter options

Once youve added this setting, the data will display correctly in the component.

Viewing the Web Services panel

You can view a list of web services that youve worked with through the Web Services panel. Display the panel by choosing Window Development Panels Web Services or by using the CTRL-SHIFT-F10 shortcut ( CMD-SHIFT-F10 on a Macintosh). Figure 9-21 shows the Web Services panel.

Figure 9-21: The Web Services panel

You can expand each web service listed in the panel to see a list of available operations as well as the schema for the params and results . This provides an alternative to using a WebServiceConnector and viewing the Component Inspector.

You can refresh all web services in the panel by clicking the Refresh Web Services button at the top of the panel, as shown in Figure 9-22. This might be useful if youve entered a WSDL URL but cant see any operations listed in the Parameters tab of the Component Inspector.

Figure 9-22: Refreshing all web services

You can also manage the web services in the list by clicking the Define Web Services button at the top left of the panel. Figure 9-23 shows this button.

Figure 9-23: Defining web services

Clicking the button displays the Define Web Services dialog box. You can use the plus and minus buttons at the top of the dialog box to add and remove the URLs for the WSDL documents for each web service. Figure 9-24 shows the Define Web Services dialog box.

Figure 9-24: The Define Web Services dialog box

You can use the panel menu to carry out these tasks , as well as to view the WSDL document in a web browser. Figure 9-25 shows how to view the WSDL document using the panel menu.

Figure 9-25: Viewing the WSDL through the panel menu

The WebServiceConnector component will become a lot clearer when we work through a simple example. In the next exercise, well create a currency converter that uses rates from a web service. Make sure you have an active connection to the Internet before you start the exercise.

Exercise 3. Creating a currency converter using the WebServiceConnector

In exercise 3, well create a currency converter that uses the XMethods currency converter web service. The WSDL is at www.xmethods.net/sd/2001/CurrencyExchangeService.wsdl. At the time of writing, you could see details of the web service at www.xmethods.com/ve2/ViewListing.po?key=uuid:D784C184-99B2-DA25-ED45-3665D11A12E5.

The web service requires two country names. The parameters are country1 and country2 , and both are string values. You can find a valid list of all country names at the XMethods URL given in the previous paragraph. The web service finds the value of the first countrys currency expressed in the second countrys currency. It returns a floating-point number called return .

Because well use a WebServiceConnector component to prepare the SOAP request, youll need Flash Professional to complete this exercise.

Open the starter file currency.fla . Figure 9-26 shows the interface.

Figure 9-26: The currency converter interface

The movie has two ComboBox components: a Convert button and a TextInput component that will display the exchange rate.
Test the movie and check that the ComboBox components populate with the country names. The Combo layer contains the ActionScript used to populate these components. You should see a list of countries in each of the ComboBox components. Figure 9-27 shows country1_cbo expanded.

Figure 9-27: The ComboBox components are populated using ActionScript.

Drag a WebServiceConnector component to the movie and place it off the Stage. Give it the name converter_wsc .
Add the following WSDL for the WSDLURL setting in the Parameters tab of the Component Inspector:

http://www.xmethods.net/sd/2001/CurrencyExchangeService.wsdl
Choose the getRate operation. If you cant see this operation, you may need to wait for a few seconds or refresh the web services in the Web Services panel. Note that you cant proceed unless you are able to choose the getRate operation.
Add a new layer called actions and enter the following code. The code finds the values in the two ComboBoxes. If weve selected two countries, that is, the values dont equal Choose , we trigger the WebServiceConnector component.
```
 convert_btn.onRelease = function():Void {   var country1:String = country1_cbo.selectedItem.label;   var country2:String = country2_cbo.selectedItem.label;   if (country1<> "Choose..." && country2<> "Choose...") {     converter_wsc.trigger();   } } 
```
I wouldnt normally place my ActionScript on two different layers but if you look at the Combo layer, youll see that the populateCombo function is very long.

Before we can test the movie, well add some bindings from the ComboBox components to the params of the web service.
Select the WebServiceConnector component and display the Bindings tab of the Component Inspector. Click the Add binding button and select country1 : String . Click in the bound to setting, choose the country1_cbo and select the value property. Repeat this process for the country2_cbo ComboBox.
Add another binding for the results . Bind it to the text property of the rate_txt TextInput component. Figure 9-28 shows the appearance of the Bindings tab at this point.

Figure 9-28: The completed bindings for exercise 3

Well add some more ActionScript so we can find out about any errors that might occur when we connect to the web service. Add the following code to the actions layer:
```
 var WSCListener:Object = new Object(); WSCListener.result = function(evtObj:Object):Void {   trace (evtObj.target.results); } converter_wsc.addEventListener("result", WSCListener); 
```
The code adds an event listener that responds to the result event from the WebServiceConnector. When this event is detected , the event listener function displays the results in an Output window. If an error occurs, we should see an error message in the Output window.
Test the movie. Select two countries, and you should see an Output window and a rate displayed in the rate_txt TextInput. Youll find the completed file currency_completed.fla with your resources. If you dont see a result, check for error messages in the Output window.

You could extend this example so that the user could enter a currency amount. You could then display the rate as well as the converted value.

In exercise 3, we created a simple currency converter using the WebServiceConnector. The WebServiceConnector created the SOAP request and sent through values from two ComboBox components. Flash received a result value, which it displayed in a TextInput component.

You can also use ActionScript to work directly with the content returned by a web service.

Working with XML content from the WebServiceConnector

In a perfect world, all web services would return content with datatypes that Flash can recognize. However, sometimes the content returned by a web service cant be mapped through the Component Inspector. Instead of an XML object, sometimes a web service returns a string representation of an XML object, which means you must use a combination of components and scripting to load the results.

Next well work through a more complicated exercise in which we use the WebServiceConnector component with ActionScript to populate an application. The application finds the weather at airports around the world, and returns the content as a string of XML information.

Exercise 4: Displaying airport weather with the WebServiceConnector and ActionScript

In this exercise, well use both the WebServiceConnector and the XML class to load the contents from a web service. Well enter a country and display a list of airports. Well then choose one of the airports and display the weather conditions. The application will use two WebServiceConnector components because were requesting two different operations from the web service.

Youll need Flash Professional to work with this exercise because were using WebServiceConnector components. Make sure you have an active Internet connection before you start.

Open the starter file weather.fla . Figure 9-29 shows the interface.

Figure 9-29: The Airport weather interface

The interface shows several UI components and a dynamic text field. Well use two WebServiceConnector components. The first will get the cities for a selected country and the second will get the weather for the selected city.

Configuring the WebServiceConnector components

Drag two WebServiceConnector components to the movie and position them off the Stage. Name them cities_wsc and weather_wsc .
Configure both WebServiceConnector components using the WSDLURL http://www.webservicex.com/globalweather.asmx?WSDL. Select the operation GetCitiesByCountry for cities_wsc and GetWeather for weather_wsc . You may need to refresh the Web Services panel if you cant see the operations.
Select cities_wsc and add an in binding from the CountryName to the country_txt TextInput component. This will send the value from the TextInput to the WebServiceConnector.
Add an out binding from the results string of cities_wsc to the TextArea component. This will allow us to see the content that the web service returns.
Select weather_wsc and add an in binding from the CountryName to the country_txt TextInput component. This binding sends the country name as a parameter to the weather_wsc connector. Bind the CityName to the value property of the ComboBox component. The weather_wsc connector receives the selected city as the second parameter.
Add another binding from the results to the text property of the TextArea component. Again, this will display the results string in the TextArea.

If you tested the movie now, nothing would happen because we still need to trigger the components. Well do that using the two buttons Get cities and Get weather . Well also add a movie clip to show the user that were waiting for results from the web service. This is useful as a call to a web service may take several seconds.

Triggering the first WebServiceConnector component

Open the Library with the CTRL-L shortcut key ( CMD-L on a Macintosh) and drag the loading movie clip to the movie. Place it off the Stage and give it the instance name loading_mc . Well use this clip to show the user that were in the process of requesting information from the web service.

Add the following code on frame 1 of the actions layer:
```
 cities_btn.onRelease = function():Void {   error_txt.text = "";   if (country_txt.text.length > 0) {     cities_wsc.trigger();     results_txt.text = "";     cities_cbo.removeAll();     showLoading();   }   else {     error_txt.text = "Enter a country";   } } 
```
This code runs when the user clicks the cities_btn . The code resets the error_txt text field and checks that the user has entered a country. If not, an error message displays. If the user has entered a country, the function triggers the first WebServiceConnector and resets the results_txt TextArea component. It also removes any existing entries in the cities_cbo ComboBox component.

Finally, the code calls the showLoading function. This function will place the loading_mc on the Stage and disable the two buttons. This shows the user that a call to the web service is in progress.

Add the showLoading function to the actions layer:

 function showLoading():Void {   loading_mc._x = 170;   loading_mc._y = 120;   cities_btn.enabled = false;   weather_btn.enabled = false; }

Test the movie, enter a country, and click the Get cities button. The results will be displayed in the TextArea component. You should see the loading_mc clip on the Stage and the buttons should be disabled. Figure 9-30 shows the interface at this point.

Figure 9-30: The results displayed in a TextArea component

You probably noticed that the web service returned the XML results as a string containing white space. One way to access the contents is using the XML class and an event handler for the result event of the WebServiceConnector.

Formatting the cities XML string

Add the following event listener function on frame 1 of the actions layer. The code looks more complicated than it is, so Ill explain it after the listing.
```
 var CitiesListener:Object = new Object(); CitiesListener.result = function(evtObj:Object):Void {   hideLoading();   var CitiesXML:XML = new XML(evtObj.target.results);   var RootNode:XMLNode;   var City:String;   for (var i:Number = 0; i < CitiesXML.childNodes.length; i++) {     if (CitiesXML.childNodes[i].toString().length > 0) {       RootNode = CitiesXML.childNodes[i];     }   }   if (RootNode.childNodes.length > 0) {     var LookupNode:XMLNode;     for (var i:Number = 0; i < RootNode.childNodes.length; i++) {       LookupNode = RootNode.childNodes[i];       for (j:Number = 0; j < LookupNode.childNodes.length; j++) {         if (LookupNode.childNodes[j].nodeName == "City") {           City = LookupNode.childNodes[j].firstChild.nodeValue;           cities_cbo.addItem(City);        }       }     }     cities_cbo.sortItemsBy("label");    }   else {     error_txt.text = "That country could not be found.";     country_txt.text = "";   } }; cities_wsc.addEventListener("result", CitiesListener); 
```
The CitiesListener listens for the result event of the WebServiceConnector. When the listener detects this event, it calls a function called hideLoading , which well add shortly. It assigns the results from the connector to an XML object called CitiesXML . The code also creates the variables RootNode and City .

The first for loop sets the RootNode . As the white space in the XML string is treated as empty nodes, we have to test for a node that is longer than 0 characters by finding the length . Notice that I used the toString method before finding the value of the length property. This treats the node as a string variable so we can find the length .

The next code block tests for children of the RootNode . If there are no childNodes , no cities were found by the web service and the code will move to the else section, where it will display an error message.

If the web service returns cities, the code loops through them, finds nodes with the name City , and adds the text to the cities_cbo component. The city name is found using LookupNode.childNodes[j].firstChild.nodeValue because text within an element is always the firstChild of that element. Finally, the code sorts the ComboBox component by label .

Well need to create the hideLoading function to enable the buttons and remove the loading_mc movie clip. Otherwise, the user wont be able to use the application. Add the following code to the actions layer:
```
 function hideLoading():Void {   cities_btn.enabled = true;   weather_btn.enabled = true;   loading_mc._x = -220;   loading_mc._y = 0; } 
```
Remove the results binding from cities_wsc . We dont need to display the XML string any more since were processing the content and adding it to a Combo Box component.
Test the movie. You should see the ComboBox component populated with the names of the cities of the chosen country. Enter an invalid country name and check that an error message displays.

Well need to configure the second WebServiceConnector so that the weather for the selected city displays in the TextArea component.

Triggering the second WebServiceConnector component

Add the following code to the actions layer:
```
 weather_btn.onRelease = function():Void {   error_txt.text = "";   results_txt.text = "";   var numCities:Number = cities_cbo.dataProvider.length;   if (country_txt.text.length > 0 && numCities > 0) {     weather_wsc.trigger();     showLoading ();   } } 
```
The onRelease event handler clears the values from error_txt and results_txt and finds the number of cities. If there is a country and at least one city, it triggers the WebServiceConnector and calls the showLoading function.
Test the movie. You should be able to select a country and choose a city. When you click the Get weather button, the results from the web service should display in the TextArea component, as shown in Figure 9-31.

Figure 9-31: The weather displayed in a TextArea component

The last step is to format the XML string to display the weather details in the TextArea.

Formatting the weather XML string

Add the following eventListener on frame 1 of the actions layer. The listener detects the result event from the weather_wsc component. Youll probably want to add the code underneath the CitiesListener code.

 var WeatherListener:Object = new Object(); WeatherListener.result = function (evtObj:Object):Void {   hideLoading();   if (evtObj.target.results == "Data Not Found") {     error_txt.text = evtObj.target.results;   }   else {     var weatherXML:XML = new XML(evtObj.target.results);     var RootNode:XMLNode;     for (var i:Number = 0; i < weatherXML.childNodes.length; i++) {       if (weatherXML.childNodes[i].toString().length > 0) {         RootNode = weatherXML.childNodes[i];       }     }     var childNodeName:String = "";     var Wind:String = "";     var SkyConditions:String = "";     var Temperature:String = "";     var RelativeHumidity:String = "";     for (var i:Number=0; i< RootNode.childNodes.length; i++) {       childNodeName = RootNode.childNodes[i].nodeName;       if (childNodeName == "Wind") {         Wind = RootNode.childNodes[i].firstChild.nodeValue;       }       else if (childNodeName == "SkyConditions") {         SkyConditions = RootNode.childNodes[i].firstChild.nodeValue;       }       else if (childNodeName =="Temperature")         Temperature = RootNode.childNodes[i].firstChild.nodeValue;       }       else if (childNodeName =="RelativeHumidity") {         RelativeHumidity=RootNode.childNodes[i].firstChild.nodeValue;       }     }     var strWeather = "Temp: " + Temperature + "\n";     strWeather += "Wind: " + Wind + "\n";     strWeather += "Conditions: " + SkyConditions + "\n";     strWeather += "Relative humidity: " + RelativeHumidity + "\n";     results_txt.text = strWeather;     } } weather_wsc.addEventListener("result", WeatherListener);

This code is long but it is not difficult to understand. We start by calling the hideLoading function to move the loading_mc clip and enable the buttons. Then we test for the message Data Not Found . If there is no data, we wont have any XML to process and we need to display the message.

If we have data, we create an XML object called weatherXML and find the root node. Then we set some variables for the weather information and add the values from the elements <Wind> , <SkyConditions> , <Temperature> , and <relativeHumidity> . A variable called strWeather stores these values, and I have used \n to create line breaks between each setting. Finally, the results_txt TextArea component displays the value from strWeather .

Test the movie. You should be able to select a country, choose a city, and display the weather conditions, as shown in Figure 9-32. You can view the completed resource file weather_completed.fla .

Figure 9-32: The completed Aiport weather application

In this exercise, we used two WebServiceConnector components to request information from a web service. We needed two components because we called two different remote procedures. Because the web service returned the XML results as a string, we used ActionScript to extract the relevant information and add it to the movie interface.

Points to note from exercise 4

Even though the content returned from the WebServiceConnector components looked like XML, it wasnt recognized that way by Flash. Instead, Flash treated the results as a string variable. By binding the results directly to the text property of a TextArea component, we could see the string. This was a useful way to see the data returned by the web service.
Because we requested two different operations from the web service, we had to use two WebServiceConnector components. Each WebServiceConnector can only call a single operation, although it can call it more than once.
We didnt know how long it would take to receive the results from the web service. It was useful to change the interface by displaying the loading_mc movie clip so that users of the application could see that the call was in progress.

As youll see in the next section, its possible to use ActionScript to work with the WebServiceConnector component instead of working with the Component Inspector panel.

The WebServiceConnector class

You can use the WebServiceConnector class to work with web services using ActionScript. It is equivalent to working with the WebServiceConnector component and, as with the XMLConnector, you can use ActionScript to bind the results to other components.

To work with the class, youll need to have a copy of the WebServiceConnector component in your library. Drag the component to the Stage and delete it again.

You can also include the WebServiceConnector class within your movie by using the following import statement. The statement means you wont have to use mx.data.components.WebServiceConnector each time you want to refer to the class.

 import mx.data.components.WebServiceConnector;

After adding the import line, you can create a new WebServiceConnector with the following code:

 var myWSConnector:WebServiceConnector = new WebServiceConnector();

Once youve created the WebServiceConnector object, you can set the properties using ActionScript.

Setting the WebServiceConnector properties

You can set the following properties for the WebServiceConnector. The properties are equivalent to those available through the Component Inspector. Table 9-1 provides an overview of these properties.

 myWSConnector.WSDLURL = "http://urltoWSDL/file.wdsl "; myWSConnector.operation = "NameOfRemoteOperation"; myWSConnector.multipleSimultaneousAllowed = true; myWSConnector.suppressInvalidCalls = true;

If youve added the web service using the Web Services panel, youll be able to view the schema for the params and results . You can display this panel with the CTL-SHIFT-F10 shortcut ( CMD-SHIFT-F10 on a Macintosh).

Sending data to the web service

Youll need to specify the data that youll send to the web service. You can find out the requirements in the params section of the web service schema. You may need to send an array of values or an XML document, depending on the requirements of the web service. Most commonly, youll send an array of values, as shown in the following code. Make sure you use the same order for the values as that listed in the params section of the web service schema.

 myWSConnector.params =[value1, value2, value3];

You could also collect the values from UI components as shown in this code:

 myWSConnector.params =[TI1_txt.text, TI2_txt.text, TI3_txt.text];

You send the request by triggering the component, using the following line. Youll have seen this line earlier in the chapter.

 myWSConnector.trigger();

You can add this code on the timeline so that it processes as soon as the movie loads. However, when youre working with web services, its more common to trigger the component within a button onRelease handler. This allows you to specify the values that youll send to the web service using UI components. When youve filled in the values, you can click a button to trigger the call to the web service.

The WebServiceConnector broadcasts the send event during the trigger process. The event occurs after gathering the params but before Flash sends them to the web service. You can use an event listener function to respond to this event as shown here:

 var WSListener:Object = new Object(); WSListener.send = function(evtObj:Object):Void {   trace ("sending data"); }; myWSConnector.addEventListener("send", WSListener);

You might add a send event handler if you have to format or transform the params before sending them to the web service.

Displaying the results

As with the XMLConnector class, the WebServiceConnector class broadcasts the result event when it receives the results from the web service. You can use a listener to display the results, as shown in the following code:

 var WSListener:Object = new Object(); WSListener.result = function(evtObj:Object):Void {   trace (evtObj.target.results); }; myWSConnector.addEventListener("result", WSListener);

Once the WebServiceConnector broadcasts the result event, you can access the results property of the component. The result event sends an event object into the handler function. In the preceding code, Ive called the object evtObj . You can refer to the WebServiceConnector using evtObj.target . You can then use the results property to see what the web service has returned to Flash. Make sure you dont confuse the result event with the results property since the terms are so similar.

Lets work through an example so you can see how to use ActionScript with the WebServiceConnector class.

Exercise 5: Consuming a web service with ActionScript and the WebServiceConnector class

In this example, well use the WebServiceConnector class to display a Flash product tip from a web service.

Open Flash if necessary and create a new file. Save it as FlashTip.fla .
Add the WebServiceConnector component to the library. Make sure it is not visible on the Stage.

Rename layer 1 as actions and add the following code at frame 1:

 import mx.data.components.WebServiceConnector; var tipWS:WebServiceConnector = new WebServiceConnector(); var WSListener:Object = new Object(); WSListener.send = function(evtObj:Object):Void {   trace ("sending data"); } WSListener.result = function(evtObj:Object):Void {   trace (evtObj.target.results); }; tipWS.addEventListener("send", WSListener); tipWS.addEventListener("result", WSListener); tipWS.WSDLURL = "http://www.flash-mx.com/mm/tips/tips.cfc?wsdl"; tipWS.operation = "getTipByProduct"; tipWS.multipleSimultaneousAllowed = false; tipWS.suppressInvalidCalls = true; tipWS.params = ["Flash"]; tipWS.trigger();

The code imports the WebServiceConnector class and creates a new WebServiceConnector object called tipWS . We create two functions to listen for the send and result events. We set the WDSLURL , operation , and other parameters. The web service needs a string value that specifies name of a product. In this case, weve used Flash in the params array so we can see Flash tips. Finally, we trigger the component.

Test the movie. You should see an Output window containing a tip, similar to the image shown in Figure 9-33. You can see the completed file saved as FlashTip.fla with your resources.

Figure 9-33: The completed tip application

In exercise 5, we were able to connect to a web service using the WebServiceConnector class. We used ActionScript to display the results in an Output window. Well extend this example so that we bind the results to a TextArea component. I covered the DataBindingClasses component in Chapter 8, so I wont go over it again here. Feel free to turn back to that chapter for a refresher.

Exercise 6: Binding the results from a WebServiceConnector object

In exercise 6, well extend the previous example so that we bind the results of our web service call to a TextArea component. Well add the TextArea component dynamically and use the DataBindingClasses component. You should complete exercise 5 first, but if you havent, you can use the starter file tip.fla from your resources.

Open Flash if necessary and open your file from exercise 5 or the starter file FlashTip.fla .
Drag a TextArea component to the Stage and delete it again, so that it appears in the library.
Add the DataBindingClasses component to your library by opening Window Other Panels Common Libraries Classes and dragging it to the Stage. Delete the symbol from the Stage so it doesnt show in the completed movie. Unlike the data components, this symbol has a visual appearance.
Open the Actions panel with the F9 shortcut and add the following lines at the top of the layer, below the first import statement:
```
 import mx.controls.TextArea; import mx.data.binding.*; 
```
Add the following lines to add a TextArea component to the Stage dynamically. The lines set the size , location, and wordWrap properties of the component.

 var tipTA:TextArea = createClassObject(TextArea, "tip_txt",     this.getNextHighestDepth());     tipTA.setSize(300, 200);     tipTA.move(50, 50);     tipTA.wordWrap = true;

Create the bindings for the results by adding the following code at the bottom of the actions layer:

 var fromBinding:EndPoint = new EndPoint(); var toBinding:EndPoint = new EndPoint(); fromBinding.component = tipWS; fromBinding.property = "results"; toBinding.component = tipTA; toBinding.property = "text"; var newBinding:Binding = new Binding(fromBinding, toBinding);

The code creates two new EndPoint objects for the binding. It binds the results from the tipWS component to the text property of the tipTA component.

Modify the result listener function as shown. Ive shown the new line in bold.
```
 WSListener.result = function(evtObj:Object):Void {  var bindingResults:Array = newBinding.execute(false);  }; 
```
This line executes the binding after Flash receives the results from the WebServiceConnector class. You can trace the bindingResults variable to see any errors encountered during the binding process. The variable will have a value of null if there were no errors.
Test the movie. You should see something similar to the screenshot shown in Figure 9-34. Ive saved the resource file as FlashTip_bound.fla .

Figure 9-34: The Tip web service bound to a TextArea component

Exercise 6 showed how to create a simple binding between the results of a web service and a TextArea component. The movie didnt have any visual components although we had to add components to the library. The example shows that its possible to create a Flash movie that consumes a web service using only ActionScript.

If you werent able to connect directly to the web service for security reasons, you could use an XMLConnector class with a server-side file that proxies the data. I covered scripting the XMLConnector class in Chapter 8. You can find out more about the security restrictions in the Flash Player in Chapter 4.

Summary of the properties, methods, and events of the WebServiceConnector class

This section summarizes the properties and methods of the WebServiceConnector class. Table 9-2 shows the only method of the WebServiceConnector class.

Table 9-2: The only method of the WebServiceConnector class
Method	Explanation
trigger	Triggers the WebServiceConnector class to make the remote call to the web service

Table 9-3 summarizes the properties of the WebServiceConnector class.

Table 9-3: Summary of properties of the XMLConnector class
Property	Explanation
multipleSimultaneousAllowed	Specifies whether multiple WebServiceConnectors can be triggered at the same time
operation	Specifies the name of the remote operation at the web service
params	Specifies the information sent to the web service when the WebServiceConnector triggers
results	Contains the information returned from the web service after an WebServiceConnector triggers
surpressInvalidCalls	Specifies whether to suppress a call if the parameters are invalid
WSDLURL	Specifies the URL for the WSDL document

Table 9-4 lists the events broadcast by the WebServiceConnector class.

Table 9-4: Summary of events of the XMLConnector class
Event	Explanation
result	Broadcasts when an WebServiceConnector has completed its call, i.e., after successfully trigger\bng the data
send	Broadcasts during the trigger method, when the parameters have been gathered before the call is initiated
status	Broadcasts when the call starts and provides information on the status on the call