Skip to content

User Data: Save user data from the widget

Jump to bottom
o5faruk edited this page May 2, 2021 · 15 revisions

⚠️⚠️⚠️

This sdk documentation is deprecated and will not be updated. Check out our new docs at https://sdk.buildfire.com/docs/user-data/

⚠️⚠️⚠️

User Data

userData is a framework provided in buildfire.js that allows the app user and app owner 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 userData service also handles caching of data and other performance enhancements.

The use of the userData is completely optional. The developer may choose to communicate with his own custom api.

If you want to work with Geospatial data check GeoData Wiki

To support high performance search and sort query check Data Indexed Fields Wiki

You can see an example of using User Data in https://github.com/BuildFire/simpleBuildFireJSExamples/tree/master/exampleWidgetUserDataPlugin

How to use userData

Every plugin page must import the buildfire.js framework. This exposes the buildfire object. Within the buildfire object there is a property called userData accesses via buildfire.userData

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

this method calls the userData 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 userData. function(err,data){}

example

buildfire.userData.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.userData.getById ( id , tag <optional>, callback)

this method calls the userData 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 userData. function(err,data){}

example

buildfire.userData.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.userData.save (obj, tag <optional>,userToken <optional>, callback)

this method calls the userData 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
  • userToken: a secure key that return with the logged in user , and it used to identify the user who making the update
  • callback: is a function that is called with the status of your save. function(err,status){}

example

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

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

this method calls the userData 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
  • userToken: a secure key that return with the logged in user , and it used to identify the user who making the update
  • checkDuplicate: is a Boolean flag ,if true it will prevent insert 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.userData.insert(contact, 'contactInfo',"1555644732378-06843910305760801",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.userData.bulkInsert (obj, tag <optional>,userToken <optional>, callback)

this method calls the userData 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
  • userToken: a secure key that return with the logged in user , and it used to identify the user who making the update
  • 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.userData.bulkInsert(contacts, 'contactInfo',"1555644732378-06843910305760801",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.userData.update(id,obj, tag <optional>,userToken <optional>, callback)

this method calls the userData to update the data object that matches that tag and object Id. if an object doesn't exists 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 userData 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
  • userToken: a secure key that return with the logged in user , and it used to identify the user who making the update
  • callback: is a function that is called with the status of your save. function(err,status){}

example

buildfire.userData.search( {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.userData.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.userData.searchAndUpdate(search, obj, tag <optional>, userToken <optional>, callback)

this method calls the userData 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 userData 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 exmaple show you how to update multiple that macthed the tag and search query

function addContactRecord(contacts){
	buildfire.userData.bulkInsert(contacts, 'contactInfo',"1555644732378-06843910305760801", 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.userData.searchAndUpdate({"active":false},{$set:{"active":true}},'contactInfo',"1555644732378-06843910305760801",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.userData.bulkInsert(contacts, 'contactInfo',"1555644732378-06843910305760801", 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.userData.searchAndUpdate({"name":"John Doe", "addresses.city": "San Diego"}, { $set: { "addresses.$.state": "CA"}} ,'contactInfo',"1555644732378-06843910305760801",function(err,data){
	console.log(data);
});

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

this method calls the userData 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

  • userToken: a secure key that return with the logged in user , and it used to identify the user who making the update

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

example

buildfire.userData.search( {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.userData.delete(rec.id,'contactInfo','1555644732378-06843910305760801',function(err, status){
			if(err)
				alert('there was a problem deleteing your data');
			else
				alert( ' record deleted');
		})
	}
});

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

this method calls the userData 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 contains 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 20.

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 20, should be set as integer in JSON.

Important: You can use User data indexed fields to enhance search query performance.

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.userData.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.userData.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"],
"page":"0",
"pageSize":"10",
"recordCount":true
};

buildfire.userData.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.userData.onUpdate(callback,[allowMultipleHandlers])

this method allows you to pass a callback function that is called whenever the control updates data in the userData. 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.userData.onUpdate(function(event){    
    alert('data has been updated ' + JSON.strigify(event.obj) );	
});

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

buildfire.userData.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.userData.onRefresh(function(){    
    buildfire.userData.get(function(err,data){
        ...
    });
});

buildfire.userData.disableRefresh()

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

arguments none

example

buildfire.userData.disableRefresh();

portal . twitter . facebook

Clone this wiki locally