How to use the Datastore Dynamic Data

⚠️⚠️⚠️

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

⚠️⚠️⚠️

Datastore Dynamic Data

Datastore Dynamic Data is a feature that allows plugin developers to combine multiple requests to certain supported data types in one request.

Dynamic Data can be used by adding a special _buildfire object inside your main datastore data object. This special object, describes the data needed to be fetched; such object can be placed anywhere within a datastore data object.

---

Why use Dynamic Data?

While this doesnt apply everywhere, there are some instances where you cannot store data locally within your data object because it keeps changing.

Example

If you were developing a folder plugin that the app owner could add other plugin instances in. You cant simply save the selected plugin instances titles , images ,...etc because these are referencing data that may be changes outside of your plugin. If you do save it locally it would simply be a snapshot in time. With Dynamic Data injection you can just keep reference to the plugins and at run time the datastore will inject the latest data properties into your object.

Data Structure

The _buildfire object should have the following structure:

_buildfire: {
		[propertyName]: { // this could be any valid property name to identify or access the dynamic data and you can add more than one.
			dataType: <SUPPORTED-DATA-TYPE>, // the type of the dynamic data to retrieve.
			data: <PARAMETER-DATA>, // static data that identifies the dynamic data to be retrieved. format and structure depends on the specified dataType.
			result: <INJECTED-RESULT>, // result will have the requested dynamic data. this is a readonly field and should not be set by the developer.
			err: <ERROR-RESULT> // returned if an error occurs while retrieving data
		}
}

example:

var myMainObject = {
	staticProperty1: "static data",
	staticProperty2: "static data",
	_buildfire: {
		myDynamicPluginCollection: {
			data: "55f71347d06b61b4010351dc"
			dataType: "pluginInstance"
		}			
	},

}

Accessing Data

---

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

After the object has been saved to the datastore (save / insert / update) using the structure explained above getWithDynamicData can be used to get the data back along with the dynamic data result injected.

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){}

example:

buildfire.datastore.getWithDynamicData("tag", function(err, result) {
	// result would be:
	/*
	{
		_buildfire: {
			staticProperty1: "static data",
			staticProperty2: "static data",
			myDynamicPluginCollection: {
				data: "55f71347d06b61b4010351dc"
				dataType: "pluginInstance",
				result: [
					{
						"id": "55f71347d06b61b4010351dc",
						"data": {
							"pluginTypeId": 3212,
							"token": "6372b101-addf-45da-bb0a-9208a09e7b6b",
							"title": "YouTube Plugin",
							"iconUrl": "http://s3-us-west-2.amazonaws.com/pluginserver/plugins/6372b101-addf-45da-bb0a-9208a09e7b6b/resources/image.png",
						},
						"hasAccess": true //if the current loggedIn user has access to the plugin
					}
				]
			}
		}
	}
	*/
});

The regular datastore get would return the data as is and will not have dynamic data injected. It is recommended to use the regular datastore get method when there is no use of the dynamic data result in the current invocation as it would be perform faster.

example:

buildfire.datastore.get("tag",function(err,data){
	// result would be:
	/*
	{
		staticProperty1: "static data",
		staticProperty2: "static data",
		_buildfire: {
			myDynamicPluginCollection: {
				data: ["123", "456"]
				dataType: "pluginInstance",
			}
		}
	}
	*/
});

Note: when saving the object both result and err objects inside _buildfire it will be removed since they are dynamic.

Supported Data Types

pluginInstance:

Retrieves plugin instances. data holds a plugin instance id or an array of ids to be retrieved in result as an array.

`data`: "<PLUGIN-INSTANCE-ID>" || ["<PLUGIN-INSTANCE-ID-1>", "<PLUGIN-INSTANCE-ID-2>"]
`dataType`: "pluginInstance",

Example Data

{
    id: "56038ca5c3bd16240b4bd5c3",
    lastUpdated: "2015-10-01T22:47:49.877Z",
    data: {
        pluginTypeId: 257,
        token: "8a50db06-fcf6-6a84b66d0f47",
        title: "Contact Us D",
        iconUrl: "https://imagelibserver.buildfire.com/9060.jpg",
        pluginType: {
            pluginTypeId: 257,
            name: "Contact Us",
            token: "8a50db06-fcf6-41a7-6a84b66d0f47",
            description: "Helps to allow users to add the contact information for their business into the app.",
            author: "BuildFire",
            supportEmail: "support@buildfire.com",
            folderName: "1e171363-6faf-4236-ab95-0bbf197d70"
        }
    }
}

pluginType:

Retrieves plugin types. data holds a plugin type id or an array of ids to be retrieved in result as an array.

`data`: "<PLUGIN-TYPE-ID>" || ["<PLUGIN-TYPE-ID-1>", "<PLUGIN-TYPE-ID-2>"]
`dataType`: "pluginType",