Web DevCenter    
 Published on Web DevCenter (http://www.oreillynet.com/javascript/)
 See this if you're having trouble printing code examples


Consuming Amazon with Flash Remoting

by Jason Michael Perry
01/09/2003

Editor's Note - In this article you'll learn how to create a responsive UI that can search and display results using Web Services and Flash Remoting. Jason will show you how to build the interface and manipulate the XML Web Service. This tutorial requires Flash MX, Flash Remoting, and a free Amazon.com associate account.

The Power of XML Web Services

As a webmaster, I frequently find myself forcing third party web tools to integrate into my Web site. In the end, I may disguise the obvious subdomain name or that slight change in the consistency of my design, but I shouldn't have to. I should request and get seamless integration from any vendor into my Web site. Well, several companies are finally coming around with XML Web Services.

XML Web Services allow you to hook into a company's infrastructure and share data through the Web. This differs from other methods because it embraces W3C's standards for transportation and descriptions known as SOAP and WSDL. Now companies can embrace this as a way to aggregate real time information. Imagine purchasing financial software off the shelf and seamlessly getting credit card balances and bank statements from different companies. Imagine having full control of that affiliate solution's look and feel.

Related Reading

Web Services Essentials
Distributed Applications with XML-RPC, SOAP, UDDI & WSDL
By Ethan Cerami

The power of XML Web Services doesn't stop there. It also allows companies to decrease paper and time by instantly transmitting data. For example, Monster.com, HotJobs.com, and CareerBuilder.com could all receive new job posting for your company via an exposed XML Web Service. This allows your Human Resources department to use one tool for writing and sending job posting that works with several job boards as well as brick and motor placement firms.

Macromedia understands this vision and plans to be part of it with Flash Remoting. Flash Remoting leaps years ahead of previous ways Flash grabbed data (remember loadVariable) and allows Flash to integrate with any complex Web application exposed as a XML Web Services, as well as ColdFusion MX, ASP.Net, and J2EE. Now Flash can consume Web Services from any remote source and spit out that data as if it where its own.

Think about this for a second. You can connect to an Amazon.com XML Web Service and create your own Flash store complete with Amazon recommendations, search, product description...the whole nine yards. Or you could create a responsive UI that can search and display results using Google.com's XML Web Service.

And that's exactly what we're going to do in this article. Amazon.com recently released a XML Web Service to allow affiliates to better integrate Amazon.com into their Web sites. This provides amazing potential for Amazon.com, as well as affiliates looking to pass Amazon.com's books off as their own. In this tutorial I'll break down Amazon.com's XML Web Service, show you how to establish a connection with Flash Remoting, and help you build a Flash spotlight that dynamically list Amazon.com's books. To follow along with this tutorial, you should download my Flash file and download Amazon's developer kit. You'll also need to register with Amazon for a unique token. Without this token you cannot connect to the XML Web Service.

Analyzing Amazon's XML Web Service

Now that we understand some of the benefits of XML Web Services, let's take a look at Amazon.com's WSDL. A WSDL (Web Service Description Language) is a XML vocabulary, and we'll use to provide all the information we'll ever need to know about a XML Web Service. With this we can view the Web Service's functions, its location, and special types. Go to http://soap.amazon.com/schemas/AmazonWebServices.wsdl to view the WSDL description.

<xsd:complexType name="KeywordRequest">
  <xsd:all>
    <xsd:element name="keyword" type="xsd:string" />
    <xsd:element name="page" type="xsd:string" />
    <xsd:element name="mode" type="xsd:string" />
    <xsd:element name="tag" type="xsd:string" />
    <xsd:element name="type" type="xsd:string" />
    <xsd:element name="devtag" type="xsd:string" />
    <xsd:element name="version" type="xsd:string" />
  </xsd:all>
</xsd:complexType>

At first this WSDL may look a little intimidating, but it's surprisingly simple and easy to understand. First, look at the <xsd:complexType> tag. This tag allows Amazon to create new types that provide additional functionality or grouping native types like strings and integers can't provide. In the this case, we have an object that stores keyword search criteria. Each type within this object is a string type. In the above code snippet, the elements wrap to the following keyword data:

I will not breakdown the other object defined types but the request wrapper objects are defined in the sample Flash download.

<message name="KeywordSearchRequest">
  <part name="KeywordSearchRequest" type="typens:KeywordRequest" />
</message>
<message name="KeywordSearchResponse">
  <part name="return" type="typens:ProductInfo" />
</message>

Another important element in the WSDL is the <message> tag; it provides information on the functions available from our Web Service. In the above code snippet, the <part> element represents the parameters for the function named KeywordSearchRequest and the type this parameter is. You should also notice that we have two separate <message> elements, one named KeywordSearchRequest and the other KeywordSearchResponse. Request should be used when calling the function while response provides the type returned.

By combining our <message> and <xsd:complexType> elements, we can understand the parameters the function requires. The next section will shed light on how to implement these objects in Flash.

Connecting with Flash Remoting

Now it's time to open Flash MX and build the framework for our application. For this application to properly run, you need to install Flash Remoting on your Web server. A 30-day trial version of Flash Remoting is available for download from Macromedia.

In Flash MX, create a new Flash File and open the action's dialog for frame 1. In this frame we will use Flash Remoting to create a connection to Amazon.com's XML Web Service.

#include "NetServices.as"

init( init== null )
{
   var init = true;

   NetServices.setDefaultGatewayURL( 
         "http://localhost/flashremoting/services/gateway.aspx" );
   gatewayConnection = NetServices.createGatewayConnection();

   AmazonWebService = gatewayConnection.getService( 
         "http://soap.amazon.com/schemas/AmazonWebServices.wsdl", this );
}

I've created a code block that initializes my XML Web Service. The first line of the code snippet grabs additional functions and objects included with Flash Remoting from an external action script file. Within the code block we need to define the location of our server using the gateway and instance of the XML Web Service. My application uses the WSDL address we discussed earlier to access Amazon.com's XML Web Service, this allows Flash Remoting to programmatically build a proxy, or interrupter, to our XML Web Service.

This code snippet is for a ASP.Net server; a JRun or Coldfusion server will not require .aspx on the gateway call. Also, ASP.Net requires a physical file in the path; JRun and Coldfusion don't.

Building the Interface

With a connection to our XML Web Service established, let's build a interface to display the output.

Using the text tool, create two text boxes on the main movie clip. Name the first text box txtName and the second txtPrice. Next, create an empty movie clip named mcImage and place it on your main movie clip. Please note that our mcImage movie clip will work as a holder for our product's image. Because the size of the image varies based on the type of product, it's a good idea to add a backdrop for your movie clip. For more information on dynamically loading images view my article on jasonmperry.com.

With our base elements in place you may want to add a little spice to your Amazon.com product spotlight. I've taken the liberty of adding a bright spinning background to draw attention to the spotlighted book and setting my text colors to white.

Manipulating the XML Web Service

Interface in hand, lets focus on filling those text boxes with dynamic content. To do this we need to implement a callback function and object that wraps to our XML Web Service's <message> and <xsd:complexType> definitions.

function AsinSearchRequest_Result( result )
{
   ProductInfo = result;

	//sets the product info for our moviec lip
   txtProductName.text = ProductInfo.Details[ 0 ].ProductName;
   txtProductPrice.text = ProductInfo.Details[ 0 ].OurPrice;
   urlProductLocation = ProductInfo.Details[ 0 ].Url;

	//loads the medium sized image onto the _root.
	//Image holder provides size holder.
   loadMovie( ProductInfo.Details[ 0 ].ImageUrlMedium, _root.mcImage );
}

function AsinSearchRequest_Status( error )
{
   trace( error.code );
   trace( error.description );
   trace( error.details );
}

Callback functions receive response data and errors sent from our XML Web Service proxy. These callbacks wrap to the AsinSearchRequest function defined in the WSDL. The "_Result" function is called with the output of AsinSearchResponse, and "_Status" is called if an error occurs during the call. When implementing a callback function take the name of the method and add both "_Result" and "_Status" to the end. In our "_Result" callback we receive an instance of the ProductInfo type defined in our WSDL. Our code snippet grabs the returned product's name, price, URL, and image from the result.

We also need to use loadMovie to dynamically grab the URL of our product's image and display it in our Flash Application. To provide better positioning of the image you should use load the jpeg into a movie clip.

	//creates a AsinRequest object type wrapper
asinRequest = function(asin, mode)
{
   this.asin = asin;
   this.mode = mode;
   this.tag = "webservices-20"; //tag
   this.token = "???";  //Your unique token
   this.version = "1.0"; //id of this version of Amazon service.  Currently 1.0.
   this.type = "heavy"; //"heavy" or "lite" determines amount of copy returned
}
Object.registerClass( "AsinRequest", asinRequest );

The next step is to create a object wrapper for our parameter type. To do this we can create mirror image of our AsinRequest WSDL complex type as a Flash object. We also need to register the new class as type AsinRequest.

AmazonWebService.AsinSearchRequest( new AsinRequest( "0672320789", "books") );

With our callbacks done and AsinRequest object registered, we can call the AsinSearchRequest method and sent our AsinRequest parameter to the XML Web Service. When Flash Remoting receives data as ether a error message or result it will call the proper callback function.

NOTE: When in debug mode you can view the result data to see the best way to access the data.

In the sample download I've taken the liberty of implementing the remaining callback functions and wrappers. This should give you a good idea of how to implement any object in Flash based on its WSDL counterpart.

Conclusion

Using Flash Remoting to create a dynamic interface to Amazon.com's XML Web Services only brushes on the capabilities of Flash Remoting. The true potential lies in developing Flash interfaces that mimic Windows UI components and are responsive. In the near future, complex applications like credit card accounts will allow you to drag and drop a payment onto the proper icon or display a progress bar as it grabs last month's statement.

The FLA source file built in this tutorial is available for download as FlashAmazonSpotlight.zip. Note the file will not work with out Flash Remoting installed and running on your computer. A 30-day trial version of Flash Remoting is available for download at Macromedia.com.

Jason Michael Perry is a partner in Out the Box Web Productions and the Webmaster for Pan-American Life, an international financial services company. You can contact Jason by visiting Jasonmperry.com.


Return to the Web Development DevCenter.

Copyright © 2009 O'Reilly Media, Inc.