# Tableau Dashboard Extensions

> Dashboard extensions only. Viz, workspace, and data app guides are out of scope.

Use this file for Dashboard Extensions. Do not apply Viz, Workspace, or Data Apps instructions.

## Dashboard Extensions


---

## Create a 'Hello World" Dashboard Extension

To create a Tableau extension you need the following components.

- A manifest file that identifies and describes the extension.
- The Tableau Extensions API JavaScript library (`tableau.extensions.N.N.N.js`)
- A web page that uses the library. The web page provides controls that interact with Tableau objects and data in the dashboard.
- Additional JavaScript and HTML and CSS files as needed for your web app.
- A web server to host your web app.

---

#### What you need to get started

These instructions assume that you already have cloned or downloaded the Extensions API SDK. For information about setting up your environment and the Tableau requirements, see [Installation](../installation.md) and [Get Started with Dashboard Extensions](trex_getstarted.md).

For convenience, you might want to create a folder for your "Hello World" dashboard extension in the same location where you installed or cloned the GitHub repository (for example, `HelloDemo` under `/extensions-api`). That way, you can use the same web server (`http-server`) that is used for the samples.

---

#### Create a manifest file

The manifest file (`EXTENSION-NAME.trex`) is an XML file that describes the extension and provides information to register the extension with Tableau. For a description of the contents of this file, see [Elements of the manifest file](./trex_manifest.md#elements-of-the-manifest-file).

1. In the `HelloDemo` folder (or where ever you want to put your files), create a manifest file for your extension.
Name the manifest file for your extension (for example, `HelloExtension`) and save it with the file name extension `.trex`.

2. Copy the following XML code into your new file. Make sure that the `<?xml ...>` declaration appears as the first element in the file (line 1, column 1). Any blank spaces in front of the declaration will cause an error when you load the extension.  

   ```xml
   <?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>Extension Description</description>
          <author name="USERNAME" email="USER@example.com" organization="MyCo" website="https://www.example.com"/>
          <min-api-version>1.0</min-api-version>
          <source-location>
            <url>SERVER:PORT/PATH</url>
          </source-location>
          <icon>
          iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEwAACxMBAJqcGAAAAlhJREFUOI2Nkt9vy1EYh5/3bbsvRSySCZbIxI+ZCKsN2TKtSFyIrV2WuRCJuBiJWxfuxCVXbvwFgiEtposgLFJElnbU1SxIZIIRJDKTrdu+53Uhra4mce7Oe57Pcz7JOULFisViwZ+29LAzOSjQYDgz1ZcCvWuXV11MJpN+OS/lm6179teqH0yDqxPTCyKSA8DcDsyOmOprnCaeP7459pdgy969i0LTC3IO/RQMyoHcQN+3cnljW3dNIFC47qDaK3g7BwdTkwBaBELT4ZPOUVWgKl4ZBnjxJPUlMDnTDrp0pmr6RHFeEjjcUUXPDGeSEwDN0Xg8sivxMhJNjGzbHd8PkM3eHRfkrBM5NkcQaY2vUnTlrDIA0NoaX+KLXFFlowr14tvVpqb2MICzmQcKqxvbumv+NAhZGCCIPwEw6QWXKYRL/VUXO0+rAUJiPwAk5MIlgVfwPjjHLCL1APmHN94ZdqeYN+NW/mn6I4BvwQYchcLnwFhJMDiYmlRxAzjpKWZkYkUCcZ2I61wi37tLbYyjiN0fHk5Oz3nGSLSzBbNHCF35R7f6K1/hN9PRhek11FrymfQQQKB4+Gl05P2qNRtmETlXW7e+b2z01dfycGNbfFMAbqNyKp9Jp4rzOT8RYFs0njJkc2iqsCObvTsOsDWWqA5C1uFy+Uz/oXJeKwVT4h0RmPUXhi79vuC0Ku6yOffTK3g9lfxfDQAisY516sg5kfOCiJk7HoLt2cf9b/9LANAc7dznm98PagG1fUOZ9IP5uMB8Q4CPoyNvausapkTt3rNMuvdf3C/o6+czhtdwmwAAAABJRU5ErkJggg==
          </icon>
        </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>
   ```

- In this file, you need to provide values for a few elements. Some key pieces 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.  

- After you have created the HTML and JavaScript files for your extension, you use this `.trex` file to add the extension to a Tableau dashboard. To do that, you drag the **Extension** object on to the dashboard. In the **Choose an Extension** dialog box, click **My Extensions** to locate and open the manifest file you just created.

- For information about the manifest file and about adding version information, see the [Tableau Extension Manifest](./trex_manifest.md).

---

#### Create your web app

The web app you create controls and interacts with the Tableau dashboard objects. The web app consists of one or more HTML files (one is the minimum). You host this web app on a web server (the server specified in the manifest file).

##### Create the HTML page

Your web application must include an HTML page. This page should link to the Extensions API JavaScript library and to any other JavaScript, CSS, or HTML resources your web app requires. You could add the JavaScript code to initialize and call Extensions API functions directly in the HTML page. However, in most cases you want to keep this code in a separate file. 

1. In the `HelloDemo` folder (or where ever you put your `.trex` file), create a file called `HelloExtension.html`.

2. You can copy and paste the following code into your file. This code creates a very simple page with a button that when clicked will initialize and use the API to get the name of the dashboard the extension is running in. This HTML code assumes that you are creating your extension in a folder (for example, `HelloDemo`) under the `/extensions-api` directory. 

   ```html
   <!DOCTYPE html>
    <html>
      <head>
        <meta charset="utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <title>Hello Extensions</title>`

        <!-- jQuery -->
        <script src="https://code.jquery.com/jquery-3.2.1.min.js"></script>

        <!-- Bootstrap -->
        <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" >
        <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js" ></script>

        <!-- Tableau Extensions API Library  -->
        <!-- library is in the /lib directory -->
        <script src="../../lib/tableau.extensions.1.latest.js"></script>

        <!-- Your JavaScript code that uses the Extensions API goes here -->
        <script src="./hello-extension.js"></script>
        </head>
        <body>
          <div class="container">
            <div>
              <h1>Hello Extensions!</h1>
              <p id="resultBox" class="lead">Not Initialized</p>
              <button id="initializeButton" class="btn btn-primary">Initialize Extensions API</button>
            </div>
          </div>
        </body>
    </html>
    ```

   The sample code includes a link to the JavaScript library (`tableau.extensions.1.latest.js`), which is available in the `/lib` folder. The sample code also includes links to jQuery and Bootstrap libraries. 

3. If necessary, adjust the relative path to the Extensions API JavaScript library (`tableau.extensions.1.latest.js`), which is available in the `/lib` folder.

   ```html

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

   ```

4. The sample code also includes a link to `hello-extension.js`, this is a JavaScript file that you will need to create. The path assumes that the JavaScript file is in the same directory as your HTML file. Adjust the path and name as necessary and save the file. 

   ```html

   <!-- Your JavaScript code that uses the Extensions API goes here -->
   <script src="./hello-extension.js"></script>

   ```

---

##### Start the web service to host the extension

1. Start the web service to verify you have the web app and files configured.
   The URL of the server must match the `SERVER` in the manifest file for the extension. Be sure to include the `http://` or `https://` in the URL. If you are using your `localhost` for development work, you might want to use the same lightweight web server that is used for the Extensions API samples and tutorial. Assuming that you've cloned or downloaded the repository, and that you've created a folder under `/extensions-api`, you can start the server by using the `npm start` command. Or if you need to use a different port and location, you can install and start the `http-server` yourself (replacing PORT with the port you need): 

   ```bash

      npm install http-server -g && http-server -p PORT

   ```

2. Check the HTML page to make sure that your web server is working. Place the URL in the address bar of your browser. This is the URL from the `<source-location>` you specified in the manifest file. Be sure to include the full path to the web page.  

   ```html

     http://localhost:8765/HelloDemo/HelloExtension.html

   ```

---

#### Test your extension in Tableau

After you have created the manifest file (`.trex`) and have hosted your web app you can test it in Tableau. It's a good idea to do this even if your application isn't completed.

1. Start up your web page or application (or make sure it is running).

2. Start Tableau and open a workbook with a dashboard, or create a new dashboard.

3. In the dashboard, under **Objects**, select **Extension** and drag it on to the dashboard. In the **Add an Extension** dialog box, click **Access Local Extensions** and browse to directory where you have your manifest file.

   After you select the manifest file, your web page should appear in the dashboard zone.

   - If not, and you see a 404 error, verify that you specified the correct URL to serve the page in the `.trex` file.

   - Tableau parses the `.trex` file when you add the extension to the dashboard. If you make changes to the `.trex` file after you have added it to the dashboard, you need to remove the extension and re-add it. See [What Happens When you Reload an Extension?](../debug/trex_reload.md)

---

#### Add code to initialize the extension and call Tableau Extensions API functions

The next step is to create the JavaScript that calls the Extensions API. In your JavaScript code (either in your HTML page or in a separate JavaScript file), you first need to initialize the extension. To do this, you call `tableau.extensions.initializeAsync()`. The function returns after the initial bootstrap operation is complete and the extension is available for use. The Extensions API follows the [CommonJS Promises/A standard](http://wiki.commonjs.org/wiki/Promises/A) for asynchronous method calls.

1. In the same directory as your HTML page, create a file called `hello-extension.js`.  The name just needs to match the name of the file that you specified in your HTML page 
(`<script src="./hello-extension.js"></script>`).

2. Copy the following example code and paste it into the file. 

   ```javascript
   $(document).ready(function() {

     // Hook up an event handler for the load button click.
     // Wait to initialize until the button is clicked.
     $("#initializeButton").click(function() {

       // Disable the button after it's been clicked
       $("#initializeButton").prop('disabled', true);

       tableau.extensions.initializeAsync().then(function() {

         // Initialization succeeded! Get the dashboard
         var dashboard = tableau.extensions.dashboardContent.dashboard;

         // Display the name of dashboard in the UI
         $("#resultBox").html("I'm running in a dashboard named <strong>" + dashboard.name + "</strong>");
       }, function(err) {

         // something went wrong in initialization
         $("#resultBox").html("Error while Initializing: " + err.toString());
       });
     });
   });

   ```

|**About the example code** The JavaScript example uses the jQuery document ready function to detect when the web page is loaded and ready. The code also uses an event handler to delay the initialization until the user clicks the `initializeButton`. When the page is ready and the user clicks the button, the initialization function (`initializeAsync`) instantiates a dashboard extension. To handle the promise, the `then` method calls two callback functions to handle successful initialization or failure. In case of success, the example gets the dashboard object from the extension, and then accesses the `name` property  to display the name of the dashboard sheet in the hosting web page. In case of an error, the error message is displayed.

---

#### Debugging and testing your extension in Tableau

After your extension is installed and showing up in Tableau, you can continue to work on your web application and see the changes without leaving Tableau.

1. Make changes to your HTML and JavaScript files and save those changes.

2. When you want to see those changes, select the extension in the dashboard.

3. In the shortcut menu, click **Reload** to refresh and reload the extension in the dashboard.

   ![alt text](../assets/extension_reload_menu.png "Shortcut menu showing the Reload option")

For information about debugging your extension, see [Debug Extensions in Tableau Desktop](../debug/trex_debugging.md) and [Debug Extensions in Tableau Server and Tableau Cloud](../debug/trex_debug_server.md).

You can also use the Tableau log files to identify issues, see [Use Log files to Troubleshoot Dashboard Extensions](../debug/trex_logging.md).

---

### What's next?

- For more information about how you can use the Extensions API to create dashboard extensions, go look at the [Samples](https://github.com/tableau/extensions-api/tree/master/Samples/Dashboard/) or follow the [Tutorial](https://github.com/tableau/extensions-api/tree/master/Tutorial/Dashboard) and learn how to build a dashboard extension, step by step.

- Get familiar with the programming interface of the Extensions API, see [API Reference](pathname:///api/).

---

## Dashboard Extension Samples

The best way to learn how to build your own extensions is to look at the sample code. To examine the sample source files to see how Tableau dashboard extensions work, you can clone or download the [Extensions API](https://github.com/tableau/extensions-api) SDK on GitHub and run the samples or the tutorial.

- To download the Extensions API SDK, if you have not already done so, see [Get Started](./trex_getstarted).

- You can browse the sample code for the dashboard extensions in the [Samples](https://github.com/tableau/extensions-api/tree/main/Samples/Dashboard?=target="_blank") and the [Tutorial](https://github.com/tableau/extensions-api/tree/main/Tutorial/Dashboard#Readme?=target="_blank") folders on GitHub.

- You can also create dashboard extensions using TypeScript. See the TypeScript dashboard sample code in [Samples-TypeScript](https://github.com/tableau/extensions-api/tree/main/Samples-Typescript/Dashboard?=target="_blank") on GitHub.

You can also check out the dashboard extensions from the community, see [Community Extensions](pathname:///community/).

---

The following instructions assume that you have already downloaded and extracted the files or have cloned the Extensions API SDK to your desktop.

#### About the dashboard extension samples

The dashboard extension samples are in the `Samples/Dashboard` folder. There is also a step-by-step tutorial you can follow in the `Tutorial` folder.

The [Samples-Typescript](https://github.com/tableau/extensions-api/tree/master/Samples-Typescript/Dashboard) folder shows how you can use the Extensions API type definitions to create extensions in TypeScript. For more information, see [Use TypeScript with the Extensions API](../core/trex_typescript).

-   **[DataSources](https://github.com/tableau/extensions-api/tree/master/Samples/Dashboard/DataSources?=target="_blank")** 

    Shows how to use the `getDataSourcesAsync` function to find the names of the data sources for each worksheet in the dashboard. Like the Filtering sample, the DataSources sample makes use the `Promise.all` function to combine the promises from the asynchronous calls together, and then waits for them to resolve. 

-   **[Filtering](https://github.com/tableau/extensions-api/tree/master/Samples/Dashboard/Filtering?=target="_blank")** 

     Demonstrates how to use the `getFiltersAsync` function to find and display the active filters in the dashboard and calls the `addEventListener` function to set a `FilterChanged` event on each workbook in the dashboard. Any time a filter value is changed, the extension refreshes the table that displays the active filters. 

-   **[Parameters](https://github.com/tableau/extensions-api/tree/master/Samples/Dashboard/Parameters?=target="_blank")**

    Finds and displays all the parameters in the dashboard and then sets an event listener that waits for a parameter to change, which triggers a refresh. 

-   **[PdfViewer (Typescript)](https://github.com/tableau/extensions-api/tree/master/Samples-Typescript/Dashboard/PdfViewer?=target="_blank")**

    Demonstrates how to use Extensions API features, such as settings, configuration, and parameters in a Typescript application. The sample allows PDF files to be viewed in a networked dashboard extension.

-   **[Settings](https://github.com/tableau/extensions-api/tree/master/Samples/Dashboard/Settings?=target="_blank")**

     Uses the `settings` namespace to save settings (key-value pairs) for the extension. Demonstrates how you can save settings for each instance of an extension, which enables sharing common views of a workbook.  

-   **[UINamespaces](https://github.com/tableau/extensions-api/tree/master/Samples/Dashboard/UINamespace?=target="_blank")**

     Demonstrates how you can use the `UI` namespace to create a modal dialog box (or popup) that runs another extension, which allows users to interact and change the settings for the parent extension. This sample controls the background auto-refresh interval for data sources in a dashboard. 

- **[Tutorial](https://github.com/tableau/extensions-api/tree/master/Tutorial/Dashboard?=target="_blank")**

     Walks you through the step-by-step process of creating and refining an extension that displays a summarized table of the currently selected marks.

- **[Samples-Typescript](https://github.com/tableau/extensions-api/tree/master/Samples-Typescript/Dashboard?=target="_blank")**

    The **Samples-Typescript** folder shows how you can use the Extensions API type definitions to create extensions in TypeScript. The sample extensions include TypeScript versions of many of the JavaScript samples. For more information, see [Use the TypeScript samples](#use-the-typescript-samples) and [Use TypeScript with the Extensions API](../core/trex_typescript).

- **[VizImage](https://github.com/tableau/extensions-api/tree/main/Samples/Dashboard/VizImage?=target="_blank")**

    Shows how you can use Tableau Viz to add visualizations to your dashboard extensions. This sample demonstrates the effects of different mark types and color palettes. For more information about Tableau Viz, see [Add Tableau Viz to Your Dashboard Extensions](../core/trex_tableau_viz).

- **[Formatting](https://github.com/tableau/extensions-api/tree/main/Samples/Dashboard/Formatting?=target="_blank")**

   Shows how you can access the CSS formatting in the Tableau workbook and apply it to the HTML elements in your dashboard extension. Create a consistent look and feel across the extension and the dashboard.

---
#### 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. These commands start the Node.js basic service `http-server`.

1. Go to the `extensions-api` folder.
1. To install the web server components, run the following command:

   ```cli
   npm install
   ```

1. To start the web server, run the following command:

   ```cli
   npm start
   ```

#### Instructions for starting a web server on a different port

The samples are set up so that the web server is using port `8765`.  If you need to specify a different port instead of `8765`, you can change ports using another Node.js or `http-server` command.  

From the `extensions-api` folder, you can start the `http-server` using one of the following commands. Replace `PORT` with the port you are using (for example, `8000`).

To install the `http-server`on your computer globally and to also start the server: 

```cli
npm install http-server -g && http-server -p PORT
```

If you have already installed `http-server`, you can start the server directly:

```cli
http-server -p PORT
```

The port you use for the web server also has to match the port specified in the manifest file (`.trex`) for the server.

```html
<source-location>
      <url>http://localhost:PORT/Samples/Dashboard/parameters/parameters.html</url>
</source-location>

```

---

#### Use the extensions in the samples folder

After you start the web server to host the sample extensions, you can try the extensions in Tableau.

1. Start Tableau and open a workbook that has a dashboard, or open a workbook and create a new dashboard.
2. In the dashboard, under **Objects**, select **Extension** and drag it on to the dashboard.  
3. In the **Choose an Extension** dialog box, click **My Extensions**. 
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\Dashboard`.
5. Select one of the folders for the samples and open the `.trex` file (for example, `DataSources.trex`).
Every Tableau extension has a manifest file (`.trex`) that describes the extension and identifies the location of the web application.

The extension should appear in the dashboard.  Play around with the extension. Examine the HTML and JavaScript source files to see how things work.  

---

### Use the TypeScript samples

The TypeScript samples show how you can write your source code in TypeScript and then use the Extensions API type definitions to compile (or transpile) the code into JavaScript. The samples use Node.js and webpack to build the extensions. These instructions assume that you have cloned or downloaded the Extensions API GitHub repository.

#### Build the samples

1. Go to the `extensions-api` folder.
1. Install the web server components:

   ```cli
   npm install
   ```

1. Build the TypeScript samples:

   ```cli
   npm run build
   ```

   Run lint with the semistandard package.

   ```cli
   npm run lint
   ```

1. Compile and start the HTTP server for the extensions. This command also watches the source file directories and automatically builds the samples when you make changes.

   ```cli
   npm run dev
   ```

#### Try the samples

1. Start Tableau and open a workbook that has a dashboard, or open a workbook and create a new dashboard.

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

1. In the **Choose an Extension** dialog box, click **My Extensions**.

1. Browse to the directory where the samples are located and add one of the extensions to the dashboard.

   For example, if you downloaded or cloned the GitHub repository, go to `\extensions-api\Samples-Typescript\Dashboard`. The folder contains the TypeScript versions of the Datasources, Filtering, and Parameters samples.

#### Build your own extensions using TypeScript

If you want to experiment with your own TypeScript code for extensions, you can use the same infrastructure that the TypeScript samples use. Create a folder in the **Samples-Typescript** directory and then add your extension source files. Add an entry to the `webpack.config.js` file for your extension TypeScript file. Update the path to your extension in the `.trex` file. Build and run your extension using the same commands you use to build the samples. For more information, see [Use TypeScript with the Extensions API](../core/trex_typescript.md).

---

## Get Started with Dashboard Extensions

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.

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](https://onlinehelp.tableau.com/current/pro/desktop/en-us/dashboard_extensions.htm). If you are looking for extensions that you can use, see the [Tableau Exchange](https://exchange.tableau.com/).

:::

----

:::info

**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 followed the instructions for [installation](../installation.md).

----

#### 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 directory would be `extensions-api-main`. If you cloned the repository, the directory would be `extensions-api`.

1. Navigate to the `extensions-api-main` or `extensions-api` directory.

2. To install the web server components, run the following npm command:

   **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](https://www.npmjs.com/package/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/Dashboard/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](https://tableau.github.io/extensions-api).

----

#### Start Tableau and add an extension to the dashboard

1. Start Tableau Desktop, or sign in to Tableau Cloud or Tableau Server, 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.

   :::note
   If you are using Tableau Cloud or Tableau Server to view the samples, you'll need to make sure that the extension is on the Allow list (safe list) for Tableau Server or Tableau Cloud. See [Add extensions to the safe list and configure user prompts](https://help.tableau.com/current/online/en-us/dashboard_extensions_server.htm#add-extensions-to-the-safe-list-and-configure-user-prompts) (Tableau Cloud) or [Add extensions to the safe list and configure user prompts](https://help.tableau.com/current/server/en-us/dashboard_extensions_server.htm#add-extensions-to-the-safe-list-and-configure-user-prompts) (Tableau Server). So you can use all the sample extensions, use the following URL and wildcard: `http://localhost:.*/Samples/.*`
   :::

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

   ![](../assets/frelard_objects_extension.png)

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\Dashboard\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.  

   ![](../assets/data_source.gif)

----

#### 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\Dashboard\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.

    ```html
    <!-- 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.

    ```javascript
    (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.

    ```xml
    <source-location>
      <url>http://localhost:8765/Samples/Dashboard/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.

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

----

### What's next?

* Start developing your extension by modifying an existing dashboard sample. See [samples (GitHub)](https://github.com/tableau/extensions-api/tree/master/Samples/Dashboard/). If you cloned or downloaded the repository, create a copy of the Samples directory. For example, if you make the copy in `\extensions-api\` directory, and call it `MySamples`, you just need to modify the URL in the `.trex` files so that you host the extensions using the same web server you created with `npm start` command.

* Follow the [Tutorial (GitHub)](https://github.com/tableau/extensions-api/tree/master/Tutorial/Dashboard) and learn how to build a dashboard extension, step by step. If you downloaded or cloned the repository, look in the `Tutorial` folder on your computer.

* For information about creating a simple "Hello World" Tableau extension, see [Create a "Hello World" Dashboard Extension](./trex_create.md).

* To get familiar with the programming interface for the Extensions API, see the [Tableau Extensions API Reference](pathname:///api).

* For information about debugging your extension, see [Debug Extensions in Tableau Desktop](../debug/trex_debugging.md) and [Debug Extensions in Tableau Server and Tableau Cloud](../debug/trex_debug_server.md).

---

## Tableau Extension Manifest File

The extension manifest file (`.trex`) contains metadata for the extension and is used for registration.

For details about a manifest or its fields, see the [Sample Manifest File](#sample-manifest-file) and [Elements of the Manifest File](#elements-of-the-manifest-file).  

### Tableau TREX Generator

To create a new manifest file (`.trex`) for your extension the easy way, use the [Tableau TREX Generator](https://trex-generator.glitch.me/) on [Glitch](https://glitch.com). The Tableau TREX Generator allows you to create the manifest file by filing in a form. You can also upload an existing `.trex` file and use that as a starting point. You can use the generator to edit and modify your `.trex` file as needed. When you are finished, just download the file to use with your extension.

### Manifest Versioning

The versioning of the manifest is designed to be semantically simple and support compatibility. The version follows the [Major].[Minor] format. Minor upgrades are backwards compatible while major upgrades involve breaking changes.

:::note

Each extension must be uniquely identified. If multiple extensions in a workbook share the same combination of URL, ID, and version number, the extension zones will not load properly. As a best practice, use unique identifiers for each viz or dashboard extension when creating the manifest file (.trex). For example, for dashboard extensions, make sure that the same `<dashboard-extension>` `id` and `extension-version`, and the `<source-location>` `url` aren't all used together in other extensions.

:::

### Error Reporting

At start up, Tableau checks the manifest file. If any errors are found while parsing the file, Tableau writes these errors to the `log.txt` file in the `My Tableau Repository/Logs` folder. This is the same location that Tableau Desktop uses to report other errors and activity.

### Sample Manifest File

```xml
        <?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>Extension Description</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>SCHEME://SERVER[:PORT][/PATH]</url> 
            </source-location>
            <icon>Base64-Encoded ICON</icon>
            <permissions>
              <permission>full data</permission>
            </permissions>
            <context-menu>
              <configure-context-menu-item />
            </context-menu>
          </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>
```

### Elements of the Manifest File

<colgroup>
<col width="30%" />
<col width="70%" />
</colgroup>

Name of element | Description

<code>manifest</code> | The root element that contains the manifest options.

<code>manifest-version</code> | The version of the manifest. The version currently supported is 0.1.

<code>dashboard-extension</code> | The root element that contains the options for the extension. The <code>dashboard-extension</code> includes the <code>id</code> attribute, which follows the reverse domain name pattern (<code>com.example.extension</code>), and <code>extension-version</code> number attribute. These attributes are required.

<code>extension-version</code> | The version of the extension. For example, <code>extension-version="0.1.0"</code>

<code>default-locale</code> | Specifies the default locale to use for localized text. Here both the locale format (en_US) and language code (en) are accepted. The default locale specified here is converted to one of the supported languages in the Tableau UI. If the language is unsupported or invalid, English is set as default.

<code>name</code> | The name of the extension as it appears under Extensions on a dashboard sheet. To provide localized text, specify the name of the resource-id and provide the text strings in the resources element of the manifest (see the manifest example). You can provide localized strings for name and description.

<code>description</code> | A short description of the extension.

<code>author</code> | Specifies metadata about the author of the extension, including <code>name</code>, <code>email</code> address, <code>organization</code>, and <code>website</code>. The <code>name</code> and <code>website</code> attributes are required. The <code>website</code> URL must use HTTPS. The <code>website</code> URL is the target of the Get Support link that users see in the About dialog box for your extension. The URL should take users to a page where they can learn about your extension and can get help on using it.

<code>source-location</code> | Contains the <code>url</code> of the server that hosts the web page you create that interacts with Tableau.

<code>url</code> | Specifies the scheme (HTTPS, HTTTP), the name of the server, the port (optional) and the path to extension (optional). The <code>url</code> must use HTTPS. For example: <code>https://example.com/extension</code>. 
The exception is for <code>localhost</code>. In this case, HTTP is allowed. For example: <code>http://localhost:8080</code>.

<code>icon</code> | If specified, the icon is what appears in the About dialog box. The icon must be a 70x70 pixel PNG file that is Base64 encoded. If you need an encoder, see https://www.base64-image.de/

<code>permissions</code> | Declares the types of permissions that this extension requires. The only option is <code>full data</code>. If your extension can access the underlying data or information about the data sources, you must declare full data permission in the manifest. Full data permissions are required if you use any one of the following APIs: <code>Worksheet.getUnderlyingDataAsync()</code>, <code>Datasource.getUnderlyingDataAsync()</code>, <code>Datasource.getActiveTablesAsync()</code>, <code>Datasource.getConnectionSummariesAsync()</code>. If your extension does not use one of these APIs, you do not need include permissions element.

<code>context-menu</code> | Adds a context menu item in the extension zone.  This is a configuration feature that allows you to register a custom JavaScript callback function and associate it with a context menu item. The only allowed element in <code>&lt;context-menu&gt;</code> is <code>&lt;configure-context-menu-item /&gt;</code>. The menu item and your configuration callback function are mapped together in the <code>initializeAsync()</code> function. When the extension is initialized, the menu item Configure... appears in the drop-down menu of the dashboard extension. When the user clicks the menu item, your callback function is executed.

<code>resources</code> | Specifies the resources that can be localized.

<code>min-api-version</code> | Specifies the minimum API version required to run the extension.

**Constraints** 

- String-based fields: 1000 characters 
- URI-based fields: 2084 characters
- Icon field: size of images are restricted to 70x70

---

## What is a Tableau Dashboard Extension?

Tableau dashboard extensions are web applications that have two-way communication with the dashboard. Dashboard extensions enable all sorts of scenarios, like letting you integrate Tableau with custom applications, making possible for you to modify the data for a viz, or even creating custom visualizations inside the dashboard. A dashboard extension is just one type of extension that can be built using the Tableau Extensions API.

---

### Components of a Tableau dashboard 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.

![](../assets/extensions_dashboard_diagram.png) 

### What can you do with a dashboard extension? 

Plenty! Using the Extensions API, you can create dashboard extensions that enable customers to integrate and interact with data from other applications directly in Tableau.

* Integrate with third-party APIs inside the dashboard.
* Use third-party charting libraries like `d3.js` to add custom visualizations.
* Create an extension that has write-back functionality, so users can modify data in a viz and have that change automatically update the source data in the database or web application.
* Build custom viz and interactivity types, such as a filter replacement with a custom interface and network diagram.

### Extensions API library

The Extensions API is a JavaScript library that you link to from your web application. The Extensions API library (`tableau.extensions.n.n.n.js`) gives your application access to Tableau dashboard content, including worksheets, filters, marks, and parameters. In your JavaScript code, you can set up event listeners to get notified when events occur on the dashboard. You can use the Extensions API to apply filters, or to get data back from selected marks in a worksheet. 

For more information about how you can use the Extensions API, go look at the dashboard [Samples](https://github.com/tableau/extensions-api/tree/master/Samples/Dashboard).

### Comparing the Tableau Extensions API and the Tableau Embedding API

The Dashboard Extensions API and the [Tableau Embedding API v3](https://help.tableau.com/current/api/embedding_api/en-us/index.html) are both JavaScript libraries that allow you to interact with Tableau, but they do so in two different fundamental ways:

* You can use the Embedding API for embedding Tableau dashboards in web pages (for example, blog posts), or in line of business applications.

* You can use the Extensions API for integrating web applications into zones in Tableau dashboards.

The Extensions API and Embedding JavaScript API share a similar programming model, but there are differences.

| Embedding API | Extensions API |
|------------| ---------------|
| Brings Tableau into other web applications | Brings other web applications into Tableau |
| Embeds Tableau views, Tableau Pulse into web pages and applications | Can be used in Desktop, Server, Online, or embedded dashboard |
| Custom-built for each embedded scenario | Can be made as a re-usable, generic-built dashboard component |
| Written in JavaScript | Written in JavaScript (similar calls) |