Datasource

A datasource plugin is made up of two parts -

  1. A definition that is registered with the portal
  2. A function that is responsible for interacting with third-party APIs, responding to various lifecycle methods, and notifying the portal when new data is available.

In this document, we will cover the following:

  1. Example Definition
  2. Datasource function
  3. Example Datasource function

Example Definition

CB_PORTAL.registerDatasource({ // this function must be called in order to register the datasource as a plugin
    type_name: "CB_PLUGIN_DATASOURCE",
    display_name: "Datasource Plugin",
    group: "ClearBlade Plugins",
    description: "A datasource as a plugin.",
    class: PluginDatasourceTest,
    settings: [
        {
            name: "query",
            display_name: "Search Query",
            type: "text",
            required: true
        },
        {
            name: "apiKey",
            display_name: "Google Search API Key",
            type: "text",
            required: true
        },
        {
            name: "searchEngineId",
            display_name: "Search Engine ID",
            type: "text",
            required: true
        },
        {
            name: "dessert",
            display_name: "Favorite Dessert?",
            type: "text",
            required: true
        },
        {
            name: "booleanVal",
            display_name: "Boolean Value",
            type: "boolean",
            default_value: true,
        },
        {
            name: "numberVal",
            display_name: "Number Value",
            type: "number",
            default_value: 42
        },
        {
            name: "colorVal",
            display_name: "Color Value",
            type: "color",
            default_value: "#fff",
        },
        {
            name: "optionVal",
            display_name: "Option Value",
            type: "option",
            default_value: "option2",
            options: [
                {
                    name: "Option 1",
                    value: "option1"
                },
                {
                    name: "Option 2",
                    value: "option2"
                }
            ]
        },
    ]
}
)

Datasource function

The datasource function takes a few parameters -

name type description
settings object The value for settings upon instantiation
updateCallback function Used to notify the portal that data has changed, will cause widgets that are hooked up to the datasource to re-render
errorCallback function Used to display an error message inside the portal. Takes two parameters - title and message

The datasource function can implement the following methods -

name required description
onSettingsChanged false Called when the datasources settings are changed, can be used to store new values
sendData true Used to interact with a third-party API
updateNow false Used to refresh the datasource with the current settings. Called when the refresh button is pressed inside the portal.
onDispose false Used to clean up any functions or objects that could cause memory leaks (interval timers, IndexedDB connections, etc.)

Example Datasource function

function PluginDatasourceTest(settings, updateCallback, errorCallback) {

    let payload = {
        query: settings.query,
        apiKey: settings.apiKey,
        searchEngineId: settings.searchEngineId,
    };

    this.onSettingsChanged = function (settings) {
        payload = {
            query: settings.query,
            apiKey: settings.apiKey,
            searchEngineId: settings.searchEngineId,
        }
        this.updateNow();
    }

    this.updateNow = function () {
        this.sendData(payload);
    }

    function handleErrors(response) {
        if (!response.ok) {
            throw Error(response.statusText);
        }
        return response;
    }

    this.sendData = function (data) {
        fetch(`https://www.googleapis.com/customsearch/v1?q=${data.query}&key=${data.apiKey}&cx=${data.searchEngineId}`, {
            method: 'GET'
        }).then(handleErrors)
            .then((resp) => resp.json().then((jsonResp) => {
            updateCallback(jsonResp);
    }))
    .catch((e) => {
            errorCallback("Failed to search", e);
    })
    }

    this.onDispose = function () {

    }

    this.updateNow();
}