Community MX publishes a web service that displays information about the latest content available from the site. This service can be used by anyone who knows how to consume a web service. Content of Community MX is copyright ©2003 by Community MX and cannot be redistributed, however you may use the web service on your own site to show a list of what is available on CMX. The first part of this article is at http://www.communitymx.com/abstract.cfm?cid=E5EA2A608932F770. To follow along, you will need the following:

• Flash MX
• ColdFusion MX server
• Flash Remoting client components

The first article showed a simple interface to the Community MX web service built in Flash. To recap, a web service is a service that is created to communicate, using standard XML formats, to any application that knows how to talk to it. The web service will have a public interface written in Web Services Description Language (WSDL). The Community MX web service utilizes a standard .wsdl file that can be consumed by any technology that can consume a web service. The web service is located at http://www.communitymx.com/services/cmxfeed.wsdl. The web service exposes four methods:

• getContent: grabs the latest content descriptions available from Community MX
• searchContent: searches the content at Community MX
• getContentTypes: retrieves a list of the latest content types (articles, extensions, etc.) for your application to aid in using the searchContent method
• getTip*: grabs the latest tip from Community MX

*not implemented yet

Using the searchContent() Method (Example 1)

The searchContent() method allows the consumer of the web service to search the content at Community MX and return the matching content to your program. There are several arguments to this method, as can be seen by examining the WSDL file:

<wsdl:message name ="searchContentRequest" >
  <wsdl:part name="search" type ="SOAP-ENC:string" />
  <wsdl:part name="anyWords" type ="SOAP-ENC:string" />
  <wsdl:part name="exactPhrase" type ="SOAP-ENC:string" />
  <wsdl:part name="contentType" type ="SOAP-ENC:string" />
  <wsdl:part name="contentDate" type ="SOAP-ENC:string" />
</wsdl:message>

All of the arguments are strings, but they need some explanation:

• search: the search word or words. This can be individual words, comma-separated words, or phrases
• anyWords: set this to true to match any of the search words (the default is "all words")
• exactPhrase: set this to true to match an exact phrase
• contentType: set this to 0 for all, or you can match one of the CMX content types, which can be retrieved using the getContentTypes() method of the service
• contentDate: search the content based on a time period, as number of days (the default is 30)

The Community MX web service was built in ColdFusion, and uses the same mechanism for searching our site content that the site search feature uses. The following step-by-step tutorial will work in Flash MX. The download package contains the example .fla files in Flash MX and Flash MX 2004 format.

Step by step:

1. Open a new file in Flash MX. You can name the file example1.fla.
2. Create a Text element on the page and set the following properties in the Properties inspector:
   
   Size: 400x300
   HTML: true
   Type: Dynamic Text
   Name: content_txt
   Multiline: true
   
   
3. If you are using Flash MX and not Flash MX 2004, you'll have to add a scrollbar to the text field. Simply drag one from the Components panel and drop it onto the text field.
4. Add another text field above that text field which will serve as a text box. This field should be have the following properties:
   
   Size: 200x20
   HTML: false
   Type: Input Text
   Name: search_txt
   Single Line: true
   
   
5. Add a PushButton component to the right of search_txt. It should be named submit_pb in the Properties inspector. The completed interface now looks like this:
   
   
6. Open the Actions panel (F9) and make sure it's set to Expert mode (Flash MX only). Add the following code to the main timeline for initializing Flash Remoting (Layer1, first frame). This part is the same as the code used in Part 1 of this tutorial:

// Include the required classes for Flash Remoting
#include "NetServices.as"

// Set up variable for the Flash Remoting URL
var myURL = "http://localhost/flashservices/gateway";
// Set up variable for the Community MX wsdl descriptor file
var servicePath = "http://www.communitymx.com/services/cmxfeed.wsdl";

// Connection hasn't been initialized; create connection and service objects
if (initialized == null) {
  initialized = true;
  NetServices.setDefaultGatewayUrl(myURL);
  var myConnection_conn = NetServices.createGatewayConnection();
  var myService = myConnection_conn.getService(servicePath);
}

The URL of the Community MX .wsdl file is http://www.communitymx.com/services/cmxfeed.wsdl. As you can see, this is hard-coded. The path to the .wsdl file becomes our service path in Flash. This will cause the ColdFusion server (or ASP.NET server) to generate a proxy for the web service on the server.

7. The next step is to add the Flash Remoting responder object to handle all responses and error messages from the server. The server will pass an array of objects back to the caller. The objects contain the following fields:
   
   AUTHOR
   CATEGORY
   DESCRIPTION
   KEYWORDS
   TITLE
   TYPE_DESCRIPTION
   URL
   
   Responder objects can take many forms, but I like to handle results with a custom object, named SimpleResult here. Again, this part is identical to the code used in Part 1:

// Define the custom SimpleResult class to display the results
function SimpleResult() { // Class constructor
}

// Set up onResult() and onStatus() handlers as methods of SimpleResult class
SimpleResult.prototype.onResult = function (myResults) {
  var temp = "";
  var theLength = myResults.length;
  if(theLength == 0) {
    temp = "No results"; // Display a message if no results
  } else { // Else, display the results
    for (var i=0; i < theLength; i++) {
      temp += makeLink(myResults[i].TITLE,myResults[i].URL) + "<br>";
      temp += "Author: " + myResults[i].AUTHOR + "<br>";
      temp += "Category: " + myResults[i].CATEGORY + "<br>";
      temp += "<br>";
    }
  }
  content_txt.htmlText = temp;
};

SimpleResult.prototype.onStatus = function (myError) {
  content_txt.text = myError.description;
};


_global.System.onStatus = SimpleResult.prototype.onStatus;

The onResult method of the SimpleResult object will handle all results from the call to the web service. It makes use of a utility function, makeLink(), to generate a link from the TITLE and URL fields. We are also using the AUTHOR field and the CATEGORY field in the results. You are free to use the other fields that are not implemented here.

We are also creating an onStatus method to handle any errors from the remote call, as well as creating a handler for the _global.System.onStatus method, which usually indicates a failure to communicate.

8. Next, we'll add the utility function, makeLink():

   // Make a clickable link out of some text, given the text and a location
   function makeLink(theText,theLink) {
     var temp = '<font color="#00cc00"><a href="';
     temp += unescape(theLink);
     temp += '" target="_blank">' + theText + '</a></font>';
     return temp;
   }
   

9. Lastly, we'll call the service directly, using an instance of the SimpleResult class to handle the results. When you place the responder object as the first argument in your call to the remote service, Flash will strip it off and use it as the responder object, and send only the 2nd through Nth arguments to the remote service:

// Call the service on submit
submit_pb.setClickHandler("searchContent");
function searchContent(button) {
  content_txt.text = "...working";
  // the searchContent arguments are in the order:
        (search, anyWords, exactPhrase, contentType, contentDate)
  myService.searchContent(
    new SimpleResult(), search_txt.text, "false", "false", "0", "0");
}

The search text field provides the first argument so that the content can be searched. The second argument specifies that the search will split the words up and make sure each word matches in the search. If this were set to true, then a search result would allow a match so long as any of the words matched. The third argument is set to false so that the search words are not treated as an exact phrase. The fourth argument specifies a search of all content. The last argument uses a 0 to return all content dates. You could set this to 30 to get the content for the last 30 days.

The results can be seen here.

Building the Example in Flash MX 2004

Quite a few changes have come along in Flash MX 2004 — some of them good, and some of them not so good. The following step can be replaced in Example 1 to make it work with Flash MX 2004:

9. Lastly, we'll call the service directly, using an instance of the SimpleResult class to handle the results. When you place the responder object as the first argument in your call to the remote service, Flash will strip it off and use it as the responder object, and send only the 2nd through Nth arguments to the remote service. In Flash MX 2004, we use a listener to listen for the click event of the button. This is a new approach in Flash MX 2004 and takes the place of event handlers that were used in Flash MX:

listenerObject = new Object(); // Create the listener object
// Create the handler for the click event
listenerObject.click = function(searchContent){
  content_txt.text = "...working";
  myService.searchContent(
    new SimpleResult(), search_txt.text, "false", "false", "0", "0");
}

// Add the listener to the click event of the button
submit_pb.addEventListener("click", listenerObject)

Adding the getContentTypes() Method (Example 2)

Another method of the web service is getContentTypes(), which gives you a list of content types in an array. This can be easily fed into a ComboBox component to further enhance the search. These content types are generated dynamically at Community MX because of the changing nature of the Community — new content and content types are being added regularly. As of this writing, the getContentTypes method returns this result:

0, ALL
1, Article
2, Tutorial
3, FAQ
4, Review
5, Extension
6, Daily Tips
7, Weekly Tips
1000, Knowledge Base

The method returns an array of objects. Each object contains a type_id and a type_desc . These properties can be fed into a drop-down list. To add the drop-down list to the first example, follow these steps for Flash MX:

Step by step

1. Using the original example (example1.fla) as a starting point, add a ComboBox component to the display. The ComboBox should be named contentTypes_cb.
2. Add this code to the bottom of the your existing code. This will create a new responder object to handle the response from the call to getContentTypes():

// New responder object class to handle the comboBox
function ComboResult(theBox) { // pass the box to the responder
  this.box = theBox;
}

// The onResult method handles the response from the web service
ComboResult.prototype.onResult = function(result) { // result contains an array
  for(var i=0; i < result.length; i++) {
    // Loop through and add the the description and ID fields (type_desc and type_id)
    this.box.addItemAt(i, result[i].TYPE_DESC, result[i].TYPE_ID);
  }
}

ComboResult.prototype.onStatus = SimpleResult.prototype.onStatus

3. Next, we need to call the getContentTypes method from within the movie. Because this method simply fills a combo box, we'll want to call this upon the movie load. The call will use the same service that was already set up, so we only need one line to call the method, passing the ComboBox to the responder object instance. Note, again, this responder object does not get sent to the service: Flash strips it off and uses it to handle the response.

myService.getContentTypes(new ComboResult(contentTypes_cb));

4. Finally, modify the call to searchContent to pass the information from the ComboBox. Recall that we hard-coded 0 in the fourth argument. We'll use the data property of the currently select ComboBox item instead (the new code is shaded):

myService.searchContent(new SimpleResult(), search_txt.text, "false", "false", contentTypes_cb.getSelectedItem().data, "0");

Now if you view the movie, you should be able to do searches based on keywords and also search only the content types that you want to search, such as extensions or articles. The results can be seen here.

Building the Example in Flash MX 2004

Component architecture has changed considerably in Flash MX 2004. For this reason, some of the existing methods used in Flash MX will not work the same way in Flash MX 2004, if at all. The ComboBox is one of those components that has been kept relatively the same between versions. This is a good thing. Example 2 should be workable with Flash MX 2004. One thing to keep in mind: Flash MX 2004 is case sensitive, so be careful when typing variables, method names, or any other part of your code. The CMX web service returns the field names as UPPER CASE, so this will not work in Flash MX 2004:

this.box.addItemAt(i, result[i].type_desc, result[i].type_id);

This will work in Flash MX 2004:

this.box.addItemAt(i, result[i].TYPE_DESC, result[i].TYPE_ID);

Conclusion

Flash Remoting remains the easiest, best way to use SOAP-based web services from within Flash. Building a Flash application that utilizes Remoting is simply a matter of learning a few easy API methods.

More information about Flash Remoting can be found at http://www.flash-remoting.com and at Macromedia's site.