Provide UI items

UiItemsProvider is a mechanism for providing UI elements such as widgets, toolbar, status bar and backstage items to the application. To create a new provider implement the interface.

import { UiItemsProvider } from "@itwin/appui-react";

const provider: UiItemsProvider = {
  id: "example:Provider",
  getWidgets: () => [],
  getToolbarItems: () => [],
};

Use the UiItemsManager to register a provider.

import { UiItemsManager } from "@itwin/appui-react";

UiItemsManager.register(provider);

To limit the scope of the provider to specific frontstages use an override object that contains an array of frontstage ids or stage usages.

import { UiItemsManager } from "@itwin/appui-react";

UiItemsManager.register(provider, { stageIds: ["example:CustomFrontstage"] });

Provide Widgets

Implement UiItemsManager.getWidgets to provide additional widgets to the application. To specify the default location of the Widget set the Widget.layouts property.

import {
  StagePanelLocation,
  StagePanelSection,
  UiItemsProvider,
} from "@itwin/appui-react";

const provider: UiItemsProvider = {
  id: "example:Provider",
  getWidgets: () => [
    {
      id: "example:Widget",
      content: <div>My custom widget</div>,
      layouts: {
        standard: {
          location: StagePanelLocation.Right,
          section: StagePanelSection.Start,
        },
      },
    },
  ],
};

Popout widget is a widget opened in a new browser window. To enable this feature set the Widget.canPopout property. When enabled the user can open the popout widget by clicking on the popout icon in the widget title bar.

Give it a try!

NOTE: widget component must be written in a way that works properly when opened in a new browser window. For example ownerDocument and ownerDocument.defaultView should be used instead of typically used window or document properties when registering the listeners.

Floating widget is displayed in a dialog like component of the page and is not docked to one of the stage panels. This feature is enabled by default, but you can provide additional options to Widget.canFloat property. Since the user is in control of the layout a docked widget can be undocked to create a new floating widget. For more information, see User Interactions.

Provide Toolbar Items

Implement UiItemsProvider.getToolbarItems to provide additional toolbar items to the application. Set the CommonToolbarItem.layouts property to specify the toolbar to which the ToolbarItem should be added. You can use one of ToolbarItemUtilities to create a toolbar item of specific type.

import {
  ToolbarItemUtilities,
  ToolbarOrientation,
  ToolbarUsage,
  UiItemsProvider,
} from "@itwin/appui-react";

const provider: UiItemsProvider = {
  id: "example:Provider",
  getToolbarItems: () => [
    ToolbarItemUtilities.createActionItem({
      id: "example:ToolbarItem",
      itemPriority: 100,
      icon: <SvgIcon />,
      label: "My custom toolbar item",
      layouts: {
        standard: {
          orientation: ToolbarOrientation.Horizontal,
          usage: ToolbarUsage.ContentManipulation,
        },
      },
    }),
  ],
};

Provide StatusBar Items

Implement UiItemsProvider.getStatusBarItems to provide additional status bar items to the application. You can use StatusBarItemUtilities to create a StatusBarItem of specific type.

import { StatusBarItemUtilities, UiItemsProvider } from "@itwin/appui-react";

const provider: UiItemsProvider = {
  id: "example:Provider",
  getStatusBarItems: () => [
    StatusBarItemUtilities.createActionItem({
      id: "example:StatusBarItem",
      itemPriority: 100,
      icon: <SvgIcon />,
      tooltip: "My status bar item",
    }),
  ],
};

Provide Backstage Items

Implement UiItemsProvider.getBackstageItems to provide additional backstage items to the application. You can use BackstageItemUtilities to create a BackstageItem of specific type.

import { BackstageItemUtilities, UiItemsProvider } from "@itwin/appui-react";

const provider: UiItemsProvider = {
  id: "example:Provider",
  getBackstageItems: () => [
    BackstageItemUtilities.createActionItem({
      id: "example:BackstageItem",
      label: "My backstage item",
    }),
  ],
};

Use Standard Providers

AppUI provides a set of standard providers that you can register to provide standard UI elements to the application: StandardContentToolsProvider, StandardNavigationToolsProvider, StandardStatusbarItemsProvider, StandardContentToolsUiItemsProvider, StandardNavigationToolsUiItemsProvider, StandardStatusbarUiItemsProvider.

Dynamic UI Item Updates

To update provided UI items dynamically use conditional value types. When creating a conditional value provide a function that returns a value based on the current state of the application. Provided function is invoked whenever the specified events are raised. AppUI provides these conditional value types: ConditionalBooleanValue, ConditionalStringValue, ConditionalIconItem. Use SyncUiEventDispatcher.dispatchSyncUiEvent to dispatch the events.

import { ConditionalBooleanValue } from "@itwin/appui-abstract";
import {
  SyncUiEventDispatcher,
  ToolbarItemUtilities,
} from "@itwin/appui-react";

function createBooleanStore(eventId: string, defaultValue: boolean) {
  let value = defaultValue;

  // Updates the state and dispatches the event which causes conditional item to update.
  const toggle = () => {
    value = !value;
    SyncUiEventDispatcher.dispatchSyncUiEvent(eventId);
  };

  // This is called by the conditional item to get the current value.
  const getValue = () => value;
  return {
    getValue,
    toggle,
    eventId,
  };
}

const isHiddenStore = createBooleanStore(
  "example:item-visibility-changed",
  false
);

// Create a toolbar item that can be hidden by an application.
ToolbarItemUtilities.createActionItem({
  id: "action-1",
  isHidden: new ConditionalBooleanValue(() => {
    // This function is called when the `example-is-hidden-changed` event is dispatched.
    return isHiddenStore.getValue();
  }, [isHiddenStore.eventId]),
});

// Toggles the state which causes the conditional item to update.
<button onClick={() => isHiddenStore.toggle()}>Toggle</button>;