JavaScript Embedded AnalyticsCustom Widgets

Custom widgets allow you to add your own widgets to AG Studio. Use them when the provided widgets do not meet your requirements.

The example above demonstrates a custom widget showing a single data value.

Implementing a Custom Widget Copy Link

To provide a custom widget, implement the AgTypeScriptWidgetDefinition interface.

Custom widgets are provided to the widgets property, similar to Customising the Available Widgets.

Provide the custom widget definitions to the createWidgets(params) helper function, and add them to the menu.

const studioProperties = {
    widgets: (widgetConfig) => createWidgets<CustomRegistry>({
        additionalTypes: [customWidgetDefinition],
        menu: [
            ...widgetConfig.menu,
            {
                label: 'Custom',
                widgetIds: ['customWidget'],
            },
        ]
    }),

    // other studio properties ...
}

For the types to work correctly, the custom widgets should be defined in the Registry Type.

interface CustomRegistry extends AgBaseRegistry {
    widgets: readonly (AgDefaultWidgetDefinition | CustomWidgetDefinition)[]
}

Data Mapping Copy Link

The dataMapping property defines the fields or fieldsets that are required to configure the widget, and the required relationships between them.

For example, to configure a line chart, the data mapping might look like this:

const dataMapping = {
    xAxisKey: {
        type: 'field', // Only a single field allowed
        // All types of value allowed
        supportedRoles: ['category', 'numeric', 'temporal'],
        requires: { cardinality: 'many' }, // Many values are accepted
        required: true, // Required field - widget cannot be displayed without it
        sort: true, // Show the sort menu
        aiDescription: 'Field for the x axis.', // Description when used with AI
    },
    yAxisKey: {
        type: 'fieldset', // Multiple fields allowed
        supportedRoles: ['numeric'], // Only numeric values allowed
        // For each `xAxisKey`, this must map to a single value
        requires: { per: 'dataMapping.xAxisKey', cardinality: 'one' },
        required: true, // Required field - widget cannot be displayed without it
        sort: true, // Show the sort menu
        // Description when used with AI
        aiDescription: 'Field(s) for the y axis. Each field becomes a separate series.',
    },
};

Custom Widget Component Copy Link

The custom component is a class that implements the AgTypeScriptComponent interface.

The init and refresh methods receive params of type AgWidgetParams.

Custom Widget Params Copy Link

Display State Copy Link

Widgets have four different display states that can be set via widgetApi.setDisplayState(state, metadata?). These will trigger different overlays to be displayed by the layout on top of the widget. The states are:

• displayed - The widget has data and is ready to display. Studio will show no overlay; the widget is rendered normally.
• loading - The widget is loading. Metadata defaults to { prominent: true } for a solid loading overlay; use { prominent: false } for an unobtrusive refresh indicator that keeps the previous content visible.
• noData - The widget has no data (e.g. everything is filtered out or the data is empty). Studio will show an overlay with "No data to display".
• incompleteDataMapping - The widget does not have all of the required fields set. Studio will show an overlay with the field selection inputs.

Each time the widget updates, set the relevant status as needed.

widgetApi.setDisplayState('loading');
const response = await widgetApi.getData(request);
// ... process the response
widgetApi.setDisplayState('displayed');

Loading Data Copy Link

Data is loaded via widgetApi.getData(request). The request can be constructed from the data mapping values in the params.

Form Copy Link

The widget form configures the form displayed in the edit panel. The values from the form are passed in the widget params.

See the Form Setup page for more details.

Cross-Filtering Copy Link

To implement cross-filtering from within a custom widget, the cross filter methods can be used from the widget API.

To support the cross filter highlight behaviour (similar to some of the default charts, e.g. column charts), enable it in the widget definition.

 const widgetDefinition = {
    // ...
    featureConfig: {
        crossFilter: {
            supportsHighlight: true
        }
    }
 };

When this is enabled, the data response will contain two datasets. The original data (response.results), and the cross-filtered data (response.crossFilter).

AI Integration Copy Link

For a custom widget to work with AI, the formatShape and ai properties must be defined in the widget definition.

The shape returned by formatShape is used to provide the AI with the schema for the format property of the widget, and to validate the format value the AI sets via state.

Using AG Grid and AG Charts in Custom Widgets Copy Link

As well as the built-in AG Grid and AG Charts widgets, it is possible to create your own custom widgets using AG Grid and AG Charts.

To match the AG Grid theming in Studio, use studioGridTheme and pass it to the theme grid option. For AG Charts, pass the result of getChartTheme(api) to the theme chart option, where api is the Studio API in the widget params.