User Guide Getting Started Help Center Documentation Community Training
Looker
  
English
Français
Deutsch
日本語
Embedded JavaScript Events

After you’ve created an embed (either publicly, privately, or with single sign-on (SSO)) you can interact with those iframes via JavaScript. You can make your page more dynamic, based on the status of the embedded item, or even make changes to the embedded item from your web page.

Be aware that Looker does not control the order in which browsers dispatch events to web applications. This means that the order of events is not guaranteed across browsers or platforms. Be sure to write your JavaScript appropriately to account for the event handling of different browsers.

There are two ways you can leverage JavaScript for Looker embedded content:

Preparation

There are a few actions you’ll need to take before you can interact with the embedded iframe:

Add an ID to the iframe

One of the things you’ll need to do later is validate that the information you’re working with has actually come from Looker’s iframe. To facilitate this, make sure you add an ID to the iframe, if you haven’t already. In the example below, we’ve added id="looker":

<iframe id="looker" src="https://my.looker.com/embed/dashboards/1"></iframe>

Add the Embed Domain to the iframe src

In the iframe’s src, add the domain where the iframe is being used. In the example below, we’ve added ?embed_domain=https://mywebsite.com":

<iframe id="looker" src="https://my.looker.com/embed/dashboards/1?embed_domain=https://mywebsite.com"> </iframe>

If you’re using SSO embedding, make sure you add the embed_domain to the embed URL.

Do not include a trailing slash (/) in the embed_domain.

Whitelist the Embed Domain

Finally, you’ll need to add the domain where the iframe is being used to the whitelist on the Embed page of Looker’s admin panel:

  1. Enter the domain where the iframe is being used. After typing it, be sure to hit the [Tab] key so that the domain appears in a box. Do not include a trailing slash (/) in the domain URL.
  2. Click the Update button.

You can use the * wildcard in the whitelist to create a domain pattern. For example, https://*.mycompany.com would allow both https://analytics.mycompany.com and https://data.mycompany.com.

Accessing Events in Javascript

Retrieving Data from the iframe

After completing the preparation steps, you can access the events passed between the Looker iframe and your domain by listening for postMessage events.

Please be sure to check that the events have come from the Looker iframe and domain to avoid malicious messages.

There are a few event types that the embedded iframe can create, as described in the Event Type Reference section below.

Accessing Events in JavaScript

Here is an example of listening for these events in native JavaScript, then logging them to the console:

window.addEventListener("message", function(event) { if (event.source === document.getElementById("looker").contentWindow) { if (event.origin === "https://my.looker.com") { console.log(JSON.parse(event.data)); } } });

Here is an example of listening for these events in jQuery, then logging them to the console:

$(window).on("message", function(event) { if (event.originalEvent.source === $("#looker")[0].contentWindow) { if (event.origin === "https://my.looker.com") { console.log(JSON.parse(event.data)); } } });

Event Type Reference

There are many different types of events that the embedded iframe can create. They are:

dashboard:run:start

This event is created when a dashboard has begun loading, when its tiles will start loading and querying for data.

type: dashboard:run:start dashboard: { id: 23, title: "My Dashboard", url: "/embed/dashboards/…", absoluteUrl: "https://my.looker.com/embed/dashboards/…", filters: { "Date": "Last 28 days", "Total Orders": "Greater than 100" } }

Attribute Format Description
dashboard.id Number The ID number of the dashboard
dashboard.url String The relative dashboard URL (just the path)
dashboard.absoluteUrl String The full dashboard URL
dashboard.title String The title, as shown at the top of the dashboard
dashboard.filters Object The filters applied to the dashboard. This object has the format: {"Filter name 1": "value 1", "Filter name 2": "value 2", ...}

dashboard:run:complete

This event is created when a dashboard has finished running and all tiles have finished loading and querying.

type: dashboard:run:complete dashboard: { id: 23, title: "My Dashboard", url: "/embed/dashboards/…", absoluteUrl: "https://my.looker.com/embed/dashboards/…", filters: { "Date": "Last 28 days", "Total Orders": "Greater than 100" } }

Attribute Format Description
dashboard.id Number The ID number of the dashboard
dashboard.url String The relative dashboard URL (just the path)
dashboard.absoluteUrl String The full dashboard URL
dashboard.title String The title, as shown at the top of the dashboard
dashboard.filters Object The filters applied to the dashboard. This object has the format: {"Filter name 1": "value 1", "Filter name 2": "value 2", ...}

dashboard:tile:start

This event is created when a tile starts loading or querying for data.

type: dashboard:tile:start dashboard: { id: 23, title: "My Dashboard", url: "/embed/dashboards/…", absoluteUrl: "https://my.looker.com/embed/dashboards/…", filters: { "Date": "Last 28 days", "Total Orders": "Greater than 100" } } tile: { id: 123, title: "Quarterly Sales", listen: { "Date": "order.date", "Total Orders": "order.count" } }

Attribute Format Description
dashboard.id Number The ID number of the dashboard that the tile belongs to
dashboard.url String The relative dashboard URL (just the path) that the tile belongs to
dashboard.absoluteUrl String The full dashboard URL that the tile belongs to
dashboard.title String The dashboard title, as shown at the top of the dashboard that the tile belongs to
dashboard.filters Object The filters applied to the dashboard that the tile belongs to. This object has the format: {"Filter name 1": "value 1", "Filter name 2": "value 2", ...}
tile.id Integer The ID number of the event, not the tile
tile.title String The tile title, as shown at the top of the tile
tile.listen Object The global dashboard filters this tile is listening for. This object has the format: {"Filter Label": "Filter Field", ...}

dashboard:tile:complete

This event is created when a tile has finished loading or querying for data.

type: dashboard:tile:complete dashboard: { id: 23, title: "My Dashboard", url: "/embed/dashboards/…", absoluteUrl: "https://my.looker.com/embed/dashboards/…", filters: { "Date": "Last 28 days", "Total Orders": "Greater than 100" } } tile: { id: 123, title: "Quarterly Sales", listen: { "Date": "order.date", "Total Orders": "order.count" } }

Attribute Format Description
dashboard.id Number The ID number of the dashboard that the tile belongs to
dashboard.url String The relative dashboard URL (just the path) that the tile belongs to
dashboard.absoluteUrl String The full dashboard URL that the tile belongs to
dashboard.title String The dashboard title, as shown at the top of the dashboard that the tile belongs to
dashboard.filters Object The filters applied to the dashboard that the tile belongs to. This object has the format: {"Filter name 1": "value 1", "Filter name 2": "value 2", ...}
tile.id Integer The ID number of the event, not the tile
tile.title String The tile title, as shown at the top of the tile
tile.listen Object The global dashboard filters this tile is listening for. This object has the format: {"Filter Label": "Filter Field", ...}

dashboard:download

This event is created when a PDF of a dashboard has started downloading.

type: dashboard:download dashboard: { id: 23, title: "My Dashboard", url: "/embed/dashboards/…", absoluteUrl: "https://my.looker.com/embed/dashboards/…", filters: { "Date": "Last 28 days", "Total Orders": "Greater than 100" } } fileFormat: "pdf"

Attribute Format Description
dashboard.id Number The ID number of the dashboard
dashboard.url String The relative dashboard URL (just the path)
dashboard.absoluteUrl String The full dashboard URL
dashboard.title String The dashboard title, as shown at the top of the dashboard
dashboard.filters Object The filters applied to the dashboard. This object has the format: {"Filter name 1": "value 1", "Filter name 2": "value 2", ...}
fileFormat String The format of the downloaded dashboard (only "pdf" at this time)

dashboard:tile:download

This event is created when a tile’s data has started downloading.

type: dashboard:tile:download dashboard: { id: 23, title: "My Dashboard", url: "/embed/dashboards/…", absoluteUrl: "https://my.looker.com/embed/dashboards/…", filters: { "Date": "Last 28 days", "Total Orders": "Greater than 100" } } tile: { title: "Quarterly Sales" } fileFormat: "pdf"

Attribute Format Description
dashboard.id Number The ID number of the dashboard that the tile belongs to
dashboard.url String The relative dashboard URL (just the path) that the tile belongs to
dashboard.absoluteUrl String The full dashboard URL that the tile belongs to
dashboard.title String The dashboard title, as shown at the top of the dashboard that the tile belongs to
dashboard.filters Object The filters applied to the dashboard that the tile belongs to. This object has the format: {"Filter name 1": "value 1", "Filter name 2": "value 2", ...}
tile.title String The tile title, as shown at the top of the tile
fileFormat String The format of the downloaded tile (only "pdf" at this time)

dashboard:filters:changed

This event is created when a dashboard’s filters have been applied or changed.

type: dashboard:filters:changed dashboard: { id: 23, title: "My Dashboard", url: "/embed/dashboards/…", absoluteUrl: "https://my.looker.com/embed/dashboards/…", filters: { "Date": "Last 28 days", "Total Orders": "Greater than 100" } }

Attribute Format Description
dashboard.id Number The ID number of the dashboard
dashboard.url String The relative dashboard URL (just the path)
dashboard.absoluteUrl String The full dashboard URL
dashboard.title String The title, as shown at the top of the dashboard
dashboard.filters Object The filters applied to the dashboard. This object has the format: {"Filter name 1": "value 1", "Filter name 2": "value 2", ...}

look:run:start

This event is created when a Look begins to load and query data.

type: look:run:start look: { url: "/embed/looks/…", absoluteUrl: "https://my.looker.com/embed/looks/…", } }

Attribute Format Description
look.url String The relative Look URL (just the path)
look.absoluteUrl String The full Look URL

look:run:complete

This event is created when a Look has finished loading and querying data.

type: look:run:complete look: { url: "/embed/looks/…", absoluteUrl: "https://my.looker.com/embed/looks/…", } }

Attribute Format Description
look.url String The relative Look URL (just the path)
look.absoluteUrl String The full Look URL

drillmenu:click

This event is created when a user clicks on a drill menu in a dashboard created with the link LookML parameter. For example, the following LookML creates a drill menu where a user can view data filtered by the state dimension:

dimension: state { type: string sql: ${TABLE}.state ;; link: { label: "Filter by {{ state | encode_uri }}" url: "filter::q={{ state | encode_uri }}" icon_url: "https://google.com/favicon.ico" } }

When the state filter is set to “Illinois”, the drillmenu:click event returns the following to the host of the iframe:

type: "drillmenu:click", label: "Filter by Illinois", link_type: "url", url: "#filter::state=Illinois"

Attribute Format Description
label String The link label as shown on the drill menu
link_type String The type of object at the link destination
url String The URL of the link destination

Sandboxing the iframe will prevent drill menu clicks from opening in a new window. Use these sandboxing values inside the iframe tag:

sandbox = "allow-same-origin allow-scripts"

explore:state:changed

This event is created when an Explore page URL changes due to the user’s actions.

type: explore:state:changed explore: { url: "/embed/explore/…", absoluteUrl: "https://my.looker.com/embed/explore/…" }

Attribute Format Description
explore.url String The relative Explore URL (just the path)
explore.absoluteUrl String The full Explore URL

explore:run:start

This event is created when an Explore begins to load and query data.

type: explore:run:start explore: { url: "/embed/explore/…", absoluteUrl: "https://my.looker.com/embed/explore/…", } }

Attribute Format Description
explore.url String The relative Explore URL (just the path)
explore.absoluteUrl String The full Explore URL

explore:run:complete

This event is created when an Explore has finished loading and querying data.

type: explore:run:complete explore: { url: "/embed/explore/…", absoluteUrl: "https://my.looker.com/embed/explore/…", } }

Attribute Format Description
explore.url String The relative Explore URL (just the path)
explore.absoluteUrl String The full Explore URL

page:changed

This event is created when a user navigates to a new page within the iframe.

type: page:changed page: { type: "dashboard", url: "/embed/dashboards/…", absoluteUrl: "https://my.looker.com/embed/dashboards/…" }

Attribute Format Description
page.type String The type of the page that has just been navigated to, such as "dashboard", "look", or "explore"
page.url String The relative URL (just the path) of the page that has just been navigated to
page.absoluteUrl String The full URL of the page that has just been navigated to

page:properties:changed

This event is created when the height of a dashboard iframe changes. It is not available for Looks or Explores because those items automatically adjust their height to the size of the iframe.

type: page:properties:changed height: 1000

Attribute Format Description
height Integer The height of the dashboard iframe in pixels

Making Changes to the iframe

After you’ve prepped your iframe for data retrieval, you can make changes to the iframe by doing the following steps:

  1. Write your request in JSON.
  2. Post the request to the iframe’s contentWindow.

Write Your Request in JSON

There are several changes you can make to the iframe, which you’ll submit in JSON form. The available options are described below in the Action Reference section. Don’t forget to use JSON.stringify to turn your action into JSON, like this:

var my_request = JSON.stringify( { type: "dashboard:run" } );

Post the Request to the iframe’s contentWindow

Finally, post your message to the iframe’s contentWindow, like this:

var my_iframe = document.getElementById("my_iframe_id"); my_iframe.contentWindow.postMessage(my_request, 'https://my.looker.com');

Action Reference

These are the available actions you can post to the embedded iframe:

Run a Dashboard

Use this action to run the dashboard in the iframe. This is the same action as hitting the Run button on the dashboard.

{ type: "dashboard:run" }

Attribute Format Description
type String Using the type dashboard:run indicates you want to run the dashboard

Updating an Existing Dashboard Filter

Use this action to update an existing dashboard filter in the iframe. You cannot add a new filter to the dashboard by using this method.

{ "type": "dashboard:filters:update", "filters": { "Sale date": "Last 28 days", "Sale amount": "Greater than 100" } }

Attribute Format Description
type String Using the type dashboard:filters:update indicates you want to update the filters used by the dashboard
filters Object The new filters you want to apply to the dashboard. This object has the format: {"Filter name 1": "value 1", "Filter name 2": "value 2", ...}

Run a Look

Use this action to run the Look in the iframe. This is the same action as hitting the Run button on the Look.

{ type: "look:run" }

Attribute Format Description
type String Using the type look:run indicates you want to run the Look

Update an Existing Look Filter

Use this action to update an existing Look filter in the iframe. You cannot add a new filter to the Look by using this method.

{ "type": "look:filters:update", "filters": { "orders.created_at": "90 days", "products.brand": "Calvin Klein" } }

Attribute Format Description
type String Using the type look:filters:update indicates you want to update the filters used by the Look
filters Object The new filters you want to apply to the Look. This object has the format: {"view_name.field_name_1": "value 1", "view_name.field_name_1": "value 2", ...}
Top