Realtime Cloud Storage

ItemRef

class ItemRef

Class with the definition of an item reference.

Methods

ItemRef decr(String property, [Number value], function(ItemSnapshot itemSnapshot) success, [function(String message) error])

Decrements the value of an items attribute. If the attribute doesn't exist, it is set to zero before the operation.

Parameters

String property

The name of the item's attribute.

Number value optional

The number to subtract. Defaults to 1 if not specified.

function(ItemSnapshot itemSnapshot) success

The function invoked once the attribute has been decremented successfully.

Arguments

ItemSnapshot itemSnapshot

An immutable copy of the decremented item.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Creates an item reference
var itemRef = tableRef.item({
	primary: "myId",
	secondary: 111222333444
});

// Increment the attribute 'replies' of the item
item.decr(
	"replies", 
	5, 
	function(itemSnapshot) {
		console.log(itemSnapshot.val());
	}, 
	function error(data) { 
		console.error("Error:", data); 
	}
);

ItemRef del([String[] properties], [function(ItemSnapshot itemSnapshot) success], [function(String message) error])

Delete the value of this item reference.

Parameters

String[] properties optional

The name of the properties to delete.

function(ItemSnapshot itemSnapshot) success optional

Response from the server when the request was completed successfully. @...{ItemSnapshot} itemSnapshot An immutable copy of the deleted item.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Creates an item reference
var itemRef = tableRef.item({
	primary: "myId",
	secondary: 111222333444
});

// delete item
itemRef.del(
	function success(itemSnapshot) {
		// Logs the value of the item
		console.log(itemSnapshot.val());
	}, 
	function error(data) { 
		console.error("Error:", data); 
	}
);

ItemRef get([function(ItemSnapshot itemSnapshot) success], [function(String message) error])

Get the value of this item reference.

Parameters

function(ItemSnapshot itemSnapshot) success optional

Response from the server when the request was completed successfully. @...{ItemSnapshot} itemSnapshot An immutable copy of the retrieved item.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Creates an item reference
var itemRef = tableRef.item({
	primary: "myId",
	secondary: 111222333444
});

// perform get
itemRef.get(
	function success(itemSnapshot) {
		// Logs the value of the item
		console.log(itemSnapshot.val());
	}, 
	function error(data) { 
		console.error("Error:", data); 
	}
);

ItemRef incr(String property, [Number value], function(ItemSnapshot itemSnapshot) success, [function(String message) error])

Increments a given attribute of an item. If the attribute doesn't exist, it is set to zero before the operation.

Parameters

String property

The name of the item's attribute.

Number value optional

The number to add. Defaults to 1 if not specified.

function(ItemSnapshot itemSnapshot) success

The function invoked once the attribute has been incremented successfully.

Arguments

ItemSnapshot itemSnapshot

An immutable copy of the incremented item.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Creates an item reference
var itemRef = tableRef.item({
	primary: "myId",
	secondary: 111222333444
});

// Increment the attribute 'replies' of the item
item.incr(
	"replies", 
	20, 
	function(itemSnapshot) {
		console.log(itemSnapshot.val());
	}, 
	function error(data) { 
		console.error("Error:", data); 
	}
);

ItemRef off([String eventType], [function(ItemSnapshot itemSnapshot) handler], [function(String message) error])

Remove an event handler.

Parameters

String eventType optional

The type of the event to remove. Possible values: put, update, delete. If not specified, it will remove all listeners of this reference.

function(ItemSnapshot itemSnapshot) handler optional

A previously attached listener. If not specified, it will remove all listeners of the specified type or all listeners of this reference.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Creates an item reference
var itemRef = tableRef.item({
	primary: "myId",
	secondary: 111222333444
});

var listener = function(itemSnapshot) {
	console.log(itemSnapshot.val());
};

// Add an update listener
itemRef.on("update", listener);

// Stop listening after 5 seconds
setTimeout(function() {
	// Remove the listener
	itemRef.off("update", listener);
}, 5000);

ItemRef on(String eventType, function(ItemSnapshot itemSnapshot) handler, [function(String message) error])

Attach a listener to run every time the eventType occurs.

Parameters

String eventType

The type of the event to listen. Possible values: put, update, delete.

function(ItemSnapshot itemSnapshot) handler

The function to run whenever the notification is received. If the event type is "put", it will immediately trigger a "getItems" to get the initial data and run the callback with each item snapshot as argument.

Arguments

ItemSnapshot itemSnapshot

An immutable copy of the modified item.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Creates an item reference
var itemRef = tableRef.item({
	primary: "myId",
	secondary: 111222333444
});

// Add an update listener. A notification is received each time the item is updated.
itemRef.on("update", function(itemSnapshot) {
	console.log(itemSnapshot.val());
});

ItemRef once(String eventType, function(ItemSnapshot itemSnapshot) handler, [function(String message) error])

Attach a listener to run only once the event type occurs.

Parameters

String eventType

The type of the event to listen. Possible values: put, update, delete.

function(ItemSnapshot itemSnapshot) handler

The function invoked, only once, when the notification is received. If the event type is "put", it will immediately trigger a "getItems" to get the initial data and run the callback with each item snapshot as argument.

Arguments

ItemSnapshot itemSnapshot

An immutable copy of the modified item.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample

// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Creates an item reference
var itemRef = tableRef.item({
	primary: "myId",
	secondary: 111222333444
});

// Add an update listener. Only one notification is received once the item is updated after the listener is set.
itemRef.once("update", function(itemSnapshot) {
	console.log(itemSnapshot.val());
});

ItemRef set(Object items, [function(ItemSnapshot itemSnapshot) success], [function(String message) error])

Updates the value of this item reference.

Parameters

Object items

The object with the properties to set or update.

function(ItemSnapshot itemSnapshot) success optional

Response from the server when the request was completed successfully. @...{ItemSnapshot} itemSnapshot An immutable copy of the inserted item.

function(String message) error optional

Response if client side validation failed or if an error was returned from the server.

Arguments

String message

The message detailing the error.

Sample


// Create a storage reference
var storageRef = Realtime.Storage.create({
	applicationKey: "myApplicationKey",
	authenticationToken: "myAuthenticationToken"
});

// Create a table reference
var tableRef = storageRef.table("myTable");

// Creates an item reference
var itemRef = tableRef.item({
	primary: "myId",
	secondary: 111222333444
});

// Update the item
itemRef.set(
	{ myNewProperty: "myNewValue" },
	function success(itemSnapshot) {
		// Logs the value of the item
		console.log(itemSnapshot.val());
	}, 
	function error(data) { 
		console.error("Error:", data); 
	}
);