Data Source

Sometimes it might be necessary to dynamically populate a component with a data source, e.g. when showing connected devices in a <sdpi-select> input. Thankfully the datasource attribute makes this incredibly easy.

supported components

Data sourcing is supported in the following components

• <sdpi-checkbox-list>
• <sdpi-radio>
• <sdpi-select>

Property Inspector

During the initialization of the component, when a datasource is specified, a request for the data source's items is sent to the plugin using sendToPlugin.

Property Inspector HTML

<sdpi-select
    setting="color"
    datasource="getColors"
    loading="Fetching colors..."
    hot-reload>
</sdpi-select>

tip

The optional loading attribute indicates the text to display whilst the data source is loading.

tip

The data source can be refreshed manually by calling .refresh() on the element. When the data source is being refreshed, the payload sent to the plugin will include the event, and isRefresh: true.

The message structure of the sendToPlugin event when requesting the data source's items looks as follow:

{
    action,
    event,
    context,
    payload: {
        event: "getColors",
        isRefresh: undefined | true
    }
}

Configuration

All components that support data sources have the following configuration options.

Name	Type	Description
datasource	string	The optional remote data source.
hot-reload	boolean	When present, sendToPropertyInspector is actively monitored allowing for the plugin to update the items.
loading	string	When a datasource is specified, this text is shown whilst the items are loaded.

Plugin

important

This is the important stuff; your plugin must return the data source using the sendToPropertyInspector using a specific payload structure.

Following the request for a data source, the plugin is responsible for "responding" using the sendToPropertyInspector using a standardized payload structure.

{
    action,
    event,
    context,
    payload: {
        event: "getColors",
        items: [{
            label: 'Primary Colors',
            children: [{
                label: 'Red',
                value: '#ff0000'
            }, {
                label: 'Green',
                value: '#00ff00'
            }, {
                label: 'Blue',
                value: '#0000ff'
            }]
        }, {
            label: 'Black',
            value: '#000000'
        }, {
            label: 'White',
            value: '#ffffff'
        }]
    }
}

With this example, the <sdpi-select> within the property inspector would then look like this after loading.

Payload Structure

The nested payload sent to the property inspector, from the plugin, via sendToPropertyInspector must include:

• event - The event that requested the data source.
• items - The items of the data source.

Payload returned to the property inspector

declare type DataSourcePayload = {
    event: string;
    items: DataSourceResult;
};

Data source types

declare type DataSourceResult = DataSourceResultItem[];
declare type DataSourceResultItem = Item | ItemGroup;

declare type Item = {
    disabled?: boolean;
    label?: string;
    value: string;
};

declare type ItemGroup = {
    label?: string;
    children: Item[];
};