A Guide to Embedding Tableau # 1: A Primer on Embedding

This is a blog I’ve been wanting to write for quite a while, but I’ve admittedly been very hesitant to do so. Why? Because the fact is that embedding requires quite a bit of programming knowledge and, while I was a programmer many years ago, I’m just an amateur these days. I was afraid that, if I wrote a blog on this topic, the code I provided might be imperfect and, therefore, I might be promoting flawed approaches. On the other hand, over my years of working with Tableau, I’ve been able to embed my workbooks successfully on my own website and at work. And I’ve helped a lot of folks on the Tableau Community Forums to get their embedding to work as expected. So, while it’s not my expertise, I have found a few things that have worked so it makes sense to share that learning.


Additionally, I have found that most resources on embedding are very focused on programmers. One of the greatest assets of the Tableau community is that we come from so many different backgrounds—and, in my opinion, this is a wonderful thing as it creates a rich tapestry of different skills, viewpoints, and life experiences. But it also means that many Tableau users aren’t programmers so much of the existing content is difficult to comprehend. Thus, after a lot of thought, I’ve decided to write a guide on embedding Tableau that is focused, as much as possible, on non-programmers. Now, that does not mean there won’t be code. The fact is that embedding requires code—generally HTML, JavaScript, and sometimes, a little CSS. But I’ll try to provide the information in a way that is as easy to understand as possible. I’ll also provide some templates that are largely plug-and-play so that, even if you don’t fully understand the code, you’ll still be able to use it.


A warning to the programmers out there: Given that this is not my expertise, I fully acknowledge that my code may be imperfect and not always the best approach for every situation. You will likely look at my code and ask, “Why did he do that when there is a much easier or more efficient approach?” The simple answer will generally be that I just don’t know any better. So, if you see something that could be improved, please let me know and I’ll do my best to integrate your feedback into this blog and into the examples. Thank you!!


Unfortunately, this is going to be a ton of content—far too much to fit into a single blog—so I’m going to be sharing this information in chunks. This post will introduce you to the concept of embedding, define some important terms, discuss the primary methods we’ll be using, and discuss a few common scenarios. The second blog will build upon this foundation and dive into some specific examples.


What and Why

Before we get started, let’s talk briefly about embedding, what it is and why you might want to use it. Embedding is basically just the integration of some outside content into a website. You may not realize it, but you use this all the time. When you view a workbook on Tableau Server, Cloud, or Public, you are viewing content that is embedded into those web pages. But, when we talk about embedding Tableau content, we’re generally talking about embedding workbooks in our personal or company websites. By embedding content, we can bring this information to our users in an interactive way, without them having to go directly into Server, Cloud, or Public. And that content can be nicely integrated into those websites in a way that feels more natural than following a link.


I’ll give a couple of examples where I’ve used embedding—both in my personal projects and at work. First, I often embed Tableau visualizations directly into my personal blog. If I’ve created something I’d like to share with the world, then I’ll often write a blog and embed the visualization there. People will see it right away without the need to jump to another link. That tends to increase engagement and provides a more integrated feel. In my work, I've embedded content in several different ways. One employer had an internal portal our administrative leaders use to access a variety of campus resources, including some Tableau workbooks. Rather than forcing them to log into Tableau Server and navigate to the necessary workbooks, we just embedded them into the portal. That way, they can easily access all their important resources in one place. I've also embedded some content on our public website. A great example of this comes from my time at Bucknell University when we created a COVID testing dashboard. Bucknell created a comprehensive section on our website dedicated to our COVID protocols, our testing process, etc. and wanted to make sure we were openly sharing data about testing being done, positive results, active cases, and several other metrics. We designed the dashboard so that it would use similar fonts and colors as the rest of the website into which it was being embedded. The page itself contained various key information about our testing program, then shared the embedded dashboard. Because of the design, the dashboard simply felt like it was part of the page—not some separate component. And it was able to provide incredibly valuable information to our community.


Primary Methods of Embedding

There are two primary methods we use for embedding Tableau workbooks—iFrames and JavaScript. Let’s define each of these briefly.


An iFrame is an HTML element that that allows you to bring another (typically outside) element into your HTML web page. iFrames have become ubiquitous and you can embed almost anything using them—video, images, other websites, etc. Think of it almost like a container on a Tableau dashboard. You drop that container on the page, then you can determine what you put inside of it.


JavaScript is a lightweight programming language, loosely based on Java, originally developed in the mid 1990’s by Brendan Eich and Netscape in order to bring more dynamic content to the web. It has since become a core technology of the web. Because HTML remains the core upon which most of the web’s content is built, JavaScript is generally integrated into HTML code.


As noted, JavaScript is a programming language. But when we talk about embedding Tableau workbooks using JavaScript, we’re more specifically talking about leveraging Tableau’s JavaScript-based embedding API. To make things more complicated, Tableau regularly updates the API, just like all its other software, to add new features, improve performance, and correct bugs. The latest version of the API is version 3 and was released in November 2022. According to Geraldine Zanolli, Product Management Director, Embedded Analytics at Tableau, version 3 “isn’t just a new name: It’s the next evolution, re-engineered from the ground up to support modular development, add new functionality, and make development faster and easier. Embedding analytics into web applications puts end users that much closer to their data, business context, and customers.” In other words, it’s completely different than the previous version. Version 3 is available for versions of Tableau from 2021.4 forward. Version 2, however, is still actively used by many people and still works with newer versions of the software. In fact, as we’ll see in the next blog, Tableau products still provide version 2 code in many cases.


Common Scenarios

While there are an endless number of potential ways you might embed Tableau content into your websites and apps, we’re going to focus on simply displaying interactive workbooks on the web. There are three common scenarios I’ve personally encountered in my work:


1) Fixed-Sized – This is a dashboard that uses fixed sizing—essentially a static height and width. This is probably the most common (and most simple) type of embed.


2) Device Layouts – While fixed-size dashboards are extremely common, they aren’t always the best bet for embedded content since much of the world now consumes web content via mobile devices. Fortunately, through Tableau’s Device Designer, we can create what amounts to separate dashboards for different target platforms—each with its own unique height and width. This complicates embedding as we need to account for these changing dimensions.


3) Automatic or Ranged Sizing – Some dashboards are built with automatic or ranged sizing, which allows them to automatically resize to fit the page. In the best of cases, this means a single design could work on multiple device types. However, in practice, it is incredibly difficult to design a single dashboard in a way that will always be usable no matter the size. For that reason—as well as some known performance inconsistencies—I generally do not recommend this option. However, when this option is used, it allows us to leverage Responsive Web Design techniques—essentially automatically updating the content’s dimensions as the window size changes. So, we’ll want our embeds to also be as responsive as possible.


I’d like to make one important point about responsive web design as it applies to embedding Tableau. Most of the tutorials you’ll find on this topic focus on maintaining a constant aspect ratio—the proportional ratio between an object’s width and height—as that is simply how most web content is built. Consider, for example, a photograph. If it was taken with an aspect ratio of 3:2, then we don’t want to resize it to 2:10 because the window size changes. Instead, we want to shrink or expand the dimensions in a way that maintains the original aspect ratio.


However, this is a somewhat foreign concept in Tableau. When you use automatic or ranged sizing, you cannot instruct the dashboard to always maintain a specific aspect ratio—it will simply automatically resize to fit the window (accounting for limits set by ranged sizing, of course). While it might be possible to design a workbook that works best at a specific aspect ratio, it’s not generally something we consider. So, when I talk about responsive web design here, I’m going to be focusing on ensuring our embedded content shrinks and expands to fit the window. But, if desired, my code could be easily modified to enforce a specific aspect ratio. If you have a good use case for this, let me know as I’d love to hear more!


OK, so those are the most common scenarios. In the next blog, I’m going to show you how to address each of these using our three different embedding methods, iFrames, JavaScript v2, and JavaScript v3—a total of 9 examples.


Raw HTML vs a Web Platform

One final item I’d like to address in this post is the difference between embedding content in a raw HTML web page and using a platform. An HTML page is just a simple text-based script that creates all the elements needed to display a web page. You can create a simple HTML page in a text editor then open it from a browser. It doesn’t have to be deployed to the web and doesn’t have to be integrated into a larger website.


By “web platform”, I’m referring to something much larger—essentially a software product that helps you to build and maintain a website. These platforms often go by the term, “Content Management System” because they help ease the burden of managing the huge amounts of content needed for a website. WordPress is a common one that is used for everything from personal blogs to departmental sites to entire corporate websites, but there are many others that provide a range of functionality to meet your specific needs. This blog, for example, uses Blogger. Many corporate websites use Drupal. Joomla, Wix, Squarespace, and Shopify are other examples. While these platforms do ultimately produce a lot of HTML, you generally don’t have to write all that HTML yourself.


This is an important distinction because, when it comes to embedding content, we need to really think about how we’re building our web pages. In most cases, we’ll be embedding into a platform, so we can largely ignore all the extraneous HTML. However, I wanted to make sure that I had complete HTML examples of all my code, so I’ve uploaded these to Github and have also made them available for viewing & interaction on flerlageapps.com. But, when embedding into a platform, you do not want to use all the code—you’ll want to strip out the extraneous HTML. Let me share an example:


Lines 1-7 and lines 19-20 are the HTML that we won’t need when embedding in a platform—in those cases, we’d just use lines 8-18. As we review each example in detail, I’ll focus on just the embed code you need to use, while also sharing a link to the full HTML examples on Github. Also, to simplify this, I’ll be using codepen.io to show just the embed code and to display the results. I’ll share a “pen” for each example. If desired, you can then take that pen and use it to test your own embeds.


Up Next

OK, I think that’s a pretty good primer on the concept of embedding. In the next blog, we’ll dive deep into the examples/templates I’ve created so you can start applying them in your own work. Thanks for reading and be sure to come back soon for the next blog in this series!


Ken Flerlage, May 1, 2023

No comments:

Powered by Blogger.