| # Using the WebServiceConnector Data Component in Flash MX Professional 2004 This document contains the following sections: Description Requirements Source files Using the population viewer How the popultaion viewer was created # Description This sample application demonstrates a unique and intuitive method of data visualization made possible by Flash MX. A map of 15 European countries allows the user to drag the "population" of each country to either side of a scale. Human figures representing the population of the selected country are placed on the scale and automatically increase in size to represent the relative population of the country. Each time a country's population is placed on the scale, the total population of each side of the scale is recalculated and the scale tips to the side with the greater total. Web services are used to obtain the initial country populations. Throughout the sample, ActionScript is used to display, track, and compare data as well as operate the scale. The web services sample shows how easy it is to accomplish the following: Connect to a Web Service through the WebServiceConnector Component Check connection status to a Web Service Use Web Service data with ActionScript # Requirements Internet connection # Source File The source file for this movie (PopulationViewer.fla) is located in the Samples folder on your hard drive. On Windows, go to boot drive\Program Files\Macromedia\Flash MX 2004\Samples\PopulationViewer. On Macintosh, go to Macintosh HD/Applications/Macromedia Flash MX 2004/Samples/PopulationViewer. # Using the Population Viewer When the application first loads a ProgressBar in the upper-right corner of the window, displays the percentage of completed connections to the web service. ## Comparing country populations: Drag a country marker from the map to the scale You can drag a marker to either side of the scale. Once dropped, the icon for the country's population will grow relative to the value received from the WSDL. Based upon the country population values, the scale will compare which side has the greater value. ## Clearing the scale Click the clear icon at the bottom left of window. All population icons are removed from the scale, and the scale returns to its balanced position # How the Population Viewer was created This section contains the following topics: Using web services to provide initial population data Configuring the WebServiceConnector component Using the WebServiceConnector component Using the ProgressBar component to track web service calls during initialization Setting up the country movie clips Initializing the movie clips Using the country movie clip Dragging the country movie clip Dropping the country movie clip Setting up the scale for operation Scale movement Resetting the application Conclusion ## Using web services to provide initial population data The population of each of the 15 countries is acquired through web service calls when the application starts. The 15 WebServiceConnector components can be seen above the Stage. Whether to use 15 individual WebServiceConnector components or one controlled by ActionScript is a decision that must be made by the developer. Both methods will solve the problem. In this example, each of the 15 components is data bound to the corresponding country movie clip at authoring time. This method requires less ActionScript. Using this method, the only ActionScript necessary triggers the component and traps the result and status events. Alternatively, using one WebServiceConnector component to retrieve the populations of all 15 countries would require additional ActionScript to sequentially control the setting of parameters and getting the populations back to their proper country movie clips when the call completed. The developer must weigh this trade off of more components and less ActionScript versus fewer components and more ActionScript at authoring time. ## Configuring the WebServiceConnector component The WebServiceConnector components are named c1ws through c15ws. The WSDLURL property of each WebServiceConnector component is set to the following: http://www.macromedia.com/cfusion/demos/population/population.cfc?wsdl The operation property of each WebServiceConnector component is set to getPopulation , which is the name of the web service the application calls to retrieve the population of each country. Using the Schema tab on the Component inspector, you can see the params object of each connector contains a string named country. This string is the parameter that the getPopulation web service expects to receive. It is the name of the country for which the population is requested. In the Bindings tab, you can see that the params.country parameter is databound "in" from a TextInput component called countryName, located inside the appropriate country movie clip. The country movie clips are named c1 through c15 and can be seen over each country on the map. Also in the Bindings tab, you can see the results property of each WebServiceConnector component is databound "out" to a TextInput component named popnum, located inside the corresponding country movie clip. The values bound into these TextInput components are used later in the application to calculate the scaling of the country movie clips and the total populations on each side of the scale. ## Using the WebServiceConnector component Select the layer named actions and open the Actions panel. Near the bottom of the ActionScript, you can see a for loop that calls the setUpListener() method once for each country. The parameters passed to setUpListener() method are the name of the country movieclip (c1-c15) and the name of the WebServiceConnector component for that country (c1ws – c15ws). The setUpListener() method assigns event listeners to each WebServiceConnector component to instruct the component on what to do when it receives the data from the web service or fails to connect to the web service. As you can see in the for loop, after the listeners have been set up for a WebServiceConnector component, the component is triggered to initiate the getPopulation web service call for that country. When a WebServiceConnector component receives its data (country population) from the web service, the progressOnSuccess() method makes the country movie clip visible and increments a variable named completed . This value is used by the progress bar to show the user how many country populations have been received successfully. If any of the WebServiceConnector components fail to connect and retrieve a population value, the bailOnError() method is called to trace the error code to the Output panel. ## Using the ProgressBar component to track web service calls during initialization The ProgressBar component named pBar can be seen above the WebServiceConnector components. In the actions layer, you can see the _y property of the pBar component is set by ActionScript to 27.4 when the application starts so that the component will be visible during initialization. Near the bottom of the actions layer ActionScript code, you can see the onEnterFrame() method. This method continually updates the pBar component during initialization to show the user how many population values have been retrieved successfully by the WebServiceConnector components. When all of the populations have been loaded and the pBar component reaches 100%, it throws the completed event. This event is handled at the bottom of the actions layer ActionScript. When the completed event is thrown, the listenerObject.complete() method turns off pBar by setting its _visible property to false. After this happens, the next time onEnterFrame executes, it detects that the pBar component is not visible and it disables the onEnterFrame() method. Program initialization is now complete and the application is ready for user interaction. ## Setting up the country movie clips After the application completes initialization, the country movie clips (c1 – c15) are draggable to the scale. When the user drags the country movie clip onto the scale, it automatically increases in size to represent the country's population. The scale then recalculates totals on each side and moves accordingly. ## Initializing the movie clips Near the bottom of the actions layer ActionScript code, you will see a for loop that executes at startup. This for loop cycles through each country movie clip and assigns methods to the onPress , onRelease , onRollOver and onRollOut events, and then sets the country movieclip _visible property to false . The country movie clip then waits for its population value from the WebServiceConnector component. The country movie clips have three frames. The first frame has ActionScript that makes the TextInput components invisible and then stops the clip on Frame 1. When the movie clip receives its population value from the WebServiceConnector component, its _visible property is set to true , showing its signpost. The movie clip then waits for the user to drag it to the scale. ## Using the country movie clip In the actions layer ActionScript, the method countryRollOver() is called when the mouse rolls over a country movie clip. This method directs another movie clip, called c X over (where X is the country number) to go to Frame 2. This action, in effect, highlights the outline of the country so the user can see the country when they roll over it with the mouse. When the mouse is moved away from the country movie clip, the cXover movie clip is directed back to Frame 1, where the country is not highlighted. ## Dragging the country movie clip When the mouse button is pressed on a country movie clip, the countryPress() method executes. This method performs multiple tasks. First, it records the position of the movie clip in case the user drops it somewhere off the scale so it can be returned to its original position. Second, it scans all of the country movie clips to determine which one has the highest depth (which one is on top.) That movie clip's depth is then swapped with the selected movie clip's depth so the selected movie clip moves to the top as it is dragged. Third, the countryPress() method tells the selected country movie clip to go to Frame 2 and show the human figure for dragging. The countryPress() method then executes the startDrag() method. The last thing countryPress() does is check whether the ProgressBar component pBar is visible. If it is, then initialization has not yet completed. If this is the case, countryPress() turns off the pBar component, effectively forcing the end of the initialization. ## Dropping the country movie clip When the mouse is released during a country movie clip drag, the countryRelease() method executes. This method determines where the movie clip was dropped. If the movie clip is not on either side of the scale, it is returned to its original position and directed back to Frame 1, the signpost. If the movie clip was dropped on either side of the scale, its position on the scale is recorded, the scale population arrays are updated (see the scale section below), and the movie clip is directed to Frame 3. Frame 3 contains the human figure that will be scaled. The application then calls the populationTween() method. The populationTween() method takes the population of the country and divides it by one million. The result is the number of pixels that will be added to the _height and _width properties of the movie clip called thedot , located on Frame 3 of the country movie clip. ## Setting up the scale for operation The scale tilts to the left and right as countries are placed on it. After a country movie clip is dropped on the scale, the population totals on each side of the scale are recalculated and the scale is set in motion if needed. When a user drops a country movie clip on either side of the scale, the countryRelease() method sets up the scale for operation. First, the location of the movie clip on the scale is recorded and pushed onto the array x DropArr (where x is "left" or "right"). This is done so that the country movie clip can be repositioned correctly as the scale moves and allows the application to make the country movie clip look like it is moving with the scale. Next, the original position of the country movie clip is pushed onto the array x ReturnArr (where x is "left" or "right") and finally the country movie clip itself is pushed onto the array x Arr (where x is "left" or "right"). The population of the country that is dropped is then added to the total population for that side of the scale (totalPopR or totalPopL variables). Once the arrays and totals have been updated, the validate() method is called to actually move the scale. ## Scale movement The validate() method determines which direction the scale will move, then sets up an onEnterFrame() function to perform the movement. In addition to moving vertically, the scales also move horizontally as the scale bar tilts. The values in the x DropArr array help reposition the country movieclips on the scale as it moves in the horizontal direction. As the scale moves vertically, the country movie clips are also repositioned to give the illusion they are moving with the scale. When the scale reaches its limit, the onEnterFrame() method is disabled and the application waits for another country movie clip to be placed on the scale. ## Resetting the application When the reset button is pressed (lower left of the Stage), each of the country movie clips is returned to its original position and depth, along with being directed back to Frame 1, the signpost. The scale is then moved back to the original position and all the arrays used by the scale are reset. ## Conclusion The number of possible population combinations is astronomical. In this example, the user can compare relative populations and any population combinations with a few simple drag-and-drop motions. Flash MX provides the developer with an opportunity to represent and manage data in a visual manner. Using data visualization with Flash MX will add multiple dimensions to the user experience – much more than you could hope to achieve with DHTML database tools.