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