Option 2: iFrame
Embed Explo dashboards through an iFrame
What is an iFrame?
The HTML Inline Frame element (<iframe>
) represents a nested browsing context, embedding another HTML page into the current one. You can read more about iFrames here.
Where can I use the component?
Since the web component is an HTML element, you can use it in any context:
-
Directly in an HTML file
-
Define it in vanilla JS
-
Any JS web framework: React, Vue, Angular, etc
Constructing the iFrame Link
The iFrame is powered by an Explo URL that will need to be constructed.
Use an Embed Secret (Recommended)
https://app.explo.co/iframe/<jwt>/<environment>
Use a Dashboard Id and Customer Token
https://app.explo.co/iframe/<dashboard_id>/<customer_token>/<environment>
URL Attributes
All strings must be quoted with double quotes "".
Attribute Name | Type | Description |
---|---|---|
jwt (recommended) | string | This is the embed secret (JWT) for the dashboard. We recommend you use this attribute instead of the dashboard_id and customer_token . Read more about embed secrets here. |
dashboard_id | string | This is the dashboard embed id that you retrieve from the Explo application. |
customer_token | string | The customer_token is the token you use to identify the customer that is viewing the dashboard. This is retrieved via the Customer API. |
environment | string | The environment name (such as production or staging) that you would like to embed. If no environment is provided, the most recent saved version will be rendered. |
refresh-minutes | number | The cadence on which you want the dashboard to automatically refresh data. (Optional) |
locale_code | string | An optional argument that overrides any localization settings for your team. This will localize your dashboard’s numbers, currencies, and dates to the desired locale, if supported. |
currency_code | string | An optional argument that overrides any currency localization settings for your team. This will localize your dashboard’s currency symbols and format to the desired locale, if supported. |
timezone | string | An optional argument that allows you to specify a timezone to display dates in. Valid values can be found here. |
disable-editable-section-editing | boolean | An optional argument that disables your user from editing the editable section at the bottom of the dashboard if enabled. |
hide-editable-section | boolean | An optional argument that hides the editable section if enabled. |
theme | string | This is the name of the theme you created in the custom styles tab |
id | string | An optional argument that allows you to uniquely identify this dashboard if you have multiple on the same page. Used in Custom JS Events |
Embedding the iFrame Link
Embed the iFrame below into your web application. The iFrame is backward-compatible with the previous Dashboard Customer Token syntax, but we recommend using the Embed Secret (JWT) syntax. Read more about embed secrets here.
Passing in Variables
You can see how to do that here.
Hide Elements
You can hide elements on your dashboard by passing a hide parameter into the url of your embed like so:
https://app.explo.co/iframe/<jwt>/?element_name.hide=<true>
Exclude Dates
You can also restrict the available dates on a dashboard by passing in a min and max date to each date picker element in the variable section like so:
https://app.explo.co/iframe/<dashboard_id>/<customer_token>/?date_range_elem_id.maxDate=<ISO DATE>&date_range_elem_id.minDate=<ISO DATE>
Event-Based Updates
You are also able to pass events to the Explo iFrame without reloading the entire dashboard. Below is an example of passing a hide element event to an iFrame component. See here for more information on Custom JS Events.
var exploIframe = document.getElementById("explo-iframe");
exploIframe.contentWindow.postMessage(
{
event: "updateExploDashboardVariable",
detail: {
varName: "data_table_1.hide",
value: "true"
}
},
"*"
);