About this codelab
1. Before you begin
You should have Looker content embedded inside an iframe with either private embedding or SSO embedding. In this codelab, we will interact with your iframe via JavaScript to make your webpage more dynamic. Your web page will send messages to and receive messages from the iframe's embedded Looker content.
Prerequisites
- Have a running Looker instance
- Have a Looker dashboard privately embedded or SSO embedded inside an iframe
- Understand the window.postMessage() method
What you'll learn
- How to prepare your iframe and Looker instance for JavaScript interaction
- How to listen to events from your iframe
- How to send action messages to your iframe
What you'll need
- Access to your frontend code's HTML and JavaScript that manages the iframe
- Access to the admin embed settings in your Looker instance
2. Preparations
You need to prepare your iframe and Looker instance before you can interact with the iframe.
Add an id
attribute to the iframe
You will need to validate the messages coming from the iframe. To do this, define an id
attribute on the iframe:
<iframe
id="looker"
src="https://instance_name.looker.com/embed/dashboards/1"
>
</iframe>
Add the embed's domain to the iframe's src
attribute
Determine the domain of the webpage hosting the iframe. Say the webpage's URL is https://mywebsite.com/with/embed
then the webpage's domain is https://mywebsite.com
.
If you're using Private Embedding, in the iframe's src, add the domain as an embed_domain
query parameter:
<iframe
id="looker"
src="https://instance_name.looker.com/embed/dashboards/1?embed_domain=https://mywebsite.com"
>
</iframe>
If you're using SSO Embedding, add the domain as an embed_domain
query parameter to the embed URL.
Allowlist the embed's domain in the Looker instance
Lastly, you need to allowlist the embed's domain in your Looker instance to allow message sending.
Navigate to the Embed page in your Looker instance's Admin section. https://your_instance.looker.com/admin/embed
In the Embedded Domain Allowlist field, enter the embed's domain. After typing it, hit the Tab key so that the domain appears in a box. Do not include a trailing slash /
.
Select the Update button.
3. Listen to event messages from the iframe
Your iframe with embedded Looker content sends messages to its host webpage. These event messages contain timely information about the embedded looker content, like if the embedded dashboard has started loading or the user has selected the Download option within the embedded content. Let's receive and parse these events.
Understand the event object schema
The event object's schema is:
{
type: "...",
eventSpecificProperty1: ...,
eventSpecificProperty2: ...,
...
}
The event will always have a type
property that lets you determine what event it is. All other event specific properties are defined in our events reference.
Receive and parse the event
Add this to where your webpage's JavaScript initialize or manages your iframe:
window.addEventListener("message", function(message) {
const iframeElement = document.getElementById("looker");
if (message.source === iframeElement.contentWindow) {
if (message.origin === "https://instance_name.looker.com") {
const event = JSON.parse(message.data);
switch (event.type):
case "dashboard:run:start":
console.log("The embedded dashboard has started loading");
}
}
});
The code snippet does the following:
- Listens for the
"message"
event from thewindow
object. - Checks the message's
source
property is the iframe with the embedded Looker content. - Checks the message's
origin
property is your Looker instance's domain. - JSON parses the message's
data
property to access and parse the event object. - Switches on the event object's
type
property to determine what event it is and act on it..
Now your host webpage can dynamically react to events your embedded Looker content emits!
4. Send action message to the iframe
Your host webpage can also send messages to your iframe's embedded Looker content. These action messages can change the state of your embedded Looker content, like updating the filters on your embedded dashboard. Let's create an action message that tells your embedded dashboard to run its queries and send the message to your iframe.
Create an action message
Create an action message inside your webpage's JavaScript:
const action = { type: "dashboard:run" };
const actionJSONFormatted = JSON.stringify(action);
The action
object follows the same format as the previous event
object. It will always have a type
property and then action specific properties which are defined in our action reference. The action message must be JSON formatted.
Send the action message
Inside your webpage's JavaScript send the JSON formatted action to your iframe:
const iframeElement = document.getElementById("looker");
iframeElement.contentWindow.postMessage(actionJSONFormatted, 'https://instance_name.looker.com');
- Determine your iframe that you will send your action to.
- Call the
postMessage()
method on the iframe'scontentWindow
property to send the message.
Now your host webpage can dynamically change the state of your embedded Looker content!
5. Additional information
Congratulations! You can now listen to events from and send actions to your iframe's embedded Looker content. Check out these resources for further information:
- Events reference for all available events and their properties
- Actions reference for all available actions and their properties
- Security best practices around embedding your Looker content