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

   1 # WARNING: This is a developer preview of our new code, not everything works yet, but new apps should use it nonetheless
   2 # Old apps should check out branch v0.6.9 instead, which has actual syncing to actual remote storage working.
   3
   4 # Adding remoteStorage.js v0.7 to your app:
   5 #### add "remoteStorage.js" (you can copy it from this repo)
   6 #### in index.html, include this script and any modules you plan to load:
   7
   8     <script src="remoteStorage.js"></script>
   9     <script src="tasks-0.1.js"></script>
  10
  11 #### in the place where you want the remoteStorage element to go, add a div:
  12
  13     <div id="remotestorage-connect"></div>
  14
  15 #### then in your app's onload function, add a call to put the 'connect your remote storage' UI into that div,
  16
  17     remoteStorage.displayWidget('remotestorage-connect');
  18
  19 #### load the 'tasks' module,
  20
  21     remoteStorage.loadModule('tasks', '0.1', 'rw');
  22
  23 #### open a private tasks list called 'todos':
  24
  25     todos = remoteStorage.tasks.getPrivateList('todos');
  26
  27 #### and specify your handlers for 'error' and 'change' on the task list:
  28
  29     todos.on('error', function(err) {
  30     });
  31     todos.on('change', function(id, obj) {
  32       refreshData();
  33     });
  34
  35 #### note that your change handler will be called with an object that has an 'origin' field, that comes with a value of 'tab', 'device', or 'cloud'
  36
  37 Note: maybe 'window' is a better term than 'tab' here, this sort of details is still subject to change in the final v0.7
  38
  39
  40 # using the tasks list:
  41
  42 #### function list.getIds();
  43
  44 returns an array of id's, which you can use to retrieve the actual objects.
  45
  46 #### function list.get(id);
  47
  48 returns an object from the list, or undefined if there is no object in the list with that id
  49
  50 #### function list.set(id, obj);
  51
  52 sets the item with that id to that object (might trigger a 'change' event with origin 'tab').
  53
  54 #### function list.add(text);
  55
  56 creates a new todo item with that text, completed set to false, and a randomly generated id, which is returned by the function.
  57
  58 #### function list.remove(id);
  59
  60 removes that item
  61
  62 #### function list.markAsCompleted(id);
  63
  64 marks that todo item as completed (you can see we really have a higher-level API here that understands that tasks are things that have a boolean 'completed' field)
  65
  66 #### function list.isCompleted(id);
  67
  68 returns true or false. this one is maybe a bit silly, you could also just get the object and read the obj.completed field. or maybe we should make obj.isCompleted(),
  69 inline with OO practice. Anyway, you get the idea. I hope that with this everybody can write apps very easily based on modules like this. For now i only included 'tasks', but once this works it should be easy to make first versions of other modules like 'documents', 'contacts', 'photos', 'stuff', 'music', etcetera. Pull requests welcome! :)