Embed tables and charts in an IFrame

In addition to the Deephaven web UI, the Deephaven server serves pages that each display a single table, chart, or other widget. In this guide, you'll learn how to embed them in your own web page using inline frames (IFrames), authenticate from your page, and set the IFrame's color theme.

Run the following script in the Deephaven IDE console, or load it at startup with Application Mode, to create the objects used in the examples below. It creates sin_table, a time table that adds a row every second, and sin_chart, a line chart of that table made with dx.line from Deephaven Express:

Display a table or chart in an IFrame

If your server runs at http://localhost:10000, the URL for a specific table, chart, or other widget is:

Replace OBJECT_NAME with the variable name of the object. For example, to show the sin_table created by the setup script at the top of this page, the IFrame URL is http://localhost:10000/iframe/widget/?name=sin_table. To show the sin_chart, the IFrame URL is http://localhost:10000/iframe/widget/?name=sin_chart.

Here is a basic HTML page that embeds the table and the chart, each in its own IFrame:

A ticking table embedded in an IFrame

A ticking chart embedded in an IFrame

Let's watch it tick: the embedded table and chart stay live, so each new row that sin_table adds every second appears in your page just as it does in the Deephaven IDE.

If the server requires authentication, each IFrame can show its own Deephaven login screen. To log in from your page instead, see Authenticate from the parent window.

Authenticate from the parent window

Your page can supply the Deephaven login credentials itself, so the embedded table or chart opens without a separate login inside the IFrame. To turn this on, add the authProvider=parent query parameter to the IFrame URL.

In the steps below, the parent window is your page that contains the IFrame, and the child window is the Deephaven page inside the IFrame:

  1. The child window uses postMessage to send the parent window an io.deephaven.message.LoginOptions.request message.
  2. Your page responds with the same message id and a payload that holds the login options, such as the authentication type and token.
  3. The child window logs in to Deephaven with those options and shows the table or chart.

The following page authenticates both IFrames with pre-shared key authentication. For another authentication type, change the type and token in the payload, and add a username if the handler requires one.

The response contains the server's secret key, so the page accepts requests only from the Deephaven server's origin and sends its response only to that origin. Anyone who can load your page can read a key written into its source, so hard-code the key only for local testing. In production, have your page fetch the token from your own backend after it signs the user in.

Expand for the full HTML.

The embedded IFrames wait for login credentials from the parent window before showing the table and chart

Set theme colors

Your page can also set the color theme of the Deephaven page inside an IFrame with postMessage. To turn this on, add the theme=external-theme query parameter to the IFrame URL. The Deephaven page then asks your page for a theme when it loads, and your page must answer. After that, your page can send a new theme at any time.

The following IFrame URL includes theme=external-theme and the optional preloadTransparentTheme=true parameter, which lets the parent window show through while the IFrame is still loading:

Both the response to the theme request and any theme you send later carry the same theme settings, which have three parts:

  • name (required): a name for the theme.
  • baseThemeKey (optional): the base theme to start from, either default-dark or default-light. Defaults to default-dark.
  • cssVars (required): overrides for --dh-color-* theme variables. To use the base theme unchanged, pass an empty object ({}). Deephaven ignores any entry that isn't a --dh-color-* variable set to a valid CSS color.

Respond to the theme request

The Deephaven page inside the IFrame sends an io.deephaven.message.ThemeModel.requestExternalTheme message when it loads. Respond to it with the theme settings and the same message id.

The following page responds to the theme request with the dark base theme and custom grid colors:

Expand for the full HTML.

Send a theme at any time

To set or change the theme at any time, send the Deephaven page inside the IFrame an io.deephaven.message.ThemeModel.requestSetTheme message that holds the theme settings. Deephaven accepts this message only when the IFrame URL includes the theme=external-theme query parameter.

Your page must still answer the initial io.deephaven.message.ThemeModel.requestExternalTheme message, as shown in Respond to the theme request. Until the IFrame receives a theme, it shows nothing. If your page never answers the request, it times out after 30 seconds and the IFrame switches to the default dark theme, even if your page already sent a theme with requestSetTheme.

The following page extends the theme request page with a Toggle Theme button. It answers the initial theme request with the dark base theme, and each click then sends requestSetTheme, switching between the light and dark base themes:

Expand for the full HTML.

The parent page toggles the embedded table between the dark and light base themes