Friday, August 16, 2013

Dashboard Text Links - Adding and Customizing, no Worksheets Needed

One of Tableau's very nice but little known features is the ability to put hyperlinks in Dashboard text components simply by adding the URL so that they work just like a standard web hyperlink, e.g. As implemented the links work by opening the URL into the first Web Page component added to the Dashboard, or into a new browser window or tab if no Web Pages are present.

This is a terrific feature because it allows one to put links into Dashboards without involving the heavy machinery required to use data in worksheets coupled with URL actions. In those circumstances where a straightforward simple link is all that's needed using worksheets and actions has always been massive overkill.

While nice, and very much appreciated, the current text URL links leave some things to be desired, so I'm presenting here a way to customize them with two additional features:

  • providing alternate text for the link instead of the naked URL; and
  • explicitly have the link open a new browser window or tab for accessing the URL.

This Tableau Public Workbook shows the basics of adding Text hyperlinks to your Dashboards. As advertised, it's dead simple: you only need to enter the URL into your Text component and Tableau will recognize it. Pasting a copied URL is usually preferred to typing it it.

It also shows some examples of the normal Text links customized to have an alternate name, and to explicitly open the URL in a new browser window or tab whether or not the Dashboard contains a Web Page.

How to customize your links.
Now that you can enter text links, how do you customize them?

NOTE: this customization requires hacking your Workbook.
It's not available in Tableau, is unsupported by Tableau (at least I haven't asked them about it), and requires editing the Tableau Workbook directly. So if you choose to try it, make sure you are using a copy of the Workbook(s) you want to customize because you just might corrupt them and render them useless.

Option 1 – hand edit your Workbooks.

Don't do this.
It's a bad idea.
Chances are very good you will corrupt your Workbook and render it unusable.

But if you absolutely must give it a go, be careful and only work on a copy of your Workbook until you're completely sure that everything's OK.

The hand customization process is simple in principle:

  • open the Workbook in your favorite text editor (NOT Word or some other word processor, and please don't let me hear about your troubles with Notepad – I've been using Textpad for years and highly recommend it);
  • find the section in it with the text link you're interested in customizing; and
  • and customize away.

Adding a new label for the link is easy, it only takes providing the new label as if you were adding it to HTML, and I assume you're familiar with that, otherwise you might want to rethink hand editing. Adding the explicit directive to always open the link in a new browser window is a fair bit trickier, I highly recommend downloading the Tableau Public workbook and looking into it to see how it's done by comparing a link that will open in a Web page and one that always opens a new browser window.

Option 2 – use the Ruby script below.

Using the Ruby script has several advantages over hand editing:

  • it will not corrupt your Workbook–customized Workbooks are saved with the original name with ".CustomLinks" appended, i.e.:
    "abc.twb" -> "abc.CustomLinks.twb";
  • it will customize all the Workbooks in the current directory, making it easy to customize a bunch of text links all at once;
  • it's easy to configure to identify the specific URL to customize with the new label and whether or not to force a new browser window.

Using the Ruby script has several dependencies:

  • it's a Ruby script so your machine must be able to run Ruby, and you must have permissions to do so (sometimes not so easy in a corporate environment);
  • it uses some non-standard Ruby gems (libraries) so these need to be installed on your system – this is usually very straightforward and a quick Google will show the way;
  • you really should be comfortable with this level of technical stuff – if you're not there's likely someone nearby who can help, or you can always contact me.

# TTC_CustomizeTextLinks.rb # - this Ruby script Copyright 2013, Christopher Gerrard require 'nokogiri' require 'open-uri' require 'CSV' # These are the values used to configure the Text links # ----------------------------------------------------- $url = '' $title = 'A Link To Google (new window)' $newWindow = true def parseTWB twb puts " - #{twb}" doc = Nokogiri::XML(open(twb)) if handleURLs(doc) then writeTWB(doc, twb) end end $newWindowStr = 'target="_blank"' def handleURLs doc customized = false # locate the Text links docNodes = doc.xpath("//formatted-text/run[@hyperlink]") docNodes.each do |node| link = node.attribute('hyperlink') linkStr = link.to_s # if the Text link contains the URL to customize... if !linkStr.index($url).nil? node.content = $title if $newWindow && linkStr.index($newWindowStr).nil? link.content = linkStr + ' ' + $newWindowStr end customized = true end end return customized end def writeTWB(doc, twb) newTwb ="#{twb.sub(/.twb$/,'')}.CustomLinks.twb",'w') newTwb.puts(doc) newTwb.close end puts "\n checking for #{$url} in:" Dir.glob("*.twb") {|twb| parseTWB twb }

What TTC_CustomizeTextLinks.rb does.

Each of the Workbooks in the current directory is opened up and examined for the presence of the Texl links to be customized. If any are found they are customized appropriately and a copy of the Workbook is made with the customized links.

No Workbooks are harmed during the customizing of the links.

The name of the new copy Workbook is the same as the name of the original Workbook with the trailing ".twb" replaced with ".CustomLinks.twb"

For example, the Workbook "abc.twb" is copied, links customized, to "abc.CustomLinks.twb"

How to use TTC_CustomizeTextLinks.rb

  • Prerequisites
    • Minimal technical skills.
    • Have Ruby installed and ready to run.
    • Have the Nokogiri Ruby gem installed—it's used in the XML parsing.
    • Have the open-uri Ruby gem installed.
    • Have TTC_CustomizeTextLinks.rb in place—it doesn't matter where, or what name you use, as long as you know where it is.
      You can copy the code above and paste it into your favourite text editor.
  • Running TTC_CustomizeTextLinks.rb
    • Open a command prompt.
      (you can run it otherwise, but this is simple and straightforward)
    • CD to the directory containing the Workbooks you're interested in.
    • Run it: "[path to]\ruby    [path to]\TTC_CustomizeTextLinks.rb"
  • Presto. You now have a set of your Workbooks with all of their identified links customized.

The usual caveats.

TTC_CustomizeTextLinks.rb works fine with the limited testing it's been through, but it's definitely not bulletproof and hardened. It's only been run against Tableau v8 Workbooks, and it's entirely possible that other Tableau version Workbooks might not be properly edited, and it's possible that there are other conditions that might casue bad outcomes.

I hope it works for you, but make no guarantees. If you do use it and make improvements I hope that you'll post them back here as comments so I can learn from them, and hopefully other people can benefit from them too.


  1. Chris,

    The Desktop version works, which is very nice, but the Tableau Public version (for me) opens the links in the existing URL frame. I see this on Chrome, Firefox and IE.

    It seems like Tableau Public creates its own target when parsing the twb file. Below are a couple of screen shots.

    The first, from the first tab in your workbook shows identical targets (to the URL obj frame) for both of the Wikipedia links in the right box.

    The second from the tab without the web page object shows identical random targets (the target number changes each time I load the workbook). This one of course works fine.

    Also, and unrelated, the Google link doesn't open in Chrome or Firefox. IE gives the error:
    > To help protect the security of information
    > you enter into this website, the publisher
    > of this content does not allow it to be
    > displayed in a frame.


  2. The links that are supposed to open in a new browser window are also loading in the Web Page Object of the dashboard for me (as of 4/2/14, IE version 11)

  3. These workbooks are basically XML. So, can't we edit these through Python code? Should be very easy and would never corrupt the workboks.

    1. Since they're XML you can edit workbooks manually or through any programmatic means, including Python. The Ruby code above can be used as a model.

      I have to point out, however that thinking that it being easy isn't the same thing as "never corrupt the workbooks".
      The XML can be well formed, and so technically correct, but still corrupted semantically in such a way that Tableau won't recognize it, and refuse to open the workbook.

  4. Have any of you tried to combine tableau with the web scraping tool from ?

    1. I haven't had any experience with cloudscrape. Perhaps someone else has and will comment.

  5. without ruby script can we able to do in the tableau dashboard using text (target url of web new tab).

    1. You can enter the URL into a Dashboard Text object. Tableau will recognize it as a URL and show it as a link that will open a new browser window when clicked. While useful, there's a lot more that one could want from Tableau.