RemoteStorage

TODO needs proper introduction and links to relevant classes etc

Constructor for global remoteStorage object.

This class primarily contains feature detection code and a global convenience API.

Depending on which features are built in, it contains different attributes and functions. See the individual features for more information.

var remoteStorage = new RemoteStorage({
  logging: true,  // defaults to false
  cordovaRedirectUri: 'https://app.mygreatapp.com' // defaults to undefined
});

Summary

RemoteStorage	TODO needs proper introduction and links to relevant classes etc
Events
ready	Fired when ready
not-connected	Fired when ready, but no storage connected (“anonymous mode”)
connected	Fired when a remote storage has been connected
disconnected	Fired after disconnect
error	Fired when an error occurs
features-loaded	Fired when all features are loaded
connecting	Fired before webfinger lookup
authing	Fired before redirecting to the authing server
wire-busy	Fired when a wire request starts
wire-done	Fired when a wire request completes
network-offline	Fired once when a wire request fails for the first time, and `remote.online` is set to false
network-online	Fired once when a wire request succeeds for the first time after a failed one, and `remote.online` is set back to true
Functions and Properties
RemoteStorage.log	Log using console.log, when remoteStorage logging is enabled.
displayWidget	Displays the widget at the top right of the page.
remote
scope	Returns a BaseClient with a certain scope (base path).
startSync	Start synchronization with remote storage, downloading and uploading any changes within the cached paths.
connect	Connect to a remoteStorage server.
disconnect	“Disconnect” from remotestorage server to terminate current session.
onChange	Add a “change” event handler to the given path.
enableLog	Enable remoteStorage logging.
disableLog	Disable remoteStorage logging
log	The same as RemoteStorage.log.
setApiKeys (experimental)	Set API keys for (currently) GoogleDrive and/or Dropbox backend support.
setCordovaRedirectUri	Set redirect URI to be used for the OAuth redirect within the in-app-browser window in Cordova apps.
hasFeature	Checks whether a feature is enabled or not within remoteStorage.
connected	Boolean property indicating if remoteStorage is currently connected.
access	Tracking claimed access scopes.
caching	Caching settings.
remote	Access to the remote backend used.
local	Access to the local caching backend used.

Events

ready

Fired when ready

not-connected

Fired when ready, but no storage connected (“anonymous mode”)

connected

Fired when a remote storage has been connected

disconnected

Fired after disconnect

error

Fired when an error occurs

Arguments

the error

features-loaded

Fired when all features are loaded

connecting

Fired before webfinger lookup

authing

Fired before redirecting to the authing server

wire-busy

Fired when a wire request starts

wire-done

Fired when a wire request completes

network-offline

Fired once when a wire request fails for the first time, and `remote.online` is set to false

network-online

Fired once when a wire request succeeds for the first time after a failed one, and `remote.online` is set back to true

Functions and Properties

RemoteStorage.log

RemoteStorage.log = function ()

Log using console.log, when remoteStorage logging is enabled.

You can enable logging with enableLog.

(In node.js you can also enable logging during remoteStorage object creation. See: RemoteStorage).

displayWidget

Displays the widget at the top right of the page. Make sure to call this function once on every pageload (after the html ‘body’ tag), unless you use a custom widget.

Parameters

domID: identifier of the DOM element which should embody the widget (optional)

remote

Properties

connected	Boolean, whether or not a remote store is connected
online	Boolean, whether last sync action was successful or not
userAddress	String, the user address of the connected user
properties	String, the properties of the WebFinger link

scope

Returns a BaseClient with a certain scope (base path). Please use this method only for debugging, and always use defineModule instead, to get access to a BaseClient from a module in an app.

Parameters

scope

A string, with a leading and a trailing slash, specifying the base path of the BaseClient that will be returned.

Code example

remoteStorage.scope('/pictures/').getListing('');
remoteStorage.scope('/public/pictures/').getListing('');

startSync

Start synchronization with remote storage, downloading and uploading any changes within the cached paths.

Please consider: local changes will attempt sync immediately, and remote changes should also be synced timely when using library defaults. So this is mostly useful for letting users sync manually, when pressing a sync button for example. This might feel safer to them sometimes, esp. when shifting between offline and online a lot.

connect

connect: function ( userAddress,
token )

Connect to a remoteStorage server.

Parameters

userAddress	The user address (user@host) to connect to.
token	(optional) A bearer token acquired beforehand

Discovers the WebFinger profile of the given user address and initiates the OAuth dance.

This method must be called after all required access has been claimed. When using the connect widget, it will call this method itself.

Special cases

1. If a bearer token is supplied as second argument, the OAuth dance will be skipped and the supplied token be used instead. This is useful outside of browser environments, where the token has been acquired in a different way.

2. If the Webfinger profile for the given user address doesn’t contain an auth URL, the library will assume that client and server have established authorization among themselves, which will omit bearer tokens in all requests later on. This is useful for example when using Kerberos and similar protocols.

disconnect

disconnect: function ()

”Disconnect” from remotestorage server to terminate current session. This method clears all stored settings and deletes the entire local cache.

onChange

onChange: function ( path,
handler )

Add a “change” event handler to the given path. Whenever a “change” happens (as determined by the backend, such as e.g. RemoteStorage.IndexedDB) and the affected path is equal to or below the given ‘path’, the given handler is called.

You should usually not use this method directly, but instead use the “change” events provided by RemoteStorage.BaseClient.

Parameters

path	Absolute path to attach handler to.
handler	Handler function.

enableLog

enableLog: function ()

Enable remoteStorage logging.

disableLog

disableLog: function ()

Disable remoteStorage logging

log

log: function ()

The same as RemoteStorage.log.

setApiKeys (experimental)

setApiKeys: function ( type,
keys )

Set API keys for (currently) GoogleDrive and/or Dropbox backend support. See also the ‘backends’ example in the starter-kit. Note that support for both these backends is still experimental.

Parameters

type	string, either ‘googledrive’ or ‘dropbox’
keys	object, with one string field; ‘clientId’ for GoogleDrive, or ‘appKey’ for Dropbox.

setCordovaRedirectUri

setCordovaRedirectUri: function ( uri )

Set redirect URI to be used for the OAuth redirect within the in-app-browser window in Cordova apps.

Parameters

uri	string, valid HTTP(S) URI

hasFeature

hasFeature: function ( feature )

Checks whether a feature is enabled or not within remoteStorage. Returns a boolean.

Parameters

name	Capitalized name of the feature. e.g. Authorize, or IndexedDB

Example

if (remoteStorage.hasFeature('LocalStorage')) {
  console.log('LocalStorage is enabled!');
}

connected

Boolean property indicating if remoteStorage is currently connected.

access

Tracking claimed access scopes. A RemoteStorage.Access instance.

caching

Caching settings. A RemoteStorage.Caching instance.

Not available in no-cache builds.

remote

Access to the remote backend used. Usually a RemoteStorage.WireClient.

local

Access to the local caching backend used. Usually either a RemoteStorage.IndexedDB or RemoteStorage.LocalStorage instance.

Not available in no-cache builds.