Frontstages

A Frontstage is a full-screen configuration designed to enable the user to accomplish a task. There are three types of frontstages:

Type Description
Primary may use all zones and stage panels and the Tool Widget contains the App button that opens the App menu
Nested is accessed from a primary frontstage. It may use all zones and panels, but instead of the App button, the Tool Widget contains a Back button to return to the primary frontstage.
Modal is accessed from another frontstage or the Backstage. It may contain any content along with a Back button. It does not use zones or stage panels. It is useful for application settings and data management user interfaces.

Example Frontstage definition for displaying a viewport

Implementing ContentGroupProvider

ContentGroupProvider describes the contents that the frontstage will contain.

export class ViewportFrontstageGroupProvider extends ContentGroupProvider {
  public override async contentGroup(): Promise<ContentGroup> {
    return new ContentGroup({
      id: "content-group",
      layout: StandardContentLayouts.singleView,
      contents: [
        {
          id: "viewport",
          classId: IModelViewportControl,
          applicationData: {
            viewState: UiFramework.getDefaultViewState,
            iModelConnection: UiFramework.getIModelConnection,
          },
        },
      ],
    });
  }
}

Registering frontstage

Stage contents are then provided to a StandardFrontstageProvider which is registered by ConfigurableUiManager for further use.

export function registerViewportFrontstage(): void {
  const stageProps: StandardFrontstageProps = {
    id: "example:ViewportFrontstage",
    contentGroupProps: new ViewportFrontstageGroupProvider(),
    cornerButton: <BackstageAppButton />,
    usage: "General",
  };
  UiFramework.frontstages.addFrontstageProvider(new StandardFrontstageProvider(stageProps));
}

Other UI items (like toolbars) contained within the frontstage should be registered via UiItemsManager.

Usage

The Stage usage prop is a way to designate the type of tasks that will be performed in the stage and can be used by UiItemsProviders to determine if it should supply items such as tool button, widgets, or status bar items, to populate the stage. See StageUsage for a default set of usages.

Example FrontstageProvider implementation for displaying custom content

Implementing FrontstageProvider

FrontstageProvider contains all the information about what is displayed on the frontstage. This includes the main content view as well as various side panels and tools passed as FrontstageConfig properties.

export class CustomFrontstageProvider extends FrontstageProvider {
  public override get id(): string {
    return "example:CustomFrontstage";
  }
  // eslint-disable-next-line @typescript-eslint/indent
  public override frontstageConfig(): FrontstageConfig {
    const id = this.id;
    const contentGroup = new ContentGroup({
      id: "test-group",
      layout: StandardContentLayouts.singleView,
      contents: [{id: "custom-content", classId: CustomContentControl }],
    });
    return {
      id,
      version: 1,
      contentGroup,
      contentManipulation: {
        id: `${id}-contentManipulationTools`,
        element: <ContentToolWidgetComposer
          cornerButton={
            <BackstageAppButton label="Toggle Backstage" icon="icon-bentley-systems"
              execute={() => BackstageManager.getBackstageToggleCommand().execute()} />
          }
        />,
      },
    };
  }
}

Implementing ContentControl

ContentControl describes the main content view of the frontstage.

class CustomContentControl extends ContentControl {
  constructor(info: ConfigurableCreateInfo, options: any) {
    super(info, options);

    this.reactNode = (
      <h1 style={{
        height: "100%",
        display: "flex",
        alignItems: "center",
        justifyContent: "center",
      }}>
        Custom content!
      </h1>
    );
  }
}

API Reference

Last Updated: 20 June, 2023