Integrating APIs with XDK - Hotwire Sample App

Starting from Blank

While the wizards and app design layout helpers in the XDK are extremely useful, there will be times when you simply need to go directly to code. As you tailor your app's scripting and apply CSS pixel-pushing, it is the source code editor that is required to make your app behave exactly the way you want.

To start building an app from scratch without the GUI IDE helpers, simply navigate to the Projects tab at the very top of the XDK. Click the Start a New Project at the bottom of the screen. On the New Project Setuppage, you’ll be prompted to name and home directory for your project. Once you create the project, you’re left with a pristine directory with a single file - index.html. This is exactly how we started this sample application.

Project Layout: JavaScript App Framework and UI

We’ve chosen to use Intel’s App Framework as the JS library. You can download the App Framework from Github - https://github.com/01org/appframework/. We use it for the following tasks:

• UI - nicely styled CSS themes for iOS, iOS7, Android, Windows 8 and more
• Query selector - easy traversal of the DOM for selecting and modifying values (very similar to jQuery)

In this sample app, we’ve imported the base files (see /js directory), along with a few CSS (see /css) files and one plugin (see /plugins). We’ve also added a few other files that well explain below.

• js/
  • appframework.min.us - minimized version of main framework (part of AF)
  • appframework.ui.min.js - minimized version of the UI framework (part of AF)
  • api.js - functions for making remote API calls and parsing results (made for this sample app)
• plugins/
  • af.8tiles.js - plugin for Windows 8 phones (part of AF)
• css/
  • af.ui.css - general UI elements (part of AF)
  • icons.css - font and icon elements (part of AF)
  • mashery.css - CSS customizations (made for this sample app)

Setting up the Hotwire API

The primary focus of this app is to demonstrate how to make API calls, parse the data, and integrate that data into the view. In this sample, we’re using the Hotwire API, which showcases data that you would find on the Hotwire travel website. In order for this sample app to operate properly, you will need to get your own Hotwire API key. The API is free to use and fetching an API key takes only a minute or two.

Navigate to Hotwire’s developer portal - http://developer.hotwire.com. If you already have a Mashery ID, sign in with your credentials. Otherwise, register for a new account. After providing your registration information and verify your e-mail address, login, and apply for a key (or create a new application). You will soon receive an API key to the Hotwire Public API – Deals and Shopping APIs on your browser and via e-mail.

With this sample app opened up in the XDK, navigate to the Develop tab. On the left side of the XDK, you’ll find a list of directories and files. Inside the js directory, you’ll find api.js. Select/open that file into the IDE (editor). Next, copy your new API key (beware of white-space padding) from your other browser window or e-mail into api.js.

// ********************SET YOUR API KEY HERE*******************// Insert your Hotwire API Key here. README for more info.varapiKey='PLACE-YOUR-API-KEY-HERE';// ************************************************************

One Page, Two Panels

This sample app consists of one view, rendered from index.html. All of the library files mentioned above are loaded from this page. The content is divided into two div sections — one with an id of “home” and the other with an id of “search-results.” The default panel view is div “home” because it is declared as selected.

<divclass="panel"title="Hotwire Demo"id="home"selected="selected"data-footer="none"><divclass="grid">

The second panel (div id “search-results”) contains two child div elements. The second one, “hotwire-results-output” is where the parsed search results from the API are placed.

App Flow: Search and Results

The flow of this app is very simple. The user types in a ZIP code, touches the Search Hotwire button, and then a list of hotel deals is presented on the next page. On the results page, the user can either click theBack button (navigates back to the div ‘home’) or click on a result, which is opened in a new browser window. The screen transition from "home" to "search-results" is done in api.js:

// Transition to 'search-results' panel// Docs: http://app-framework-software.intel.com/api2/index.html#$_ui_loadContent$.ui.loadContent("#search-results",false,false,"slide");

Making Call, Parsing Results

The searchDeals() in api.js is where the API call is initiated. The url to the Hotwire Hotel Deals method is prepared, with API key and ZIP code concatenated. The call is made with the following statement:

varapiCall=$.get(url,function(data){searchDealsCallback(data);});

$.get is an App Framework function, similar to the GET function in jQuery. The call is my asynchronously. On success, it will call searchDealsCallback. That's the function that performs the parsing, appends the list of links to the DOM, and transitions to the other div element.

The results come back in JSON. By using the $.parseJSON() function, iteratin through the results is a breeze. One of root level elements of the results object is an array named Result[].

{"Result":[{"Headline":"San Francisco 4 Star Hotel, $99/night","Url":"http://www.hotwire.com/hotel/...",...},{"Headline":"San Francisco 4 Star Hotel, $105/night","Url":"http://www.hotwire.com/hotel/...",...}]}

The code to parse through this result set looks like this:

vardata=$.parseJSON(payload);for(varxindata.Result){vardeal=data.Result[x];// Use deal.Url and deal.Headline}