Skip to main content

Create a custom widget

To create and add a new widget to Atoti UI, follow these steps:

  • Create a new widget file. The widget file holds the code to describe the widget.
  • Use pluginWidget to make the new widget available to the UI
  • Register the new widget to make it visible for users on the dashboard.

Widget file​

You need to create a widget file that contains the widget component. In this example, you can name it CustomWidget.tsx.

import React, { FC } from "react";

import { WidgetPluginProps } from "@activeviam/atoti-ui-sdk";

export const CustomWidget: FC<WidgetPluginProps> = (props) => {
  return <div>Hello World!</div>;
};

CustomWidget is a function component that accepts WidgetPluginProps and simply returns a div containing "Hello World!".

Plugin widget file​

The widget plugin is an object containing all the information needed to register a new widget in Atoti.

Here you can create a second file in the same location and call it pluginWidgetCustomWidget.ts.

TIP: Naming plugins

Take note of the naming here. When defining plugins it's good practice to use a consistent naming convention. For example:

  1. Start with "plugin".
  2. Reveal the type of "plugin". In this case it is a "widget", but it also could have been a "cell" or a "menuItem".
  3. Provide the underlying component's name . In this case it is called "customWidget".

This gives a final name of pluginWidgetCustomWidget.

pluginWidgetCustomWidget contains several properties:

  • The component is the thing that actually gets displayed. In this case it is CustomWidget.
  • The key is added to each widget to register the widget. This detail can be used to allow users to visualise the widget.
  • The initialState describes the look of the widget when it is first added to a dashboard.
  • icon
  • translations

By editing this object, you can change how this widget will look and behave.

import { WidgetPlugin } from "@activeviam/atoti-ui-sdk";

import { CustomWidget } from "./CustomWidget";

const widgetKey = "customWidget";
export const pluginWidgetCustomWidget: WidgetPlugin = {
  Component: CustomWidget,
  initialState: { widgetKey },
  key: widgetKey,
};

Register a new widget type​

To use this widget in your application:

  • Open up plugins.tsx.
  • Add pluginWidgetCustomWidget into the widgetPlugins array.
note

The widgetPlugins array is eventually passed to the plugin registry. This is how Atoti UI knows what plugins it has.

+ import { pluginWidgetCustomWidget } from "./pluginWidgetCustomWidget";

...

// Make sure to put it at the top of `widgetPlugins` so it becomes the first widget in the Widgets Panel. This will make it easier to find in the coming steps.
const widgetPlugins: Array<WidgetPlugin> = [

+ pluginWidgetCustomWidget,
  pluginWidgetPivotTable,
  ...
  ]

Connect a widget to the server​

Depending on your needs, you may want to add useQueryResult to the widget. This hook allows the user to run a query from the dashboard and see the retrieved data displayed in the widget. If useQueryResult is not added to the widget, the widget does not retrieve and display data from the server.