Dashboard extension API reference

Build custom visualizations that run inside Dashboard Studio as iframe extensions using the core dashboard extension API.

This package provides the core API for building custom visualizations that run inside Splunk Dashboard Studio as iframe extensions. It exposes methods for listening to and retrieving dashboard state such as data sources, options, dimensions, mode, theme, and tokens.

Usage

The API library will be imported into the custom visualization JavaScript source code:
PYTHON 
import { VisualizationAPI } from '@splunk/dashboard-extension';
Generally, the functions act as a communication bridge between the custom visualization iframe window and the parent window. Listener functions subscribe the iframe window to the parent window. When an event triggers the listener function, it invokes the provided callback function.
JAVASCRIPT 
// Subscribe to data source updates 

VisualizationAPI.addDataSourcesListener( 
    ({ dataSources, loading }) => { 
        if (loading || !dataSources?.primary?.data) return; 
        const { fields, columns } = dataSources.primary.data; 
        render(fields, columns); 
    }, 
    { invokeImmediately: true } 
);

The following provides a list of the functions that the API supports.

addDataSourcesListener

Subscribe to and retrieve data source state.

Request parameters
Parameter Description

callback: (args: DataSourcesState) => void

Callback to invoke when data source object updates are received from the dashboard.

options: ListenerOptions

General configuration options for the established event listener. Provides controls such as an abort signal for early subscription cancellation and an option to invoke the callback immediately on first subscribe.

addDimensionsListener

Subscribe to and retrieve visualization dimensions.

Request parameters
Parameter Description

callback: (args: DimensionsState) => void

Callback to invoke when the visualization is resized (dimension changes).

options: ListenerOptions

General configuration options for the established event listener. Provides controls such as an abort signal for early subscription cancellation and an option to invoke the callback immediately on first subscribe.

addDrilldownListener

Subscribe a DOM node to Dashboard Studio event handlers for drilldowns.

Request parameters
Parameter Description

node: HTMLElement

HTML node to attach listener callback to. Listens to 'click' events

action: string

Identifier for the action type causing the drilldown interaction (e.g. 'custom.click')

payloadCallback: () => DrilldownPayloadState

Callback used to retrieve the drilldown payload when a click event occurs for the provided node

addErrorListener

Listen for changes to the iframe error state. The custom visualization controls and updates the iframe error state.

Request parameters
Parameter Description

callback: (args: ErrorState) => void

Callback to invoke when the error state is modified for the visualization.

options: ListenerOptions

General configuration options for the established event listener. Provides controls such as an abort signal for early subscription cancellation and an option to invoke the callback immediately on first subscribe.

addModeListener

Subscribe to and retrieve dashboard mode (view or edit).

Request parameters
Parameter Description

callback: (args: ModeState) => void

Callback to invoke when the mode state for the dashboard is changed.

options: ListenerOptions

General configuration options for the established event listener. Provides controls such as an abort signal for early subscription cancellation and an option to invoke the callback immediately on first subscribe.

addOptionsListener

Subscribe to and retrieve visualization options.

Request parameters
Parameter Description

callback: (args: VisualizationOptionsState) => void

Callback to invoke when visualization options updates are received from the dashboard.

options: ListenerOptions

General configuration options for the established event listener. Provides controls such as an abort signal for early subscription cancellation and an option to invoke the callback immediately on first subscribe.

addThemeListener

Subscribe to and retrieve theme information.

Request parameters
Parameter Description

callback: (args: ThemeState) => void

Callback to invoke when theme updates are received from the dashboard.

options: ListenerOptions

General configuration options for the established event listener. Provides controls such as an abort signal for early subscription cancellation and an option to invoke the callback immediately on first subscribe.

addTokensListener

Subscribe to and retrieve dashboard tokens.

Request parameters
Parameter Description

callback: (args: TokensState) => void

Callback to invoke when the set of submitted tokens are modified in the dashboard.

options: ListenerOptions

General configuration options for the established event listener. Provides controls such as an abort signal for early subscription cancellation and an option to invoke the callback immediately on first subscribe

clearError

Reset the iframe error state. Removes any present error overlay on the visualization.

Returned values

void

getDimensions

Retrieve the current width and height dimensions of the visualization in pixels.

Returned values

Name Description
DimensionsState Object containing 'width' and 'height' pixel data for the visualization

getError

Retrieve the error state from the Iframe.

Returned values

Name Description
ErrorState Object containing the current 'error' message associated with the visualization

getDataSources

Retrieve the current datasources object attached to the visualization.

Returned values

Name Description
DataSourcesState Object containing the current 'dataSources' object and associated 'loading' state assigned to the visualization

getMode

Retrieve the current mode state of the dashboard (edit or view).

Returned values

Name Description
ModeState Object containing the current 'mode' state of the dashboard. Either 'view' or 'edit'

getOptions

Retrieve the current visualization options state.

Returned values

Name Description
VisualizationOptionsState Object containing a VisualizationOptions generic object holding the options configured by the user for the visualization via Dynamic Editors or Source Editor

getTheme

Retrieve the current theme state of the dashboard (light or dark).

Returned values

Name Description
ThemeState Object containing the current 'theme' state for the dashboard. light or dark

getTokens

Retrieve the submitted tokens state from the dashboard.

Returned values

Name Description
TokensState Object containing the 'tokens' object currently submitted for the dashboard.

setError

Modify the iframe error state. Setting to a non-empty string triggers an error overlay to present to the user on the visualization.

Parameter Description
error: string Error message to display to the user within the visualization

Returned values

void

setOptions

Update the current visualization options state. Used in rare cases as it is best practice for user configuration to entirely control visualization options during editing.

Parameter Description
options: VisualizationOptions Object of defined visualization option properties and associated values to be set for these options.

Returned values

void

triggerDrilldown

Trigger a Dashboard Studio event handler for drilldown.

Parameter Description
drilldownArgs: DrilldownArgs

Object containing the trigger 'action', the drilldown payload to be used by the dashboard framework drilldown handlers to perform the user configured drilldown interaction.

Optional 'originalEvent' property supported for trigger events other than standard 'click'.

Returned values

void

Dashboard extension React reference

This package provides a React context provider and hooks for building custom visualizations that run inside Splunk Dashboard Studio as iframe extensions. It is built on top of @splunk/dashboard-extension and provides an API for React-based development.

The API library will be imported into the custom visualization JavaScript source code:

PYTHON 
import { VisualizationExtensionProvider, useDataSources, useOptions, ... } from '@splunk/dashboard-extension/react';
JAVASCRIPT 
function App() {
    return (
        <VisualizationExtensionProvider>
            <MyVisualization />
        </VisualizationExtensionProvider>
    );
}

React-based development uses components called context providers and functions called hooks. In this case, the context provider is VisualizationExtensionProvider, which aggregates all visualization states. Child components use the hooks to access the visualization states.

The following provides details for the hooks that the API supports.

Hook Description
useDataSources Subscribe to stateful updates for data source update events. Core hook used to render the Splunk data associated with the visualization. Returns { dataSources, loading }.
useDimensions Subscribe to stateful updates for visualization resize events. Provides the 'width' and 'height' pixel dimensions for the visualization container to support responsive visualizations. Returns { width, height }.
useError Subscribe to stateful updates for the visualization iframe error state.
useMode Subscribe to stateful updates for the dashboard mode ('view' or 'edit'). Returns { mode }.
useOptions Subscribe to stateful updates for the visualization options configurations. Captures options edited by users via dynamic editors or source editor. Returns { options, setOptions }.
useTheme Subscribe to stateful updates for the dashboard theme state ('light' or 'dark'). Returns { theme }.
useTokens Subscribe to stateful updates for the currently submitted tokens state of the dashboard. Returns a `tokens` object containing the key-value pairs for each token set in the current dashboard context. Returns { tokens }.