Angular Embedded AnalyticsConfiguring Widgets

Version 3.1.1

The set of widgets available to report authors, and the configuration of each individual widget, can both be customised through the widgets Property.

Available Widgets Copy Link

The example above arranges the widget menu to:

  • Add new groups of widgets
  • Show one of the groups collapsed by default
  • Re-use one of the default widget groups
  • Change the default widget type when dragging fields to the Value widget
<ag-studio
    [widgets]="widgets"
    /* other studio properties ... */ />

this.widgets = createWidgets({
    menu: [
        // new menu configuration
    ],
    defaultType: 'value',
});

The menu arranges the widgets but does not hide any. Any widget type that is not placed in a group is listed in a collapsed "More" section at the end of the menu, so reports that use it remain valid and the widget can still be added.

To remove a widget type entirely, use the function form of the widgets property to filter it out of widgets. Remove the same id from every menu group, otherwise a warning is logged for each missing id, and make sure defaultType refers to a type that remains:

<ag-studio
    [widgets]="widgets"
    /* other studio properties ... */ />

this.widgets = (config) => {
    const removed = ['pie-chart'];
    return {
        widgets: config.widgets.filter(({ id }) => !removed.includes(id)),
        menu: config.menu.map((group) =>
            Object.assign({}, group, {
                widgetIds: group.widgetIds.filter((id) => !removed.includes(id)),
            })
        ),
        defaultType: config.defaultType,
    };
};

A report that uses a removed widget type fails state validation.

See the Widget Configuration API for details on the createWidgets helper function.

Widget Overrides Copy Link

The example above changes the configuration for the Table widget to update the label from 'Table' to 'Grid', and move the widget selection input to the bottom of the setup tab.

<ag-studio
    [widgets]="widgets"
    /* other studio properties ... */ />

this.widgets = createWidgets({
    overrides: [
        {
            id: 'grid',
            label: 'Grid',
            // ... other overrides
        }
    ]
});

Updating the form property for a widget allows the items in the Edit Panel to be customised, including changing their default values. See Form Configuration for more details.

A string icon in an override is parsed as HTML, so supply it only from a trusted source. Use a CSS class name or an SVG URL for icons that come from anywhere else.

Pre-Configured Widgets Copy Link

The example above updates the widget configuration to have two pre-configured widgets. These re-use the existing grouped column chart widgets, but set the fields and title, and hide all of the form options except for the widget selection input.

The pre-configured widgets are set up in a similar way to Creating a Custom Widget, but they copy the existing grouped column chart widget definition.

The extends property is set to 'column-chart-grouped' so that all of the default values are set correctly, and the defaultState property is set with the desired data mapping, sort and title details.

Cell Renderers Copy Link

Table and pivot table widgets can render their cells with your own components, using AG Grid cell renderers.

The example above renders a gold circle next to each value in the 'Gold' column of both widgets, a flag next to each country and a weather icon next to each year on the pivot table widget's Row Labels axis.

A field or Format definition can carry a context property holding any data your application needs. The createCellRenderer option on the table and pivot table widgets receives each field and can return a cell renderer, or undefined to keep the default rendering.

AG Grid renders a string returned from a plain-function cell renderer as HTML. Escape any untrusted values in the string, or return a DOM element instead.

On the pivot table widget the option also covers the fields on the Row Labels axis, with two differences worth knowing:

  • A Row Labels renderer is rendered inside the row's group cell, alongside its expand control and indentation, rather than replacing the cell.
  • A Row Labels renderer receives no field information in its cell renderer params, so a renderer that needs to know which field it is rendering should close over the field passed to the callback.
const fields = [
    // ... other fields
    { id: 'gold', context: { cellRenderer: 'gold' } },
    { id: 'country', context: { cellRenderer: 'countryFlag' } },
    { id: 'year', context: { cellRenderer: 'olympicSeason' } },
]
<ag-studio
    [widgets]="widgets"
    /* other studio properties ... */ />

this.widgets = createWidgets({
    overrides: [
        {
            id: 'grid',
            options: {
                createCellRenderer: (field) =>
                    field.context != null && field.context.cellRenderer === 'gold'
                         ? GoldCellRenderer
                         : undefined,
            },
        },
        {
            id: 'pivot-grid',
            options: {
                createCellRenderer: (field) => {
                    switch (field.context != null ? field.context.cellRenderer : undefined) {
                        case 'countryFlag':
                            return CountryFlagCellRenderer;
                        case 'olympicSeason':
                            return OlympicSeasonCellRenderer;
                        case 'gold':
                            return GoldCellRenderer;
                        default:
                            return undefined;
                    }
                },
            },
        },
    ],
});

Refer to the AG Grid Cell Component Documentation for more details on how to create custom cell renderers.

Linked Fields Copy Link

A cell renderer sometimes needs the value of another field in the same row, without that field being shown as a column. The getLinkedFields option on the table and pivot table widgets lets you link such fields to a displayed field. It receives each displayed field and returns the fields to fetch alongside it, or undefined to link nothing. The linked values are fetched with every row.

The example above links the 'Silver' and 'Bronze' totals to the 'Gold' field. Its cell renderer reads them to show each country's total medal count beside the gold value, in the table and, for each year, in the pivot table, although neither field is displayed.

The links are held in the context of the field definition, so getLinkedFields only needs to return them:

const fields = [
    // ... other fields
    {
        id: 'gold',
        context: {
            cellRenderer: 'medalTotal',
            linkedFields: [
                { id: 'medals.silver', aggregation: 'sum' },
                { id: 'medals.bronze', aggregation: 'sum' },
            ],
        },
    },
]
<ag-studio
    [widgets]="widgets"
    /* other studio properties ... */ />

this.widgets = createWidgets({
    overrides: [
        {
            id: 'grid',
            options: {
                createCellRenderer: (field) =>
                    field.context != null && field.context.cellRenderer === 'medalTotal'
                        ? MedalTotalCellRenderer
                        : undefined,
                getLinkedFields: (field) => field.context != null ? field.context.linkedFields : undefined,
            },
        },
        {
            id: 'pivot-grid',
            options: {
                createCellRenderer: (field) =>
                    field.context != null && field.context.cellRenderer === 'medalTotal'
                        ? MedalTotalCellRenderer
                        : undefined,
                getLinkedFields: (field) => field.context != null ? field.context.linkedFields : undefined,
            },
        },
    ],
});

A cell renderer created by createCellRenderer receives a getLinkedValue function in its params. Pass it a reference from the linked fields to get that row's value, or undefined if the reference was not linked to the cell's field:

const silver = params.getLinkedValue({ id: 'medals.silver', aggregation: 'sum' });

Read linked values only through params.getLinkedValue, never from params.data.

Linked fields behave as follows:

  • Only aggregates are used: a measure, or a field reference with an aggregation. To read a category, use an aggregation such as first, for example { id: 'medals.country', aggregation: 'first' }. Any other reference is ignored.
  • They are never shown as columns, are not exported and cannot be sorted.
  • getLinkedFields is called for each displayed field each time the widget refreshes its data, for example when its fields or options change, so nothing extra is saved in the report state. Rows fetched while scrolling use the links from the latest refresh, so return links based only on the field passed in, such as its context.
  • Linked values count towards the widget's data limits.
  • Linked fields should come from the table's own data source.

On a pivot table:

  • getLinkedFields is called for each value field, not for Row Labels or Column Labels fields.
  • Each value cell reads the linked value for its own row and column, including subtotal and total columns and the total row. Row Labels cells never receive linked values.
  • Each linked field is fetched for every column shown, so linked fields count towards the widget's column limit (by default dataOptions.maxColumns) and a wide pivot table reaches it sooner. The limit is not raised for them.

On a table that shows aggregates, a row whose shown aggregates are all empty can appear when a linked value is not empty. On a pivot table, the same applies to a row or a column whose shown values are all empty.

Toolbar Actions Copy Link

Each widget has a toolbar containing buttons that trigger various actions.

To customise the toolbar, follow the steps for Widget Overrides and set the toolbar property.

The following actions are available by default:

ActionIDWidgets
Duplicate widget'duplicate'All
Delete widget'delete'All
CSV export'export'Grid and chart widgets
Download as image'download'Chart widgets

Actions can also be executed via the API method performWidgetAction.

performWidgetActionCopy Link
Function
Execute an action for a widget. Action can be one of the default actions ('duplicate' or 'delete'), or an action specific to that widget.

The example above demonstrates exporting data for the first widget via the API when the button is clicked.

CSV Export Copy Link

When performing CSV export, values are formatted the same way as in the widget.

By default, exports are limited to 1,000 rows by applying a limit on the related query. Set maxExportRows on dataOptions to change this.

<ag-studio
    [dataOptions]="dataOptions"
    /* other studio properties ... */ />

this.dataOptions = {
    maxExportRows: 5000,
};

maxExportRows supports -1 for unlimited exports. Depending on the size of your data, you may get unexpected or undesired results, including but not limited to: memory, bandwidth or resource exhaustion.