Permalink
Browse files

Update documentation for new features like geoloqi.Batch(), HTML5 int…

…egration, and context options.
  • Loading branch information...
1 parent 2fd6b99 commit 5a7c64ddee04b5ef847822679765b81fd3cf8302 @patrickarlt patrickarlt committed May 1, 2012
Showing with 180 additions and 3 deletions.
  1. +180 −3 README.markdown
View
@@ -24,7 +24,10 @@ Usage
All the examples are in the demos folder, but here are a few samples to get you started.
-This first example only requires an access token, which all user accounts receive automatically. You can retrieve yours at the [Geoloqi Developers Site](https://developers.geoloqi.com/getting-started).
+This first example only requires an access token, which all user accounts receive automatically. You can retrieve yours at the [Geoloqi Developers Site](https://developers.geoloqi.com/getting-started).
+
+**You should never use your access token in production applicaitons as it would allow anyone to read/write your data.**
+It is only used here for demonstration purposes.
<!DOCTYPE html>
<html>
@@ -89,6 +92,180 @@ Want to make an application with OAuth2? Create an application at the [Geoloqi D
</body>
</html>
+Config Options
+---
+ geoloqi.init({
+ client_id: '[STRING : enter your client_id here (get your applications client_id at https://developers.geoloqi.com/account/applications)]',
+ package_name: '[STRING : an optional name for your package (will be tracked in statistics at https://developers.geoloqi.com/account)]',
+ package_version: '[STRING : an optional version for your package (will be tracked in statistics at https://developers.geoloqi.com/account)]',
+ persist: '[STRING : should be either localStorage or cookie, sets the persistance method used to store user sessions. Uses localStorage if available and cookies if not]'
+ })
+
+Making API Requests
+---
+
+To make requests to the [Geolqoi API](https://developers.geoloqi.com/api) you will need to authenticate the user with `geoloqi.login(username, password)`, `geoloqi.authenticate()` or `geoloqi.authenticateWithPopup()`.
+
+Once the user is authenticated you can use `geolqoi.get()` or `geoloqi.post()` to make requests.
+
+#### `geoloqi.get(method, arguments, callback, context)`
+
+
+* `path` is the API method you want to run. You can find a full list of API methods [here](https://developers.geoloqi.com/api).
+* `arguments` is an optional object that will encoded as a query string before being sent to the API.
+* `callback` is a function that will be run when the request is complete. Takes `response` and `error` params
+* `context` optional, will bind the callback function to the given context. Similar to [_.bind](http://documentcloud.github.com/underscore/#bind) and [jQuery.proxy](http://api.jquery.com/jQuery.proxy/)
+
+**Examples**
+
+Get the authenticated users profile
+
+ geoloqi.get('account/profile', function(response, error){
+ console.log(response, error);
+ });
+
+Get nearby places
+
+ geoloqi.get('place/nearby', {
+ latitude: 45.516454,
+ longitude: -122.675997,
+ radius: 100
+ }, function(response, error){
+ console.log(response, error);
+ });
+
+Get the users last known location and run the callback where this = User
+
+ User = {
+ latitude: null,
+ longitude: null,
+ };
+
+ //arguments are optional
+ geolqoi.get('location/last', funciton(response, error){
+ this.latitude = response.location.position.latitude;
+ this.longitude = response.location.position.longitude;
+ }, User);
+
+#### `geoloqi.post(method, arguments, callback, context)`
+
+* `path` the API method you want to run. You can find a full list of API methods [here](https://developers.geoloqi.com/api).
+* `arguments` an object that will encoded as a query string before being sent to the API.
+* `callback` a function that will be run when the request is complete. Takes `response` and `error` params
+* `context` optional, will bind the callback function to the given context. Similar to [_.bind](http://documentcloud.github.com/underscore/#bind) and [jQuery.proxy](http://api.jquery.com/jQuery.proxy/)
+
+**Examples**
+
+Update the users profile
+
+ geoloqi.post("account/profile", {
+ 'website': "http://mycoolsite.com"
+ }, function(response, error){
+ console.log(response, error);
+ });
+
+Create a new place for the user
+
+ geoloqi.post("place/create", {
+ latitude: 45.516454,
+ longitude: -122.675997,
+ radius: 100,
+ name: "Geoloqi Office"
+ }, function(response, error){
+ console.log(response, error)
+ });
+
+Batch Requests
+---
+
+The Geoloqi API supports running multupile requests at once through the `batch/run` method. you can use the `geolqoi.Batch()` helper to build batch requests and send then to the API. This is particularly good for things such as initialization functions where you may want to make multupile requests at once.
+
+ MyAPP = {
+ places: [],
+ User: {
+ profile: {},
+ location: {}
+ }
+ }
+
+ init_batch = new geoloqi.Batch();
+
+ init_batch.get("account/profile")
+ .get("place/list", {limit: 50})
+ .get("location/last");
+
+ // Run with a context
+ init_batch.run(function(response){
+ // response.result is an array of responses in the order you requested them.
+ this.places = response.result[0].body.places
+ this.User.profile = response.result[1].body
+ this.User.location = response.result[2].body
+ }, MyApp);
+
+ // Run without a context
+ init_batch.run(function(response){
+ // response.result is an array of responses in the order you requested them.
+ MyApp.places = response.result[0].body.places
+ MyApp.User.profile = response.result[1].body
+ MyApp.User.location = response.result[2].body
+ });
+
+HTML5 Geolocation Helpers
+---
+
+Using HTML5s new geolocation features you can update users locations in the Geoloqi API with geolqoi.js once you have authenticated a user.
+
+
+
+#### `geoloqi.updateLocation()`
+
+You can use `geoloqi.updateLocation()` to make a one time update to a users location. It uses the standard `navigator.geolocation.getCurrentPosition` function under the hood and send the results to the Geoloqi API and a optional callback function.
+
+**Options**
+
+* success: a function that will be run after successfully updating a users location. Will recive a HTML5 position object as its parameter.
+* error: function will be run if there was an error getting or updating the users location
+* context: an object to bind the context of the callback functions
+
+** Example **
+
+ geoloqi.updateLocation({
+ success: function(position){
+ console.log("updated users position", position);
+ },
+ error: function(error){
+ console.log("there was an error", error);
+ }
+ });
+
+#### `geoloqi.watchLocation()`
+
+You can use `geoloqi.watchLocation()` to make update a users location as it changes. Impliments `navigator.geolocation.watchPosition` under the hood and sends each point to the Geoloqi API and a callback function.
+
+**Options**
+
+* success: a function that will be run after successfully updating a users location. Will recive a HTML5 position object as its parameter.
+* error: function will be run if there was an error getting or updating the users location
+* context: an object to bind the context of the callback functions
+
+** Example **
+
+ // when initialized this will start watching a users location automatically
+ watch_user = new geoloqi.watchPosition({
+ success: function(position){
+ console.log("updated users position", position);
+ },
+ error: function(error){
+ console.log("there was an error", error);
+ }
+ });
+
+ // stop watching a users location
+ watch_user.stop();
+
+ // start watching a users location again
+ watch_user.start();
+
Found a bug?
---
Let us know! Send a pull request or a patch. Questions? Ask! We're here to help. File issues, we'll respond to them!
@@ -99,6 +276,6 @@ Authors
* Kyle Drake
* Aaron Parecki
-TODO
+TODOS
---
-* Mainly cleanups
+* Full API documentation

0 comments on commit 5a7c64d

Please sign in to comment.