Skip to content

Public Data: Save data from the widget

Jump to bottom
Ayman Habeb edited this page Feb 10, 2017 · 16 revisions

Public Data

publicData 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 publicData service also handles caching of data and other performance enhancements.

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

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

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

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

example

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

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

example

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

this method calls the publicData 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.publicData.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.publicData.insert (obj, tag <optional>, checkDuplicate , callback)

this method calls the publicData 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 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.publicData.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.publicData.bulkInsert (obj, tag <optional>, callback)

this method calls the publicData 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.publicData.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.publicData.update(id,obj, tag <optional>, callback)

this method calls the publicData 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 publicData 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.publicData.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.tel='555-333-3333';
		buildfire.publicData.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.publicData.delete(id, tag <optional>, callback)

this method calls the publicData 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.publicData.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.publicData.delete(rec.id,'contactInfo',function(err, status){
			if(err)
				alert('there was a problem deleteing your data');
			else
				alert( ' record deleted');
		})
	}
});

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

this method calls the publicData 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.
  • limit: is a number of record for this call, the max value is 20.

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.publicData.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.publicData.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.publicData.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.publicData.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.publicData.onUpdate(function(event){    
    alert('data has been updated ' + JSON.strigify(event.obj) );	
});

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

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

buildfire.publicData.disableRefresh()

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

arguments none

example

buildfire.publicData.disableRefresh();

portal . twitter . facebook

Clone this wiki locally