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