React Embedded AnalyticsContext Menu

Version 3.1.0

When the user right-clicks anywhere in the dashboard canvas, Studio calls the getContextMenuItems callback. If the callback returns menu items, Studio opens a context menu showing them. If it returns none, no menu opens. Studio has no menu items of its own: you supply every item through the callback.

Right-click a country in the grid or a column in the chart below, then open the Copy sub menu. The Show item logs a message to the browser console, and the Copy items copy to the clipboard. The example returns no items for a right-click on the empty canvas, so no menu opens there.

index.tsx

("use client");

import React, {
  useCallback,
  useMemo,
  useRef,
  useState,
  StrictMode,
} from "react";
import { createRoot } from "react-dom/client";
import { AgStudio, AgStudioRef } from "ag-studio-react";
import {
  AgContextMenuItem,
  AgDataEngine,
  AgDataSourcesDefinition,
  AgFilterDefinition,
  AgGetContextMenuParams,
  AgLogicalDefinition,
  AgReportHistory,
  AgReportState,
  AgStudioApi,
  AgStudioApiReadyEvent,
  AgStudioMode,
  AgStudioProperties,
  enableStudioDevValidations,
} from "ag-studio";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableStudioDevValidations();
}

const isLogicalDefinition: (
  filter: AgFilterDefinition,
) => filter is AgLogicalDefinition = (filter: AgFilterDefinition) => {
  return (filter as AgLogicalDefinition).conditions != null;
};

const getFilterValues: (filter: AgFilterDefinition) => string[] = (
  filter: AgFilterDefinition,
) => {
  if (isLogicalDefinition(filter)) {
    return filter.conditions.flatMap(getFilterValues);
  }
  // A grid total row has no value for the grouping fields, so skip empty values.
  return filter.value == null ? [] : [String(filter.value)];
};

const StudioExample = () => {
  const containerStyle = useMemo(() => ({ width: "100%", height: "100%" }), []);
  const studioStyle = useMemo(() => ({ height: "100%", width: "100%" }), []);
  const [data, setData] = useState<AgDataSourcesDefinition | AgDataEngine>();
  const initialState = useMemo<AgReportState | AgReportHistory>(() => {
    return {
      pages: [
        {
          id: "summary",
          widgets: {
            "medals-by-country": {
              type: "grid",
              dataMapping: {
                cols: [
                  {
                    id: "medals.country",
                  },
                  {
                    id: "medals.gold",
                    aggregation: "sum",
                  },
                  {
                    id: "medals.silver",
                    aggregation: "sum",
                  },
                  {
                    id: "medals.bronze",
                    aggregation: "sum",
                  },
                  {
                    id: "medals.total",
                    aggregation: "sum",
                  },
                ],
              },
              format: {
                title: {
                  enabled: true,
                  text: "Medals by Country",
                },
              },
              sort: [
                {
                  field: {
                    id: "medals.total",
                    aggregation: "sum",
                  },
                  direction: "desc",
                },
              ],
            },
            "medals-by-sport": {
              type: "column-chart-grouped",
              dataMapping: {
                categoryKey: [
                  {
                    id: "medals.sport",
                  },
                ],
                valueKey: [
                  {
                    id: "medals.total",
                    aggregation: "sum",
                  },
                ],
              },
              format: {
                title: {
                  enabled: true,
                  text: "Medals by Sport",
                },
              },
              sort: [
                {
                  field: {
                    id: "medals.total",
                    aggregation: "sum",
                  },
                  direction: "desc",
                },
              ],
            },
          },
          filter: {
            page: [],
            widget: {
              "medals-by-sport": [
                {
                  field: {
                    id: "medals.total",
                  },
                  view: {
                    expanded: true,
                    viewTypeId: "rank",
                  },
                  model: {
                    operator: "rank",
                    value: [10, null],
                  },
                },
              ],
            },
          },
          widgetLayout: {
            "medals-by-country": {
              xTrack: 0,
              yTrack: 0,
              xSpan: 24,
              ySpan: 16,
            },
            "medals-by-sport": {
              xTrack: 0,
              yTrack: 16,
              xSpan: 24,
              ySpan: 16,
            },
          },
        },
      ],
      selectedPageId: "summary",
      panels: {
        filters: {
          collapsed: true,
        },
        edit: {
          collapsed: true,
        },
        data: {
          collapsed: true,
        },
      },
    };
  }, []);

  const onApiReady = useCallback((params: AgStudioApiReadyEvent) => {
    fetch("https://www.ag-grid.com/studio/example-assets/olympic-winners.json")
      .then((resp) => resp.json())
      .then((data: any[]) => setData({ sources: [{ id: "medals", data }] }));
  }, []);

  const getContextMenuItems = useCallback(
    (params: AgGetContextMenuParams): AgContextMenuItem[] => {
      const { filter, widgetId, widgetType } = params;
      // Offer no items on the empty canvas, so no menu opens there.
      if (widgetId == null) {
        return [];
      }
      const values = filter ? getFilterValues(filter) : [];
      const value = values.length > 0 ? values.join(" / ") : "Widget";
      return [
        {
          name: `Show ${value}`,
          action: () => console.log(`Show: ${value}`),
        },
        "separator",
        {
          name: "Copy",
          subMenu: [
            {
              name: "Copy Value",
              shortcut: "Ctrl+C",
              action: () => navigator.clipboard.writeText(value),
            },
            {
              name: "Copy Widget Type",
              action: () => navigator.clipboard.writeText(widgetType ?? ""),
            },
          ],
        },
      ];
    },
    [],
  );

  return (
    <div style={containerStyle}>
      <div style={{ display: "flex", flexDirection: "column", height: "100%" }}>
        <AgStudio
          style={studioStyle}
          className="my-studio-container"
          data={data}
          initialState={initialState}
          mode={"edit"}
          getContextMenuItems={getContextMenuItems}
          onApiReady={onApiReady}
        />
      </div>
    </div>
  );
};

const root = createRoot(document.getElementById("root")!);
root.render(
  <StrictMode>
    <StudioExample />
  </StrictMode>,
);

Studio calls getContextMenuItems once for each right-click in the dashboard canvas, and opens a menu showing the items it returns. Return 'separator' in the list to draw a divider between items:

const getContextMenuItems = (params) => [
    { name: 'Show Details', action: () => showDetails(params.filter) },
    'separator',
    { name: 'Export', disabled: true },
];

<AgStudio getContextMenuItems={getContextMenuItems} />

With no callback, Studio opens no menu of its own and the browser's own context menu appears instead. When the callback returns an empty array, no menu opens and the browser's context menu stays hidden. To show a menu only for some right-clicks, for example only on grid rows, check the params and return an empty array for the rest.

The callback is read again on every right-click, so you can replace it at runtime with api.setProperty('getContextMenuItems', newCallback).

Using the Callback Params Copy Link

The callback is called for a right-click anywhere in the dashboard canvas, including on the empty space between widgets. Where the user right-clicks decides which params are set:

On the empty canvas, widgetId, widgetType, filter and getActiveFiltersForWidget are not set.
On any widget, widgetId and widgetType identify the widget, and getActiveFiltersForWidget is set.
On a grid or pivot grid cell, filter also holds the values of the clicked row, and widgetContext holds the grid's context menu params. filter is not set for a row that is still loading.
On a chart or gauge, widgetContext also holds the chart's context menu params. filter is set only on a chart series node, such as a column, bar or point, and not on treemap or sunburst charts.

A Custom Widget can pass the same extra information for a right-click inside it by calling api.showContextMenu({ event, filter }) from its widget API, passing the mouse event and the filter that describes what was clicked. See Custom Widgets - Context Menu for an example.

When set, the params hold:

filter: the field values of what was right-clicked.
getActiveFiltersForWidget(): returns the filters currently constraining the widget's data, split into page, widget and crossFilter, with selections the widget shows only as a highlight in crossFilterHighlight so you can choose whether to apply them. Each is omitted when no filter of that kind applies. Rank conditions, which widget may hold, are not supported in a drill-through filter.
widgetContext: any additional context from the widget. Its shape depends on widgetType.
api and context: the Studio API and your application context.

The example uses the values in filter to label its first item, and checks widgetId to offer no items on the empty canvas. Drill Through is built on the same callback, using filter to open a detail view of the clicked row.

Sub Menus Copy Link

Set subMenu on an item to an array of items, and the item opens them as a sub menu when hovered. Sub menus can nest:

{
    name: 'Copy',
    subMenu: [
        { name: 'Copy Value', action: () => copyValue() },
        { name: 'Copy Widget Type', action: () => copyWidgetType() },
    ],
}

Restoring Focus Copy Link

When a keyboard user closes the menu and nothing else has focus, Studio returns focus to the widget. If an action opens its own popup, call restoreFocusOnClose from the params when that popup closes, so focus goes back to the widget. The Drill Through popup example does this.

A right-click with ⌃ Ctrl/⌘ Cmd held opens the browser's own context menu instead of the Studio menu, for example to reach the browser's developer tools. This applies everywhere in the dashboard, including grids, charts, gauges and custom widgets. A menu opened from the keyboard, with the context menu key or ⇧ Shift + F10, is not affected.

To always open the Studio menu, even with ⌃ Ctrl/⌘ Cmd held, set allowContextMenuWithControlKey to true:

const allowContextMenuWithControlKey = true;

<AgStudio allowContextMenuWithControlKey={allowContextMenuWithControlKey} />

On macOS, ⌃ Ctrl + click is also the system's own secondary click. Users who right-click that way see the browser's context menu by default, and setting allowContextMenuWithControlKey to true opens the Studio menu for them instead.

The property can be changed at runtime with api.setProperty('allowContextMenuWithControlKey', true).

Properties Copy Link

Function

Called when the user right-clicks in the dashboard canvas. Studio opens a context menu showing the returned items. Return an empty array to show no menu. When this property is not set, Studio shows no menu of its own and the browser's context menu appears. A right-click with the Ctrl key (Cmd on macOS) held also shows the browser's context menu, unless allowContextMenuWithControlKey is true.

boolean

default: false

Set to true to open the Studio context menu when the user right-clicks with the Ctrl key (Cmd on macOS) held. By default, a right-click with Ctrl or Cmd held shows the browser's own context menu instead, everywhere in the dashboard including grids and charts.

HTMLElement | null

DOM element to use as the popup parent for Studio popups (context menus, etc.).

Properties available on the AgContextMenuItemDefinition interface.

string

Name of the menu item.

boolean

Set to true to display the menu item as disabled.

string

Shortcut text displayed inside menu item. Setting this doesn’t actually create a keyboard shortcut binding.

Function

Function that gets executed when item is chosen.

boolean

Set to true to provide a check beside the option.

string | Element

The icon to display, either a DOM element or HTML string.

string[]

CSS classes to apply to the menu item.

string

Tooltip text to be displayed for the menu item.

AgContextMenuItem[]

If this item is a sub menu, contains a list of menu item definitions.

Callback Params Copy Link

Properties available on the AgGetContextMenuParams<TWidgetContext = any, TCommon = any> interface.

string

ID of the widget that was right-clicked, or undefined if on the empty canvas.

string

Type of the widget that was right-clicked, for example grid or column-chart-grouped, or undefined if on the empty canvas.

TWidgetContext

Context from the widget, e.g. AG Charts context menu event params for chart widgets. The shape depends on the widget type.

AgFilterDefinition

The field values of what was right-clicked, such as the grouping values of a grid row or the category of a chart series node. Not set when the right-click is not on a row or data point.

Function

Returns the page, widget and cross filters currently constraining the data of the widget that was right-clicked, with selections the widget only highlights reported separately so you can choose whether to apply them. Set when widgetId is set. The returned filters can be combined and supplied as a drill-through filter to another report. Rank conditions, which widget may contain, are not supported in a drill-through filter.

MouseEvent | Touch

The mouse or touch event for the right-click.

Function

Returns keyboard focus to the widget. Call this when a popup opened from a menu item action is closed.

TCommon

Application context as set on context Studio property.

AgStudioApi

Studio API.

Getting Started

Connecting Data

Agent Framework

Fields & Formatting

Appearance & Behaviour

Interaction

Widgets

Server-Side Data

React Embedded AnalyticsContext Menu

Providing Menu Items Copy Link

Using the Callback Params Copy Link

Sub Menus Copy Link

Restoring Focus Copy Link

Showing the Browser Context Menu Copy Link

Context Menu API Copy Link

Properties Copy Link

Menu Items Copy Link

Callback Params Copy Link