Assemble the Social Web with zembly: Basics

This chapter is from the book

Assemble the Social Web with zembly

Learn More Buy

This chapter is from the book

This chapter is from the book 

Assemble the Social Web with zembly

Learn More Buy

2.7 Putting It All Together—Using the WeatherBug API

You’ll now build a service and widget that uses the WeatherBug API. (Note that zembly already provides a sample service and widget for the WeatherBug API. However, in this section you’ll build your own.) Here’s a summary of the steps you’ll follow to build this service and widget.

Steps to create the WeatherBugService

1. Obtain a WeatherBug API key (from WeatherBug) and add it to your zembly Keychain.
2. Create a new service to access the WeatherBug API.
3. Add a parameter to the service.
4. Using Find & Use, add the JavaScript code to call the WeatherBug API.
5. Format the return data.
6. Test and publish the service.

Steps to create the WeatherBugWidget

1. Create a new blank widget.
2. Provide HTML for formatting.
3. Using Find & Use, add the call your WeatherBug service.
4. Include the Prototype library.
5. Add JavaScript code.
6. Preview and publish the widget.
7. Embed it in a web page.

Let’s begin. The WeatherBug API is included in the list of services you can access from zembly. These services have been wrapped as adapters by the zembly structure, giving you easy access to WeatherBug’s API.

Using Your Keychain

To start, access your Keychain (click Manage your Keychain from your home page). This displays the service providers currently supported on zembly. Scroll down to the WeatherBug’s listing, as shown in Figure 2.42.

Figure 2.42 Accessing WeatherBug’s registration page

The first step is to register with the WeatherBug service to obtain a key. You do this directly with WeatherBug. (Click Register with WeatherBug to get started.) After several email confirmations, WeatherBug will send you a key. When you add the WeatherBug API key to your keychain, zembly prompts for your name. (Each API site has its own requirements for what constitutes a legal API key.) Your name is stored with the key in your private keychain data.

zembly knows this key is associated with the WeatherBug API. When you access the WeatherBug API using Owner.keychain, the WeatherBug key is used in exactly the correct format required by WeatherBug. Also, when other people use a service you build, they access the service using your key. Your key is protected since it is wrapped in the Keychain mechanism.

Building WeatherBugService

Now that you have a WeatherBug key, you can build a service. From your Keychain page, scroll down to the WeatherBug listing and click Check out the services offered by WeatherBug. This directs you to the list of services; currently LiveWeatherRSS is the only one. Now click on WeatherBug.LiveWeatherRSS and zembly directs you to the LiveWeatherRSS page, as shown in Figure 2.43.

Figure 2.43 Drilling down to check out the services offered by WeatherBug

The WeatherBug.LiveWeatherRSS information page describes how to call the adapter and use its data. Besides the description, the page provides information on the parameters and error codes and a text box tells you how to call the adapter from a service.

Here’s the code template to access the LiveWeatherRSS adapter.

var result = Things.WeatherBug.LiveWeatherRSS({
     zipcode: "", // 5-digit ZipCode, U.S. cities only
     // unittype: "", // Optional. Default value is 1. Values are 0
     // (US customary units) or 1 (metric units - kms, degrees Celsius, etc).
     keys: Owner.keychain
 });

The LiveWeatherRSS API call takes three parameters: the target zip code, the unit type (this is optional, but it defaults to ‘1’ which means metric units), and keys. When you build this service, you’ll supply values for unit type and keys and allow the user to supply the target zip code.

Now, let’s build the service. Click at the top of the page and choose Service from the drop down menu. For this service, you’ll have a single parameter (the target zip code). The unit type defaults to “1” (metric units) but you’ll specify U.S. units (such as Fahrenheit and inches) which is “0”. For the keys data use Owner.key-chain, which pulls your WeatherBug-specific API key. You write this service using JavaScript. The LiveWeatherRSS service returns XML. You’ll extract just the data you want and return the results to the caller in JSON.

Using E4X and JavaScript

zembly returns XML data as a DOM document object. This means that you can access the object directly in your JavaScript using E4X notation.

Listing 2.6 shows a sample of the XML response from WeatherBug. Let’s show you how to access the various nodes using JavaScript and E4X.

Listing 2.6. Sample XML Response from WeatherBug

<rss version="2.0">
   <channel>
      <title>Observations from Encinitas,  CA - USA</title>
      <link>...</link>
      <description> . . . (contains HTML code) . . . </description>
         . . . omitted data . . .
   </channel>
</rss>

Because the data is already returned as a DOM document object, you access node title using (for example),

data.channel.title

As discussed earlier, you provide a single parameter (“zipcode”), which is a String, it’s required, and is escaped, as shown in Figure 2.44.

Figure 2.44 Editing a parameter

To add the code you need to call the adapter to the editor, select the Find & Use tab in the box to the right of the editor. Specify LiveWeatherRSS and click Search. zembly returns the matching services. Click Add to editor and zembly adds the code you need to the editor, as shown in Figure 2.45.

Figure 2.45 Find & Use lets you search for services and add code to the editor

Listing 2.7 shows the JavaScript source for WeatherBugService. Function Log.write allows you to write information to a log file that you can view in the Call window to the right of the editor. Select Log at the bottom of the Call window to view. Here, function Log.write(typeof data) writes “xml” to the log file.

Using the E4X notation, the WeatherBugService extracts the data for the title, description, and link to pass to the caller. This is the data you’ll work with when you create a widget that uses this service.

Listing 2.7. WeatherBugService (JavaScript)

var data = Things.WeatherBug.LiveWeatherRSS({
   "zipcode": Parameters.zipcode, // 5-digit ZipCode, U.S. cities only
   "unittype": "0",
   "keys": Owner.keychain
});

//log type of the result object (XML object)
Log.write(typeof data); // writes "xml"

//You can use E4X notation to access the elements and attributes
//inside this object directly

var result = new Object();

result.title = ""+data.channel.item.title;
result.description = ""+data.channel.item.description;
result.link = ""+data.channel.link;

// Returns JSON
return result;

As you build the service, you can test drive it and look at the results that are returned.

Calling WeatherBugService

The next step is to build a widget that uses this service. The point of building a widget is to create a user-friendly snippet of code that others can paste directly into a web page. This widget should provide nice formatting of the data returned by WeatherBugService. Before leaving the WeatherBugService page, you’ll see that it tells you how to call this service from a widget. Here is the template code zembly provides.

Things.callService("ganderson.WeatherBugService",
 {
     zipcode: "" // 5-digit ZipCode, U.S. cities only
 },
 {
     onSuccess: function(data) {
         Log.write(data);
     },
     onFailure: function(error) {
         Log.write("Error: " + error.code + " : " + error.message);
     }
 });

When you build your widget, you’ll use this code to call the service. Let’s take a brief look at the response you get when you make a successful call to a service (the onSuccess handler). The code within Things.callService examines the response and gives you a pointer to the data object directly (as the first argument).

• If the service returns an object (if the response content type is application/json), then data is a JavaScript object. The WeatherBugService returns JSON data to the calling widget.
• If the service returns an XML document (if the response content type is application/xml), then data is a DOM object.
• If the service returns a plain string, number, boolean or date, then the data object will have its string representation. The LoanPaymentService returns a number, which will have its string representation in the calling widget.

Note that the onFailure handler accesses the error object.

Building WeatherBugWidget

From the top of the page, click and select Widget from the drop down menu. Choose Create a blank widget. The widget page lets you rename the widget, provide a description, and specify HTML, CSS, and JavaScript code. The HTML code should provide an input field for the zip code and a button to click and grab the weather data. You’ll also need a named <div> tag to display the results. (This is id="weatherBugResults" in Listing 2.8 below.)

Here is the HTML code for the WeatherBugWidget.

Listing 2.8. WeatherBugWidget (HTML)

<div id="weatherBugWidget">
   Please enter a ZipCode to search WeatherBug service: <br/>
   <input id="zipcode" type="text" value="92024" />
   <br/>
   <button id="weatherButton">Get Weather</button>
   <br/><hr/><br/>
   <div id="weatherBugResults"></div>
</div>

Sample JSON Output

Before you look at the JavaScript code for this widget, let’s look at the data that the service returns. Listing 2.9 shows sample JSON output (property description has been shortened). The result object is embedded in curly braces { } and each property is identified in quotation marks followed by a colon and its value. Properties are separated with commas.

Because the data arrives to the caller as a JavaScript object, you do not need to perform any parsing. For example, the title property is accessed using (for example)

data.title

Listing 2.9. Sample JSON Output

{
   "title": "Live Conditions from Encinitas,  CA - USA",
   "description":
"<img src=\"http://deskwx.weatherbug.com/images/Forecast/icons/cond026.gif\"
      border=\"0\" alt=\"Current Conditions\"/>

      ( . . . data omitted . . . )

   <br />",
   "link":
   "http://weather.weatherbug.com/CA/Encinitas
weather.html?ZCode=Z5546&Units=0&stat=ENCNT"
}

WeatherBugWidget JavaScript

This widget doesn’t specify any CSS. Listing 2.10 shows the JavaScript code for this widget. Note that each property in the returned data object (data) is accessed directly using JavaScript notation. Since the data in property description is straight HTML, you can use that directly in the HTML markup.

Listing 2.10. WeatherBugWidget (JavaScript)

// WeatherBugWidget (WBW)
// Register a listener for the "weatherButton" with Prototype Event.observe
Event.observe($("weatherButton"), 'click', function() {
   var zipcode = $("zipcode").value;
   // call service and pass zipcode
   Things.callService("ganderson.WeatherBugService", {
      zipcode: zipcode},
      {
      onSuccess: function(data) {
         // format the return data and inject into page markup
         var resultsHtml = "<b>" + data.title + "</b><br/>" +
            data.description + "<br/><b><a href=" + data.link +
            ">weather details</a></b><br/> " ;
         $("weatherBugResults").innerHTML = resultsHtml;
      },
      onFailure: function(error) {alert(error.code);}
   });
});

Each time you edit the widget, you can test it directly on the widget page. Once you’re finished editing, publish it. zembly provides the code you use to run the widget in a browser. You can configure the iframe by specifying height and width attributes. Here is the HTML source.

Listing 2.11. Sample HTML source to call the WeatherBugWidget

<iframe width=500 height="350"
   src="https://0eb6e21170b8405ca2658cec54fc5005.zembly.com/things/
0eb6e21170b8405ca2658cec54fc5005;iframe" frameborder="0">
</iframe>

Figure 2.46 shows sample output from running the above HTML.

Figure 2.46 WeatherBugWidget running in a browser