Embedding Dashboards into your Application

Introduction

This article will review how to embed GoodData analytics into your application via iframes. In HTML, an iframe provides for a frame to be placed inside the body of a document. It lets you build user experiences into embeddable ‘cross-domain components’, which let users interact with other sites without being redirected. While iframes may have some disadvantages (such as slower initial load), they often serve as the easiest and fastest way to achieve the desired result with minimal coding.

What’s the story?

Let’s assume there’s an application with a particular look & feel that your users are accustomed to. It contains some basic charts and works fine, but any time your PMs or customers request a change, you need developers to change the code, which often takes quite a lot of time and effort. What you need is a simple to use GUI that will allow anybody – even your customers – to make the changes easily.

The aim of this exercise is to replace the hardcoded table and the two charts with an embedded Dashboard that is customizable while maintaining the same look & feel and preserving the filtering capabilities of the whole environment.

Implementation

This could be a very simplified source code of the current state of the application:

<MyPage>
  <AttributeDropdown attribute={PRODUCT_BRAND} />
  <AttributeDropdown attribute={PRODUCT_CATEGORY} />
  <Kpi measure={AVG_PRICE_OF_PRODUCTS} />
  <Kpi measure={TOTAL_LISTINGS} />
  <Kpi measure={PERC_SELL_THROUGH} />
  <Kpi measure={TOTAL_SALES} />
  <CustomTable />
  <LineChart />
  <ColumnChart />
  <GeoPushpinChart />
</MyPage>

To replace the main hardcoded insights on the page with an iframe, we need to roughly do the following:

<MyPage>
  <AttributeDropdown attribute={PRODUCT_BRAND} />
  <AttributeDropdown attribute={PRODUCT_CATEGORY} />
  <Kpi measure={AVG_PRICE_OF_PRODUCTS} />
  <Kpi measure={TOTAL_LISTINGS} />
  <Kpi measure={PERC_SELL_THROUGH} />
  <Kpi measure={TOTAL_SALES} />
  <iframe src="https://secure.gooddata.com/dashboards/embedded/#/project/<projectId>/dashboard/<dashboardId>" /> 
</MyPage>

After a few necessary CSS adjustments, our application could look like this:

Now we need to connect the custom filters at the top of the page to the dashboard in the iframe. For this, we’ll utilize so-called “commands” (see more at https://help.gooddata.com/doc/growth/en/expand-your-gooddata-platform/gooddata-integration-into-your-application/embed-gooddata-elements-into-your-applications/embed-a-dashboard/communication-with-embedded-dashboards). Commands are incoming messages sent from our application to the embedded Dashboard to apply actions. We’ll add the following logic into our attribute dropdown’s onChange handler:

document.getElementById(IFRAME_ID).contentWindow.postMessage(
  {
    gdc: {
      product: "dashboard",
      event: {
        name: "setFilterContext",
        data: {
          filters: [newFilter]
        }
      }
    }
  },
  backend
);

Every time Product Brand and Product Category filters are used, they will get propagated and applied to the embedded dashboard as well.
 

When we confirm that the shared filter context works as expected, as a last step we’re gonna hide the filter bar and the top bar by modifying the URL like so:

<iframe src=”https://secure.gooddata.com/dashboards/embedded/#/project/<projectId>/dashboard/<dashboardId>?showNavigation=false&hideControl=[filterBar,topBar]” />

Perfect!

Conclusion

Embedding Dashboards is fast and easy! Check our documentation to learn more about the embedding capabilities: https://help.gooddata.com/doc/growth/en/expand-your-gooddata-platform/gooddata-integration-into-your-application/embed-gooddata-elements-into-your-applications/embed-a-dashboard/communication-with-embedded-dashboards.

Dashboard will soon be coming as a React component as well so that embedding will be possible also for those who prefer not to use iframes. Stay tuned!

Edit: The Dashboard component that allows you to integrate a Dashboard using JavaScript without using an iframe is out! Read more about it here.