Get Started with Dashboard Extensions

Edit this page   Submit an issue

The Tableau Dashboard Extensions API allows developers to create extensions for Tableau. Tableau extensions are web applications that can interact and communicate with Tableau. A dashboard extension can be placed in the dashboard like any other dashboard object.

Note If you are looking for information about how to extend Tableau calculations to include popular data science programming languages and external tools, see the Tableau Analytics Extensions API.

This section will take you through the process of setting up your environment to use one of the sample dashboard extensions. Using one of the sample extensions is a great way to learn and great way to get started developing your own extensions. In this section, you will start a simple web server on your computer to host the sample. You can use the same process for hosting the extension when you start developing your own.

Note If you are looking for information about how to add an extension to a dashboard in Tableau, see Use Dashboard Extensions. If you are looking for extensions that you can use, see the Tableau Exchange.

In this section

What’s in a Tableau extension?
A Tableau extension consists of a manifest file (.trex), a web page that uses a Tableau-provided JavaScript library, and the JavaScript file (or files) that contain your extension logic. The Tableau extensions are supported on Tableau Desktop, Tableau Server, and Tableau Cloud.

What you need to get started

If you want to create an extension or work with the sample code, make sure you have the following dependencies installed:

You need Node.js and npm to run the dashboard extension demos. Node.js is a JavaScript runtime. npm is a package manager for Node.js and is installed when you install Node.js.

Requirements for using dashboard extensions in Tableau:

To run extensions on Tableau Server or Tableau Cloud, support for extensions must be enabled, and depending upon the extension and the data access it requires, the extension might need to be added to the safe list for the site. See Manage Dashboard Extensions on Tableau Server or Manage Dashboard Extensions on Tableau Cloud for more information.

Get the Tableau Extensions API SDK

You can get the Tableau Extensions API SDK in two ways. Clone the repository if you want to contribute to the open source project or keep current with the latest changes. Download the .zip file if you want to view the samples and work on your own.

Start a web server to host the sample dashboard extensions

To use the dashboard extension samples, you need to start up a web server on your computer to host the HTML pages. If you downloaded or cloned the Extensions API repository, you can start the web service in the root directory of the repository on your computer. For example, if you downloaded the extensions-api-main.zip file to your Downloads directory, after you extract the files, the path might be Downloads\extensions-api-main\extensions-api\.

  1. Navigate to the extensions-api directory.

  2. To install the web server components, run the following npm commands to install the package:

    npm install

    npm run build

  3. To start the web server, run the following npm command:

    npm start

    The start command runs a script to start the web server over port 8765. You only need to install the web server components the first time. Subsequently, you can just start the web server, using npm start. The start commands uses the npm http-server package, a simple HTTP server that uses Node.js for serving static files to the browser.

    Note: The web server just serves the extension samples, which have URLs similar to the following: http://localhost:8765/Samples/DataSources/datasources.html This local web server is not intended to serve the Extensions API Help pages. View the Help on GitHub at https://tableau.github.io/extensions-api.

Start Tableau and add an extension to the dashboard

  1. Start Tableau and open a workbook that has a dashboard, or open a workbook and create a new dashboard. For example, you could use one of the Tableau sample workbooks like Superstore to start with.

  2. In the dashboard, under Objects, select Extension and drag it on to the dashboard.

  3. In the Add an Extension dialog box, click Access Local Extensions. Every Tableau extension has a manifest file (.trex) that describes the extension and identifies the location of the web application.

  4. Browse to the directory where the samples are located. For example, if you downloaded or cloned the GitHub repository, go to \extensions-api\Samples\DataSources.

  5. Open the DataSources.trex file. The sample extension (web application) appears in the dashboard frame. The DataSources sample finds and displays the data source for each worksheet in the dashboard.

  6. In the DataSources extension, click the Info (i) button. This action opens a dialog box that displays more details about the selected data source.

Examine the source code for the extension

Looking at the files that make up an extension will give you an idea of how an extension is constructed.

  1. Browse to the directory where the DataSources sample is located. For example, if you downloaded or cloned the GitHub repository, go to \extensions-api\Samples\DataSources.

  2. Open the datasources.html file in your favorite Text or Code editor. This HTML page provides the interface that users see when they load the extension. This file includes links to the Extensions API library file and to the file that contains all the JavaScript code for the extension.

     <!-- Extensions Library  -->
 <script src="../../lib/tableau.extensions.1.latest.js"></script>

 <!-- Our extension's code -->
 <script src="./datasources.js"></script>

  3. Open the datasources.js file. This file contains code to initialize the Extensions API, and contains functions to gather all the data sources used by the workbooks in the dashboard. Read through the code and the code comments to get an understanding about how this extension works. The Extensions API makes use of JavaScript Promises to collect the data returned from the asynchronous function calls. Look for the code that initializes the extension. An extension will often place the initialization code in the JQuery $(document).ready() function so that it will run when the page is loaded.

     (function () {
   $(document).ready(function () {
     tableau.extensions.initializeAsync().then(function () {
     /* body of function  */
     /* controls what the extension does */
     /* extension calls other functions here */ 
     } function (err) {
     // Something went wrong in initialization.
        console.log('Error while Initializing: ' + err.toString());
     });
   });
 /*  extension can define other functions here as needed */
 })();

  4. Open the DataSources.trex file. This is the manifest file for the extension. This is the file that you selected to add the extension to the dashboard. This file defines certain properties for the extension, such as the name, and author, and the location (URL) of the extension.

     <source-location>
   <url>http://localhost:8765/Samples/DataSources/datasources.html</url>
 </source-loc>

    If you make a copy of the sample directory so that you can start to modify the code and experiment with the Extensions API, you just need to modify this path so that the URL reflects the new location.

     <source-location>
   <url>http://localhost:8765/_your-new-folder-here_/DataSources/datasources.html</url>
 </source-loc>

What’s next?