Class: DataSnapshot

DataSnapshot(node, ref, eventTypeopt)

DataSnapshot is useful to read data from a specific location. Callbacks passed to on() and once() are called with DataSnapshot instances as first parameter. To get data, use val() method.

DataSnapshot instance are immutables. To update data, use instead Webcom.set(), Webcom.update(), Webcom.push() or Webcom.remove() method.

Constructor

new DataSnapshot(node, ref, eventTypeopt)

DataSnapshot constructor

Parameters:
Name Type Attributes Description
node core.snap.LeafNode | core.snap.ChildrenNode

the snapshot
ref Webcom

the Webcom reference for the location that generated this DataSnapshot
eventType string <optional>

The event type that generated this DataSnapshot
Example
A DataSnapshot is passed to your event callbacks with on() and once()
var ref = new Webcom("contacts").child("friends/john");

ref.once("value", function(snapshot) {
 // Your code
});

Data model for example
{
 "contacts":{
     "friends":{
         "john":{
             "name":{
                 "first": "John",
                 "last": "Doe"
             },
             "address" : "avenue des tulipes"
         },
         ...
     },
     "family":{
         ...
     },
     ...
 }
}

Methods

child(childPathString) → {api.DataSnapshot}

Retrieve child DataSnapshot corresponding to specified relative path

Parameters:
Name Type Description
childPathString String

relative path
Returns:

child DataSnapshot

Type
api.DataSnapshot
Example
// Get a reference to John
var ref = new Webcom("contacts").child("friends/john");

ref.once("value", function(snapshot){
 var nameSnapshot = snapshot.child("name");
 var name = nameSnapshot.val();
 console.log(name);
 // ==> { first: "John", last: "Doe" }

 var firstName = snapshot.child("name/first").val();
 //Or
 var firstName = nameSnapshot.child("first");
 // It's like you do snapshot.child("name").child("first");
 console.log(firstName.val());
 // ==> John

 var mobilePhone = snapshot.child("mobilePhone");
 console.log(mobilePhone.val());
 // ==> null (There is no "mobilePhone" child)
});

exportVal() → {api.DataSnapshot}

Retrieve value object of the DataSnapshot with priority data.

Returns:

value object with priority data

Type
api.DataSnapshot
Example
// Get a reference to our contacts
 var ref = new Webcom("contacts").child("friends");

 // Iterates over all friends with a priority
 ref.setWithPriority({ name: "John" }, 300, function(error){
     ref.on("value", function(snapshot) {
         var user = snapshot.exportVal();
         // Display information of current user
         console.log(user.first_name);
         //David
         console.log(user[".priority"];
         //300
     });
 });

forEach(action) → {Boolean}

Iterate over DataSnapshot's children

Parameters:
Name Type Description
action function

For each child, this function is called with child as parameter. You can return true to stop loop.
Returns:

true if loop was stopped intentionaly.

Type
Boolean
Example
// Get a reference to friends
var ref = new Webcom("contacts").child("friends");

ref.once("value", function(snapshot){
 // Callback function will get called once per user found
 snapshot.forEach(function(childSnapshot){
     // key contains key value of occurrence, per example "john"
     var key = childSnapshot.name();

     // childData will be current value of the child
     var childData = childSnapshot.val()
     // childData ==> { first: "John", last: "Doe" }

     //If you want you can cancel the enumeration with a return true
     //It's useful for a search function for example
     return true;
 });
});

hasChild(childPathString) → {Boolean}

Returns if specified child exists

Parameters:
Name Type Description
childPathString String

relative path
Returns:

true if child exists, false otherwise

Type
Boolean
Example
// Get a reference to John
var ref = new Webcom("contacts").child("friends/john");

ref.once("value", function(snapshot){
 var hasNameChild = snapshot.hasChild("name");
 // hasNameChild ==> true

 var hasMobilePhoneChild = snapshot.child("mobilePhone");
 // hasMobilePhoneChild ==> false
});

hasChildren() → {Boolean}

Returns if current DataSnapshot has at least one child.

Returns:

true if any child exists, false otherwise

Type
Boolean
Example
// Get a reference to John
var ref = new Webcom("contacts").child("friends/john");

ref.once("value", function(snapshot){
 var johnHasChildren = snapshot.hasChildren();
 // johnHasChildren ==> true

 var nameHasChildren = snapshot.child("name").hasChildren();
 // nameHasChildren ==> true

 var firstHasChildren = snapshot.child("name").child("first").hasChildren();
 // firstHasChildren ==> false ; a string doesn't have children
});

name() → {String}

Retrieve key of current location targeted by DataSnapshot

Returns:

key name

Type
String
Examples
// Get a reference to John
var ref = new Webcom("contacts").child("friends/john");

ref.once("value", function(snapshot){
 var johnKey = snapshot.name();
 // johnkey ==> "john"

 var lastKey = snapshot.child("name").child("last");
 // lastKey ==> "last"
});
//Other example without nodes
var ref = new Webcom("contacts");

ref.once("value", function(snapshot){
 var rootKey = snapshot.name();
 // rootkey ==> null

 var johnKey = snapshot.child("friends/john");
 // lastKey ==> "john"
});

numChildren() → {Number}

Retrieve number of children

Returns:

number of children

Type
Number
Example
// Get a reference to John
var ref = new Webcom("contacts").child("friends/john");

ref.once("value", function(snapshot){
 var johnChildren = snapshot.numChildren();
 // johnChildren ==> 1 ("name")

 var nameChildren = snapshot.child("name").numChildren();
 // nameChildren ==> 3 ("last","first","address")

 var firstChildren = snapshot.child("name").child("first").numChildren();
 // firstChildren ==> 0 ; It'a string therefore there isn't children
});

rawVal() → {Object|String|Number|Boolean|Null}

Retrieves the raw value of this DataSnapshot. The raw value is either a constant or a treelike value involving exclusively JSON objects (with no JSON array at any level).

See:
  • val
Returns:

value object

Type
Object | String | Number | Boolean | Null
Example
// Get a reference to our contacts
 var ref = new Webcom("contacts");

 // Display all contacts
 ref.once("value", function(snapshot) {
     console.log(snapshot.rawVal());
     // {"0": {"firstname": "john", "name": "doe"},
     //  "1": {"firstname": "david", "name": "smith"}}
 });

ref() → {Webcom}

Retrieve current Webcom instance for this DataSnapshot.

Returns:

{Webcom} instance

Type
Webcom
Example
// Get a reference to John
var ref = new Webcom("contacts").child("friends/john");

ref.once("value", function(snapshot){
 var snapshotRef = snapshot.ref();

 var snapshotRefJohn = snapshotRef.name();
 // snapshotRefJohn ==> "john"
 //snapshotRefJohn === snapshot.name()
});

val() → {Object|String|Number|Boolean|Null}

Retrieves the value of this DataSnapshot as a JSON value. Subtrees whose keys are integer values are returned as JSON arrays.

See:
  • rawVal
Returns:

value object

Type
Object | String | Number | Boolean | Null
Example
// Get a reference to our contacts
 var ref = new Webcom("contacts");

 // Display all contacts
 ref.once("value", function(snapshot) {
     console.log(snapshot.val());
     // [{"firstname": "John", "name": "Doe"}, {"firstname": "Robert", "name": "Martin"}]
 });