Embedding GoodData 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?

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, you 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, your application could look like this:

Now you need to connect the custom filters at the top of the page to the dashboard in the iframe. For this, utilize so-called “commands” (see more at https://help.gooddata.com/pages/viewpage.action?pageId=86797110#CommunicationwithEmbeddedKPIDashboards-Commands). Commands are incoming messages sent from our application to the embedded Dashboard to apply actions. You’ll need to add the following logic into your 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 you confirm that the shared filter context works as expected, as the last step you can 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: Embedding Dashboards and Communication with Embedded Dashboards.

The 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!