Class: Webcom

Webcom

A Webcom instance represents a particular location in the data tree of a [[service]] application, which is specified by the url parameter.

Reading data is done using on() and once(). Writing data is done using set(), push(), update() and remove(). Browsing the data tree is done using child(), parent() or root(). See Data navigation for more details.

Internally, a Webcom instance opens a global connection to the [[service]] server for the requested application. All Webcom instances on the same application share the same connection as well as the same authentication state. Consequently, you cannot authenticate several users on the same application.

new Webcom (url, options)

Webcom.js, line 100

Constructs a Webcom instance.

Name Type Default Description
url String

URL representing a location in the data tree of your [[service]] application. It should look like:
[[baseUrl]]/base/<your-app>/<data-path>

options Object { optional

Options of the shared connection to the [[service]] server

Name Type Default Description
persist boolean false optional

If true, the shared connection can be used offline and make visible the data stored in the local client cache.

Example
// Get a reference to the "friends" data node of the "contacts" application
var ref = new Webcom('[[baseUrl]]/base/contacts/friends');

Extends

Methods

auth (cred, onComplete)

Webcom.js, line 721

Authenticates the user using a (already available) [[service]] authentication token.

Name Type Description
cred String

The [[service]] authentication token to use

onComplete Webcom.authCallback optional

Callback function to be called when the authentication completes.

Deprecated

authAnonymously (onComplete)

Webcom.js, line 970

Authenticates the user using a temporary account (to be lost at next log-out) with no explicit credentials.

Name Type Description
onComplete Webcom.authCallback optional

Callback function to be called when the authentication completes.
Deprecated: Consider rather using the returned Promise.

Versions
  • ≥ 1.1

See:
Returns:
Type Description
Promise The authentication is performed asynchronously, and its result may be caught by assigning a resolve and/or a reject callback to the returned Promise. The resolve (resp. reject) callback is called with one argument filled with the same value than the auth (resp. error) parameter of authentication callbacks.
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Anonymously log the user in
ref.authAnonymously().then(function(auth) {
  console.log("User logged in, with UID", auth.uid);
});
// ==> ends up in calling authentication callbacks previously registered using resume()

authWithCustomProvider (provider, credentials, onComplete)

Webcom.js, line 998

Authenticates the user using credentials provided by a third-party identity provider.

Name Type Description
provider String

Identifier of the custom provider to use.

credentials String

Credentials for the user to authenticate, which are generated by the 3rd-party identity provider.

onComplete Webcom.authCallback optional

Callback function to be called when the authentication completes.
Deprecated: Consider rather using the returned Promise.

Versions
  • ≥ 2.2.2

See:
Returns:
Type Description
Promise The authentication is performed asynchronously, and its result may be caught by assigning a resolve and/or a reject callback to the returned Promise. The resolve (resp. reject) callback is called with one argument filled with the same value than the auth (resp. error) parameter of authentication callbacks.
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Log the user in, using a 3rd-party identity provider
ref.authWithCustomProvider("myprovider", "theprovidedcredentialsfortheusertoauthenticate").then(function(auth) {
  console.log("User logged in, with UID", auth.uid);
});
// ==> ends up in calling authentication callbacks previously registered using resume()

authWithOAuth (provider, options, onComplete)

Webcom.js, line 1064

Authenticates the user using an OAuth2 provider.

Name Type Description
provider String

The OAuth2 provider to use. Currently supported providers are:

options Object optional

The authentication options to use, with the following properties:

Name Type Default Description
scope String optional

The OAuth2 scope requested to OAuth2 provider. This value is provider-specific and documented in the OAuth API of the provider.
If not set, the minimal scope is used (see Default Scope). This parameter is not relevant when the mode parameter equals code.

mode String popup optional

Currently 3 authentication modes are supported:

  • popup: the calling window opens a popup window to play the OAuth2 authorization call-flow and closes it when completed,
  • redirect: the calling window is redirected to the OAuth2 provider authentication portal and will be reloaded a the end of the authorization call-flow.
  • code: this mode is relevant when using an OAuth2 provider-specific SDK to play the authorization call-flow and that SDK returns an OAuth2 authorization code. In this case, the returned code must be specified in the code parameter.
code String optional

The OAuth2 authorization code to use when the mode parameter equals code. This parameter is not relevant otherwise.

state String optional

The OAuth2 state parameter to use when the mode parameter equals code. This parameter is not relevant otherwise.

onComplete Webcom.authCallback optional

Callback function to be called when the authentication completes.
Deprecated: Consider rather using the returned Promise.

Versions
  • ≥ 1.3

See:
Returns:
Type Description
Promise The authentication is performed asynchronously, and its result may be caught by assigning a resolve and/or a reject callback to the returned Promise. The resolve (resp. reject) callback is called with one argument filled with the same value than the auth (resp. error) parameter of authentication callbacks.
Examples
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Log the user in with Orange France using a popup
ref.authWithOAuth('orange');
// ==> ends up in calling authentication callbacks previously registered using resume()
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Log the user in with Facebook using redirection
ref.authWithOAuth('facebook', {mode: 'redirect'});
// ==> ends up in reloading the page
//     the authentication callbacks will be then called as soon as registered using resume()
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Log the user in with Google using an authorization code (returned by the Google SDK)
ref.authWithOAuth('google', {mode: 'code', code:'XXX...XXX'});
// ==> ends up in calling authentication callbacks previously registered using resume()

authWithPassword (credentials, onComplete)

Webcom.js, line 1029

Authenticates the user using email & password credentials (locally managed by the [[service]] server).

Name Type Description
credentials Object

The user's credentials

Name Type Description
email String

The user's email

password String

The user's password

onComplete Webcom.authCallback optional

Callback function to be called when the authentication completes.
Deprecated: Consider rather using the returned Promise.

See:
Returns:
Type Description
Promise The authentication is performed asynchronously, and its result may be caught by assigning a resolve and/or a reject callback to the returned Promise. The resolve (resp. reject) callback is called with one argument filled with the same value than the auth (resp. error) parameter of authentication callbacks.
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Log the user in with credentials
ref.authWithPassword({
  email: "john@webcom.com",
  password: "pwd"
}).then(function(auth) {
  console.log("User logged in, with UID", auth.uid);
}).catch(function(error) {
  console.log("Login failed, with error", error);
});
// ==> ends up in calling authentication callbacks previously registered using resume()

authWithToken (token, onComplete)

Webcom.js, line 941

Authenticates the user using a (already available) [[service]] authentication token.

Name Type Description
token String

The [[service]] authentication token to use

onComplete Webcom.authCallback optional

Callback function to be called when the authentication completes.
Deprecated: Consider rather using the returned Promise.

Versions
  • ≥ 1.3

See:
Returns:
Type Description
Promise The authentication is performed asynchronously, and its result may be caught by assigning a resolve and/or a reject callback to the returned Promise. The resolve (resp. reject) callback is called with one argument filled with the same value than the auth (resp. error) parameter of authentication callbacks.
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Log the user in with a custom-made [[service]] authentication token
ref.authWithToken('').then(function(auth) {
  console.log("User logged in, with UID", auth.uid);
});
// ==> ends up in calling authentication callbacks previously registered using resume()

changePassword (email, oldPassword, newPassword, onComplete)

Webcom.js, line 1271

Changes the password of an existing email/password identity.

Name Type Description
email String

The email of the identity, the password of which has to be updated

oldPassword String

The current password of the identity

newPassword String

The new password to set

onComplete function optional

A 1-argument callback function that is called after the password change completion, which receives an Error object if it has failed or no argument otherwise.

Returns:
Type Description
Promise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Change the password associated to "john@webcom.com" identity
ref.changePassword("john@webcom.com","pwd","newPwd", function(error) {
  if (error) {
    switch (error.code) {
      case "INVALID_CREDENTIALS":
        console.log("The email doesn't exist or the current password is incorrect!");
        break;
      case "TOO_WEAK_PASSWORD":
        console.log("The new password is not strong enough!");
        break;
      default:
        console.log("The password change failed: " + error.message);
    }
  } else {
    console.log("Password changed successfully!");
  }
});

child (pathString)

Webcom.js, line 225

Gets a Webcom instance that refers to a specific data node within the application data tree, specified as a relative path to the data node referred to by this Webcom instance.

Name Type Description
pathString String

Data path, relative to the location of this Webcom instance.
It may include several segments separated by slashes ("/"). Special path-segments like "." or ".." are not supported. Even with a leading slash, the path is always interpreted relatively.

Returns:
Type Description
Webcom A Webcom instance that refers to the specified path
Example
// Get a reference to the "friends" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

var johnRef = ref.child("john");
console.log(johnRef.name());
// ==> "john"

var maryRef = ref.child("/mary");
console.log(maryRef.toString());
// ==> "[[baseUrl]]/base/contacts/friends/mary"

var nameThenLastRef = johnRef.child("name").child("last");
console.log(nameThenLastRef.toString());
// ==> "[[baseUrl]]/base/contacts/friends/john/name/last"

var lastNameRef = johnRef.child("name/last");
console.log(lastNameRef.toString());
// ==> "[[baseUrl]]/base/contacts/friends/john/name/last"

var wrongRef = johnRef.child("..");
// ==> Error

createUser (credentials, onComplete)

Webcom.js, line 1159

Creates a new [[service]] account bound to an email/password identity.

Name Type Description
credentials Object

The credentials associated to the account to create.

Name Type Description
email String

The email associated to the account to create.

password String

The password associated to the account to create.

profile Object optional

A user-profile structure associated to the account to create. This piece of information can be further retrieved within the providerProfile attribute of the auth parameter received by the authentication callbacks.

onComplete Webcom.authCallback optional

Callback function to be called when the account creation completes.
Deprecated: Consider rather using the returned Promise.

See:
Returns:
Type Description
Promise The account creation is performed asynchronously, and its result may be caught by assigning a resolve and/or a reject callback to the returned Promise. The resolve (resp. reject) callback is called with one argument filled with the same value than the auth (resp. error) parameter of authentication callbacks.
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Create a new account for this application
ref.createUser({
  email: "john@webcom.com",
  password: "pwd"
}, function(error, auth) {
  if (error) {
    switch (error.code) {
      case "EXISTING_IDENTITY":
        console.log("Email already in use!");
        break;
      case "INVALID_EMAIL":
        console.log("Email format is not valid!");
        break;
      default:
        console.log("Account creation failed: " + error.message);
    }
  } else {
    console.log("Successfully created account with UID:" + auth.uid + ", it must be confirmed before use!");
  }
});

inherited endAt (name)

api/Query.js, line 452

Creates a Query object that returns children beginning at a specific ending point.

Name Type Description
name String optional

The child name to end at

Versions
  • ≥ 2.2

Returns:
Type Description
api.Query
  • Generated query
Example
// Get a reference to friends
var ref = new Webcom("/base/contacts/friends");

// Display friends whoses names (keys) come before john
ref.endAt("john").on("value", function(snapshot){
     console.log(snapshot.val());
});

inherited equalTo (name)

api/Query.js, line 477

Creates a Query object that returns children matching a specific value.

Name Type Description
name String optional

The child name to match for.

Versions
  • ≥ 2.2

Returns:
Type Description
api.Query
  • Generated query
Example
// Get a reference to friends
var ref = new Webcom("/base/contacts/friends");

// Display friends whoses names (keys) is exactly john
ref.equalTo("john").on("value", function(snapshot){
     console.log(snapshot.val());
});

goOffline ()

Webcom.js, line 854

Forces disconnection from the [[service]] server and disables the retry connection feature. This method affects all connections.

Example
// Disconnect all local Webcom instances
Webcom.goOffline();

goOnline ()

Webcom.js, line 871

Force reconnection to the [[service]] server and enables the retry connection feature. This method affects all connections.

Example
// Disconnect all local Webcom instances
Webcom.goOffline();
// Reconnect all local Webcom instances
Webcom.goOnline();

inherited limit (lim)

api/Query.js, line 375

Create Query object to limit number of children

Name Type Description
lim Number

Number of items

Versions
  • ≥ 2.2

Returns:
Type Description
api.Query
  • new limited Query object.
Examples

Last

// Get a reference to friends
var ref = new Webcom("/base/contacts/friends");

var lastfriends = ref.endAt().limit(5);
// Display the 5 last friends
lastfriends.on("value", function(snapshot){
     console.log(snapshot.val());
});

First

// Get a reference to friends
var ref = new Webcom("/base/contacts/friends");

var lastfriends = ref.startAt().limit(5);
// Display the 5 first friends
lastfriends.on("value", function(snapshot){
     console.log(snapshot.val());
});

First starting at some key

// Get a reference to friends
var ref = new Webcom("/base/contacts/friends");

var lastfriends = ref.startAt("john").limit(5);
// Display friends whoses names (keys) come after john display the following 5
lastfriends.on("value", function(snapshot){
     console.log(snapshot.val());
});

logout (onComplete)

Webcom.js, line 1431

Logs the currently authenticated user out.

Name Type Description
onComplete function optional

A 1-argument callback function that is called after the log-out, which receives an Error object if it has failed or no argument otherwise.

Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Register an authentication callback
ref.resume(myAuthCallback);
// Log the current user out ==> ends up in calling myAuthCallback
ref.logout(function (error) {
  if (error) {
    console.log("The log-out failed: " + error.message);
  } else {
    console.log("Logged out successfully!");
  }
});

name (){String}

Webcom.js, line 195

Returns the name of the data node this Webcom instance refers to.

Returns:
Type Description
String The name of the data node or null if this instance refers to the root of the application
Example
// Get a reference to the "john" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends/john");

console.log(ref.name());
// ==> "john"

console.log(ref.child("name").name());
// ==> "name"

console.log(ref.root().name());
// ==> null

inherited off (eventType, callback, context)

api/Query.js, line 243

Unwatches data changes at the data node referred to by this Query instance.

It actually unregisters a callback function (or all ones) previously registered on the data node referred to by this Query instance using the on() method.

Note: unregistering all callback functions attached to a data node doesn't unregister callback functions attached to its child nodes. The off() method must be called on all the data nodes that the on() method has been called on.

Name Type Description
eventType String optional

The type of event to unwatch. It can be either value, child_added, child_changed or child_removed.
If not specified, all callbacks previously registered on the data node are unregistered.

callback api.Query~watchCallback optional

Reference to the callback function to unregister (previously passed to or returned by the on() method).
If not set, all callbacks of type eventType previously registered on the data node are unregistered.

context Object optional

Context object for callback binding, passed to previous call to on().

Examples

Unregister a single callback

// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

var onChange = ref.on("value", function(snapshot) {
  // your handler
});

// later...
ref.off("value", onChange);

Unregister several callbacks

// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

var onChanged = function(snapshot) {
  // your first handler
});
var onAdded = function(snapshot) {
  // your second handler
});

ref.on("value", onChanged);
ref.on("child_added", onAdded);

// later...

// Unregister all callback functions from ref...
ref.off();
// ...or all callback function associated to a specific kind of event
ref.off("value"); // onChanged is unregistered while onAdded remains registered

inherited on (eventType, callback, cancelCallback, context)

api/Query.js, line 105

Watches data changes at the data node referred to by this Query instance.

It actually registers a callback function on the data node referred to by this Query instance for a given type of event to watch.

The specified callback will be called initially once (when the on method is called) with the data stored at this node, and then whenever the data change. The notifications can be stopped using the off() method.
Several kinds of callback are available depending on the kind of event to watch:

  • value event

    The callback is called initially once with the current data.
    It is then called again each time the data (stored a this node or any sub-node) change.

    The DataSnapshot passed to the callback refers to the new data stored at the data node referred to by this Query instance.
    The prevChildName argument passed to the callback is not used and remains undefined.

  • child_added event

    The callback is called initially once for each current child node of this node.
    It is then called again each time a new data child is added to this node.

    The DataSnapshot passed to the callback refers to the new data stored at the corresponding child data node.
    The prevChildName argument passed to the callback refers to the name of the sibling child node that precedes the added child node in the data tree structure (following key order), or null if the added child node is the first child of the data node referred to by this Query instance.

  • child_changed event

    The callback is not initially called.
    It is then called each time the value of one of the data children changes (excluding child additions and removals).

    The DataSnapshot passed to the callback refers to the new data stored at the corresponding child data node.
    The prevChildName argument passed to the callback refers to the name of the sibling child node that precedes the changed child node in the data tree structure (following key order), or null if the changed child node is the first child of the data node referred to by this Query instance.

  • child_removed event

    The callback is not initially called.
    It is then called each time one of the data children is removed (or its value becomes null or it loses all of its children).

    The DataSnapshot passed to the callback refers to the old data stored at the corresponding child data node.
    The prevChildName argument passed to the callback is not used and remains undefined.

Note: data is first synchronized locally, so that if you set (using the set() method) some data locally after registering a watch callback, this callback will be called immediately. Later, when the synchronization with the server occurs, the callback will be possibly called again for data update, or even for data deletion if the synchronization fails.

Name Type Description
eventType String

The type of event to watch. It can be either value, child_added, child_changed or child_removed (see above).

callback api.Query~watchCallback

Callback function called when the specified event occurs (see above).

cancelCallback api.Query~cancelCallback optional

Callback function called when the authenticated user loses read permission at the data node referred to by this Query instance. In this case, the watch callback function is automatically unregistered and will no longer be called.

context Object optional

Context object for callback binding

Returns:
Type Description
api.Query~watchCallback A reference to the callback function provided in the callback parameter. It is intended to be passed to the off() method, especially when the callback parameter is given as an inline function.
Examples

Value

// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

// This callback is called only when some data change under the "friends" node
ref.on("value", function(snapshot) {
  console.log("New friends value is: " + JSON.stringify(snapshot.val()));
});

Child Added

// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

// This callback is called only when a new child is added to the "friends" node
ref.on("child_added", function(snapshot, prevChildName) {
  console.log("New child for friends: " + snapshot.name() + " -> " + JSON.stringify(snapshot.val()));
  if (prevChildName) {
    console.log("This new child comes after " + prevChildName);
  } else {
    console.log("This new child is the only one");
  }
});

Child Changed

// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

// This callback is called only when the value of an existing child of the "friends" node changes
ref.on("child_changed", function(snapshot, prevChildName) {
  console.log("The " + snapshot.name() + " child has changed value to: " + JSON.stringify(snapshot.val()));
  if (prevChildName) {
    console.log("This child comes after " + prevChildName);
  } else {
    console.log("This child is the only one");
  }
});

Child Removed

// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

// This callback is called only when a child of the "friends" node is removed
ref.on("child_removed", function(snapshot) {
  console.log("The " + snapshot.name() + " child has been removed, its value was: " + JSON.stringify(snapshot.val()));
});

inherited once (eventType, callback, cancelCallback, context)

api/Query.js, line 311

Watches the next data change at the data node referred to by this Query instance.

This method is similar to on(), except it automatically unregisters the given callback function from the data node referred to by this Query instance as soon as it is called. In other words, the given callback function will be called no more than once.

With the value event type, this method makes it possible to read (asynchronously) the data stored at a given data node.

Name Type Description
eventType String

The type of event to watch. It can be either value, child_added, child_changed or child_removed (see on()).

callback api.Query~watchCallback

Callback function called when the specified event occurs.

cancelCallback api.Query~cancelCallback optional

Callback function called when the authenticated user loses read permission at the data node referred to by this Query instance. In this case, the watch callback function is automatically unregistered and will no longer be called.

context Object optional

Context object for callback binding

Examples
// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

// Read the value of the "friends" node
ref.once("value", function(snapshot) {
  console.log("The value of the " + snapshot.name() + " node is: " + JSON.stringify(snapshot.val()));
});
// Get a reference to the "friends" node of the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

// Check the read permission on the "friends" node
ref.once("value", function() {}, function(error) {
  console.log("Insufficient read permission");
});

onDisconnect (){api.OnDisconnect}

Webcom.js, line 700

Gets an instance of OnDisconnect, which refers to the data node referred to by this Webcom instance.

Returns:
Type Description
api.OnDisconnect
Example
// Get a reference to the "john" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends/john");

// Create a disconnection listener
var disconnectRef = ref.child("online").onDisconnect().set(false);

parent (){Webcom}

Webcom.js, line 277

Gets a Webcom instance that refers to the parent data node of the one referred to by this Webcom instance.

Returns:
Type Description
Webcom A parent instance of this Webcom instance or null if the data node referred to by this Webcom instance has no parent.
Example
// Get a reference to the "friends" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

var contactsRef = ref.parent();
console.log(contactsRef.toString());
// ==> "[[baseUrl]]/base/contacts"

push (value, onComplete)

Webcom.js, line 639

Adds a new child at the data node referred to by this Webcom instance. Its key is automatically generated, so that it is unique and lexicographically ordered after any previously generated key.

Name Type Description
value Object | String | Number | Boolean | null optional

The value of the new child to add. If not set, the new child is created without value.

onComplete function optional

A 1-argument callback function called after synchronization with the server. Its argument is filled with an Error object if an error occurred or null otherwise.

Returns:
Type Description
Webcom A Webcom instance referring to the added child.
Examples
// Get a reference to the "john" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends/john");

// Create a randomly generated unique child
var refPhone = ref.push();
console.log(refPhone.toString());
// ==> "[[baseUrl]]/base/contacts/friends/john/-Jjj6vK9L0NAd9JHusrd"

// Set a value on this new child
refPhone.set({number : "0123456789"});
var ref = new Webcom("[[baseUrl]]/base/contacts/friends/john");

// The same as the previous example, in a single operation
ref.push({number : "0123456789"});
var ref = new Webcom("[[baseUrl]]/base/contacts/friends/john");

// The same as the previous example, with a completion callback
ref.push({number : "0123456789"}, function(error) {
  if (error) {
    console.log("synchronisation error:", error);
  } else {
    console.log("synchronisation ok.");
  }
});

inherited ref (){Webcom}

api/Query.js, line 83

Returns a Webcom reference associated to the data node referred to by this Query instance.

Returns:
Type Description
Webcom A Webcom reference.
Example
// Get a reference to the "friends" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends");

var query = ref.limit(2);
var refSameLocation = query.ref(); //ref === refSameLocation

registerAuthCallback (callback)

Webcom.js, line 792

Registers an authentication callback function, to be called each time the authentication state changes.

Name Type Description
callback Webcom.authCallback

the callback function

See:
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Register an authentication callback
ref.registerAuthCallback(function(error, auth) {
  if (error) {
    console.log("An error occurred while authenticating", error);
  } else if (auth) {
    console.log("The user with the following identity information has logged in", auth);
  } else {
    console.log("The user has logged out");
  }
});
// Log the user in, this will end in calling the authentication callback
ref.authAnonymously();

remove (onComplete)

Webcom.js, line 506

Removes data at the data node referred to by this Webcom instance.

Name Type Description
onComplete function optional

A 1-argument callback function called after synchronization with the server. Its argument is filled with an Error object if an error occurred or null otherwise.

Example
// Get a reference to the "john" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends/john");

// Remove all data from the "john" data node
ref.remove();

removeUser (email, password, onComplete)

Webcom.js, line 1312

Removes an existing email/password identity.
Warning: this method doesn't remove the associated [[service]] account.

Name Type Description
email String

The email of the identity to remove

password String

The password of the identity to remove

onComplete function optional

A 1-argument callback function that is called after the email/password identity removal, which receives an Error object if it has failed or no argument otherwise.

See:
Returns:
Type Description
Promise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Remove the "john@webcom.com" identity
ref.removeUser("john@webcom.com", "pwd")
  .then(function() {
    console.log("Identity removed!");
  }).catch(function(error) {
    switch (error.code){
      case "INVALID_CREDENTIALS":
        console.log("The identity or the password is invalid!");
        break;
      default:
        console.log("The identity removal failed: " + error.message);
    }
  });

resume (callback)

Webcom.js, line 754

Resumes the authentication state (based on records from the local storage).

Name Type Description
callback Webcom.authCallback optional

If set, registers additionally an authentication callback function to be called each time the authentication state changes.
Deprecated The usage of this parameter is strongly discouraged, use explicitly the registerAuthCallback() method instead.

Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Register an anthentication callback
ref.registerAuthCallback(function(error, auth) {
  if (error) {
    console.log("An error occurred while authenticating", error);
  } else if (auth) {
    console.log("The user with the following identity information has logged in", auth);
  } else {
    console.log("The user has logged out");
  }
});
// Resume the authentication state, this will possibly end in calling the authentication callback
ref.resume();

root (){Webcom}

Webcom.js, line 302

Gets a Webcom instance that refers to the data tree root of current [[service]] application.

Returns:
Type Description
Webcom A Webcom instance that refers to the root data node
Example
// Get a reference to the "john" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends/john");

var rootRef = ref.root();
console.log(rootRef.toString());
// ==> "[[baseUrl]]/base/contacts"

sendConfirmationEmail (email, onComplete)

Webcom.js, line 1389

Sends an email with a link to confirm an email/password identity. This method is particularly useful when the user has not received the initial confirmation email sent when creating her/his account (using the Webcom#createUser method.

Name Type Description
email String

The email address of the identity to confirm, which the email must be send to

onComplete function optional

A 1-argument callback function that is called after the sending of the confirmation email, which receives an Error object if it has failed or no argument otherwise.

Returns:
Type Description
Promise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Send a confirmation email
ref.sendConfirmationEmail("john@webcom.com", function(error) {
  if (error) {
    switch (error.code) {
      case "INVALID_CREDENTIALS":
        console.log("The specified identity is invalid!");
        break;
      case "ALREADY_VERIFIED_IDENTITY":
        console.log("The specified identity is already confirmed");
        break;
      default:
        console.log("The sending of the confirmation email failed: " + error.message);
    }
  } else {
    console.log("Confirmation email successfully sent!");
  }
});

sendPasswordResetEmail (email, onComplete)

Webcom.js, line 1351

Sends an email to the user of an email/password identity, with a link to reset the associated password. This method is intended to be used when the user has lost her/his password.

Name Type Description
email String

The email of the identity to reset

onComplete function optional

A 1-argument callback function that is called after the sending of the password reset email, which receives an Error object if it has failed or no argument otherwise.

Returns:
Type Description
Promise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Send a password reset email
ref.sendPasswordResetEmail("john@webcom.com", function(error) {
  if (error) {
    switch (error.code) {
      case "INVALID_CREDENTIALS":
        console.log("The specified identity is invalid!");
        break;
      default:
        console.log("The sending of the password reset email failed: " + error.message);
    }
  } else {
    console.log("Reset password email successfully sent!");
  }
});

set (newVal, onComplete)

Webcom.js, line 360

(Over)writes data at the data node referred to by this Webcom instance.

Name Type Description
newVal Object | String | Number | Boolean | null

The value to write. If it is an Object, all children of the current data node are removed before writing this value. In order to merge existing children with the ones of the value to write, use update().

onComplete function optional

A 1-argument callback function called after synchronization with the server. Its argument is filled with an Error object if an error occurred or null otherwise.

Examples

Write a single value

// Get a reference to the "john" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends/john");

// Overwrite first name and last name with "John" and "Doe" values
ref.child("name/first").set("John");
ref.child("name/last").set("Doe");

Write an object

// Get a reference to the "john" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends/john");

// Define a callback to log the result
var onFinish = function(error) {
  if(error) {
    console.log("There is a problem...");
  } else {
    console.log("It's OK!");
  }
};
// Overwrite the "name" data node atomically
ref.child("name").set({first:"John",last:"Doe"}, onFinish);

inherited startAt (name)

api/Query.js, line 424

Creates Query object that returns children beginning at a specific starting point.

Name Type Description
name String optional

The child name to start at

Versions
  • ≥ 2.2

Returns:
Type Description
api.Query
  • Generated query
Example
// Get a reference to friends
var ref = new Webcom("/base/contacts/friends");

// Display friends whoses names (keys) come after john
ref.startAt("john").on("value", function(snapshot){
     console.log(snapshot.val());
});

toString (){String}

Webcom.js, line 327

Returns the absolute URL of the data node referred to by this Webcom instance.

Returns:
Type Description
String The absolute URL of this Webcom instance
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");

console.log(ref.toString());
// ==> "[[baseUrl]]/base/contacts"

var johnRef = ref.child("friends/john");
console.log(johnRef.toString());
// ==> "[[baseUrl]]/base/contacts/friends/john"

var alfredRef = ref.child("friends/alfred:54");
console.log(alfredRef.toString());
// ==> "/contacts/friends/alfred%3A54"

transaction (transactionUpdate, onComplete, applyLocally)

Webcom.js, line 530

Writes data atomically within a transaction at the data node referred to by this Webcom instance. This means the data will be actually written only if the data node is not modified by another client during the transaction. Otherwise, the transaction is retried (up to 25 times) until it can be completed safely without conflict.

Name Type Description
transactionUpdate function

A 1-argument function that receives the current value of the data node and is expected to return either an undefined value to abort the transaction, or the new value to overwrite at the data node.
It may be called several times if the transaction performs retries.

onComplete function optional

A 3-argument function that is called after the transaction execution whatever its outcome (completed or aborted):

  • The first argument receives null if no error occurred during the transaction or an Error object otherwise.
  • The second argument is a Boolean indicating whether the transaction has completed (true) or has been aborted (false) because transactionUpdate returned an undefined value.
  • The third argument is a api.DataSnapshot object containing the resulting value of the data node (this value is passed even in case of error).
applyLocally Boolean optional

If set to true (default), updates locally the data node value (and further calls the listeners on the data node) each time transactionUpdate is called, that is possibly many times if the transaction performs several retries.
If set to false, updates the data node value only once the transaction is completed.

Versions
  • ≥ 1.1

Examples

Increment the value of a data node

// Get a reference to the "john" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends/john");

ref.child("numberOfCalls").transaction(function(current) {
  if (current === null) {
    return 0;           // initial value
  } else {
    return current + 1; // next values
  }
});

Write some data only if there is none

// Get a reference to the "john" data node
var ref = new Webcom("[[baseUrl]]/base/contacts/friends/john");

ref.transaction(function(current) {
  if (current === null) {  // there is no data at the "john" data node => set some
    return {
      name: {
        first: "John",
        last: "Doe"
      }
    };
  } else { // there is already some data => abort transaction
    console.log("John already exists!");
    return;
  }
}, function(error, committed, snapshot){
  if (error) {
    console.log("An unexpected error occurred:", error);
  } else if (!committed) {
    console.log("Transaction aborted (John already exists)");
  } else {
    console.log("Transaction completed (John added)");
  }
  console.log("John:", snapshot.val());
});

unregisterAuthCallback (callback)

Webcom.js, line 821

Unregisters an authentication callback function.

Name Type Description
callback Webcom.authCallback optional

the callback function to unregister. Note that it must be a reference to a function previously registered with registerAuthCallback() (an inline function would not be recognized).
If not specified, this method unregisters all callbacks

See:
Returns:
Type Description
boolean true if the callback function to unregister was found, or false otherwise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// Defined an authentication callback
var myCallback = function(error, auth) {
  console.log(auth ? "User logged in!" : "User logged out or error!");
};
// Register it
ref.registerAuthCallback(myCallback);
// Log the user in, this will end in calling the authentication callback
ref.authAnonymously();
// Unregister the callback
ref.unregisterAuthCallback(myCallback);
// Log the user out, this no longer calls the authentication callback
ref.logout();

update (newVal, onComplete)

Webcom.js, line 405

Updates data at the data node referred to by this Webcom instance.

Name Type Description
newVal Object

The children to add to the current data node, given as a json Object. The difference with set() is that existing children (at depth 1 only) are preserved (provided newVal doesn't specify a new value for them).

onComplete function optional

A 1-argument callback function called after synchronization with the server. Its argument is filled with an Error object if an error occurred or null otherwise.

Examples
// Get a reference to the "lords" data node
var ref = new Webcom("[[baseUrl]]/base/got/lords");

// Update first name and last name without deleting other existing children of "id56".
ref.child("id56").update({first:"John",last:"Snow"});
// Thus: if data at ref.child('id56') was {first:"Ned",last:"Stark",status:"King of the North"}
// it is now: {first:"John",last:"Snow",status:"King of the North"}.

Warning about update depth

ref.child('id57').update({ name: { first:'Alice' } })
//is exactly equivalent to
ref.child('id57').child("name").set({ first:'Alice' })
// Thus: if data at ref.child('john') was {first:"John",last:"Doe"}
// it is now: { first:'Alice' }. Note that last field is deleted

//Other example:
ref.child('id57').update({ name: { first:'John' } , age:43})
//is equivalent to
ref.child('id57').child("name").set({ first:'John' })
//PLUS
ref.child('id57').child("age").set(43)
//except that update performs 2 operations atomically.

updateEmailPasswordProfile (path, data, onComplete)

Webcom.js, line 1225

Updates some data within the profile associated to the currently authenticated email/password identity. This method fails if no user is currently authenticated or if the currently authenticated user is not identified with an email/password identity.

Name Type Description
path Object optional

The path within the profile where to update the data

data String

The data to update within the profile (as a JSON object)

onComplete function optional

A 1-argument callback function that is called after the profile update completion, which receives an Error object if it has failed or no argument otherwise.

Returns:
Type Description
Promise
Example
// Get a reference to the "contacts" application
var ref = new Webcom("[[baseUrl]]/base/contacts");
// We must be authenticated...
ref.authWithPassword({email:"john@webcom.com", password:"mypassword"})
    // ...before updating the identity profile
    .then(auth => ref.updateEmailPasswordProfile({age: 42}))
    .then(() => console.log("profile updated!")
    .catch(error => console.log("profile update failure:", error);

Type Definitions

authCallback (error, auth)

Webcom.js, line 52

A callback function that is called when the authentication state changes.

Name Type Description
error Error

If not null, indicates that the last authentication-related operation failed. This object is provided with the following properties:

Name Type Description
code String

A machine-readable code that identifies the error

message String

A human-readable description of the error

auth Object

Relevant only when error is null.
If null, no user is currently authenticated (typically the previously authenticated user has logged out), otherwise, this object describes the authenticated user identity (which depends on the authentication method).
Here are the main properties of this object, common to all authentication methods:

Name Type Description
provider String

The authentication method used

uid String

The [[service]] account identifier of the authenticated user

expires Number

The expiration date of the authentication (in seconds since the Unix epoch)

See: