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: