Adding showcase widgets to your iTwin Viewer

Introduction

This tutorial will take widgets from the sample showcase and add them to your iTwin Viewer using the uiProviders prop.

Info

Skill level:

Basic

Duration:

30 minutes

Prerequisites

This tutorial assumes that you already have:

Explored the sample showcase.
Your own local source for the iTwin Web Viewer based on the template @itwin/web-viewer
- Instructions for that can be found here
Configured your local source to open the “House Model” sample iModel.
- Instructions to use this sample iModel can be found here.
Understand the concept of a UI Provider and adding widgets.
Completed “Customizing the iTwin Viewer” tutorial.

1. Understanding the Sample Showcase

We hope you have given the sample showcase a tour and enjoyed the many samples provided. You may want to use some of these samples in your own iTwin Viewer, and to do so you’ll first need to understand how the showcase works.

If we take a closer look at the files involved in each sample, you’ll notice they all follow the same pattern containing a few important files:

[SampleName]App.tsx - Corresponds to App.tsx in the iTwin Viewer template and provides the main Viewer component.
[SampleName]Widget.tsx - Defines the UiItemsProvider that will be passed into prop uiProviders for our sample widget component. This widget is the controller for our samples.
[SampleName]Api.ts - Defines widget functionality that uses the iTwin.js API being showcased.
[SampleName].scss - Defines the styles in our css classes used inside the widget.

Given this pattern, it’s simple to identify the parts required to bring our sample showcase to your iTwin Viewer. The component revolves around the [SampleName]Widget.tsx file so we need to copy all the files associated with our custom widget’s UiItemsProvider and pass it in the Viewer component.

2. Example using a sample

For this tutorial, we’ll be taking the widget from sample View Attributes and adding it into our iTwin Viewer.

Starting with our entry file ViewAttributesApp.tsx, the Viewer component is shown in a code snippet.

The Viewer component in ViewAttributesApp.tsx file

<Viewer
  contextId={process.env.IMJS_CONTEXT_ID ?? ""}
  iModelId={process.env.IMJS_IMODEL_ID ?? ""}
  authConfig={{ oidcClient: AuthorizationClient.oidcClient }}
  viewportOptions={viewportOptions}
  onIModelConnected={_oniModelReady}
  defaultUiConfig={default3DSandboxUi}
  theme="dark"
  uiProviders={uiProviders}
/>

Prop uiProviders is passed in as an array that contains the ViewAttributesWidgetProvider, imported and defined at the top of the file.

Passing ViewAttributesWidgetProvider to uiProviders

1
2
3

import { ViewAttributesWidgetProvider } from "./ViewAttributesWidget";
...
const uiProviders = [new ViewAttributesWidgetProvider()];

To sum it up, three lines shown is a code snippet are the only lines you’ll need to add in your iTwin Viewer in App.tsx.

Lines you need to add in your iTwin Viewer in `App.tsx`

... // Import the widget provider
import { ViewAttributesWidgetProvider } from "./ViewAttributesWidget";
... // Construct the widget provider
const uiProviders = [new ViewAttributesWidgetProvider()];
... // A Prop passed into the <Viewer> component
uiProviders={uiProviders}

We now have made all the necessary coding modifications to our iTwin Viewer. We’ll just need to copy the remaining three files to bring our widget over.

ViewAttributesApi.ts
ViewAttributesWidget.tsx
ViewAttributes.scss

For this tutorial, these files will be placed directly in our src directory so your file structure should look similar to this:

ViewAttributesStructure

Running our iTwin Viewer now, you’ll notice the same fully functional widget from the sample showcase in your iTwin Viewer.

ViewAttributesResults

Feel free to customize these widgets to your liking.

3. Multiple ways to extend uiProviders

If you already have a uiProviders prop passed in or would like to add more widgets from the sample showcase, the uiProviders prop takes in an array of providers. Extending the widget is as simple as appending to your array.

You can add to the uiProviders const variable, i.e.:

const uiProviders = [new ViewAttributesWidgetProvider(), new HyerModelingWidgetProvider(), ...]

or ignore the variable completely and pass the array in directly:

<Viewer
  contextId={process.env.IMJS_CONTEXT_ID ?? ""}
  iModelId={process.env.IMJS_IMODEL_ID ?? ""}
  authConfig={{ oidcClient: AuthorizationClient.oidcClient }}
  viewportOptions={viewportOptions}
  onIModelConnected={_oniModelReady}
  defaultUiConfig={default3DSandboxUi}
  theme="dark"
  uiProviders={[new ViewAttributesWidgetProvider(), new HyperModelingWidgetProvider(), ...]}
/>

Just remember to copy corresponding files to your source.

If you’d like to use an existing UiItemsProvider instead of passing in multiple new ones, just add the widget in your provideWigets() function along with copying and pasting the react component to your desired location.

Using an existing UiItemsProvider instead of passing in multiple new ones

export class MyCustomUiProvider extends UiItemsProvider {
  ... // Your custom code
  public provideWidgets(
    _stageId: string,
    _stageUsage: string,
    location: StagePanelLocation,
    _section?: StagePanelSection
  ): ReadonlyArray<AbstractWidgetProps> {
    const widgets: AbstractWidgetProps[] = [];
    if (location === StagePanelLocation.Right) {
      widgets.push({
        id: 'ViewAttributesWidget',
        label: 'View Attributes Controls',
        defaultState: WidgetState.Floating,
        getWidgetContent: () => <ViewAttributesWidget />, // Don't forget to copy code for the ViewAttributesWidget
      });
    }
  }
}

As you can see, extending your iTwin Viewer with multiple widgets is simple. It’s completely up to you on how you want to structure your directories and components. Feel free to extend as many widgets as you like.

Continue learning

Start building a Viewer App

This quick start is intended to help you get started with using iTwin Platform visualization components. By the end of this walkthrough, you will be able to build and run a web application for viewing an infrastructure digital twin (iTwin).

Customizing the iTwin Viewer - "The Basics"

This tutorial will take you through the first steps of customizing your iTwin Web Viewer. First you will learn how to add a new user interface component. Later you will customize that component to change the background color of your viewer.

More resources that you may like

Create a test iModel from a Bentley provided sample

The quickest way to get access to a cloud hosted iModel is by creating an iModel seeded with Bentley provided sample data.

Sample House Model

Bentley provided sample of a House for test iModel creation.

UI Provider

Describes interface of objects that want to provide UI component to the running IModelApp.

View Attributes Sample

This sample demonstrates the API used to control view attributes.

Visit the iTwin Sample Showcase

The iTwin Sample Showcase provides many samples demonstrating options for customizing the iTwin viewer.