10.0.0.21 Git - remotestorage.js/blob - README.md

   1 # remoteStorage.js
   2 This is a library for adding remoteStorage support to your client-side app. See http://tutorial.unhosted.5apps.com/ for example usage.
   3
   4 # Version and license
   5 This is version 0.4.5 of the library, and you can use it under AGPL or MIT license - whatever floats your boat. Pull requests are very welcome (if you're not on github you can email them to michiel at unhosted.org).
   6
   7 # Browser support
   8 This library relies heavily on [cors](http://caniuse.com/#search=cors).
   9 Known to work: Firefox, Chrome, Safari, Safari-iOS.
  10 Might work: Firefox-mobile, Android-native, Opera 12+, Opera-mobile 12+, IE 10+.
  11 Coming soon: IE 8 & 9 (please help with this!).
  12
  13
  14 #Code example
  15 Minimal HTML:
  16
  17 ```html
  18 <!DOCTYPE html>
  19 <html>
  20   <head>
  21     <script src="./path/to/require.js"></script>
  22     <script src="./path/to/your/app.js"></script>
  23   </head>
  24   <body></body>
  25 </html>
  26 ```
  27
  28 Your `app.js`:
  29
  30 ```js
  31 require(['./path/to/remoteStorage'], function(remoteStorage) {
  32   remoteStorage.getStorageInfo('user@example.com', function(err, storageInfo) {
  33     var token = remoteStorage.receiveToken();
  34     if(token) {
  35       //we can access the 'notes' category on the remoteStorage of user@example.com:
  36       var client = remoteStorage.createClient(storageInfo, 'notes', bearerToken);
  37       client.put('foo', 'bar', function(err) {
  38         client.get('foo', function(err, data) {
  39           client.delete('foo', function(err) {
  40           });
  41         });
  42       });
  43     } else {
  44       //get an access token for 'notes' by dancing OAuth with the remoteStorage of user@example.com:
  45       window.location = remoteStorage.createOAuthAddress(storageInfo, ['notes'], window.location.href);
  46     }
  47   });
  48 });
  49 ```
  50
  51 #Function reference
  52 ### remoteStorage.getStorageInfo(userAddress, callback)
  53
  54     userAddress: string of the form 'user@host'
  55     callback: function(err, storageInfo)
  56     -err: null, or a string describing what went wrong
  57     -storageInfo: an object describing some details of the user's remoteStorage
  58
  59 ### remoteStorage.createOAuthAddress(storageInfo, categories, redirectUri)
  60
  61     storageInfo: the object you got from the getStorageInfo call
  62     categories: an array of strings describing categories of data you will be accessing.
  63     @returns: string, the url you should go to for the OAuth dance
  64 See https://github.com/unhosted/website/wiki/categories for a list of categories you might want to access.
  65
  66 ### remoteStorage.receiveToken()
  67
  68     @returns: when coming back from the OAuth dance, a string containing the bearer token. Otherwise, null.
  69
  70 ### remoteStorage.createClient(storageInfo, category, bearerToken)
  71
  72     storageInfo: the object you got from the getStorageInfo call
  73     category: one of the strings from the array you passed to createOAuthAddress earlier
  74     @returns: a Client
  75
  76 ### Client.get(key, callback)
  77
  78     key: a string, identifying which element you want to retrieve
  79     callback: function(err, data)
  80     -err: null, or a string describing what went wrong
  81     -data: undefined, or a string, that is the current value of 'key' within 'category' on the user's remoteStorage
  82
  83 #### Client.put(key, value, callback)
  84
  85     key: a string, identifying which element you want to assign value to
  86     value: a string you want to assign to the element identified by key
  87     data: a string that, if successful, will be the new value of 'key' within 'category' on the user's remoteStorage
  88     callback: function(err)
  89     -err: null, or a string describing what went wrong
  90
  91 ### Client.delete(key, callback)
  92
  93     key: a string, identifying which element you want to reset to undefined
  94     callback: function(err)
  95     -err: null, or a string describing what went wrong