DB Write-Back Part 1: The Minimal Extension & Manifest File

Let’s start by building the minimal extension – the least possible code that we can call a Tableau extension.

Glitch.com is a site that enables JavaScript development with automated hosting of web pages and JavaScript apps. By using glitch to host part1.html, we’ll avoid setting up a desktop environment for this first baby step. Unfortunately, because the Tableau Extensions JavaScript library has grown past a key file size threshold, and because there is no official CDN for the Tableau extensions library at this point, this is as far as we can go with glitch.

Here’s part1.html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>TabBlogs.com DB Write-Back Tableau Extension: How to Write the Code</title>
  </head>
  <body>
    <p>
      <b>Contratulations! </b>
      You've loaded your first extension!
    </p>
    <p>    </p>
    <p>The minimal extension is just a simple html page like this, but we are going well beyond this.</p>
    <p>This extension window is just a web browser using chromium version 61 (as of Tableau Desktop 2019.1).</p>
  </body>
</html> 

The Manifest

To instruct Tableau to open this extension, we will need a manifest file. This is a text file with a specific XML format and a “trex” filename extension. The required element details are:

  • For <dashboard-extension id=” “> use reverse domain name notation to uniquely identify the extension (com.example.extension.hello.demo)
  • For <source-location> make sure that this specifies the URL of your web application. You must use the HTTPS protocol. The exception to this requirement is localhost, where you can use HTTP. For example, if you created a HelloDemo folder and want to host the file locally on your computer using port 8765, you might use: http://localhost:8765/HelloDemo/HelloExtension.html
  • The <min-api-version> element that specifies the minimum version of the Extensions API library that is required to run the extension.
  • For <icon> you must use a Base64-encoded icon. To use the default icon, copy and paste the <icon> example here, or copy one of the manifest files (.trex) from the samples.
  • Provide the name for your extension (Hello Extensions!). The manifest file can be localized, so provide the name (or names) in the appropriate <text> elements in the <resources> section.

Given those details, create a directory in your local machine, and within that directory create an empty file called tabblogs_writeback.trex. Paste the following XML into that file. The file is also available at https://tabblogs-dbwriteback.glitch.me.

<?xml version="1.0" encoding="utf-8"?> 
<manifest manifest-version="0.1" xmlns="http://www.tableau.com/xml/extension_manifest">
  <dashboard-extension id="com.example.extensions.name" extension-version="0.1.0">
    <default-locale>en_US</default-locale>
    <name resource-id="name"/>
    <description>TabBlogs.com extension article series.</description>
    <author name="USERNAME" email="USER@example.com" organization="My Company" website="https://www.example.com"/>
    <min-api-version>1.0</min-api-version>
    <source-location>
      <url>https://tabblogs-dbext-part1.glitch.me/</url> 
    </source-location>
    <icon></icon>
    <permissions>
      <permission>full data</permission>
    </permissions>
  </dashboard-extension>
  <resources>
    <resource id="name">
      <text locale="en_US">name in English</text>
      <text locale="fr_BE">name in French</text>
      <text locale="de_DE">name in German</text>
    </resource>
  </resources>
</manifest>

Now to implement our first extension.

  1. Open Tableau desktop; open the superstore sample to the overview dashboard.
  2. Left click and drag the extension icon from the “Objects” area onto the dashboard. Notice that you can place it on any border between dashboard tiles, under, over or to the side of the whole dashboard, or in a floating tile.
  3. In the “choose an extension” dialog, choose “My Extensions”, navigate to your project directory and choose the tabblogs_writeback.trex file that you created above.
  4. The “Allow Extension” dialog is the only place where you have a chance to (or not to) grant execution permissions to an extension. Notice the four fields from the trex file that are shown here. Technically, our trex file doesn’t need the “permissions” tag, because we’re not accessing any of the APIs that require that tag… yet.
  5. If all has gone right, your extension will load, and you’ll see a simple html page within the extension tile:

Summary

The simplest possible extension is just a plain html web page. The manifest file containing the URL to that page is how Tableau knows what to load. In the next article we will look at the Tableau extension debugging environment and the API that we will use.

Author: Larry Clark

Larry has been a Tableau employee since October of 2018. Prior to Tableau, Larry was a BI consultant for Catapult Systems. Prior to Catapult, Larry was in DB/BI technical sales for Microsoft for >20 years.

Leave a Reply

Your email address will not be published. Required fields are marked *