| Through the use of the WebServiceConnector component, a Flash movie can connect to a Web service and load information from it. A Web service is a server-side application that accepts data, performs a service based on that data, and returns a result. For instance, a Web service might allow you to feed it a zip code and, as a result, return the weather in the specified area. Another Web service could find all the spelling mistakes in a string of text fed to it, correct the spelling errors, and return the modified text. To send data to a Web service, the data must be formatted in XML. More precisely, the XML must meet the SOAP (Simple Object Access Protocol) standard. Fortunately, you don't need to learn this standard. The WebServiceConnector component handles the process of converting data to XML (the data you send to the Web service) in the appropriate format, sending it to the Web service as well as receiving and parsing the response. This means that you can communicate with Web services without having to worry about formatting the request properly or figuring out how to interpret the returned XML. The WebServiceConnector component handles everything. 
The WebServiceConnector component has five parameters: WSDLURL. This parameter is the URL for the file that defines the Web service operation. When this parameter is entered, the Flash authoring environment automatically attempts to load the destination file. This allows the authoring environment to display information related to the Web service in the Schema tab of the Component Inspector, which will be discussed later in this lesson. operation. After the file located at WSDLURL is loaded, the operation parameter allows you to select from a drop-down list the operation that you want to execute. Many Web services provide only one operation, such as getPrice, whereas other Web services may provide several types of operations, such as SendICQmessage, SendMSNmessage, and SendAIMmessage. multipleSimultaneousAllowed. This is a drop-down list in which you can choose true or false. The default value is true. If true is selected, the component makes Web requests to the Web service whenever it is asked to do so, even if it hasn't received a response from a previous request. If false, it won't make any more requests until a response to the current request has been received. suppressInvalidCalls. You can select either true or false from a drop-down list for this parameter. The WSDL file loaded via the WSDLURL parameter specifies what type of data is required to process the request. If suppressInvalidCalls is set to true and your Web services request doesn't contain the specified type of data, the request is not sent. If suppressInvalidCalls is set to false, the request is sent, no matter what type of data is entered. timeout. This parameter is optional. It expects either nothing or a number. If a number is entered, the WebServiceConnector component cancels the request for the service if a response is not received before the number of seconds in the timeout parameter is reached.
As mentioned a moment ago, the Schema tab of the Component Inspector is dynamically populated based on the file at the WSDLURL property and the value of the operation property. It defines what information you should send and what information you should expect as a result. For example, there is a Web service that will give you the physical distance between two zip codes. If you enter its WSDLURL into the component and select the getDistance operation, the Schema table updates to show the following image: 
There are two main areas in the schema: params and results. The params property contains the variables that you should send with the Web service request, which in this case consist of two zip codes. The results property is usually just a string. You use the params property on the Schema tab to learn what information you should send to the Web service. You then create an array in the component instance called params and assign it values in the order in which they appeared in the params property on the Schema tab. For example, if we gave the WebServiceConnector component an instance name of zip_ws, we would add the params array like this: zip_ws.params = ["27609", "90210"];
The first zip code in the array corresponds to the first property in the Schema, fromZip. The second one corresponds to the second property in the Schema, toZip. To get the component instance to perform the service request, you must invoke the trigger() method. For example: zip_ws.trigger();
The trigger() method tells the component to take the params property, format a request, send the request, and wait for a response. The response fires an event called the results event. You must add a Listener to capture that event. For example: function distanceReceived (ev:Object) { var distance:String = ev.target.results; } zip_ws.addEventListener("result", distanceReceived);
This code adds a Listener to the zip_ws WebServiceConnector component and calls the distanceReceived function when the results event is fired. TIP http://www.xmethods.com contains an extensive listing of Web services you can use in your applications.
In the following exercise, you will get a chance to use everything introduced in this section. You will use a language translation Web service to create an application that enables you to translate English into a number of other languages. NOTE The WebServiceConnector component uses XML.sendAndLoad to communicate with the Web service; therefore, it is subject to the same security restrictions found when loading data onto one domain from another. For you to be able to use a Web service from an application sitting on a domain, the target domain (that is, where the Web service is located) must grant you access via its crossdomain.xml file.
Open Translator1.fla in the Lesson11/Assets folder. There are three layers on the main timeline: Actions, Assets, and Background. The Actions layer will contain the ActionScript that you will be adding to this project. On the Assets layer are a ComboBox component with an instance name of language_cb, two TextArea components named input_ta and output_ta, and a Button component named translate_btn. 
When this project is complete, you will be able to enter text in the input_ta TextArea component, select a translation language using the language_cb ComboBox component instance, and click the translate_btn Translate button. The Web service will then be sent a request containing the text to translate, as well as information about the selected language to translate it into. The Web service will translate the text and send the result back to the application, where it will be displayed in the output_ta TextArea component. Communication with the Web service is handled by an instance of the WebServiceConnector component, which we'll add to our project next.
Open the Components panel and drag an instance of the WebServiceConnector component onto the stage. Place it to the left of the visible stage area so that it doesn't get in the way of the other assets. You have now added an instance of the WebServiceConnector component to your project. Over the next few steps you will configure this component to do what you need.
Select the WebServiceConnector component and give it an instance name of translator_ws. This name will be used in our scripts to communicate with the component.
With the component still selected, open the Component Inspector. The Component Inspector should open showing three tabs: Parameters, Bindings, and Schema. In the steps that follow, you will work with the Parameters tabs and the Schema tabs.
On the Parameters tab of the Component Inspector, enter the following URL into the WSDLURL parameter: http://www.xmethods.net/sd/2001/BabelFishService.wsdl
This is the URL for the WSDL file that defines exactly how the WebServiceConnector should talk to this particular Web service. In the WSDL file, the only data that interests us is the information regarding what data we need to send and what data we expect to be returned. As soon as you enter the http://www.xmethods.net/sd/2001/BabelFishService.wsdl URL and deselect that particular parameter, the Flash authoring system loads that file into the authoring environment. When the file is loaded, you will be able to select a Web service operation from the operation parameter drop-down list shown on the Parameters tab. The Schema tab will update depending on the operation selected.
NOTE You must be connected to the Internet to complete Step 5. Flash cannot load the WSDL file if you are not connected to the Internet. On the Parameters tab, click the operation drop-down list. Select BabelFish. For this particular Web service, there is only one operation from which to choose. You will not need to change any of the other parameters of this component instance.
Select the Schema tab in the Component Inspector. Notice that there are now two fields listed below params (translationmode and sourcedata). The params object on the Schema tab defines what data should be sent to the Web service. From what we see here we determine that we need to send a string, translationmode, which represents the language of the text being sent as well as the language to which the text should be translated. In addition, we need to send a string, sourcedata, which represents the text to be translated. While the Schema tab gives you some idea of what you're supposed to send, it doesn't tell you everything. For example, the translationmode string accepts strings such as "en_fr" (which stands for "English to French"). The only way you know this information is by actually reading about the Web service from wherever you found the Web service. For this example, the Web service was found through Xmethods.com. The listing for this Web service described exactly what the Web service does and exactly what the Web service needs to get the job done. The following list shows just a few of the many acceptable translationmode string values: The sourcedata string simply holds the text that you want to be translated. In the next few steps, you will create an array called on the WebServiceConnector instanceparams, and will assign values. The params array holds the information that will be sent to the Web service. You are now ready to ready to add the ActionScript needed to complete this project.
Select Frame 1 in the Actions layer and open the Actions panel. Add the following code: language_cb.dataProvider = [{label:"English to French", data:"en_fr"}, {label:"English to  German", data:"en_de"}, {label:"English to Italian", data:"en_it"}, {label:"English to Spanish", data:"en_es"}];
You'll remember that language_cb is the name of the ComboBox component instance in our project. By setting the dataProvider property of the component instance equal to an array, we automatically populate the contents of the component. Each element in the array represents one item in the ComboBox and has two properties label and data. When the Flash movie is published, the ComboBox shows the text entered in each of the label properties. When an item is selected, the value property of the ComboBox is set to the data property associated with the selected item. If a user selects English to German, for example, the value of the ComboBox component instance is changed to "en_de". This value will be used when the Translate button is clicked.
Add the following function to the frame: function translationReceived(ev:Object) { var str = ev.target.results; output_ta.text = str; }
In a moment, we will script our project to execute this function when a response from the Web service has been received. The ev parameter is a reference to the Event object created specifically for this event. (See Lesson 10, "Scripting UI Components," for more information about Event objects.) The first line of this function creates a variable named str. This variable is assigned a value based on the results property of the Web services component in our project. This can be a tricky concept, so let's look at an example of how this will work. As mentioned earlier, when a WebServiceConnector instance receives a response from the Web service with which it's communicating, that information is stored in the results property of the instance. Because receiving a response from the Web service executes this function, ev.target (as used in the function) is a reference to the translator_ws component instance in our project; therefore, ev.target.results is a reference to the information the Web service has sent back to our component instance. In the end, the value of str is the string value sent back from the Web service. The second line in this function displays the value of str (the resulting translated text) in the output_ta component instance.
Add the following function, which asks the WebServiceConnector component instance to do its job: function translate() { var direction:String = language_cb.value; var textToTranslate:String = input_ta.text; translator_ws.params = [direction, textToTranslate]; translator_ws.addEventListener("result", translationReceived); translator_ws.trigger(); }
This function is executed when the Translate button is clicked (ActionScript to handle this action is added in the next step). A variable called direction is set. It gets its value from the value property of the language_cb ComboBox component instance. For example, if the user has selected English to French, direction is assigned a value of "en_fr". The next variable created is textToTranslate. This variable value is the text from the input_ta TextArea component. The next line creates an array in the translator_ws instance called params. This array is used to store the data that will be sent to the Web service. Remember that the Schema tab listed the data to be sent to the Web service in this order: translationmode, sourcedata, with translationmode (the first parameter) representing a value such as "en_fr", and sourcedata (the second parameter) representing the text to translate. The names used for these parameters (as shown on the Schema tab) are really not as important as their order. In other words, the first parameter should hold a value representing how to translate the text, and the second parameter should hold the text to translate. The params array we've added to the translator_ws instance holds the data sent to the Web service, stored in the correct order. The next line of the function registers the translationReceived() function (defined in Step 9) to listen for the results event in relation to the translator_ws instance. When the translator_ws instance receives a response from the Web service, the translationReceived() function is executed. The last line of the function tells the translator_ws WebServiceConnector component instance to perform the request. This is done by invoking the trigger() method.
Add the following ActionScript to capture the click button event: var buttonListenerObject:Object = new Object(); buttonListenerObject.click = function() { translate(); }; translate_btn.addEventListener("click", buttonListenerObject);
You should be familiar with this type of ActionScript by now. We create a Listener object for the button instance and then add a function called click to the Listener object. Finally, we register the Listener object to listen for that event when fired by the translate_btn instance. In summary, when the translate_btn is clicked, the translate() function is called. translate() puts the data to be sent into the WebServiceConnector instance (by setting its params property), tells the instance to call the translationReceived() function when the results have been received, and finally triggers the connection process.
Add this final line of ActionScript to the frame: input_ta.text = "Enter text here...";
This line of ActionScript forces the input_ta TextArea instance to show text when the application is launched. The user can remove this displayed text (by deleting or typing over the displayed text), and then enter new text.
Choose Control > Test Movie to test your work. Enter some English text into the input_ta instance, choose the destination language from the drop-down list, and click the Translate button. If you're connected to the Internet, your text should be translated and displayed in the output_ta component. When you click the Translate button, the WebServiceConnector component formats a request for the Web service, sends the request, and waits for a response. When a response is received, the results event is fired and the text is displayed for the user to see.
Close the test movie and save your work as Translator2.fla. You have successfully created an application that uses the WebServiceConnector component. Now that you know how to use this component, you can hook into any number of Web services to enhance the functionality of your projects.
|
