Class: Query

Methods

endAt (name)

api/Query.js, line 435

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());
});

equalTo (name)

api/Query.js, line 457

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());
});

limit (lim)

api/Query.js, line 364

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());
});

off (eventType, callback, context)

api/Query.js, line 237

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 | Array.<string>	optional The type of event to unwatch. It can be either a single value among value, child_added, child_changed or child_removed, or a list of values among the same constants. 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

on (eventType, callback, cancelCallback, context)

api/Query.js, line 98

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 or a given set of types of events to watch.

The specified callback may be called initially (when the on method is called) with respect to the data currently stored at this node (depending on the requested event type). And then, it will be called 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 | Array.<string>	The type of event to watch. It can be either a single value among value, child_added, child_changed or child_removed (see above), or a list of values among the same constants.
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()));
});

once (eventType, callback, cancelCallback, context)

api/Query.js, line 303

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");
});

pathString (){String}

api/Query.js, line 69

Returns the path of the data node represented by this instance of Query.

Versions

• ≥ 2.6.2

Returns:

Type	Description
String	The path of this data node, with path levels separated by "/" (slashes)

ref (){Webcom}

api/Query.js, line 80

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

startAt (name)

api/Query.js, line 410

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());
});

Type Definitions

cancelCallback (error)

api/Query.js, line 550

A callback function to fire when an event subscription must be cancelled because of permission loss.

Name	Type	Description
error	Error	Description of the reason of the event subbscription cancellation.

See:

• on(), once() and off()

watchCallback (snapshot, prevChildName)

api/Query.js, line 559

A callback function to fire when a data watching event occurs.

Name	Type	Description
snapshot	api.DataSnapshot	Snapshot data corresponding to the event.
prevChildName	String | null	optional Name of the previous sibling child depending on key order, or null for an only child. This parameter is valued only for the child_added and child_changed events, otherwise it remains undefined.

See:

• on(), once() and off()