📘

This guide assumes knowledge of React and TypeScript.

You can configure a view in Formant and embed it in an external website. You can integrate a Formant view within your applications, and apply custom styling to white-label the Formant view.

This guide will teach you how to embed a Formant view into an external web application.

Steps 1 through 4 contain instructions and reference materials for various customization options in an embedded view. The Example section contains documentation on our interactive code sample for an embedded view hosted on Storybook.

Prerequisites

Build a Formant view

Before you can embed a Formant view in an external web application, you'll have to create a view. For more information, see Create a view and add modules.

🚧

Embedded views only work with Observability v2 beta views

Be sure to create an Observability (v2 beta) view as described in the link above, and NOT an Observability view as described in the Getting Started section of the documentation center.

Generate an auth token which sets access levels

A valid authentication token is required to access data in an embedded view. You will set the access level for devices, data, and entities when generating an authentication token for that session. For more information, see Generate an auth token for an embedded view.

Step 1: Install the Formant embedded view package

Run the following commands to install the Formant embedded view package:

npm install @formant/view-embed-react-wrapper
yarn add @formant/view-embed-react-wrapper

Step 2: Generate React code for your Formant view

1. Navigate to the view you want to embed.
2. In the view header, click the arrow next to the view name >> Embed...

3. You'll see a pop-up window with a code sample.

Step 3: Create React application which embeds your Formant view

Once you have the React package installed, you can copy the code in the Usage field and paste it into a React application to embed your view.

The parameters for the embedded view are as follows:

viewTags have the following syntax:

viewTags = {
  "tag-key-1": ["tag-value-1"],
  "tag-key-2": ["tag-value-2", "tag-value-3"]
}

This would show data tagged with tag-key-1: tag-value-1 AND (tag-key-2: tag-value-2 OR tag-key-2: tag-value-3). For a complete reference and more examples of tag syntax, see Generate an auth token for an embedded view: data and entities syntax.

📘

Default values for optional parameters

If not specified, the values for optional parameters listed above are inherited from the configuration of your view in the Formant web application.

This does not apply to themeOverride and wrapperStyleOverride. The default value for themeOverride is the default Formant style. The default value for wrapperStyleOverride is the default iframe style, which includes a border.

Step 4 (optional): White-label your interface

ThethemeOverride property contains the following parameters:

{
  fontFamily: "Oswald",
  fontFamilyUrl: "https://fonts.googleapis.com/css2?family=Oswald:[email protected]&display=swap",
  colors: {
    "formant-color-primary-white": "#FFFFFF",
    "formant-color-primary-silver": "#BAC4E2",
    "formant-color-primary-black": "#000000",
    "formant-color-opacity-dark": "rgba(0, 0, 0, 0.5)",
    "formant-color-opacity-light": "rgba(0, 0, 0, 0.25)",
    "formant-color-primary-dark": "#0A0B10",
    "formant-color-primary-flagship": "#1C1E2D",
    "formant-color-background": "#1c1e2d",
    "formant-color-primary-module": "#2D3855",
    "formant-color-primary-steel01": "#282F45",
    "formant-color-primary-steel02": "#3B4668",
    "formant-color-primary-steel03": "#657197",
    "formant-color-highlights-blue": "#18D2FF",
    "formant-color-data-royal-blue": "#20A0FF",
    "formant-color-data-purple": "#A961E4",
    "formant-color-data-red": "#EA719D",
    "formant-color-data-orange": "#F89973",
    "formant-color-data-yellow": "#F9C36E",
    "formant-color-data-green": "#2EC495",
  }
}

You can use the themeOverride parameter to white-label your embedded view. The following screenshots show which properties control which sections of the UI:

formant-color-primary-white

formant-color-primary-silver

formant-color-primary-black

formant-color-background

formant-color-primary-module

formant-color-primary-steel01

Interactive example

To see an interactive example of an embedded view, see Storybook: View Embed.

Customize the example

You can update the variables in the source code and customize the example using the Controls tab:

Source code

You can see the source code for the example under the Code tab:

See also

• Embedded views
• Generate an auth token for an embedded view
• Create a view and add modules

👋

If you notice an issue with this page or need help, please reach out to us! Use the 'Did this page help you?' buttons below, or get in contact with our Customer Success team via the Intercom messenger in the bottom-right corner of this page, or at [email protected].