Getting started with Looker

Best Practices

Documentation

Community

Training

Certification

Articles in this section

See more

Embedded JavaScript events

Avatar
Looker Support
  • Updated
Follow

After you’ve created an embed — this can be done publicly, privately, with single sign-on (SSO), or through the API — 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 webpage.

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.

You can leverage JavaScript two ways for Looker embedded content:

  • Using Looker’s embed Software Development Kit (SDK), described on the Embed SDK documentation page
  • Using JavaScript events, described in the Accessing Events in JavaScript section on this page

Preparation

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

Adding 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 following example, we’ve added id="looker":

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

Adding the embed domain to the iframe src attribute

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

<iframe id="looker" src="https://instance_name.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.

Adding the embed domain to the allowlist

Finally, you’ll need to add the domain where the iframe is being used to the allowlist 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 allowlist to create a domain pattern. For example, https://*.mycompany.com would allow both https://analytics.mycompany.com and https://data.mycompany.com.

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.

The embedded iframe can create a few event types, as described in the Event type reference section on this page.

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://instance_name.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://instance_name.looker.com") { console.log(JSON.parse(event.data)); } } });

Event type summary table

The following table summarizes event types. Click on an event type to see the details about that event.

Event Type Event Cause
dashboard:loaded On dashboards where the tiles are not set to auto-run, a dashboard and its elements have loaded but queries are not yet running.
dashboard:run:start A dashboard has begun loading, and its tiles have started loading and querying for data.
dashboard:run:complete A dashboard has finished running and all tiles have finished loading and querying.
dashboard:download A PDF of a dashboard has started downloading.
dashboard:save:complete ADDED21.6 A dashboard has been edited and saved.
dashboard:delete:complete ADDED21.6 A dashboard has been deleted.
dashboard:tile:start A tile has started loading or querying for data.
dashboard:tile:complete A tile has finished running the query.
dashboard:tile:download A tile’s data has started downloading.
dashboard:tile:explore A user has clicked the Explore From Here option in a dashboard tile.
dashboard:tile:view A user has clicked the View Original Look option in a dashboard tile.
dashboard:filters:changed A dashboard’s filters have been applied or changed.
look:ready A Look has begun to load query data, whether the query will run or not.
look:run:start A Look has begun to load query data and the query has begun to run.
look:run:complete A Look has finished running the query.
look:save:complete ADDED21.6 A Look has been edited and saved.
look:delete:complete ADDED21.6 A Look has been moved into the Trash folder.
drillmenu:click A user has clicked on a drill menu in a dashboard that was created with the link LookML parameter.
drillmodal:download ADDED7.20 A user has opened a drill dialog box from a dashboard tile and clicked the Download option.
drillmodal:explore A user has clicked the Explore From Here option in a drill dialog box.
explore:ready An Explore has begun to load query data, whether the query will run or not.
explore:run:start An Explore has begun to load query data and the query has begun to run.
explore:run:complete An Explore has finished running the query.
explore:state:changed An Explore page URL has changed as a result of the user’s actions.
page:changed A user has navigated to a new page within the iframe.
page:properties:changed The height of a dashboard iframe has changed.

Event type reference

The embedded iframe can create many different types of events:

dashboard:loaded

On dashboards where the tiles are not set to auto-run, this event is created after a dashboard and its elements have loaded but before queries are run.

The options attribute is not available on legacy dashboards.

type: "dashboard:loaded", status: "complete", dashboard: { id: 1, title: "Business Pulse", dashboard_filters: { "date": "Last 6 Years", "state": "" }, absoluteUrl: "https://self-signed.looker.com:9999/embed/dashboards/1?embed_domain=https%3A%2F%2Fself-signed.looker.com%3A9999&date=Last+6+Years&state=", url: "/embed/dashboards/1?embed_domain=https%3A%2F%2Fself-signed.looker.com%3A9999&date=Last+6+Years&state=", options: { layouts: [ { id: 1, dashboard_id: 1, type: "newspaper", active: true, column_width: null, width: null, deleted: false, dashboard_layout_components: [ { id: 1, dashboard_layout_id: 1, dashboard_element_id: 1, row: 0, column: 0, width: 8, height: 4, deleted: false }, { id: 2, dashboard_layout_id: 1, dashboard_element_id: 2, row: 0, column: 8, width: 8, height: 4, deleted: false } ] } ], elements: { 1: { title: "Total Orders", title_hidden: false, vis_config: { type: "single_value", font_size: "medium", title: "Total Orders" } }, 2: { title: "Average Order Profit", title_hidden: false, vis_config: { type: "single_value", title: "Average Order Profit" } } } } }

Attribute Format Description
status String Indicates whether the dashboard and its elements have successfully loaded.
dashboard.id Number The ID number of the dashboard.
dashboard.title String The title, as shown at the top of the dashboard.
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.absoluteUrl String The full dashboard URL.
dashboard.url String The relative dashboard URL (just the path).
dashboard.options Object The dashboard layout, dashboard layout component, and dashboard element properties and values. All properties returned in the options object can be given updated values using the dashboard:options:set event. This option is not available on legacy dashboards.

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://instance_name.looker.com/embed/dashboards/…", dashboard_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.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. This event is created whether or not all tiles load successfully.

The options and tileStatuses attributes are not available on legacy dashboards.

type: "dashboard:run:complete", status: "complete", dashboard: { id: 23, title: "My Dashboard", url: "/embed/dashboards/…", absoluteUrl: "https://my.looker.com/embed/dashboards/…", dashboard_filters: { "Date": "Last 28 days", "Total Orders": "Greater than 100" } options: { layouts: [ { id: 1, dashboard_id: 1, type: "newspaper", active: true, column_width: null, width: null, deleted: false, dashboard_layout_components: [ { id: 1, dashboard_layout_id: 1, dashboard_element_id: 1, row: 0, column: 0, width: 8, height: 4, deleted: false }, { id: 2, dashboard_layout_id: 1, dashboard_element_id: 2, row: 0, column: 8, width: 8, height: 4, deleted: false } ] } ], elements: { 1: { title: "Total Orders", title_hidden: false, vis_config: { type: "single_value", font_size: "medium", title: "Total Orders" } }, 2: { title: "Average Order Profit", title_hidden: false, vis_config: { type: "single_value", title: "Average Order Profit" } } } } }

Attribute Format Description
status String Indicates whether the dashboard and its elements have successfully run. If the dashboard and its elements were successfully run, status returns "complete"; otherwise, status returns "error". If the running dashboard was stopped, either from the user interface or with the dashboard:stop action, status will return "stopped".
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.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.options Object The dashboard layout, dashboard layout component, and dashboard element properties and values. All properties returned in the options object can be given updated values using the dashboard:options:set action. This option is not available on legacy dashboards.
dashboard.tileStatuses Object array An array of objects providing tile statuses. Object properties are:
  • tileId — the ID number of tile.
  • status — If the tile query was successfully run, status returns "complete"; otherwise, status returns "error".
  • errors — Populated when the status property is "error". An array of objects providing details of the error, including the error message text, a more detailed description of the error, and the tile’s SQL query that produced the error.
This option is not available on legacy dashboards.

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://instance_name.looker.com/embed/dashboards/…", dashboard_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.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:save:complete

This event is created when a dashboard is edited and then saved.

This event is not available on legacy dashboards.

type: "dashboard:save:complete", dashboard: { id: 23, title: "My Dashboard", dashboard_filters: { "Date": "Last 28 days", "Total Orders": "Greater than 100" } absoluteUrl: "https://instance_name.looker.com/embed/dashboards/…", url: "/embed/dashboards/…", options: { layouts: [ { id: 1, dashboard_id: 1, type: "newspaper", active: true, column_width: null, width: null, deleted: false, dashboard_layout_components: [ { id: 1, dashboard_layout_id: 1, dashboard_element_id: 1, row: 0, column: 0, width: 8, height: 4, deleted: false }, { id: 2, dashboard_layout_id: 1, dashboard_element_id: 2, row: 0, column: 8, width: 8, height: 4, deleted: false } ] } ], elements: { 1: { title: "Total Orders", title_hidden: false, vis_config: { type: "single_value", font_size: "medium", title: "Total Orders" } }, 2: { title: "Average Order Profit", title_hidden: false, vis_config: { type: "single_value", title: "Average Order Profit" } } } } }

Attribute Format Description
dashboard.id Number The ID number of the dashboard.
dashboard.title String The title, as shown at the top of the dashboard.
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.absoluteUrl String The full dashboard URL.
dashboard.url String The relative dashboard URL (just the path).
dashboard.options Object The dashboard layout, dashboard layout component, and dashboard element properties and values. All properties returned in the options object can be given updated values using the dashboard:options:set event.

dashboard:delete:complete

This event is created when a dashboard is deleted.

This event is not available on legacy dashboards.

type: "dashboard:delete:complete", dashboard: { id: 23, title: "My Dashboard", dashboard_filters: { "Date": "Last 28 days", "Total Orders": "Greater than 100" } absoluteUrl: "https://instance_name.looker.com/embed/dashboards/…", url: "/embed/dashboards/…", options: { layouts: [ { id: 1, dashboard_id: 1, type: "newspaper", active: true, column_width: null, width: null, deleted: false, dashboard_layout_components: [ { id: 1, dashboard_layout_id: 1, dashboard_element_id: 1, row: 0, column: 0, width: 8, height: 4, deleted: false }, { id: 2, dashboard_layout_id: 1, dashboard_element_id: 2, row: 0, column: 8, width: 8, height: 4, deleted: false } ] } ], elements: { 1: { title: "Total Orders", title_hidden: false, vis_config: { type: "single_value", font_size: "medium", title: "Total Orders" } }, 2: { title: "Average Order Profit", title_hidden: false, vis_config: { type: "single_value", title: "Average Order Profit" } } } } }

Attribute Format Description
dashboard.id Number The ID number of the dashboard.
dashboard.title String The title, as shown at the top of the dashboard.
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.absoluteUrl String The full dashboard URL.
dashboard.url String The relative dashboard URL (just the path).
dashboard.options Object The dashboard layout, dashboard layout component, and dashboard element properties and values. All properties returned in the options object can be given updated values using the dashboard:options:set event.

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://instance_name.looker.com/embed/dashboards/…", dashboard_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 to which the tile belongs.
dashboard.url String The relative dashboard URL (just the path) to which the tile belongs.
dashboard.absoluteUrl String The full dashboard URL to which the tile belongs.
dashboard.title String The dashboard title, as shown at the top of the dashboard to which the tile belongs.
dashboard.dashboard_filters Object The filters applied to the dashboard to which the tile belongs. 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 running the query.

The errors attribute is not available on legacy dashboards.

type: "dashboard:tile:complete", dashboard: { id: 23, title: "My Dashboard", url: "/embed/dashboards/…", absoluteUrl: "https://instance_name.looker.com/embed/dashboards/…", dashboard_filters: { "Date": "Last 28 days", "Total Orders": "Greater than 100" } } status: "complete", truncated: false, 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 to which the tile belongs.
dashboard.url String The relative dashboard URL (just the path) to which the tile belongs.
dashboard.absoluteUrl String The full dashboard URL to which the tile belongs.
dashboard.title String The dashboard title, as shown at the top of the dashboard to which the tile belongs.
dashboard.dashboard_filters Object The filters applied to the dashboard to which the tile belongs. This object has the format: {"Filter name 1": "value 1", "Filter name 2": "value 2", ...}
status String Whether the tile query completed successfully. Possible values are "complete" or "error".
truncated Boolean Whether the tile query results were truncated as a result of the query returning more rows than the query row limit. The row limit could be either a user-specified row limit or the Looker default row limit of 5,000.
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", ...}
tile.errors Object array Populated when the status property is "error". An array of objects providing details of the error, including the error message text, a more detailed description of the error, and the tile’s SQL query that produced the error. This option is not available on legacy dashboards.

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://instance_name.looker.com/embed/dashboards/…", dashboard_filters: { "Date": "Last 28 days", "Total Orders": "Greater than 100" } } tile: { id: 123, title: "Quarterly Sales" listen: { "Date": "order.date", "Total Orders": "order.count" } } fileFormat: "pdf"

Attribute Format Description
dashboard.id Number The ID number of the dashboard to which the tile belongs.
dashboard.url String The relative dashboard URL (just the path) to which the tile belongs.
dashboard.absoluteUrl String The full dashboard URL to which the tile belongs.
dashboard.title String The dashboard title, as shown at the top of the dashboard to which the tile belongs.
dashboard.dashboard_filters Object The filters applied to the dashboard to which the tile belongs. 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", ...}
fileFormat String The format of the downloaded tile (only "pdf" at this time).

dashboard:tile:explore

This event is created when a user clicks the Explore From Here option in a dashboard tile.

type: "dashboard:tile:explore", label: 'Explore From Here', url: '/embed/explore/model/view…', dashboard: { id: 23, title: "My Dashboard", url: "/embed/dashboards/…", absoluteUrl: "https://instance_name.looker.com/embed/dashboards/…", dashboard_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
label String The button label.
url String The relative URL (just the path) of the Explore to be viewed.
dashboard.id Number The ID number of the dashboard to which the tile belongs.
dashboard.url String The relative dashboard URL (just the path) to which the tile belongs.
dashboard.absoluteUrl String The full dashboard URL to which the tile belongs.
dashboard.title String The dashboard title, as shown at the top of the dashboard to which the tile belongs.
dashboard.dashboard_filters Object The filters applied to the dashboard to which the tile belongs. 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:view

This event is created when a user clicks the View Original Look option in a dashboard tile.

type: "dashboard:tile:view", label: 'View Original Look', url: '/embed/look/…', dashboard: { id: 23, title: "My Dashboard", url: "/embed/dashboards/…", absoluteUrl: "https://instance_name.looker.com/embed/dashboards/…", dashboard_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
label String The button label.
url String The relative URL (just the path) of the Look to be viewed.
dashboard.id Number The ID number of the dashboard to which the tile belongs.
dashboard.url String The relative dashboard URL (just the path) to which the tile belongs.
dashboard.absoluteUrl String The full dashboard URL to which the tile belongs.
dashboard.title String The dashboard title, as shown at the top of the dashboard to which the tile belongs.
dashboard.dashboard_filters Object The filters applied to the dashboard to which the tile belongs. 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:filters:changed

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

The options attribute is not available on legacy dashboards.

type: "dashboard:filters:changed", dashboard: { id: 23, title: "My Dashboard", url: "/embed/dashboards/…", absoluteUrl: "https://instance_name.looker.com/embed/dashboards/…", dashboard_filters: { "Date": "Last 28 days", "Total Orders": "Greater than 100" } options: { layouts: [ { id: 1, dashboard_id: 1, type: "newspaper", active: true, column_width: null, width: null, deleted: false, dashboard_layout_components: [ { id: 1, dashboard_layout_id: 1, dashboard_element_id: 1, row: 0, column: 0, width: 8, height: 4, deleted: false }, { id: 2, dashboard_layout_id: 1, dashboard_element_id: 2, row: 0, column: 8, width: 8, height: 4, deleted: false } ] } ], elements: { 1: { title: "Total Orders", title_hidden: false, vis_config: { type: "single_value", font_size: "medium", title: "Total Orders" } }, 2: { title: "Average Order Profit", title_hidden: false, vis_config: { type: "single_value", title: "Average Order Profit" } } } } }

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.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.options Object The dashboard layout, dashboard layout component, and dashboard element properties and values. All properties returned in the options object can be given updated values using the dashboard:options:set event. This option is not available on legacy dashboards.

look:ready

This event is created when a Look begins to load query data, whether the query runs or not.

type: "look:ready", look: { url: "/embed/looks/…", absoluteUrl: "https://instance_name.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:start

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

type: "look:run:start", look: { url: "/embed/looks/…", absoluteUrl: "https://instance_name.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 running the query.

type: look:run:complete look: { url: "/embed/looks/…", absoluteUrl: "https://instance_name.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:save:complete

This event is created when a Look is edited and saved. This event is created when a user performs one of the following tasks:

This event is not created if the Look is saved with the Save > To existing dashboard or Edit Settings menu option.

type: look:save:complete look: { url: "/embed/looks/…", absoluteUrl: "https://instance_name.looker.com/embed/looks/…", spaceId: 123 } }

Attribute Format Description
look.url String The relative Look URL (just the path)
look.absoluteUrl String The full Look URL
look.spaceID Integer The folder ID where the Look is stored

look:delete:complete

This event is created when a Look is moved to the Trash folder.

type: look:delete:complete look: { url: "/embed/looks/…", absoluteUrl: "https://instance_name.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", modal: false, target: '_self', url: "#filter::state=Illinois" context: ' '

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
modal Boolean Whether the drill dialog box will be used instead of browser navigation
target String Is _self if the link destination will replace the current iframe, _blank if the link destination will open a new window
url String The URL of the link destination
context String Internal attribute used by some types of visualizations

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"

drillmodal:download

This event is created when a user opens a drill dialog box from a dashboard tile and clicks the Download option.

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

Attribute Format Description
dashboard.id Number The ID number of the dashboard to which the tile belongs.
dashboard.title String The dashboard title, as shown at the top of the dashboard to which the tile belongs.
dashboard.url String The relative dashboard URL (just the path) to which the tile belongs.
dashboard.absoluteUrl String The full dashboard URL to which the tile belongs.
dashboard.dashboard_filters Object The filters applied to the dashboard to which the tile belongs. This object has the format: {"Filter name 1": "value 1", "Filter name 2": "value 2", ...}
drillExploreUrl String The relative Explore URL (just the path) to be downloaded.
fileFormat String The file format of the data download.

drillmodal:explore

This event is created when a user clicks the Explore From Here option in a drill dialog box.

type: "drillmodal:explore", label: "Explore From Here", url: "/embed/explore/model/view…"

Attribute Format Description
label String The button label as shown on the drill menu
url String The relative Explore URL (just the path) to be viewed

explore:ready

This event is created when an Explore begins to load query data, whether the query runs or not.

type: "explore:ready", explore: { url: "/embed/explore/…", absoluteUrl: "https://instance_name.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 query data and the query begins to run.

type: "explore:run:start", explore: { url: "/embed/explore/…", absoluteUrl: "https://instance_name.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 running the query.

type: "explore:run:complete", explore: { url: "/embed/explore/…", absoluteUrl: "https://instance_name.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:state:changed

This event is created when an Explore page URL changes as a result of the user’s actions.

type: "explore:state:changed", explore: { url: "/embed/explore/…", absoluteUrl: "https://instance_name.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://instance_name.looker.com/embed/dashboards/…" }

Attribute Format Description
page.type String The type of 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 with the following steps:

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

Writing your request in JSON

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

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

Posting the request to the iframe’s contentWindow property

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://instance_name.looker.com');

Action summary table

The following table summarizes actions. Click on an action to see the details about that action.

Action Action Description
dashboard:load Loads a new dashboard in the iframe, replacing an existing dashboard.
dashboard:run Runs the dashboard in the iframe.
dashboard:filters:update Updates an existing dashboard filter in the iframe.
dashboard:options:set Writes new values to dashboard layout and dashboard element properties.
dashboard:schedule_modal:open ADDED7.20 Opens the Scheduler, which lets users deliver Looker content to various destinations.
dashboard:stop Stops a dashboard that is running or reloading data.
look:run Runs the Look in the iframe.
look:filters:update Updates an existing Look filter in the iframe.
explore:run Runs the Explore in the iframe.
explore:filters:update Updates or removes an existing Explore filter in the iframe.

Action reference

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

dashboard:load

This action is not available on legacy dashboards.

Use this action to load a new dashboard in the iframe, replacing an existing dashboard. The new dashboard will begin executing queries as if a new dashboard page had been opened.

{ type: "dashboard:load", id: "101", pushHistory: false }

Attribute Format Description
type String Using the type dashboard:load indicates that you want to load a new dashboard into the iframe.
id String The ID of the dashboard to load.
pushHistory Boolean If true, the dashboard loaded creates a new browser history entry, and the user can use the browser’s back button to return to the previous dashboard. If false, the current dashboard is replaced and browser navigation cannot be used to return to it.

dashboard:run

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

{ type: "dashboard:run" }

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

dashboard:filters:update

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 that 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", ...}

dashboard:options:set

This action is available after the dashboard:run:complete event occurs and is not available on legacy dashboards.

The embedder creates the message and sends it to the iframe, but the dashboard does not respond until after dashboard:run:complete occurs. The dashboard:options:set action writes new values to dashboard layout and dashboard element properties. Only properties that have been returned in the options attribute of the dashboard:run:complete event can be updated using dashboard:options:set. Any properties set that were not previously returned by the options attribute of the dashboard:run:complete event are ignored.

{ type: "dashboard:options:set", layouts: [ { id: 1, dashboard_id: 1, type: "newspaper", active: true, column_width: null, width: null, deleted: false, dashboard_layout_components: [ { id: 1, dashboard_layout_id: 1, dashboard_element_id: 1, row: 0, column: 0, width: 8, height: 4, deleted: false }, { id: 2, dashboard_layout_id: 1, dashboard_element_id: 2, row: 0, column: 8, width: 8, height: 4, deleted: false } ] } ], elements: { 1: { title: "Total Orders", title_hidden: false, vis_config: { type: "single_value", font_size: "medium", title: "Total Orders" } }, 2: { title: "Average Order Profit", title_hidden: false, vis_config: { type: "single_value", title: "Average Order Profit" } } } }

Attribute Format Description
type String Using the type dashboard:options:set indicates that you want to write new values to dashboard layout and dashboard element properties.
layouts Object The dashboard layout properties returned by the options attribute in the dashboard:run:complete event. These will be in a format similar to:

id: "string",
dashboard_id: "string",
type: "newspaper",
active: boolean,
column_width: number,
width: number | null,
deleted: boolean,
layouts.dashboard_layout_components Object One or more dashboard layout component objects returned by the options attribute in the dashboard:run:complete event. These will be in a format similar to:

id: "string",
dashboard_layout_id: "string",
dashboard_element_id: "string",
row: number,
column: number,
width: number,
height: number,
deleted: boolean,
elements Object One or more dashboard element objects returned by the options attribute in the dashboard:run:complete event. These will be in a format similar to:

id: {
  title: "string" | null,
  title_hidden: boolean,
  vis_config: {
    type: "string", title: "string" | null
  }
}

dashboard:schedule_modal:open

Use this action to open the Scheduler, which lets users deliver Looker content to various destinations.

This event is not available on legacy dashboards.

{ type: "dashboard:schedule_modal:open" }

Attribute Format Description
type String Using the type dashboard:schedule_modal:open indicates that you want to open the Schedule dialog box.

dashboard:stop

Use this action to stop a dashboard that is running or reloading data. This is the same action as clicking the Cancel button on the dashboard. A dashboard stopped using dashboard:stop sends a dashboard:run:complete event with status: set to “stopped”.

This action is not available on legacy dashboards.

{ type: "dashboard:stop" }

Attribute Format Description
type String Using the type dashboard:stop indicates that you want to stop the running dashboard.

look:run

Use this action to run the query on which the Look is based in the iframe. This is similar to hitting the Run button on the Look, with the exception that look:run always queries the database directly and does not retrieve data from the Looker cache.

{ type: "look:run" }

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

look:filters:update

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.department": "sweaters" } }

Attribute Format Description
type String Using the type look:filters:update indicates that 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", ...}

explore:run

Use this action to run the Explore in the iframe. This is similar to hitting the Run button on the Explore, with the exception that explore:run always queries the database directly and does not retrieve data from the Looker cache.

{ type: "explore:run" }

Attribute Format Description
type String Using the type explore:run indicates that you want to run the Explore.

explore:filters:update

Use this action to update or remove an existing Explore filter in the iframe. Including a new filter that references a valid field will add the new filter to the Explore.

{ type: "explore:filters:update", filters: { "orders.created_at": "90 days", "orders.status": "complete" } deleteFilters: ["products.department"] }

Attribute Format Description
type String Using the type explore:filters:update indicates that you want to update the filters used by the Explore.
filters Object The new filters you want to apply to the Explore. If filters includes a filter that does not currently exist in the Explore but that does reference a valid field, that filter will be added to the Explore. This object has the format: {"view_name.field_name_1": "value 1", "view_name.field_name_1": "value 2", ...}
deleteFilters Array The existing filters you want remove from the Explore. The array has the format: ["view_name.field_name_1", ”view_name.field_name_2”, ...]