Responsive Design and Embedded Tableau Vizes – responsive_scaling_tableau.js

Web sites have to work on an incredibly wide variety of displays these days. The work to make a single page look as good as possible on all those displays often falls under the heading of “Responsive Design”.

When embedding a Tableau viz into another application, the actual “view area” for the Tableau viz is just one component of a page. In this situation, the view we pick from Tableau really needs to fill the most space of the area it has been allotted on the page. So let’s think a little more deeply about proportions and how we can best fit our embedded vizes given the tools available, and how to tie them all together to give the best possible experience to the end user, with the least effort for our Tableau viz designers.

Tableau recognizes the need for Responsive Design with a feature called Device Designer. It allows you to specify three different layouts, which are called in the system Desktop, Tablet, and Phone. These map well to the situations where you are looking at Tableau Server directly or in the Tableau phone app, and the Tableau viz is assumed to take the full width of the viewing area (and often most of the height). If different layouts exist, Tableau Server will automatically pick a layout based on the view space dimensions it detects.

However, when a Tableau viz is embedded into another page, it lives in a regular HTML div which can be styled using CSS3 and changed dynamically using JavaScript. Web designers regularly use these features to make page elements respond to changes in the viewing area (hence Responsive Design). Modern web browsers can actually scale up or down whatever is in a div without needing the content of the div to change.

Given all these capabilities, what is the best way to get our Tableau content to look its best in a page, regardless of the size or device it loads on?

Summary of Best Practices

  • Use Device Designer to specify several Dashboard layouts in different proportions
  • Use CSS / JavaScript to detect the proportions of the area allocated for the Tableau Viz, then manually control which Tableau Dashboard Device Layout is loaded
  • Use CSS3 transform-scale to maximize the fit of the chosen Device Layout to the available space on the page
  • Use break-point detection to reload the Tableau Viz using a different Device Layout once the available space would be better served by a Viz in different proportions

Now let’s dig into how to make all of this happen.


tableau_tools 6: Final Release

This post outlines a bittersweet event: the release of tableau_tools 6, which will also be the final release of the library by me, the original author of the library. My time at Tableau has come to an end, but ownership of this blog and all of the various code will remain with Tableau. As the project has always been open-source under a permissive license, this just means that there won’t be any updates from me, but the project can continue as long as it proves useful to someone.

As always, you can install or upgrade tableau_tools from PyPi.org via pip:

pip install tableau_tools --upgrade

Note: Version 6.0.0 does break some backward compatibility (see below) and you may need to do some slight updates to code that used a 5.0.0 release, or a lot if you are still using 4.0.0.

What is different in version 6?

  • Removal of the old style TableauRestApiConnection class. Only TableauServerRest remains. No functionality is lost but you may need to update old code
  • Added an “API Version Override” so you can set what API version is being used in the URLs. Also removed a lot of “option checks” so the library remains useful even as newer versions of Tableau are released
    • Older versions of tableau_tools had fairly strict checking on options to always match what was available in a given version of the Tableau Server REST API. Unfortunately this also meant the library could get far behind if it wasn’t updated, without the ability to override and force newer versions / options. So those limitations have been removed
  • CREATE and UPDATE Site method refactoring: At some point, the number of possible options for these endpoints made it difficult to cover all the possibilities within the arguments of the method. As part of the “allow future changes” design of version 6, only the site_name and site_content_url arguments will be defined in the method, and then it will accept a Dict for all other options. You will have to check the Tableau Server REST API documentation for valid options.
  • Methods that had all of their possible Filters listed out as arguments, have been reduced down to just take a list of UrlFilter objects, and all of the checking removed. More future proofing – maybe more options will be available you’ll want to take advantage of.
  • Documentation on the basic structure and methods in the README. If anyone wants to take over maintenance, or just needs to implement something newer from a more recent API release, the documentation of the simplest pieces of the library is now available for you to build with.

Thoughts on tableau_tools vs. Tableau Server Client and tableau-api-lib

It’s 2021 (thankfully!), and you are reading this, and probably thinking – why are there multiple libraries for working with the Tableau REST API. It’s a long story, but in essence much of tableau_tools and the content on this blog covering it was written before the Tableau Server Client (TSC) library either existed or was mature enough to cover certain use cases. There is also the tableau-api-lib which is a newer implementation along the original lines of what tableau_tools started out as, and it seems fine for getting work done, but doesn’t seem to have some of the abstraction layers of tableau_tools.

All of the libraries are fit for a wide number of purposes. tableau_tools is distinguished by having two main packages:

  • tableau_rest_api: Equivalent to TSC, used to send Tableau REST API commands
  • tableau_documents: Equivalent to the Tableau Document API , used for modifying the Tableau XML documents themselves

There was a time where tableau_rest_api referenced some of the tableau_documents capabilities, but there are no longer any supported versions of Tableau Server where those techniques were necessary, so either component can be used by itself.

Where is tableau_tools still a strong choice?

  • Dealing with Permissions on Tableau Server: There is a whole abstraction layer dealing with Published Content and Permissions, designed for replicating setups across many sites programmatically.
  • Login Impersonation: Necessary for exposing a restricted form of the Rest API as a web service to the browser. There is even a class designed to be used in Flask or Django just for this purpose
  • XML Document Modification: tableau_documents has more capabilities than the Document API, including updating TDSX / TWBX files with newly generated Hyper files from the Hyper API
  • Very complex searching using XPath queries on the XML results: Tableau Server REST API has a lot more filtering possible through the API than it started with, but there are still plenty of requests that need filtering on the result set, and tableau_tools has those requests built in
  • A learning tool / reference for the XML requests if you are building REST API calls in another language: The logging modes in tableau_tools can spit out the exact URL and XML of both requests and responses in a way that can be reasonably followed. Particularly for complex chains of actions, you can use tableau_tools as a prototype to double-check that your own code is doing the right thing.

If you have any of these needs in your project, then it is worth considering tableau_tools for at least some of the implementation. Otherwise, you should go with the TSC as it is more widely used, available, and supported within Tableau and the partner network.


Tableau Localization – Controlling the assigned contentUrl with non-ASCII (extended Latin or CJK) characters in content names

Even though Tableau Server stores the “full names” of published Workbooks, Datasources and Worksheets in Unicode exactly as published, the algorithm used to create the “contentUrl” used in the URL to reference the published content is based only on the ASCII English characters. The algorithm completely drops any non-ASCII character (and a few other non-URL safe characters). If any other existing contentUrl is found, an underscore and numeral is appended at the end.

In European languages with an expanded character set beyond the ASCII characters, the algorithm results in reduced but still distinctive contentUrls. For example (in Spanish):  “Años” -> “Aos”. The risk here, depending on language, is that there may be distinct content names that are reduced to the same contentUrl, resulting in the appending of the numeral to distinguish them like: “Aos” vs. “Aos_1”.

In Chinese, Korean and Japanese (and any other fully non-Latin character sets), the names are reduced to nothing, and then a random number is assigned: “销售运营分析仪表板”-> “_0” or “_1”.

Best Practices

  1. Always publish all Published Data Sources first to a Tableau Server, before publishing Workbooks
  2. Give unique name to all Content you publish, especially Data Sources. Tableau Server allows you to use the same name if Content is in different Projects on the same Site, but this will result in the contentUrls being given “_1” or “_923304292” type endings, with no way to control or change them other than through the names you choose at publish time
  3. If your content is named using non-Latin characters, add additional ASCII text to your names to ensure distinctive and controllable content URLs. This is especially important for Chinese, Japanese and Korean (CJK) text or other fully non-Latin scripts, but also might be necessary in Latin based scripts that frequently use diacritic marks on characters to distinguish (Vietnamese comes to mind)
    1. One solution for CJK languages: Add a transliteration (Pinyin, Hepburn, etc.) in parentheses after the name in the actual script. Alternatively add a unique numeric identifier after a Workbook or Data Source Name, and number your published Worksheets within a workbook.

Quick Explanation of Row Level Security in Tableau

There’s a great Whitepaper which really goes in depth on how to configure Tableau for Row Level Security, but sometimes it’s nice to have a quick overview that cuts right to the chase. Over a lot of years of explaining how it works, I hope this will outline the standard way of implementing RLS in Tableau in a way that helps you get results as quickly as possible.

Row Level Security is the process of securely filtering data down so a user only see what they should once they are looking at a data source. You could call it “User Data Filtering” just as easily. In essence, you are limiting the returned rows – hence “row level security”.


Forcing Tableau to Re-Query without using Refresh

This question was brought by my fantastisch colleague Timo Tautenhahn, who runs tableaufans.com. He was seeing some performance issues with using the Refresh commands in the JS and Extensions API, but not encountering the issues when changing a filter, which also was causing a new query to the database

In essence, whatever happens when the Refresh command fires off involves more steps than just re-querying. So the question is: what can force a re-query without the Refresh commands?

Solution: Add an Integer Tableau Parameter to a Custom SQL query that doesn’t actually affect the logic of the Query

You can have your own fun coming up with logical statements that are always true, but you don’t need anything more complex than:

SELECT * FROM table t WHERE [Tableau Parameter] = [Tableau Parameter]

As long as you change the value of the parameter to something you haven’t used yet within the session, each change should force a query refresh without using the Refresh action. Simply incrementing up from zero is enough to make it work.


New Method for Embedding Web Edit from Madhav Kannan

Madhav Kannan has been a superstar in Tableau’s APAC region for a few years now, but he’s really outdone himself with an improved technique for embedding the Web Edit functionality of Tableau Server smoothly into another web application, without requiring anything additional be added to the Tableau Server. I highly recommend you check out his blog post if you are looking to embed Web Edit!

Flexible Trellis Views in Tableau

Tableau does small multiples really well, but if you really only have one dimension, the only way to display things is in a straight list. With a couple of simple calculations, you can transform that list into a trellis, making 2 dimensions out of one!

Trellis Pies

If you look at the screenshot, you’ll notice that the Columns and Rows are both calculations, Table Calculations to be precise.  These are generic calculations that can be added to any workbook.

[Number of Columns] is an Integer type Parameter, necessary for the modulo and division calculations..

Column Calc

( INDEX() – 1 ) % [Number of Columns]

Row Calc

INT ( ( INDEX() – 1) / [Number of Columns] )

How do these calculations work? The Column Calc is using the Modulo operator (%), which only returns the remainder from division. The remainder will be the same for each multiple in a list — i.e. 3, 5, 7 all have 1 as a remainder when divided by 2. This allows for grouping in the columns.

The Row Calc is basically cutting the Index into as many slices as there are columns.

You set both of these calculations to be Discrete (blue pills) and they will create individual “slots” in a trellis.

In the screenshot, the “listing” element is Sub-Category. So the Compute Using option of both calculations should be set to Sub-Category. This makes the INDEX() function calculate down the Sub-Category field. This field must be on the Marks card somewhere — at minimum in the Detail. You can add in additional fields to make more interesting displays, like the pies. It’s also a great way to display multiple text elements without them being straight lists.

Deselect “Show Headers” and the trellis layout calcs disappear to the end user.

Trellis Text

Developing and Deploying Tableau Content

When you use Tableau in an embedded solution, the “Tableau method” of Desktop users publishing in a free-form method to the Tableau Server on a single site often doesn’t cover the requirements for controls and QA that a software development effort requires. While the classic “dev-test-qa-prod” is not as necessary with Tableau,  any SaaS customer that is embedding Tableau will need a process for deploying Tableau to their customer’s sites from templates.

In this post, I’ll go over the deployment methodology my team recommends to customers. We’ll be looking at the two separate phases, which are often split into different teams: (1) Development (2) Deployment.

Many thanks to Tyler Dugal who helped develop much of this content for our presentation at TC16.


Exporting Scrolling Worksheets in a Dashboard to PDF

Let’s say you have a Dashboard in Tableau, where at least one Worksheet is a list long enough to have a vertical scrollbar. If you export to PDF in Tableau Server, you will only get an single page, with an image of the scrollable sheet at the top of its scrolling. If you want to give your users the ability to get a PDF with ALL of the data included, you’ll need to set up your workbook in a particular fashion, based on the following rule:

Worksheets that scroll will export out as multiple pages, showing all of the data. Dashboards export out as a single page always.

With this in mind, you can build your Workbooks in the following way:

  1. Put your Dashboard tab first
  2. Put any sheets that scroll in a dashboard directly after the Dashboard tab
  3. Hide any sheets that do not scroll in a dashboard


The user needs to choose “Sheets in Workbook” to get both the Dashboard and the Sheets with all the details, but you can choose which sheets you want in the selector at the bottom.


Ad Hoc Tableau Server Reports with Default Formatting

Prior to Tableau 10, all formatting was done on a worksheet by worksheet basis. Tableau Desktop now has a concept of “workbook formatting” which become the default for any new worksheet. Each version of Tableau is bringing more formatting options into the scope of workbook formatting (for example, line formatting is being added in 10.2), but not everything is available yet.

Make a Template Worksheet and Dashboard

For any option available in workbook formatting, you should set it there (in the Format->Workbook menu at the top). For other things, like background shading, you should create both a template worksheet and a template workbook.

For the template worksheet, I suggest creating a Calculated Field with a simple message indicating that it is a template to be copied. Drag the field onto Text and change the fill type selector at the top from “Standard” to “Entire View” to make your message show up.  Use the Format->Worksheet menu to set everything you’d like.

Next make a template dashboard the same way, and drag out the Template Worksheet. In the end, it will look something like this:


Now publish it to Tableau Server. Rather than having users start their ad hoc analysis from a Data Source, have them start from the Ad Hoc Template Workbook. When they Save As to a new workbook, they can delete the templates sheet and dashboard because the new sheets will have that formatting which they can duplicate from.