App Data
buildfire.appData
#
appData
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.
App Data differs from publicData
, userData
, and datastore
in that it allows plugins within the same app to share data in a clean, consistent, and reliable way.
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 appData
service also handles caching of data and other performance enhancements.
The use of the appData
is completely optional. The developer may choose to communicate with his own custom api.
important
appData
has read/write permissions on widget and control side. appData
is data that is saved from the widget or control and it's accessable to all users on all plugins.
note
If you want to work with Geospatial data check GeoData Wiki
tip
To support high performance search and sort query check Indexed Fields
tip
You can see an example of using User Data in https://github.com/BuildFire/simpleBuildFireJSExamples/tree/master/exampleWidgetUserDataPlugin
#
Methodsget()
#
buildfire.appData.get(tag, callback)
Calls the appData to retrieve plugin data objects in JSON format.
note
If there are many objects with the same id, only one random record will be returned
tag
#
Name | Type | Required | Description | Default |
---|---|---|---|---|
tag | string | no | Key used to differentiate your content saved in appData. ex(settings or questions ) etc. |
callback(err, result)
#
Callback function after something is done
Name | Type | Description |
---|---|---|
err | string | error string, null when operation is successful |
result | object | Result object containing appData tag and data |
#
resultName | Type | Description |
---|---|---|
data | object | Object saved in appData under the selected tag |
tag | string | Object tag |
#
More ExamplesIf your appData has only one object and does not use tags, you can skip the tag argument
getById()
#
buildfire.appData.getById(id, tag, callback)
Calls the appData to retrieve plugin data object by id in JSON format.
id
#
Name | Type | Required | Description | Default |
---|---|---|---|---|
id | string | yes | Datastore object id |
tag
#
Name | Type | Required | Description | Default |
---|---|---|---|---|
tag | string | no | Key used to differentiate your content saved in appData. ex(settings or questions ) etc. |
callback(err, result)
#
Callback function after something is done
Name | Type | Description |
---|---|---|
err | string | error string, null when operation is successful |
result | object | Result object containing appData tag and data |
#
resultName | Type | Description |
---|---|---|
data | object | Object saved in appData under the selected id |
tag | string | Object appData tag |
save()
#
buildfire.appData.save(obj, tag, callback)
This method calls the appData 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
note
Data objects saved using save()
method will not get assigned ids. Data will be saved in the same format as provided.
obj
#
Name | Type | Required | Description | Default |
---|---|---|---|---|
obj | object | yes | Object to be stored in appData |
tag
#
Name | Type | Required | Description | Default |
---|---|---|---|---|
tag | string | no | Key used to differentiate your content saved in appData. ex(settings or questions ) etc. |
callback(err, result)
#
Callback function after something is done
Name | Type | Description |
---|---|---|
err | string | error string, null when operation is successful |
result | object | Result object containing appData tag and data |
#
resultName | Type | Description |
---|---|---|
data | object | Object saved in appData |
tag | string | Object appData tag |
insert()
#
buildfire.appData.insert(obj, tag, checkDuplicate, callback)
Calls the appData to insert a data object. If an object already exists with this tag and checkDuplicate
is false it will create another record otherwise it will return a duplicate entry error. Use this method to save multiple records under the same tag. Every inserted item will get unique id. You can use this id later in getById
obj
#
Name | Type | Required | Description | Default |
---|---|---|---|---|
obj | object | yes | Object to be stored in appData |
tag
#
Name | Type | Required | Description | Default |
---|---|---|---|---|
tag | string | no | Key used to differentiate your content saved in appData. ex(settings or questions ) etc. |
checkDuplicate
#
Name | Type | Required | Description | Default |
---|---|---|---|---|
checkDuplicate | boolean | no | If true it will prevent insertion of duplicate records, if false it will allow duplicates | false |
callback(err, result)
#
Callback function after data is inserted
Name | Type | Description |
---|---|---|
err | string | error string, null when operation is successful |
result | object | Result object containing appData tag, data and id |
result
#
Name | Type | Description |
---|---|---|
data | object | Object inserted in appData |
tag | string | Object appData tag |
id | string | Object unique id |
bulkInsert()
#
buildfire.appData.bulkInsert(obj, tag, callback)
Calls the appData to insert multiple data objects at once. If objects already exist with this tag it will create new records. Use this method to save multiple records with single API call.
note
Data objects inserted using bulkInsert()
method will not get assigned ids.
obj
#
Name | Type | Required | Description | Default |
---|---|---|---|---|
obj | [object] | yes | Array of object to be inserted in appData |
tag
#
Name | Type | Required | Description | Default |
---|---|---|---|---|
tag | string | no | Key used to differentiate your content saved in appData. ex(settings or questions ) etc. |
callback(err, result)
#
Callback function after data is inserted
Name | Type | Description |
---|---|---|
err | string | error string, null when operation is successful |
result | object | Result object containing appData tag, data and id |
result
#
Name | Type | Description |
---|---|---|
data | object | Object array inserted in appData |
tag | string | Object appData tag |
update()
#
buildfire.appData.update(id, obj, tag, callback)
Calls the appData to update the data object that matches that tag and id. If an object doesn't exist this operation will fail. Use this method to update a single record.
id
#
Name | Type | Required | Description | Default |
---|---|---|---|---|
id | string | yes | Datastore object id |
obj
#
Can be one of two options:
- The JSON object you'd like saved.
Name | Type | Required | Description | Default |
---|---|---|---|---|
obj | object | yes | Object to be updated in appData. Object must contain the original id of the object. |
- A command object meant to pass data modifying operators to the appData to update certain properties only
Name | Type | Required | Description | Default |
---|---|---|---|---|
obj | object | yes | Data modifying object. |
tag
#
Name | Type | Required | Description | Default |
---|---|---|---|---|
tag | string | no | Key used to differentiate your content saved in appData. ex(settings or questions ) etc. |
callback(err, result)
#
Callback function after data is inserted
Name | Type | Description |
---|---|---|
err | string | error string, null when operation is successful |
result | object | Result object containing appData tag, data and id |
result
#
Name | Type | Description |
---|---|---|
data | object | Object array inserted in appData |
tag | string | Object appData tag |
id | string | Object unique id |
#
More ExamplessearchAndUpdate()
#
buildfire.appData.searchAndUpdate(search, obj, tag, callback)
Calls the appData 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.
search
#
JSON object that containing the filter (search query). See search operators
Name | Type | Required | Description | Default |
---|---|---|---|---|
search | object | yes | Object containing data filters |
obj
#
Can be one of two options:
- The JSON object you'd like saved.
Name | Type | Required | Description | Default |
---|---|---|---|---|
obj | object | yes | Object to be updated in appData. Object must contain the original id of the object. |
- A command object meant to pass data modifying operators to the appData to update certain properties only
Name | Type | Required | Description | Default |
---|---|---|---|---|
obj | object | yes | Data modifying object. |
tag
#
Name | Type | Required | Description | Default |
---|---|---|---|---|
tag | string | no | Key used to differentiate your content saved in appData. ex(settings or questions ) etc. |
callback(err, status)
#
Callback function after data is inserted
Name | Type | Description |
---|---|---|
err | string | error string, null when operation is successful |
status | object | Status object |
result
#
Name | Type | Description |
---|---|---|
data | object | Object array inserted in appData |
tag | string | Object appData tag |
id | string | Object unique id |
#
More ExamplesHow to update and set values inside array of the data objects
delete()
#
buildfire.appData.delete(id, tag, callback)
Calls the appData to delete the data object that matches that tag and object id. If an object doesn't exists this operation will fail.
id
#
Name | Type | Required | Description | Default |
---|---|---|---|---|
id | string | yes | Object id issued when inserting the data. Can be retrieved initially using get() method. |
tag
#
Name | Type | Required | Description | Default |
---|---|---|---|---|
tag | string | no | Key used to differentiate your content saved in appData. ex(settings or questions ) etc. |
callback(err, result)
#
Callback function after data is inserted
Name | Type | Description |
---|---|---|
err | string | error string, null when operation is successful |
result | object | {"status": "deleted"} |
#
More examplessearch()
#
buildfire.appData.search(options, tag, callback)
Calls the appData 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
options
#
JSON object that contains the filter, sort column, pagination parameters and get total records count.
Name | Type | Required | Description | Default |
---|---|---|---|---|
filter | object | no | 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. See search operators | |
sort | object | no | Object with properties you'd like to sort on with 1 for ascending and -1 for descending | |
fields | [string] | no | Array of fields that you'd like to get. If this option is not provided all fields will be returned | |
recordCount | boolean | no | If true the result will return the object with totalRecord number and a result array | false |
page | number | no | Page you want to retrieve. Should be used in combination with pageSize | 0 |
pageSize | number | no | Number of records per page , the max value is 50. | 50 |
skip | number | no | Number of record that you need to skip. Should be used with limit | 0 |
limit | number | no | Number of records for this call, the max value is 50. | 50 |
note
For pagination you can either use page
and pageSize
or skip
and limit
, but not both at the same time
tag
#
Name | Type | Required | Description | Default |
---|---|---|---|---|
tag | string | no | Key used to differentiate your content saved in appData. ex(settings or questions ) etc. |
callback(err, result)
#
Callback function after data is inserted
Name | Type | Description |
---|---|---|
err | string | error string, null when operation is successful |
result | [object] or object | If recordCount flag is true, the result is object with totalRecord number and result array, otherwise it's array of fetched objects |
#
More examplesaggregate()
#
buildfire.appData.aggregate(params, tag, callback)
Calls the appData to run aggregation pipeline that allow us to analyze documents data in real time and return computed results based on pipeline stages, which we can create an aggregation pipeline that consists of one or more stages. Each stage transforms the documents and passes the output to the next stage.
The aggregation pipeline provide results like the total number
of documents, sum
, average
, maximum
and minimum
values for objects that matches that tag and pipeline stages.
params
#
JSON object that contains the pipelineStages, pagination parameters.
Name | Type | Required | Description | Default |
---|---|---|---|---|
pipelineStages | [object] | yes | Array of objects represent the pipeline stages. The format is inspired by MongoDB Aggregation. Read more about Aggregation Pipeline Stages | |
page | number | no | Page you want to retrieve. Should be used in combination with pageSize | 0 |
pageSize | number | no | Number of records per page , the max value is 50. | 50 |
skip | number | no | Number of record that you need to skip. Should be used with limit | 0 |
limit | number | no | Number of records for this call, the max value is 50. | 50 |
note
For pagination you can either use page
and pageSize
or skip
and limit
, but not both at the same time.
tag
#
Name | Type | Required | Description | Default |
---|---|---|---|---|
tag | string | no | Key used to differentiate your content saved in appData. ex(settings or questions ) etc. |
callback(err, result)
#
Callback function after data is retrieved
Name | Type | Description |
---|---|---|
err | string | error string, null when operation is successful |
result | [object] | Array of objects contain your aggregation results |
#
More examplesThe examples use a collection named articles with the following documents:
#
Equality MatchThe following operation uses $match
stage to perform a simple equality match:
The $match
selects the documents where _buildfire.index.string1 equal "e1efdf3a-a8a5-4c5a-8404-005c4b84b510" and the author field equals "dave", and the aggregation returns the following:
#
Perform a CountThe following example selects documents to process using the $match
pipeline operator and then pipes the results to the $group
pipeline operator to compute a count of the documents:
In the aggregation pipeline, $match
selects the documents where _buildfire.index.string1 equal "e1efdf3a-a8a5-4c5a-8404-005c4b84b510" and either the score is greater than 70 and less than 90 or the views is greater than or equal to 1000. These documents are then piped to the $group
to perform a count.
The aggregation returns the following:
#
Perform Sum and AverageThe following example selects documents to process using the $match
pipeline operator and then pipes the results to the $group
pipeline operator to compute the sum of views and average of score for "moe" author:
In the aggregation pipeline, $match
selects the documents where _buildfire.index.string1 equal "e1efdf3a-a8a5-4c5a-8404-005c4b84b510" and author field equals "moe". These documents are then piped to the $group
to compute the totalViews
and avgScore
.
The aggregation returns the following:
#
Perform Min and Max with GroupingThe following example selects documents to process using the $match
pipeline operator and then pipes the results to the $group
pipeline operator to compute the Min
and Max
of views, and Min
and Max
of score grouped by author:
In the aggregation pipeline, $match
selects the documents where _buildfire.index.string1 equal "e1efdf3a-a8a5-4c5a-8404-005c4b84b510". These documents are then piped to the $group
to compute the minViews
, maxViews
, minScore
and maxScore
grouped by author field .
The aggregation returns the following:
#
Exclude FieldsThe following example selects documents to process using the $match
pipeline operator and then pipes the results to the $project
pipeline operator to includes only the author, and score fields in its output documents:
The aggregation result
#
Full Aggregation ExampleThe aggregation result
#
Full Aggregation ExampleThe following example selects documents to process using the $match
pipeline operator and then pipes the results to the $group
pipeline operator to compute the total of views, and average of score grouped by author then pipes the grouping stage results to $sort
pipeline that sort the result descending based on totalViews
:
The aggregation result
onUpdate()
#
buildfire.appData.onUpdate(callback, allowMultipleHandlers)
Allows you to pass a callback function that is called whenever the control updates data in the appData. 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. Returns a cleanup function to clear the listener.
callback(event)
#
Function you pass that gets called on each appData update
Name | Type | Description |
---|---|---|
event | object | Updated appData records |
allowMultipleHandlers
#
Name | Type | Required | Description | Default |
---|---|---|---|---|
allowMultipleHandlers | boolean | no | Tells the method to override all other handlers, or allow multiple handlers to exist at the same time. | false |