Who Called Me - Sample Application

This is a Ruby on Rails application which implements a phone number query. Enter the phone number and get the contact information associated with that number. You will need a working Ruby on Rails installation to install and run this sample application.

Download and untar

To download the sample application:

Download the Who Called Me tar file
Extract the contents of the tar file.

Files

Once the files are downloaded and unpacked, you should see the following files:

      index_controller.rb - Proxy and main page for this example. 
                            This is where you will input your API key.
      index.rhtml - All JS and CSS styles are included in this file
      reverseLookUp.rhtml - dummy page used for reverse phone look up controller response 
      json2.js - Third party JSON library.
      wp_logo_us.png - WhitePages.com logo

Requirements

To successfully install and run this sample application, you should have the following available.

Ruby interpreter - tested with Ruby 1.8.6
Rails gem - tested with Rails 2.0.2
Database - SQLite version 3, SQLite Ruby gem (db not used but required to start Rails)

Install (Linux)

To install on a machine running Linux:

Assuming the name of your app is APIDemo, create a directory structure for it with the following command:
```
rails APIDemo
```
Next create a controller for this application
Make sure you're in the APIDemo directory and run the following command:
```
ruby script/generate controller index
```
Now copy code from index_controller.rb downloaded from this page into APIDemo/app/controllers/index_controller.rb
Replace API_KEY in this file with your own WhitePages API key you got during registration. (See http://developer.whitepages.com for instructions on how to register for an account and an API key)
Now put index.rhtml and reverseLookUp.rhtml downloaded from this page into the APIDemo/app/views/index directory
Put json2.js in APIDemo/public/javascripts directory
Move or rename APIDemo/public/index.html
```
mv index.html index.html.old
```
Put the WhitePages.com logo: wp_logo_us.png into directory: APIDemo/public/images

Your directory structure should look like this:

app
    controllers
	index_controller.rb - Proxy and main page for this example. 
                              This is where you will input your API key.
    views
        index.rhtml - All JS and CSS styles are included in this file
        reverseLookUp.rhtml - dummy page used for reverse phone look up controller response 
public
    javascripts
        json2.js - Third party JSON library.
    images
        wp_logo_us.png - WhitePages.com logo

That's it. You should be able to start the server and access the app at :http://hostname:port/index

Application Notes

95% of this demo is done using JavaScript. The other 5% is a proxy written in Ruby on Rails and just provides a way for the client-side JavaScript to call theWhitepages API without causing cross scripting issues.

The JavaScript is self contained to the API_demo.page namespace in the page. Applying an inline template system in the page allows for all of the UI and logic to be kept on the client. This makes the call to the API for the JSON data the only network communication required. All templates can be altered by simply making changes to the HTML and using the keywords surrounded by % as the area for which the data will replace these keywords.

During page load these templates are copied to private variables within the API_demo.page object and stored for use while processing the JSON into UI elements. The drawback of this approach is that because we are using the innerHTML property to get and set these templates into the DOM we do not have access to the contents as DOM level elements. This is OK for this purpose as we are using the templates for display only. Another approach would be to store all the templates on the server and requesting them as needed via AJAX and doing all the regex on the client. This would lighten the load of the initial page when more complex or heavy templates are required. In our case we have a small set of templates required for the demo and they are very lightweight.