RemoteStorage.BaseClient

scope: function ( path )

Returns a new BaseClient operating on a subpath of the current base path.

getListing: function ( path, maxAge )

Get a list of child nodes below a given path.

The callback semantics of getListing are identical to those of getObject.

Parameters

Returns

A promise for an object, representing child nodes.  If the maxAge requirement cannot be met because of network problems, this promise will be rejected.  If the maxAge requirement is set to false or the library is in offline state, the promise will always be fulfilled with data from the local store.

Keys ending in a forward slash represent folder nodes, while all other keys represent data nodes.

For spec versions <= 01, the data node information will contain only the item’s ETag.  For later spec versions, it will also contain the content type and -length of the item.

Example

client.getListing('', false).then(function (listing) {
  // listing is for instance:
  // {
  //   'folder/': true,
  //   'document.txt': true
  // }
});

getAll: function ( path, maxAge )

Get all objects directly below a given path.

Parameters

Returns

A promise for an object in the form { path : object, ...  }. If the maxAge requirement cannot be met because of network problems, this promise will be rejected.  If the maxAge requirement is set to false, the promise will always be fulfilled with data from the local store.

For items that are not JSON-stringified objects (e.g. stored using `storeFile` instead of `storeObject`), the object’s value is filled in with `true`.

Example

client.getAll('', false).then(function (objects) {
  for (var key in objects) {
    console.log('- ' + key + ': ', objects[key]);
  }
});

getFile: function ( path, maxAge )

Get the file at the given path.  A file is raw data, as opposed to a JSON object (use getObject for that).

Except for the return value structure, getFile works exactly like getObject.

Parameters

Returns

A promise for an object:

If the maxAge requirement cannot be met because of network problems, this promise will be rejected.  If the maxAge requirement is set to false, the promise will always be fulfilled with data from the local store.

Example

// Display an image:
client.getFile('path/to/some/image', false).then(function (file) {
  var blob = new Blob([file.data], { type: file.mimeType });
  var targetElement = document.findElementById('my-image-element');
  targetElement.src = window.URL.createObjectURL(blob);
});

storeFile: function ( mimeType, path, body )

Store raw data at a given path.

Parameters

The given mimeType will later be returned, when retrieving the data using getFile.

Example (UTF-8 data)

client.storeFile('text/html', 'index.html', '<h1>Hello World!</h1>');

Example (Binary data)

// MARKUP:
<input type="file" id="file-input">
// CODE:
var input = document.getElementById('file-input');
var file = input.files[0];
var fileReader = new FileReader();

fileReader.onload = function () {
  client.storeFile(file.type, file.name, fileReader.result);
};

fileReader.readAsArrayBuffer(file);

getObject: function ( path, maxAge )

Get a JSON object from given path.

Parameters

Returns

A promise for the object.  If the maxAge requirement cannot be met because of network problems, this promise will be rejected.  If the maxAge requirement is set to false, the promise will always be fulfilled with data from the local store.

Example

client.getObject('/path/to/object', false).
  then(function (object) {
    // object is either an object or null
  });

storeObject: function ( typeAlias, path, object )

Store object at given path.  Triggers synchronization.

Parameters

Returns

A promise to store the object.  The promise fails with a ValidationError, when validations fail.

What about the type?

A great thing about having data on the web, is to be able to link to it and rearrange it to fit the current circumstances.  To facilitate that, eventually you need to know how the data at hand is structured.  For documents on the web, this is usually done via a MIME type.  The MIME type of JSON objects however, is always application/json.  To add that extra layer of “knowing what this object is”, remoteStorage aims to use JSON-LD.  A first step in that direction, is to add a @context attribute to all JSON data put into remoteStorage.  Now that is what the type is for.

Within remoteStorage.js, @context values are built using three components

In retrospect that means, that whenever you introduce a new “type” in calls to storeObject, you should make sure that once your code is in the wild, future versions of the code are compatible with the same JSON structure.

How to define types?

See declareType for examples.

remove: function ( path )

Remove node at given path from storage.  Triggers synchronization.

Parameters

getItemURL: function ( path )

Retrieve full URL of item

Parameters

Returns a new <RS.BaseClient> scoped to the given path.

Parameters

Example

var foo = remoteStorage.scope('/foo/');

// PUTs data "baz" to path /foo/bar
foo.storeFile('text/plain', 'bar', 'baz');

var something = foo.scope('something/');

// GETs listing from path /foo/something/bla/
something.getListing('bla/');

Declare a remoteStorage object type using a JSON schema.  See RemoteStorage.BaseClient.Types