How to use Datastore

Alex Cavazos edited this page Sep 14, 2018 · 53 revisions

Datastore

Datastore is a framework provided in buildfire.js that allows the plugin developer to save and retrieve simple and complex data. The framework facilitates CRUD operations common to all data operations as well as searching, sorting and paging complex data.

This service also takes care of all server side infrastructure to unburden the developer and app owner for developing the server side components and the costs of running a server. This service is provided out of the box at no additional charge.

The datastore service also handles complex synchronizations between the control and widget. For example, it will notify the widget when the control has made changes to the data. It also handles caching of data and other performance enhancements.

The use of the datastore is completely optional. The developer may choose to communicate with his own custom api. The only caveat to keep in mind is when a plugin is in draft mode of live mode (see publish). You can work around this with publish web hooks (see publish web hooks)

##How to use Datastore Every plugin page must import the buildfire.js framework. This exposes the buildfire object. Within the buildfire object there is a property called datastore accesses via buildfire.datastore


buildfire.datastore.get ( tag <optional>, callback)

this method calls the datastore to retrieve plugin data objects in JSON format , and if there are many objects with the same id, only one record randomly will be returned

arguments

  • tag: is an optional string that you use to differentiate content JSON objects from design objects or master vs detail objects... etc
  • callback: is a function that is called when the data is retrieved from the datastore. function(err,data){}
  • If no entry is found, the callback will still return a data object with NO ID.

example

buildfire.datastore.get('main record',function(err,data){
    if(err)
        alert('there was a problem retrieving your data');
    else
        alert('got your data ' + JSON.stringify(data) );
});

buildfire.datastore.getById ( id , tag <optional>, callback)

this method calls the datastore to retrieve plugin data objects in JSON format

arguments

  • id: is used to specify a particular object to get
  • tag: is an optional string that you use to differentiate content JSON objects from design objects or master vs detail objects... etc
  • callback: is a function that is called when the data is retrieved from the datastore. function(err,data){}

example

buildfire.datastore.getById( '55bfa813032868a0115c5f98','main record',function(err,data){
    if(err)
        alert('there was a problem retrieving your data');
    else
        alert('got your data ' + JSON.stringify(data) );
});

buildfire.datastore.save (obj, tag <optional>, callback)

this method calls the datastore to update all plugin data objects that have that tag. if no object is found it will create one, and does not check for duplicates

arguments

  • obj: is the JSON object you'd like saved. Can be a complex JSON object as long as its not recursive. Must be under the maximum size limitation of a single object (see Maximum Object Size limit)
  • tag: is an optional string that you use to differentiate content JSON objects from design objects or master vs detail objects... etc
  • callback: is a function that is called with the status of your save. function(err,status){}

example

buildfire.datastore.save({name:"Daniel Hindi", tel:"555-555-5555"}, 'contactInfo',function(err,data){
    if(err)
        alert('there was a problem saving your data');
    else
        alert('your data has saved successfully');
});

buildfire.datastore.insert (obj, tag <optional>,checkDuplicate , callback)

this method calls the datastore to insert a data object. if an object already exists with this tag and checkDuplicate is false it will create another record otherwise a duplicate entry error will return. Use this method to save multiple records.

arguments

  • obj: is the JSON object you'd like saved. Can be a complex JSON object as long as its not recursive. Must be under the maximum size limitation of a single object (see Maximum Object Size limit)
  • tag: is an optional string that you use to differentiate content JSON objects from design objects or master vs detail objects... etc
  • checkDuplicate: is a Boolean flag; if true it will prevent insertion of duplicate records, If false it will allow duplicate
  • callback: is a function that is called with the status of your save. function(err,status){}

example

function addContactRecord(contact){
	buildfire.datastore.insert(contact, 'contactInfo',false,function(err,data){
		if(err)
			alert('there was a problem saving your data');
		else
			alert( contact.name + ' saved successfully');
	});
};

 addContactRecord ( {name:"John Doe", tel:"555-111-1111"} );
 addContactRecord ( {name:"Jane Doe", tel:"555-222-2222"} );

buildfire.datastore.bulkInsert (obj, tag <optional> , callback)

this method calls the datastore to bulkInsert a data object. if an objects already exists with this tag it will create another records. Use this method to save multiple records with single API call.

arguments

  • obj: is the JSON array you'd like saved.
  • tag: is an optional string that you use to differentiate content JSON objects from design objects or master vs detail objects... etc
  • callback: is a function that is called with the status of your save. function(err,status){}

example

//contacts is an array of objects
function addContactRecord(contacts){
	buildfire.datastore.bulkInsert(contacts, 'contactInfo',function(err,data){
		if(err)
			alert('there was a problem saving your data');
		else
			alert(' saved successfully');
	});
};

 addContactRecord ( [{name:"John Doe", tel:"555-111-1111"},{name:"John Doe", tel:"555-222-2222"}] );

buildfire.datastore.update(id,obj, tag <optional>, callback)

this method calls the datastore to update the data object that matches that tag and object Id. if an object doesn't exist this operation will fail. Use this method to update a single record.

arguments

  • id : is the id number issued to your object that you are attempting to update. Should be retrieved initially from the get call
  • obj: can be one of two options
    1. The JSON object you'd like saved. Can be a complex JSON object as long as its not recursive. Must be under the maximum size limitation of a single object (see Maximum Object Size limit). Obj must contain the original Id of the object.
    2. A command object meant to pass update operators to the datastore to influence certain properties only
  • tag: is an optional string that you use to differentiate content JSON objects from design objects or master vs detail objects... etc
  • callback: is a function that is called with the status of your save. function(err,status){}

example

buildfire.datastore.search( {filter: {"$json.name":"Jane Doe"} }, "contactInfo",function(err,records){  // see search below
    if(err)
        alert('there was a problem retrieving your data');
    else if ( records.length == 0)
		alert('no records found');
	else{
		var rec = records[0];
		rec.data.tel='555-333-3333';
		buildfire.datastore.update(rec.id,rec,'contactInfo',function(err, status){
			if(err)
				alert('there was a problem saving your data');
			else
				alert( rec.name + ' updated tel');
		})
	}
});


buildfire.datastore.searchAndUpdate(search, obj, tag <optional>, callback)

this method calls the datastore to search and update the data object that matches that tag and search query. Use this method to update a multiple records or to update spacific element on each record.

arguments

  • search : is a JSON object that contains the filter.
  • obj: can be one of two options
    1. The JSON object you'd like saved. Can be a complex JSON object as long as its not recursive. Must be under the maximum size limitation of a single object (see Maximum Object Size limit).
    2. A command object meant to pass update operators to the datastore to influence certain properties only
  • tag: is an optional string that you use to differentiate content JSON objects from design objects or master vs detail objects... etc
  • callback: is a function that is called with the status of your save. function(err,status){}

example The below example shows you how to update multiple that matched the tag and search query

function addContactRecord(contacts){
	buildfire.datastore.bulkInsert(contacts, 'contactInfo', function(err,data){
		if(err)
			alert('there was a problem saving your data');
		else
			alert( ' saved successfully');
	});
};

addContactRecord ( [{name:"John Doe", tel:"555-111-1111", active:false},{name:"John Doe", tel:"555-222-2222", active:true}] );


//update all objects that has value active=false to active=true
buildfire.datastore.searchAndUpdate({"active":false},{$set:{"active":true}},'contactInfo',function(err,data){
	console.log(data);
});

example The below example explain how to update and set values in side array of the data object

function addContactRecord(contacts){
	buildfire.datastore.bulkInsert(contacts, 'contactInfo', function(err,data){
		if(err)
			alert('there was a problem saving your data');
		else
			alert( ' saved successfully');
	});
};

addContactRecord ( [{name:"John Doe", tel:"555-111-1111", addresses:[{city:"San Diego"}]},{name:"Mike Rotch", tel:"555-222-2222"}] );


//update all object has name="John Doe" and has city="San Diego" and add state "CA"
buildfire.datastore.searchAndUpdate({"name":"John Doe", "addresses.city": "San Diego"}, { $set: { "addresses.$.state": "CA"}} ,'contactInfo',function(err,data){
	console.log(data);
});


buildfire.datastore.delete(id, tag <optional>, callback)

this method calls the datastore to delete the data object that matches that tag and object Id. if an object doesn't exists this operation will fail.

arguments

  • id : is the id number issued to your object that you are attempting to delete. Should be retrieved initially from the get call

  • tag: is an optional string that you use to differentiate content JSON objects from design objects or master vs detail objects... etc

  • callback: is a function that is called with the status of your save. function(err,status){}

example

buildfire.datastore.search( {filter: {"$json.name":"Jane Doe"}} , 'contactInfo',function(err,records){  // see search below
    if(err)
        alert('there was a problem retrieving your data');
    else if ( records.length == 0)
		alert('no records found');
	else{
		var rec = records[0];
		buildfire.datastore.delete(rec.id,'contactInfo',function(err, status){
			if(err)
				alert('there was a problem deleteing your data');
			else
				alert( ' record deleted');
		})
	}
});

buildfire.datastore.search(options, tag <optional>, callback)

this method calls the datastore to search through objects that matches that tag and options criteria. Use this method to search through many records to pull a matching subset. This method allows complex filtering as well as sorting and pagination

arguments

  • options: is a JSON object that contains the filter ,sort column , pagination parameters and get total records count.
  • tag: is an optional string that you use to differentiate content JSON objects from design objects or master vs detail objects... etc
  • callback: is a function that is called when the status of your save. function(err,records){}

Search Options

  • filter: Optionally takes a JSON object. The format is inspired by MongoDB. While many features overlap they are not a direct match. You must add $json. as a prefix for any property you want to filter. read more about search operators here

  • sort : is a JSON object and its optional and should contain an object with properties you'd like to sort on with 1 for ascending and -1 for descending

  • fields : is a JSON Array and its optional and should contain the fields name that you'd like to return it back , if this option not provided the saved data with all its fields will return.

  • recordCount : is boolean indicator , if true the result will return the total number of records according the same filter and the return object will contain a property totalRecord and an array of the filtered result.

and for pagination you can either use:

  • page : is number that determine the page that need to retrieve.
  • pageSize: is a number of record per page , the max value is 50.

Or use:

  • skip : is number of record that you need to skip, should be set as integer in JSON.
  • limit: is a number of record for this call, the max value is 50, should be set as integer in JSON.

example 1

var searchOptions={
"filter":{"$or":[{"$json.rank": { "$gt": "600", $lt:"900" }},{"$json.name":"Jane Doe"}]},
"sort":{"rank":1 , "lastName":-1 },
"fields":["rank","lastName"],
"page":"0",
"pageSize":"10"
};

buildfire.datastore.search( searchOptions , 'contactInfo',function(err,records){
    if(err)
        alert('there was a problem retrieving your data');
    else {
	    alert('found ' + records.length + ' record(s)');
	    alert(JSON.strigify(records.length) );	
    }
});

example 2

var searchOptions={
"filter":{"$or":[{"$json.rank": { "$gt": "600", $lt:"900" }},{"$json.name":"Jane Doe"}]},
"sort":{"rank":1 , "lastName":-1 },
"fields":["rank","lastName"],
"skip":20,
"limit":10
};

buildfire.datastore.search( searchOptions , 'contactInfo',function(err,records){
    if(err)
        alert('there was a problem retrieving your data');
    else {
	    alert('found ' + records.length + ' record(s)');
	    alert(JSON.strigify(records.length) );	
    }
});

example 3

var searchOptions={
"filter":{"$or":[{"$json.rank": { "$gt": "600", $lt:"900" }},{"$json.name":"Jane Doe"}]},
"sort":{"rank":1 , "lastName":-1 },
"fields":["rank","lastName"],
"skip":20,
"limit":10,
"recordCount":true
};

buildfire.datastore.search( searchOptions , 'contactInfo',function(err,data){
    if(err)
        alert('there was a problem retrieving your data');
    else {
	    alert('total records ' + data.totalRecord + ' record(s)');
           alert('current records ' + data.result.length + ' record(s)');
	    	
    }
});

buildfire.datastore.onUpdate(callback,[allowMultipleHandlers])

this method allows you to pass a callback function that is called whenever the control updates data in the datastore. Use this method in the widget to be notified that the control made a change so you can reflect that change directly in the widget

arguments

  • callback: is a function that is called with the status of your save. function(event){}
  • allowMultipleHandlers: optional bool param that tells the method to override all other handlers. Default false

return

  • returns an object that allows you to clear the listener.
    • clear a function that allows you to stop listening to the event

example

var e = buildfire.datastore.onUpdate(function(event){    
    alert('data has been updated ' + JSON.stringify(event.data) );	
});

// when you want to stop listening
e.clear();

buildfire.datastore.onRefresh(callback,[allowMultipleHandlers])

this method allows you to pass a callback function that is called whenever the app user "pulls down" to refresh the widget. Use this method in the widget to be refresh current data and state of the widget

arguments

  • callback: is a function that is called with the status of your save. function(event){}
  • allowMultipleHandlers: optional bool param that tells the method to override all other handlers. Default false

example

buildfire.datastore.onRefresh(function(){    
    buildfire.datastore.get(function(err,data){
        ...
    });
});

buildfire.datastore.disableRefresh()

this method allows you to disable the feature "pulls down" to refresh on the widget.

arguments none

example

buildfire.datastore.disableRefresh();
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.