# Tableau Viz Extensions

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

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

## Viz Extensions


---

## Create a "Hello World" Viz Extension

To create a Tableau viz extension you need the following components.

- A manifest file that identifies and describes the viz extension.
- The Tableau Extensions API JavaScript library (`tableau.extensions.N.N.N.js`)
- A web page that hosts the viz and uses the library. The web page provides a viz specification that interacts with Tableau and data in the worksheet.
- 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 have already cloned or downloaded the Extensions API SDK. For information about setting up your environment and the Tableau requirements, see [Get Started](./trex_viz_getstarted.md).

For convenience, you might want to create a folder for your "Hello World" viz extension in the same location where you installed or cloned the GitHub repository. Create your folder, for example, **HelloVizExtension** in the Samples folder, under `/extensions-api/Samples`. 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 viz manifest file](./trex_viz_manifest.md#elements-of-the-viz-manifest-file).

1. In the HelloVizExtension folder, create a manifest file for your extension.
Name the manifest file for your extension (for example, `HelloVizExtension` and save it with the file name extension `.trex`).

1. 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">
  <worksheet-extension id="com.tableau.extension.demo.hello.viz" extension-version="0.1.0">
    <default-locale>en_US</default-locale>
    <name resource-id="name"/>
    <description>Hello Viz Extension</description>
    <author name="tableau" email="projectfrelard@tableau.com" organization="tableau" website="https://www.tableau.com"/>
    <min-api-version>1.1</min-api-version>
    <source-location>
      <url>http://localhost:8765/Samples/HelloVizExtension/HelloVizExtension.html</url>
    </source-location>
    <icon/>
    <encoding id="drop">
      <display-name>Drop...</display-name>
    </encoding>
  </worksheet-extension>
  <resources>
    <resource id="name">
      <text locale="en_US">Hello Viz Extension</text>
    </resource>
  </resources>
</manifest>

``````

- In this file, you need to provide values for a few elements. Some key pieces are:
- For `<worksheet-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 `HelloVizDemo` folder and want to host the file locally on your computer using port 8765, you might use: `http://localhost:8765/Samples/HelloVizDemo/HelloVizExtension.html`
- The `<min-api-version>` element that specifies the minimum version of the Extensions API library that is required to run the extension.
- The `<icon>` element currently isn't implemented for viz extensions. This metadata is used to provide branding for the extension, as would be shown in an About dialog box.
- Provide the `name` for your extension (`Hello Viz 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 worksheet. To do that, open a worksheet, on the **Marks** card, expand the Mark Type drop-down menu. Under Viz Extensions, select **Add Extensions**. In the **Add an Extension** dialog box that appears, select **Access Local Extensions**. Browse to the location where you put the manifest file you just created, for example, the `HelloVizExtension` folder and select the `HelloVizExtensions.trex` file.

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

---

#### Create your web app

The web app you create provides the code to create the visualization interacts with the Tableau worksheet to get data and the encoding. The web app consists of an HTML file and the supporting JavaScript code that initializes and accesses the worksheet using the Extensions API. You host this web app on a web server (the server specified in the manifest file). In this case, we are using a web server running on your local computer.

##### 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 `HelloVizExtensions` folder (or wherever you put your `.trex` file), create a file called `HelloVizExtension.html`.

1. You can copy and paste the following code into your file. This code creates a very simple page that displays a single line of text. This HTML code assumes that you copied or cloned the `extensions-api` repository and are creating your extension in a HelloVizExtension folder, under Samples.

  ```html
   <!DOCTYPE html>
   <html>
     <head>
      <title>Hello Viz Extensions</title>

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

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

     <body>
      <div style="width: 100%; height: 100%; position: fixed" id="content">
         <p>Drag a field on to the tile labeled <b>Drop</b> on the Marks card.</p>
      </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.

1. 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>

   ```

1. The sample code also includes a link to `HelloVizExtension.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="./HelloVizExtension.js"></script>

   ```

###### Location, Location, Location

For this exercise, it makes your life easier if you place your own extensions in the Samples folder.
Keeping your own extensions in the Samples folder has two advantages.

* You can host the extensions using the same web server you started with `npm start` command.

* If you've already configured your Tableau Cloud or Tableau Server site to allow all extensions under the path `http://localhost:8765/Samples`, you don't need to specifically add each extension. 

  For example, if you add the following URL and wildcard to the allow list: `http://localhost:.*/Samples/.*`, the URL allows all extensions (on any port) under the Samples folder. Because the extension is running on your local computer (`http://localhost`) and uses the URL that is allowed on the site, you're good to go. In general, when you’re creating your own viz extensions, you must ensure that the extension URL has been added to the allow list. For more information, 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).

---

##### 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 and that matches the port you specified in the manifest file):

   ```bash

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

   ```

1. 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. Make sure the PORT in your URL matches the PORT you specified in the command to start the http-server. Be sure to include the full path to the web page.  

   ```html

     http://localhost:8765/Samples/HelloVizExtension/HelloVizExtension.html

   ```

1. If your web page appears, great. Close the browser window and test the extension in Tableau. If it doesn't, verify that you specified the correct URL. The URL path and port number should match what you specify in your `.trex` file. Verify that the local web server is using the correct port. In the Terminal or Console window where you started the web server, check for any error messages. And try again.

---

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

:::note
If you are using Tableau Cloud or Tableau Server, you need to make sure you've added the URL of your extension to the allow list. See this [note about location](#location-location-location).
:::

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

1. Start Tableau Desktop, or log on to Tableau Cloud or Tableau Server and open a workbook, for example, Superstore. Click **Edit** and create a new worksheet (from the Worksheet menu, select **New Worksheet**), or open a new workbook in your Personal Space and connect to the **Superstore Datasource**.

1. On the **Marks** card, expand the Mark Type drop-down menu. Under Viz Extensions, select **Add Extensions**.

1. In the **Add an Extension** dialog box that appears, select **Access Local Extensions**. Browse to the location where you put the manifest file you just created, `HelloVizExtension`.  Select the `HelloVizExtension.trex` file.

   After you select the manifest file, your web page should appear in the worksheet zone, as a blank page.

   - 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 worksheet. If you make changes to the `.trex` file after you have added it to the worksheet, you need to remove the extension from the worksheet and then add it back again.

1. From the Data pane, drag a field onto to the **Drop** encoding tile on the Marks card.

1. The message "Drag a field on to the tile labeled Drop on the Marks card." should appear. Close the worksheet without publishing (from the File menu, select **Close**).

---

#### 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 `HelloVizExtension.js`.  The name just needs to match the name of the file that you specified in your HTML page 
(`<script src="./HelloVizExtension.js"></script>`).

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

```javascript

'use strict';

// Wrap everything in an anonymous function to avoid polluting the global namespace
(function () {
  window.onload = tableau.extensions.initializeAsync().then(() => {
    // Get the worksheet that the Viz Extension is running in
    const worksheet = tableau.extensions.worksheetContent.worksheet;
    console.log(worksheet);

    console.log(`The name of the worksheet is ${worksheet.name}`);

    // Listen to event for when the summary data backing the worksheet has changed.
    // This tells us that we should refresh the data and encoding map.
    worksheet.addEventListener(
      tableau.TableauEventType.SummaryDataChanged,
      updateDataAndRender
    );
  }, function (err) {
    // Something went wrong in initialization.
    console.log('Error while Initializing: ' + err.toString());
  });

  // Uses getVisualSpecificationAsync to build a map of encoding identifiers (specified in the .trex file)
  // to fields that the user has placed on the encoding's shelf.
  // Only encodings that have fields dropped on them will be part of the encodingMap.
  async function getFieldsOnEncoding (worksheet) {
    const visualSpec = await worksheet.getVisualSpecificationAsync();
    const marksCard =
      visualSpec.marksSpecifications[visualSpec.activeMarksSpecificationIndex];
    const encodings = [];
    for (const encoding of marksCard.encodings) {
      if (encoding.id === 'drop') {
        encodings.push(encoding.field.name);
      }
    }

    return encodings;
  }

  async function updateDataAndRender () {
    const fields = await getFieldsOnEncoding(tableau.extensions.worksheetContent.worksheet);

    // Clear the content region before we render
    const content = document.getElementById('content');
    content.innerHTML = '';

    const msg = JSON.stringify(fields);

    // Display the array of fields mapped to the encoding ("drop")
    content.innerHTML = msg;


    // To do: 
    // Add encodings to Marks card (for example, x, y, and r coordinates)
    // Call worksheet.getSummaryDataReaderAsync() to get worksheet data
    // Combine the worksheet data with the encodings (x, y, r)
    // Pass the coordinates and data to code that generates visualization
    // See the connectedScatterplot sample for an example
  }
 })();


```

#### Try it out in Tableau

1. Sign into Tableau and open the Superstore workbook, click edit and open an new worksheet. Alternatively, open a new workbook in your Personal Space and connect to a data source.

1. In a worksheet, on the Marks card, expand the Mark Type drop-down menu.

1. Under Viz Extensions, select **Add Extension**.

1. In the Add an Extension dialog box that appears, select **Access Local Extensions**.

1. Browse to the directory where your extension is located. For example, if you downloaded or cloned the GitHub repository, go to `\extensions-api\Samples\HelloVizExtension` and select the `HelloVizExtension.trex` file.

1. Drag some fields on to the **Drop** tile on the Marks card. The name of the fields that you've added to the Marks card are displayed in the worksheet. Every time you add or remove a field, the names are updated.

#### About the example code

This example illustrates some of the components that are common need to include in your viz extension.

1. Initialize the Extensions API

   When the HTML page is added to the worksheet, the `window.onload` event calls the code to initialize the Extensions API (`initializeAsync`). During the viz extension initialization, the code uses the `worksheetContent` object to access the current `worksheet`. The `worksheet` object is used in subsequent calls. If the initialization fails for some reason, for example, you are using the older version of the library that does not support viz extensions (`<worksheet-extension>`), the error is written to console log.

2. Add an event listener to catch changes in the worksheet

   In the initialization code, the code adds an event listener for the `tableau.TableauEventType.SummaryDataChanged` event and specifies an event handler called `updateDataAndRender`.  Whenever the backing data for the worksheet changes, the event handler is called to redraw the viz. For example, whenever you drop a field onto the encoding tile on the Marks card the worksheet data changes. 

3. Create the event handler to fetch the data and the encodings and render the viz

   This is the code that draws the viz based on the current encodings and data. This example is extremely simplified and just uses the method called to retrieve the encoding, `worksheet.getVisualSpecificationAsync()`. From the `visualSpec`, the list of encodings is collected from the Marks card. The HelloVizExtensions example just has one encoding tile labeled "Drop..." The list of fields that are dropped on the tile are displayed in the content area of the worksheet. In real life, you would use multiple encodings that would correspond to the coordinates in your visualization (for example, x, y, and r). 

   The other missing piece from this code example is the data. To retrieve the data from the worksheet, you call the `worksheet.getSummaryDataReaderAsync()` method. This method returns a `DataTableReader`, which you use to page through the summary data in the worksheet, to extract the rows of data. See the ConnectedScatterplot viz extension sample to see an example of how this is done. 

  Finally, after you have the data and the map of encodings to fields you can pass this to code that can generate a scatterplot, a Sankey diagram, or network visualization. This example just prints the fields to the content area of the worksheet. But it's a start.

---

#### Debugging and testing your extension in Tableau

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

#### Code Style

Our sample code follows the [Semi-Standard Style](https://github.com/Flet/semistandard) for JavaScript samples linting. If you create your own extension code, you can run `npm run lint` to validate the style of your code.

`npx semistandard --fix` to fix linting issues, which can be fixed automatically.

---

### What's next?

- For more information about how you can use the Extensions API, go look at the [Samples](https://github.com/tableau/extensions-api/tree/main/Samples/). Study the sample, ConnectedScatterPlot, to see a full implementation of a viz extension.

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

- If you use the local web server in the Extensions API SDK to host your own viz extensions, you can take advantage of the [d3](https://d3js.org/) libraries that are installed locally. When you run the **npm run build** command in the root directory of the repo, the d3 libraries are installed the `node_modules` directory. To use the libraries, add the path to your HTML file. For example, the `ConnectedScatterplot` and `Sankey` samples are in the Samples directory and include the following relative path to the d3 library:  

  ```html

  <script src="../../node_modules/d3/dist/d3.min.js"></script>

  ```

---

## Viz 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 viz extensions work, you can clone or download the [Extensions API](https://github.com/tableau/extensions-api) SDK on GitHub and run the samples.

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

- You can browse the sample code for the extensions in the [Samples](https://github.com/tableau/extensions-api/tree/master/Samples?=target="_blank") folder on GitHub.

---

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 viz extension samples

The viz extension samples are in the `Samples\Viz` folder.

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

    Shows how to create a viz extension. 

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

    Shows how to use the `getDataSourcesAsync` function to find the names of the data sources for the worksheet. 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/main/Samples/Viz/Filtering?=target="_blank")** 

     Demonstrates how to use the `getFiltersAsync` function to find and display the active filters in the worksheet and calls the `addEventListener` function to set a `FilterChanged` event on the worksheet. 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/main/Samples/Viz/Parameters?=target="_blank")**

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

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

    Sankey diagrams or charts - named after their creator, Matthew Henry Phines Riall Sankey, who first used this chart type in 1898. Somewhat similar to the Sankey viz type  Tableau had offered in the recent Sankey and Radial new chart types pilot (June 2023).

-   **[Settings](https://github.com/tableau/extensions-api/tree/main/Samples/Viz/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/main/Samples/Viz/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 worksheet. 

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

    Shows how you can use Tableau Viz to add visualizations to your 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 Extensions](../core/trex_tableau_viz.md).

---
#### Start a web server to host the sample viz extensions

To use the viz 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/Viz/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. Sign in to Tableau, open an existing workbook, click Edit and open a new worksheet. Or open a new workbook in your Personal Space.

1. In a worksheet, on the Marks card, expand the Mark Type drop-down menu.

1. Under Viz Extensions, select **Add Extension**.

1. In the Add an Extension dialog box that appears, select **Access Local Extensions**.

1. Browse to the directory where the samples are located. For example, if you downloaded or cloned the GitHub repository, go to `\extensions-api\Samples\Viz`.
1. 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 worksheet.  Play around with the extension. Examine the HTML and JavaScript source files to see how things work.

---

## Get Started with Viz Extensions

The Tableau Viz Extensions API allows developers to create new viz types that Tableau users can access through the worksheet Marks card. Like Dashboard Extensions, Viz Extensions are web applications that can interact and communicate with Tableau. Developers will be able to build bespoke Viz Extensions that can be made available to Tableau users through the Tableau Extensions API.

This section will take you through the process of setting up your environment to use one of the sample viz 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 use viz extensions in Tableau, see [Add Viz Extensions to Your Worksheet](https://help.tableau.com/v0.0/pro/desktop/en-us/viz_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 an XML manifest file (`.trex`), a web page (`.html`) that uses a Tableau-provided JavaScript library, and the JavaScript file (`.js`) (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 viz extensions

To use the viz 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 to install and build the package:

   **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.

4. To verify that the web server is up and running, open a browser window and add the following URL to the menu bar:

    `http://localhost:8765/assets/flex.png`

   If your local web server is working, you should see Flex, the T-Rex. If not, check the Command or Terminal window where you started the web server and check for error messages. You should see the output of HTTP activity. If not, try running the npm commands again. Don't close this Command or Terminal window while you are running the web server.

   :::note

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

   :::

----

#### Sign in to Tableau and add a viz extension to the worksheet

1. Start Tableau Desktop or sign in to Tableau Cloud or Tableau Server and open the Superstore workbook. Alternatively, open a new workbook in your Personal Space and connect to the **Superstore Datasource**.

   :::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/.*`
   :::

1. In a worksheet, on the Marks card, expand the Mark Type drop-down menu.

1. Under Viz Extensions, select **Add Extension**.

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

1. In the Add an Extension dialog box that appears, select **Access Local Extensions**.

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

    Every Tableau extension has a manifest file (.trex) that describes the extension and identifies the location of the web application. For more information on creating a `.trex` manifest file, see [Tableau Viz Extension Manifest File](./trex_viz_manifest.md).

1. Navigate to the directory where the connectedScatterplot manifest file (`.trex`) is located
`\extensions-api\Samples\Viz\ConnectedScatterplot`.

1. Open the `connectedScatterplot.trex` file. If prompted, click OK to allow the Viz Extension to run in the workbook. The extension is a network-enabled extension, which means it has access to resources outside of Tableau and it is not hosted on the Tableau Sandbox.

When the extension loads, the worksheet is blank, but the Marks card will show the name of the viz extension and any custom encoding tiles the extension uses.

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

#### Configure the connectedScatterplot viz extension

The connectedScatterplot extension is based on one that has been showcased in the d3 gallery and developed by Observable.
Some slight modifications have been made to make it able to be used with WorkbookFormatting. For more information, see [https://observablehq.com/@d3/connected-scatterplot](https://observablehq.com/@d3/connected-scatterplot).

1. In the worksheet, drag the Profit field onto the **X** encoding box.

1. Drag the Sales field onto the **Y** encoding box.

1. Drag the Order Date field onto the **Text** encoding box.

1. Right click the blue pill, which now says YEAR(Order Date) and change to **Month**.

   The connected scatterplot appears in the view.

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

----

### What's next?

* Start developing your extension by modifying an existing viz extension sample. See [samples (GitHub)](https://github.com/tableau/extensions-api/tree/main/Samples/Viz/). If you cloned or downloaded the repository, create a copy of one of the existing samples in the Samples directory and start with that. For example, if you make the copy of the ConnectedScatterplot directory, rename the copy and place it in the Samples directory. You will need to change the URL in the `.trex` file so that the source location URL shows the new path.

   Keeping your own extensions in the Samples folder has two advantages. The first is that you can host the extensions using the same web server you started with `npm start` command. The second advantage is that you won't need to add your extension to the allow list (or safe list) if you configured your Tableau Cloud or Tableau Server site so that all extensions under the path `http://localhost:8765/Samples`. For example, if you added this URL and wildcard to the safe list: `http://localhost:.*/Samples/.*`, the URL allows all extensions (on any port) under the Samples folder.  Because the extension is running on your local computer (`http://localhost`) and uses the URL that is allowed on the site, you are good to go. In general, when you are creating your own viz extensions, you will need to ensure that that the extension URL has been added to the safe list. For more information, 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).

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

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

---

## Tableau Viz Extension Manifest File

The viz extension manifest file (`.trex`) contains metadata for the extension and is used for registration. The manifest file for viz extensions is similar to the file used for dashboard extensions in structure, but instead of the `dashboard-extension` element, you define a `worksheet-extension` element. The manifest files are not interchangeable.

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

---

### 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 viz extensions, make sure that the same `<worksheet-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 Viz Manifest File

```xml
<?xml version="1.0" encoding="utf-8"?>
<manifest manifest-version="0.1" xmlns="http://www.tableau.com/xml/extension_manifest">
  <worksheet-extension id="com.example.extensions.name" extension-version="0.1.0">
    <default-locale>en_US</default-locale>
    <name resource-id="name"/>
    <description>Viz extension description</description>
    <author name="USERNAME" email="USER@example.com" organization="MyCo" website="https://www.example.com"/>
    <min-api-version>1.1</min-api-version>
    <source-location>
      <url>SCHEME:SERVER:PORT/PATH</url>
    </source-location>
    <icon>Base64-Encoded ICON</icon>
    <permissions>
      <permission>full data</permission>
    </permissions>
    <encoding id="Encoding-id">
      <display-name resource-id="encoding-name">Encoding display name</display-name>
      <data-spec>
        <data-type>Encoding-type</data-type>
      </data-spec>
      <role-spec>
        <role-type>Encoding-role</role-type>
      </role-spec>
      <fields max-count="n"/>
      <encoding-icon token="letter-m" />
      <tooltip resource-id="tooltip-id">Default tooltip text for encoding</tooltip>
    </encoding>
  </worksheet-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>
    <resource id="encoding-name">
      <text locale="en_US">EnglishEncoding</text>
      <text locale="fr_BE">FrenchEncoding</text>
      <text locale="de_DE">GermanEncoding</text>
    </resource>
    <resource id="tooltip-id">
      <text locale="fr_BE">French tooltip text</text>
    </resource>
  </resources>
</manifest>

``````

### Elements of the Viz 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. Leave this as version 0.1.

<code>worksheet-extension</code> | The root element that contains the options for the viz extension. The <code>worksheet-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 your 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 on the Marks card under Viz Extensions. 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> .

<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> | Not currently used. The icon is 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>Worksheet.getUnderlyingTablesAsync()</code>, <code>Worksheet.getUnderlyingTableDataAsync()</code>, <code>Worksheet.getUnderlyingTableDataReaderAsync()</code>, <code>Datasource.getLogicalTables()</code>, <code>Datasource.getLogicalTableData()</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. For more information, see Accessing Underlying Data.

<code>encoding</code> | Adds tiles to the Marks card for encoding. This is an optional element. By default, the Detail and Tooltip tiles appear on the Marks card. You can use the encoding element to add additional tiles for the fields you want to encode. See the Encoding section for more information.

<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

----

### Add encoding in the viz manifest

By default, the viz extension has access to the Detail and Tooltip tiles on the Marks card. You can specify additional encoding tiles for the fields you use in your viz extension by adding `<encoding>` elements. Adding encoding elements is optional.

To add custom encoding, you provide definitions for the encoding in the manifest file. For example, the following XML code defines three encoding tiles: an X and Y encoding for continuous numeric measures, and a text encoding for string values. The value of attribute named `id` inside the `<encoding>` element can be used to map to a variable in your JavaScript code. That code then generates the visualization based upon your data.

```xml

<encoding id="x">
  <display-name>X</display-name>
  <data-spec>
    <data-type>numeric</data-type>
  </data-spec>
  <role-spec>
    <role-type>continuous-measure</role-type>
  </role-spec>
  <fields max-count="1"/>
  <tooltip resource-id="tooltip-x-id">Default tooltip text for X encoding</tooltip>
  <encoding-icon token="letter-x" />
</encoding>
<encoding id="y">
  <display-name>Y</display-name>
  <data-spec>
    <data-type>numeric</data-type>
  </data-spec>
  <role-spec>
    <role-type>continuous-measure</role-type>
  </role-spec>
  <fields max-count="1"/>
  <encoding-icon token="letter-y" />
  <tooltip resource-id="tooltip-y-id">Default tooltip text for Y encoding</tooltip>
</encoding>
<encoding id="text">
  <display-name>Text</display-name>
  <data-spec>
    <data-type>string</data-type>
  </data-spec>
  <encoding-icon token="text" />
  <tooltip>Only tooltip text for TEXT encoding</tooltip>
</encoding>

``````

These encodings are rendered on the Marks card as tiles, with the X, Y and Text icons.

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

:::note

The Tooltip and Details tiles encoding are always part of a viz extension.

:::

The following table lists the elements and values you can use to add encoding tiles to the Marks card.

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

Name of element | Description

<code>encoding</code> | (Optional) The element that contains the encoding definition. By default, all viz extensions will have the Tooltip and Details encoding tiles. If you want to add your own encoding tile, add this &lt;encoding&gt; element to the manifest file and specify a unique <code>id</code> for the encoding. The <code>id</code> corresponds to a variable in your code that is used to generate the visualization from the data. For example, the encoding with the <code>id</code> of <code>'x'</code> could be used to map fields to the x-axis of the visualization. You can add up to four custom encodings.

<code>display-name</code> | (Required) The text string to display on the encoding tile on the Marks card. You can localize this text string by adding an optional <code>resource-id</code> for the encoding. For example, <code>&lt;display-name resource-id="encoding1"&gt;Encoding Name&lt;display-name&gt;</code>. You provide localized strings for this <code>resource-id</code> in the <code>resources</code> section of the manifest file.

<code>data-spec</code> | (Optional) Includes the list of data types supported by this encoding. If a &lt;data-spec&gt; element is included, only fields of the specified data types are accepted for this encoding. If the <code>data-spec</code> attribute is omitted, all supported data types will be accepted. The supported data types are defined in this table.

<code>data-type</code> | There are four possible data types.
<code>numeric</code>, which supports integer and decimal numeric fields.
<code>temporal</code>, which supports the three temporal related fields, date, time, and date/time.
<code>string</code>, any text string field.
<code>boolean</code>, which supports a boolean (true/false) field.
Geographic and cluster group data types are not supported. For more information, see Data Types in Tableau.

<code>role-spec</code> | (Optional) Includes the list of role types supported by this encoding. Role types correspond to the dimensions and measures in Tableau (indicated by the blue and green pills you place on the visualization). If omitted, all four possible values are supported. For more information, see Dimensions and Measures, Blue and Green.

<code>role-type</code> | (Required) Specifies whether the encoding is for a continuous or discrete dimension or measure. The options are:  <code>continuous-measure</code>, <code>discrete-dimension</code>, <code>continuous-dimension</code>, <code>discrete-measure</code>.

<code>fields</code> | (Optional) The maximum number of fields that can use this encoding. Use the `max-count` attribute to specify the maximum number of fields. If not specified, there is no limit on the number of fields that can use this encoding.

<code>encoding-icon</code> | (Optional) Specify the icon to use in the Encoding tile and next to fields when associated to your encoding. Select from one of the many predefined icons which Tableau offers to Viz Extension developers. If none is specified, the next available default icon which hasn't been used yet will be associated with your encoding. The defaults are the Ⓐ, Ⓑ, Ⓒ, or Ⓓ icons.

<code>tooltip</code> | (Optional) The text string to display as a tooltip when the mouse is hovering over this particular encoding tile. You can localize this tooltip text by adding an optional <code>resource-id</code>.  You provide localized strings for this <code>resource-id</code> in the <code>resources</code> section of the manifest file. With no <code>resource-id</code> xml attribute, the value will be used as the tooltip in all locales.

### Icons

Custom encodings can be assigned a specific icon by using the <code>&lt;encoding-icon&gt;</code> XML tag inside each <code>&lt;encoding&gt;</code> entry in the `.trex` manifest file.

```xml

<encoding-icon token="letter-x" />

```

Note that the `<encoding-icon>` keywords ("`letter-x`", for example) are ids in Tableau associated with specific icons. You should define your own friendly encoding names using the `<display-name>` tag. To help your users, the names you choose for the encoding icons should be related to the viz extension and viz type you are creating. For example, the following snippet uses the encoding icon `token="edge"` (), but labels the icon "Link" to reflect its role in a Sankey visualization.

```xml

<encoding id="edge">
  <display-name resource-id="edge-id">Link</display-name>
  <role-spec>
    <role-type>continuous-measure</role-type>
    <role-type>continuous-dimension</role-type>
  </role-spec>
  <fields max-count="1"/>
  <encoding-icon token="edge" />
  <tooltip resource-id="edge-id">Edge</tooltip>
</encoding>

```

The table shows the list of icons you can use. 
Note that the icons and keywords for the letters "f" through "y" follow the same pattern as the other letters (`token="letter-f"` ). For brevity, they aren't shown in this table.

<colgroup>
<col width="30%" />
<col width="10%" />
<col width="%20" />
<col width="30%" />
<col width="10%" />
</colgroup>

keyword | Icon | &nbsp; | keyword | Icon

color |  | &nbsp; | letter-a | 

size |  | &nbsp; | letter-b | 

text |  | &nbsp; | letter-c | 

line |  | &nbsp; | letter-d | 

shape |  | &nbsp; | letter-e | 

wedge |  | &nbsp; | ... | ..

level-of-detail |  | &nbsp; | letter-z | 

tooltip |  | &nbsp;

level |  | &nbsp; | digit-0 | 

level-radial |  | &nbsp; | digit-1 | 

edge |  | &nbsp; | digit-2 | 

&nbsp; | &nbsp; | &nbsp; | digit-3 | 

dot |  | &nbsp; | digit-4 | 

favorite |  | &nbsp; | digit-5 | 

filter |  | &nbsp; | digit-6 | 

flow |  | &nbsp; | digit-7 | 

forecast |  | &nbsp; | digit-8 | 

globe |  | &nbsp; | digit-9 | 

grid |  | &nbsp; | &nbsp; | &nbsp;

highlight |  | &nbsp; | hash | 

image |  | &nbsp; | dollar | 

join |  | &nbsp; | percentage | 

link |  | &nbsp; | ampersand | 

metric |  | &nbsp; | exclamation | 

delta-down |  | &nbsp; | smaller-than | 

delta-up |  | &nbsp; | equal | 

three-dots |  | &nbsp; | larger-than | 

arrow-down |  | &nbsp; | question | 

arrow-up |  | &nbsp; | at-symbol | 

arrow-left |  | &nbsp; | function | 

arrow-right |  | &nbsp; | &nbsp; | &nbsp;

thumbnail-even |  | &nbsp; | &nbsp; | &nbsp;

---

## What is a Tableau Viz Extension?

Viz Extensions is a new feature that allows developers to create new viz types that Tableau users can access through the worksheet Marks card. Like Dashboard Extensions, Viz Extensions are web applications that can interact and communicate with Tableau. Developers will be able to build bespoke Viz Extensions that can be made available to Tableau users through the Tableau Extensions API.

---
#### Example: a connected scatterplot

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

---

### Components of a Tableau Viz Extension

A Tableau extension consists of a manifest file (`.trex`), a web page (`.html`) that uses a Tableau-provided JavaScript library, and the JavaScript (`.js`) file (or files) that contain your extension logic and code that builds the visualization.

### Why are we building Viz Extensions?

The Tableau Community has many great ideas for new ways to see and understand data. Viz Extensions empowers our community to add to the visualization library directly, enabling our customers to better personalize their experiences in visualizing data.

### How will Viz Extensions be used?

In our New Chart Types pilot program, we tested first-party Viz Extensions such as Sankey and Radial charts, which have been long-requested viz types from our community. We can't wait to see all the different Viz Extensions that will be built that will allow Tableau users to create worksheets tailored to their specific industry and needs.

### How are these different from built-in viz types?

Tableau has a robust viz type library built into our products. They aren't going anywhere. You can still build bar charts, scatter plots, maps, and many more vizzes directly in Tableau. Viz Extensions must be added as an extension to your instance of Tableau before use. Built-in viz types are built by Tableau Developers. Viz Extensions can be built by Tableau Developers or a developer within our community. With built-in viz types, Tableau assigns encoding attributes to marks on the viz. With Viz Extensions, the developer can customize the types of encoding boxes that make sense for their custom viz types. Most, but not all, functionality that works with built-in vizzes will work with Viz Extensions.

### How are Viz Extensions different from Dashboard Extensions?

Dashboard Extensions are custom web applications that you drag directly onto a dashboard, whereas Viz Extensions are loaded in the worksheet. Dashboard Extensions interact with Tableau and provide unique capabilities to your dashboard. Viz Extensions are added to the worksheet while building your viz via the Marks card and enable a more custom visual exploration experience in the flow of work.

While Viz Extensions and Dashboard Extensions share a common library, Viz Extensions have access to the contents of a worksheet (`worksheetContent`) and Dashboard Extensions primarily access the contents of the dashboard (`dashboardContent`).

A few distinctions:

* Viz Extensions will support automatic data updates from the marks card. As users drag and drop new fields in the worksheet, Viz Extensions will update automatically.

* Viz Extensions enable UX customizations on the Marks Card—allowing developers to customize the authoring experience to fit their viz type. Developers can define custom encodings along with the data rules that come with them.

* Viz Extensions provide more options for developers to add to the extension experience by introducing concepts that offer more interactivity, such as selection, Tableau-styles, and tooltips.