User:Georgeccampbell/sandbox

=Generating Mobile OCLC Apps with PhoneGap=

Introduction
OCLC has recently provided some new API's to permit transactional access to our databases to our customers via the web. To assist developers in putting this API's to work, we've compiled some code examples for mobile apps.

WMS Circulation - the "Pull List"
The pull list is a list of books that the librarian needs to remove from the stacks to place on the hold shelf, reserve shelf or transfer to another institution or branch. This list can be retrieved if you have the following information:

The request is assembled from the following parts:

The base URL
https://circ.sd00.worldcat.org/pulllist/

The location
In the case of the OCLC Sandbox (for testing purposes):

The security information (WSKey2)
These example numbers are not valid - contact OCLC to get numbers that are valid with your InstitutionID.

The WSKey2 protocol is explained here.

Parameters for WMS Circulation
The parameters for a Pull List request are limited to:

Retrive Pull List - PHP Sample Code
Before attempting to access API's from a mobile device, it is instructional to look at a simple server side script. This example displays a pull list in a browser window. Note that this script would have to be protected behind a password to keep the security keys private. The steps followed here can be replicated in Javascript, Objective-C or Android Java for mobile applications.

Retrive Pull List - Javascript Sample Code
These Javascript libraries can be used to access WMS API's when running phoneGap on a mobile device. Becaue javascript lacks PHP's native ability to encode hashes, substantial library files are provided to serve the same purpose. You can learn more about javascript and encryption at Stanford Javascript Crypto Library.

Download the following javascript files:


 * WMS_encryption_library.js
 * WMS_API_library.js

Sample code to create a PullList object, retrieve it, convert the XML result to a Javascript object and display it on the screen,

The security and location objects should be set depending on the institution you are developing for:

Your phoneGap .html file should look something like this:

An important reason for using phoneGap is that you can program your mobile app in Javascript once, and then run it on iPhone and Android. Developers are also building a library of Javascript routines to interface with the OCLC API's.

Installing and Programming Phonegap
To install phonegap, choose the instructions based on your platform:

Getting Started Guides for PhoneGap

These sites are also useful:


 * Phonegap WIKI
 * Android PhoneGap Hello World!
 * iPhone PhoneGap Hello World!

jQuery Ajax Calls
When javascript is employed in a browser, XMLHttpRequests (or $.ajax with jQuery) can only be made to the server hosting the site. With phoneGap, however, the localhost acts as a proxy server and Ajax requests can be made to any site. Here is sample code for the "GET" and "POST" functions

Note that the WSKey2 Authorization string is emplaced using the "beforeSend" parameter in all cases.

GET
The call returns XML in a text format. After the call, the data can be extracted from the XML using string functions, or converted to XML in jQuery, and data extracted with DOM functions.

POST
Note that xml data is posted as text, with processData set to false. Also note the content type.

HTML 5 - localstorage
It is a good idea, after retrieving data with an XMLHttpRequest or $.ajax request, to store it in localstorage. Dealing with intermittent contact between the phone and the server is part of designing a remote data driven application.

Local storage explained