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 #Code example
   8 Minimal HTML:
   9
  10 ```html
  11 <!DOCTYPE html>
  12 <html>
  13   <head>
  14     <script src="./path/to/require.js"></script>
  15     <script src="./path/to/your/app.js"></script>
  16   </head>
  17   <body></body>
  18 </html>
  19 ```
  20
  21 Your `app.js`:
  22
  23 ```js
  24 require(['./path/to/remoteStorage'], function(remoteStorage) {
  25   remoteStorage.getStorageInfo('user@example.com', function(err, storageInfo) {
  26     var token = remoteStorage.receiveToken();
  27     if(token) {
  28       //we can access the 'notes' category on the remoteStorage of user@example.com:
  29       var client = remoteStorage.createClient(storageInfo, 'notes', bearerToken);
  30       client.put('foo', 'bar', function(err) {
  31         client.get('foo', function(err, data) {
  32           client.delete('foo', function(err) {
  33           });
  34         });
  35       });
  36     } else {
  37       //get an access token for 'notes' by dancing OAuth with the remoteStorage of user@example.com:
  38       window.location = remoteStorage.createOAuthAddress(storageInfo, ['notes'], window.location.href);
  39     }
  40   });
  41 });
  42 ```
  43
  44 #Function reference
  45 ### remoteStorage.getStorageInfo(userAddress, callback)
  46
  47     userAddress: string of the form 'user@host'
  48     callback: function(err, storageInfo)
  49     -err: null, or a string describing what went wrong
  50     -storageInfo: an object describing some details of the user's remoteStorage
  51
  52 ### remoteStorage.createOAuthAddress(storageInfo, categories, redirectUri)
  53
  54     storageInfo: the object you got from the getStorageInfo call
  55     categories: an array of strings describing categories of data you will be accessing.
  56     @returns: string, the url you should go to for the OAuth dance
  57 See https://github.com/unhosted/website/wiki/categories for a list of categories you might want to access.
  58
  59 ### remoteStorage.receiveToken()
  60
  61     @returns: when coming back from the OAuth dance, a string containing the bearer token. Otherwise, null.
  62
  63 ### remoteStorage.createClient(storageInfo, category, bearerToken)
  64
  65     storageInfo: the object you got from the getStorageInfo call
  66     category: one of the strings from the array you passed to createOAuthAddress earlier
  67     @returns: a Client
  68
  69 ### Client.get(key, callback)
  70
  71     key: a string, identifying which element you want to retrieve
  72     callback: function(err, data)
  73     -err: null, or a string describing what went wrong
  74     -data: undefined, or a string, that is the current value of 'key' within 'category' on the user's remoteStorage
  75
  76 #### Client.put(key, value, callback)
  77
  78     key: a string, identifying which element you want to assign value to
  79     value: a string you want to assign to the element identified by key
  80     data: a string that, if successful, will be the new value of 'key' within 'category' on the user's remoteStorage
  81     callback: function(err)
  82     -err: null, or a string describing what went wrong
  83
  84 ### Client.delete(key, callback)
  85
  86     key: a string, identifying which element you want to reset to undefined
  87     callback: function(err)
  88     -err: null, or a string describing what went wrong