# Extensions API Reference Guides > Publishing, Tableau Viz input specs, release notes, and known issues. Reference material. Use a product domain file for how to build that extension type. ## Publishing and Distribution --- ## Hosting and Contributing to the Community Portal Submit your extension to the [Community Extension](pathname:///community) portal to share your work with other developers. To make it easier for others to use your extension, we ask that you include a link to a hosted version of your extension. If you don't have a hosted version yet, see our [suggestions for hosting](#suggestions-for-hosting-your-extension). ### Submitting extensions to the Community Portal :::note Before you submit a extension, you'll need a GitHub account. ::: 1. Create a fork of the `extensions-api` repository. 1. In your fork of the repository, find the community folder at the root of the repository. 1. In the `community_extensions.json` file, add an entry for your extension. Name, author, and description are required. All other fields are optional. While we recommend both providing the source code and a hosted version of your extension, you may choose one or the other. If you choose to provide a hosted version of your extension, see the next step (skip otherwise). 1. First, host your extension on a web server (see below for suggestions). Second, create a manifest file (`.trex`) where the URL points to the hosted location of your extension. Finally, in your pull request, place the manifest file in the `community/CommunityManifests` folder. Also place the file name into your entry in community_extensions.json. Ensure the filename matches your manifest file and it is unique from others in the folder. 1. Submit a pull request from your fork to the main branch in the official repository. After that, a member of the Tableau Extensibility team will review your submission. ### Suggestions for hosting your extension --- There are several free hosting services that you can use for your extension. You can host your extension anywhere you please, but we have two suggested locations that we have seen to be the easiest to use. 1. Host your static content on GitHub pages. If your extension is composed of client-side code only (just HTML/CSS/JS files), you can host your content for free on GitHub Pages (This is actually what's hosting the documentation you are currently reading!). GitHub Pages makes it really easy to host content, especially if your extension code is already on GitHub. Check out their tutorial for details: [pages.github.com/](https://pages.github.com) 2. Host your node app on Heroku. If your extension contains a sever component, like the Node Proxy sample, you can host your extension for free on Heroku. There are certain usage restrictions; for example, their free tier requires the extension to be offline for a few hours a day. Check out their tutorial for more details: [Heroku Tutorial](https://devcenter.heroku.com/articles/getting-started-with-nodejs#introduction) --- ## Publish and share a Tableau Extension If you want to share the dashboard extensions you create with others you have several options. If the dashboard extension is running on a publicly accessible web server over HTTPS, you can distribute the manifest file (`.trex`). Dashboard authors can then add the extension to their dashboards. ### Sharing an extension by sharing the workbook The easiest way to share an extension with others is to share the workbook that contains the dashboard extension. If the extension is hosted on a website that is accessible and the extension is using HTTPS protocol, viewers of the dashboard will be able to see and use the extension. However, if the users do not also have access to the dashboard extension manifest file (`.trex`), they will not be able to add the extension to other dashboards or to other workbooks. ![](../assets/frelard_share_twb.png) ### Publishing a dashboard extension to Tableau Server or Tableau Cloud While you don't exactly publish a dashboard extension to Tableau Server or Tableau Cloud, you can publish the workbook that contains an extension to Tableau Server. You can also add a dashboard extension to a dashboard on Tableau Server or Tableau Cloud when you are in authoring mode. However, to run on Tableau Server or Tableau Cloud, your extension must: * Be hosted on a web server that uses HTTPS (`localhost` is the exception during development). Note that hosting your extension on the same computer that is running Tableau Server is not recommended. * Declare full data access (if the extension calls any functions that access the underlying data in the dashboard). * Be granted permission to run on Tableau Server or Tableau Cloud. :::note If you want to test your extension with Tableau Cloud and you are running an extension on `http://localhost` during development, see [Load and view localhost content on sites that use secure connections](../security/trex_security#load-and-view-localhost-content-on-sites-that-use-secure-connections) ::: Tableau Server and Tableau Cloud have settings that control whether dashboard extensions are allowed to run and whether specific extensions can access the underlying data in a dashboard. To enable a dashboard extension on Tableau Server or Tableau Cloud, the server administrator or the site administrator (Tableau Cloud) must allow extensions for the site. The administrators can then choose to enable the default policy that allows *unknown* extensions that only request summary data to run, provided users grant the extension permission. These extensions are unknown in the sense that they have not been explicitly added to the safe list or to the blocked list on Tableau Server or Tableau Cloud. If your extension requires access to full data (underlying data) the server or site administrator must add the URL of your extension to a safe list and must explicitly grant the extension access to full data. The server or site administrator can also configure whether users of your extension will see prompts requesting permission to run. The following flowchart shows how the settings on Tableau Server or Tableau Cloud determine whether an extension is allowed or denied permission to run. ![alt text](../assets/Extensions_Safe_List_Block_List_Evaluation_2x.png "Flowchart showing the process that allows or denies an extension to run on Tableau Server or Tableau Cloud.") See [Manage Dashboard Extensions on Tableau Server](https://onlinehelp.tableau.com/current/server/en-us/dashboard_extensions_server.htm) or [Manage Dashboard Extensions on Tableau Cloud](https://onlinehelp.tableau.com/current/online/en-us/dashboard_extensions_server.htm) for more information. ### Publishing a dashboard extension to the Tableau Exchange If you want to make your dashboard extension readily available to a large number of people, you can take steps to have your extension added to the [Tableau Exchange](https://exchange.tableau.com/). Publishing your extension to the Tableau Exchange means that people will be able to discover your extension, find out what it can do, and then add the extension to their dashboards, all while working within Tableau. In addition to the requirements for all extensions to ensure security and usability, such as: * Using HTTPS * Validating user input * Declaring data access requirements * Providing a URL that customers can use to get support for your extension Dashboard extensions that appear in the Tableau Exchange must also: * Follow the Design Guidelines for Dashboard Extensions (user interaction and style guidelines for user interface elements). * Ensure that the information in the extension manifest file (`.trex`) matches the content that you will publish in the Tableau Exchange. For example, the `name`, `description` fields are used to populate the name and description fields in the Tableau Exchange. The icon you use in the manifest should also be the icon that is used in the Exchange. You need to provide a 280x280 pixel `.png` version of the icon. For information about getting your extension into the Tableau Exchange, see [Submitting your Extension to the Tableau Exchange](../ux_extension_gallery.md). For information about designing an extension, see [Design Guidelines for Dashboard Extensions](../ux_design.md). ![](../assets/trex_gallery.png) ### Publishing or sharing a dashboard extension on the Communities page Another way to share your work with other developers is to add it to the [Community Portal for Dashboard Extensions](pathname:///community/). You can use the portal to provide links to your source code and you can also provide a `.trex` file for users to download. To make it easier for others to use your extension, we ask that your `.trex` file specifies a link to a hosted version of your extension See [Hosting and Contributing to the Community Portal](./trex_contributing.md) Submit your extension to the [Community Portal for Dashboard Extensions](pathname:////community/) --- ## Publish Sandboxed Extensions Sandboxed Extensions are Tableau dashboard extensions that are not permitted to make external network requests. Sandboxed Extensions are hosted by Tableau and run inside an environment that prevents communication with anything except the Tableau hosting server. Sandboxed Extensions are supported in Tableau 2019.4 and later. ### Before publishing your extension Be sure to follow the guidelines and requirements to [Create and Test Sandboxed Extensions](../security/trex_sandbox_test). Make sure your extension works as expected in the development environment. The development environment replicates the Tableau Sandboxed Extension Hosting Cloud Service. If your extension works in the development environment, it will work when you submit the extension package to Tableau for publication. ### Submit your Sandboxed Extension for publication After you finish developing and testing your Sandboxed Extension, you can submit your extension to the Tableau Exchange. To submit your extension to the Tableau Exchange, you must be added as a contributor on the Exchange. Contact the Tableau Exchange at [extensiongallery@tableau.com](mailto:extensiongallery@tableau.com) and see [Submitting your Extension to the Tableau Exchange](../ux_extension_gallery.md) for more information. --- ## Tableau Viz Reference The programming interface for Tableau Viz consists of a method call in the Dashboard Extensions API called `createVizImageAsync`. The `createVizImageAsync` method returns an SVG image. The method takes a single argument, a JavaScript object (the `inputSpec`). The `inputSpec` describes the viz that you want to create and includes the data, or a reference to the data, and the information about how you want that data displayed. The following sections describe the components and syntax of the `inputSpec` for Tableau Viz v1 and Tableau Viz v2. Tableau Viz v2 of the `inputSpec` adds support for combination charts, multiple panes, and dual-axis visualizations. --- For Tableau 2021.3 and later and the Tableau Dashboard Extensions API v1.6 (and later) * See [Tableau Viz inputSpec v1](./trex_tableau_viz_ref_v1.md) --- For Tableau 2022.3 (and later) and the Tableau Dashboard Extensions API v1.9 (and later) * See [Tableau Viz inputSpec v2](./trex_tableau_viz_ref_v2).md --- For information about how to add a Tableau Viz, see [Add Tableau Viz to your Dashboard Extensions](./core/trex_tableau_viz.md). --- ## Tableau Viz v1 inputSpec The `createVizImageAsync` method takes a single argument, the `inputSpec`, a JavaScript object, and returns the SVG description of that image. Note that you can use the Tableau Viz v1 `inputSpec` with Tableau 2021.3 (and later). To create combination charts and dual-axis visualizations, you need to use version 2 of the `inputSpec`, available in Tableau 2022.3 and later. See the [Tableau Viz v2 inputSpec](./trex_tableau_viz_ref_v2.md). ### The createVizImageAsync method The `createVizImageAsync` method is one of the methods in the Tableau Dashboard Extensions API `extensions` namespace. The method has the following syntax: ```javascript createVizImageAsync( inputSpec: *object* ): Promise ``` This method takes a single argument, the `inputSpec`, a JavaScript object, and returns the SVG description of that image. To call this method, you first initialize the Dashboard Extensions API (`tableau.extensions.initialize()`). You then create the `inputSpec` object that defines your graphic. For more information about the method, see [`tableau.extensions.createVizImageAsync`](pathname:///api/interfaces/Extensions#createvizimageasync) in the Dashboard Extensions API reference. ### Specification for `inputSpec` (version 1) object The `inputSpec` is a JavaScript object that specifies the name-value pairs to use to create the SVG image. The object consists of the `data` and the properties that specify how to format the data, for example, `mark`, `markcolor`, `size`, and `encoding`. The `data` is an array of objects. The `data` is listed in row-level order, where each object represents one item. The `mark` property specifies the type of mark to use in the image, for example, you can change the mark type from bars to lines. The following shows an example `inputSpec` that creates a bar chart image. ```javascript { description: "A bar chart with multiple encodings", size: {width: 800, height: 600}, data: { values: [ {"Category": "A", "Sales": 28, "Weather": "Sun", "Quantity": 3}, {"Category": "B", "Sales": 55, "Weather": "Sun", "Quantity": 6}, {"Category": "C", "Sales": 43, "Weather": "Sun", "Quantity": 9} ] }, mark: tableau.MarkType.Bar, markcolor: "#FFA500", encoding: { columns: {field: "Sales", type: tableau.VizImageEncodingType.Continuous}, rows: {field: "Category", type: tableau.VizImageEncodingType.Discrete, hidden: "true"}, sort: { field: "Category", sortby: "Sales", direction: tableau.VizImageSortDirectionType.Ascending } color: {field: "Weather", type: tableau.VizImageEncodingType.Discrete, palette: "seattle_grays_10_0"}, size: {field: "Quantity", type: tableau.VizImageEncodingType.Continuous}, text: {field: "Category", type: tableau.VizImageEncodingType.Discrete} } } ``` --- ### Description of `inputSpec` (version 1) properties The following table describes the properties in the `inputSpec`, the JavaScript object that you provide as input to the `createVizImageAsync` method. #### `description` (Optional) A description about the visualization. Currently, the description is not used anywhere and is not visible when the image is generated. However, it might be helpful to use this description as you comment your code. #### `title` (Optional) Creates a title for the image. ```javascript title: "My Custom Viz", ``` #### `data` (Required) The data to use to create the image. The `data` consists of an array of objects, specified with the `"values"` property. Data is listed in row level order, where each object represents one item. ```javascript data: { values: [ { Category: 'A', Sales: 28 }, { Category: 'B', Sales: 55 }, { Category: 'C', Sales: 43 }, { Category: 'D', Sales: 91 }, { Category: 'E', Sales: 81 }, { Category: 'F', Sales: 53 }, { Category: 'G', Sales: 19 }, { Category: 'H', Sales: 87 }, { Category: 'I', Sales: 52 } ] }, ``` #### `mark` (Optional) Supported mark types include: `tableau.MarkType.Bar`, `tableau.MarkType.Line`, `tableau.MarkType.Area`, `tableau.MarkType.Square`, `tableau.MarkType.Circle`, `tableau.MarkType.Text`. If no mark type is specified, the generated image will use the Tableau default for that data. #### `markcolor` Specifies a mark color for all marks, for example, hex values. This is equivalent to selecting an arbitrary color in the Color Shelf of the Marks card in Tableau. ```javascript markcolor: "#FFA500", ``` #### `size` (Optional) Specifies the size of the image in pixels. The size is described with width and height dimensions. | Property | Value | |:--- |:--- | |`width` | Width of the SVG image. | |`height`| Height of the SVG image.| |`showlegend` | Boolean (`true`, `false`). Specifies whether to show or hide the Size legend. | If you specify the size, you must specify both the width and height. If you don't specify a size, the image uses the default size (600 x 400). ```javascript size: {width: 800, height: 600}, ``` #### `encoding` Corresponds to the Marks card in Tableau and describes how the marks (measures and dimensions) are encoded. In Tableau, when you drag fields onto the properties on the Marks card it encodes the data in the view. The `encoding` property lets you set the properties of the marks for the image. The `columns`, `rows` properties allow you to define the layout of your view, just like you do in Tableau today. You can also map fields to the `color`, `size`, and `text` properties. Within these properties, you must specify the field to encode and its type (`tableau.VizImageEncodingType.Continuous` or `tableau.VizImageEncodingType.Discrete`). Some properties allow you to set additional values as shown in the following table. --- ##### encoding: `columns` and `rows` | Property | Value | |:--- |:--- | |`field` | The name of the field to encode. | |`type`| The type of field, either `tableau.VizImageEncodingType.Discrete` (blue "pill") or `tableau.VizImageEncodingType.Continuous` (green "pill"). | |`hidden` | Boolean (`true`, `false`). Specifies whether to show or hide the column or row header. | | `showgridline` | Boolean (`true`, `false`). Specifies whether to show or hide the gridlines. | |`title` | Specifies a custom axis title (x-, or y-axis) for the columns and rows. A `title` can only be used for continuous fields (`tableau.VizImageEncodingType.Continuous`). Custom titles for discrete fields are not supported. | | `showtitle` | Boolean (`true`, `false`). Specifies whether to show or hide the custom column or row title. | The following are examples of how you might specify the encodings for columns and rows: ```javascript encoding: { columns: {field: "Sales", type: tableau.VizImageEncodingType.Continuous, title: "My Custom Title", showtitle: true}, rows: {field: "Category", type: tableau.VizImageEncodingType.Discrete } } ``` ```javascript mark: tableau.MarkType.Line, encoding: { columns: {field: "Category", type: tableau.VizImageEncodingType.Discrete, showgridline: true}, rows: {field: "Measure", type: tableau.VizImageEncodingType.Continuous, showgridline: true}, } ``` ##### encoding: `size` Specifies the size encoding of the mark. The `size` property corresponds to the Size button on the Marks card. For continuous fields, you can set the bar mark to either manual or fixed size. You can also set the mark’s alignment. | `size` Property | Value | |:--- |:--- | |`field` | The name of the field to encode. | |`type`| The way the data is distributed in the view (discrete or continuous).| |`setting` | For continuous fields of the bar mark type, specifies the size and alignment properties of a mark. The options are manual (`tableau.VizImageSizeSettingType.Manual`) or fixed size (`tableau.VizImageSizeSettingType.Fixed`). For manual, you can specify a `size` value from `0` to `2`. For fixed, you can set the alignment and width in axis units. See the `setting` properties for more information. | |`showlegend` | Boolean (`true`, `false`). Specifies whether to show or hide the color legend. | |`setting` Property | Value | |:--- |:--- | |`tableau.VizImageSizeSettingType.Fixed` | Mark size is fixed. When `Fixed` is selected, you can set the `alignment` to `tableau.VizImageSizeSettingAlignmentType.Right`, `tableau.VizImageSizeSettingAlignmentType.Left`, or `tableau.VizImageSizeSettingAlignmentType.Center`. You can set the `width_in_axis_units` to a fixed number of units (floating point values accepted). | |`tableau.VizImageSizeSettingType.Manual` | Specifies that the mark size type is manual. When this is selected, set the `marksize` value (from 0 to 2, floating point values accepted). | Example of fixed sized type: ```javascript encoding: { ... size: {field: "Age", setting: tableau.VizImageSizeSettingType.Fixed, alignment: tableau.VizImageSizeSettingAlignmentType.Right, width_in_axis_units: 3} } ``` Example of manual sized type: ```javascript encoding: { ... size: {field: "Measure", type: tableau.VizImageEncodingType.Continuous, setting: tableau.VizImageSizeSettingType.Manual, marksize: 0.35} } ``` ##### encoding: `sort` Specifies the sort order for a field (continuous or discrete). Supports sorting the field by ascending or descending values (`VizImageSortDirectionType.Ascending`, `VizImageSortDirectionType.Descending`), based on the `sortby` criteria you provide. ```javascript sort: { field: "Category", sortby: "Weather", direction: tableau.VizImageSortDirectionType.Ascending } ``` ##### encoding: `color` The `color` property corresponds to the Color button on the Marks card. The color can contain additional properties: | Property | Value | |:--- |:--- | |`field` | The name of the field to encode. | |`type`| The way the data is distributed in the view (discrete or continuous).| |`palette` | Specifies color encoding for the field from the Tableau palette. Note that there are separate palettes for discrete or continuous fields. You can also create custom color palettes for continuous fields. See [Create Custom Color Palettes](#create-custom-color-palettes). | |`showlegend` | Boolean (`true`, `false`). Specifies whether to show or hide the color legend. | **`palette` names for continuous fields** You can specify one of the following Tableau color palettes with the `palette` property for continuous fields. Note that the list of available palettes depends upon the version of Tableau that is being used. Be aware that the palette colors are subject to change. The following is an example that shows how you might encode a continuous field with a Tableau palette. You can also create custom color palettes for continuous fields. See [Create Custom Color Palettes](#create-custom-color-palettes). ```javascript encoding: { ... color: { field: 'Measure', type: tableau.VizImageEncodingType.Continuous, palette: 'green_blue_white_diverging_10_0'}, ... } ``` | Continuous colors palettes | Palette name | |:--- |:--- | | ![Tableau Continuous Palette](./assets/continuous_palette.png) | `blue_10_0` `orange_10_0` `green_10_0` `red_10_0` `purple_10_0` `brown_10_0` `gray_10_0` `gray_warm_10_0` `blue_teal_10_0` `orange_gold_10_0` `green_gold_10_0` `red_gold_10_0` `orange_blue_diverging_10_0` `red_green_diverging_10_0` `green_blue_diverging_10_0` `red_blue_diverging_10_0` `red_black_10_0` `gold_purple_diverging_10_0` `red_green_gold_diverging_10_0` `sunrise_sunset_diverging_10_0` `orange_blue_white_diverging_10_0` `red_green_white_diverging_10_0` `green_blue_white_diverging_10_0` `red_blue_white_diverging_10_0` `red_black_white_diverging_10_0` `tableau-blue-light` `tableau-orange-light` `tableau-orange-blue-light` `tableau-map-blue-green` `tableau-map-temperatur` | **`palette` names for discrete fields** You can specify one of the following Tableau color palettes with the `palette` property for discrete fields. Note that the list of available palettes depends upon the version of Tableau that is being used. Be aware that the palette colors are subject to change. The following is an example that shows how you might encode a discrete field with a Tableau palette. ```javascript encoding: { ... color: { field: 'Category', type: tableau.VizImageEncodingType.Discrete, palette: 'seattle_grays_10_0'}, ... } ``` | Discrete color palettes | Palette name | |:--- |:--- | | ![Tableau Discrete Palette](./assets/discrete_palette.png) | `tableau10_10_0` `tableau20_10_0` `color_blind_10_0` `seattle_grays_10_0` `traffic_light_10_0` `superfishel_stone_10_0` `miller_stone_10_0` `nuriel_stone_10_0` `jewel_bright_10_0` `summer_10_0` `winter_10_0` `green_orange_cyan_yellow_10_0` `blue_red_brown_10_0` `purple_pink_gray_10_0` `tableau-10` `tableau-10-medium` `tableau-20` `blue_10_0` `orange_10_0` `green_10_0` `red_10_0` `purple_10_0` `brown_10_0` `gray_10_0` `gray_warm_10_0` `blue_teal_10_0` `orange_gold_10_0` `green_gold_10_0` `red_gold_10_0` `cyclic_10_0` | --- ##### Create custom color palettes You can set the color palette to a custom diverging or custom sequential color palette that you specify, and not just the Tableau defined palates, such as, `green_blue_white_diverging_10_0`. | Custom Palette Property | Value | |:--- |:--- | |`tableau.VizImagePaletteType.CustomDiverging` | Defines a custom diverging palette. Specify the `start` value and an `end` value, each as a hexadecimal value. | | `tableau.VizImagePaletteType.CustomSequential` | Defines a custom sequential palette. Specify the `end` value as a hexadecimal value. | For example, you could set a custom palette as shown in the following examples: ```javascript palette: tableau.VizImagePaletteType.CustomDiverging, start: "#FFB6C1", end: "#90ee90" ``` Or ```javascript palette: tableau.VizImagePaletteType.CustomSequential, end: "#FFB6C1" ``` --- ## Tableau Viz v2 inputSpec The `createVizImageAsync` method takes a single argument, the `inputSpec`, a JavaScript object, and returns the SVG description of that image. Starting with Tableau 2022.3, you can use version 2 of the `inputSpec` to create combination charts and dual-axis visualizations. Version 2 of the `inputSpec` allows you to specify different mark types for the measures along the encoding axis (either rows or columns). For versions of Tableau prior to 2022.3, you can use the Tableau Viz v1 `inputSpec`. The Tableau Viz v1 is supported in Tableau 2021.3 (and later). See the [Tableau Viz v1 inputSpec](./trex_tableau_viz_ref_v1.md). --- ### The createVizImageAsync method The `createVizImageAsync` method is one of the methods in the Tableau Dashboard Extensions API `extensions` namespace. The method has the following syntax: ```javascript createVizImageAsync( inputSpec: *object* ): Promise ``` This method takes a single argument, the `inputSpec`, a JavaScript object, and returns the SVG description of that image. To call this method, you first initialize the Dashboard Extensions API (`tableau.extensions.initialize()`). You then create the `inputSpec` object that defines your graphic. For more information about the method, see [`tableau.extensions.createVizImageAsync`](pathname:///api/interfaces/Extensions.html#createvizimageasync) in the Dashboard Extensions API reference. --- ### Specification for `inputSpec` (version 2) object The `inputSpec` is a JavaScript object that specifies the name-value pairs to use to create the SVG image. The object consists of the `data` and the properties that specify how to format the data, for example, `vizlayout`, `columns`, `rows`, `encodingaxis` and `encodings`. The `data` is an array of objects. The `data` is listed in row-level order, where each object represents one item. The `mark` property specifies the type of marks to use for the measures on the encoding axis in the image. For example, if you have two continuous fields on the columns shelf, you can specify `columns` as the `encodingaxis` and set the marks to different types (bar, line, area, circle, square, or text). The following shows an example `inputSpec` that creates a combination chart image that specifies bar and area mark types for the `Sales` and `Profits` measures on the columns shelf. ```javascript { version: 2, description: 'Example Tableau Viz v2', data: { values: [ { Segment: 'Consumer', ShipMode: 'First Class', Category: 'Technology', Profit: 11560.75, Sales: 61089.43 }, { Segment: 'Corporate', ShipMode: 'First Class', Category: 'Technology', Profit: 7235.75, Sales: 39201.43 }, { Segment: 'Home Office', ShipMode: 'First Class', Category: 'Technology', Profit: 8706.75, Sales: 39074.43 }, ], }, vizlayout: { title: 'Example Tableau Viz v2', }, columns: [ { field: 'ShipMode', type: tableau.VizImageEncodingType.Discrete }, { field: 'Sales', type: tableau.VizImageEncodingType.Continuous }, { field: 'Profit', type: tableau.VizImageEncodingType.Continuous }, ], rows: [{ field: 'Segment', type: tableau.VizImageEncodingType.Discrete }], encodingaxis: 'columns', defaultencoding: { mark: tableau.MarkType.Bar }, encodings: [ { mark: tableau.MarkType.Bar, }, { mark: tableau.MarkType.Area, color: { field: 'Category', type: tableau.VizImageEncodingType.Discrete, palette: { name: 'green_orange_cyan_yellow_10_0' } }, }, ], }; ``` --- ### Description of `inputSpec` (version 2) properties The following table describes the properties in version 2 of the `inputSpec`, the JavaScript object that you provide as input to the `createVizImageAsync` method #### `version` (Required) Specifies the version of the Tableau Viz. Only used for version 2 and later. ```javascript { version: 2, // ... } ``` #### `description` (Optional) A description about the visualization. Currently, the description is not used anywhere and is not visible when the image is generated. However, it might be helpful to use this description as you comment your code. ```javascript description: 'Example description', ``` #### `data` (Required) The data to use to create the image. The `data` consists of an array of objects, specified with the `"values"` property. Data is listed in row level order, where each object represents one item. ```javascript data: { values: [ { Segment: 'Consumer', ShipMode: 'First Class', Category: 'Technology', Profit: 11560.75, Sales: 61089.43 }, { Segment: 'Corporate', ShipMode: 'First Class', Category: 'Technology', Profit: 7235.75, Sales: 39201.43 }, { Segment: 'Home Office', ShipMode: 'First Class', Category: 'Technology', Profit: 8706.75, Sales: 39074.43 }, ], }, ``` #### `vizlayout` (Required) Contains information about the layout of the Tableau Viz. You can set the size of the layout and whether to show or hide the color and size legends. The `vizlayout` structure is required but specifying `size`, `showcolorlegend`, `showsizelegend`, `showrowsgridline` is optional. Example: ```javascript vizlayout: { title: 'Example multi-pane viz', size: {width: 800, height: 600}, showcolorlegend: true, showsizelegend: false, showcolumnsgridline: false, showrowsgridline: false, }, ``` ##### vizlayout: `title` (Optional) (string) Specifies a title for the image. ##### vizlayout: `size` (Optional) Size of the viz requested (in pixels). Needs to be specified inside `vizlayout`. ```javascript vizlayout: { size: {width: 800, height: 600}, }, ``` ##### vizlayout: `showsizelegend` (Optional) (Boolean) Show size legend with the image. Needs to be specified inside `vizlayout`. ```javascript vizlayout: { showsizelegend: true, }, ``` ##### vizlayout: `showrowsgridline` (Optional) (Boolean) Show the horizontal gridlines in the image. (Optional) Needs to be specified inside `vizlayout`. ```javascript vizlayout: { showrowsgridline: true, }, ``` ##### vizlayout: `showcolumnsgridline` (Optional) (Boolean) Show the vertical gridlines in the image. (Optional) Needs to be specified inside `vizlayout`. ```javascript vizlayout: { showcolumnsgridline: true, }, ``` ##### vizlayout: `showcolorlegend` (Optional) (Boolean) Show the color legend with the image. (Optional) Needs to be specified inside `vizlayout`. ```javascript vizlayout: { showcolorlegend: true, }, ``` #### `rows` An array of fields on the Tableau Rows shelf that represent the rows in the image. A row includes the name of the field to add and its type (continuous or discrete). ##### `row` properties | Property | Value | |:--- |:--- | |`field` | The name of the field that appears on the Tableau Rows shelf. | |`type`| The type of field, either `tableau.VizImageEncodingType.Discrete` (blue "pill") or `tableau.VizImageEncodingType.Continuous` (green "pill"). | For example, the following specifies that there is a single field on the Rows shelf, named "Segment." The `type` can be either `tableau.VizImageEncodingType.Continuous` or `tableau.VizImageEncodingType.Discrete`. ```javascript rows:[ { field: 'Segment', type: tableau.VizImageEncodingType.Discrete } ], ``` #### columns An array of fields on the Tableau Columns shelf that represent the columns in the image. A column includes the name of the field and its type (continuous or discrete). The column can also specify an axis range (`axisrange`) that specifies the extent. ##### columns: attributes | Property | Value | |:--- |:--- | |`field` | The name of the field that appears on the Tableau Column shelf. | |`type`| The type of field, either `tableau.VizImageEncodingType.Discrete` (blue "pill") or `tableau.VizImageEncodingType.Continuous` (green "pill"). | |`title` | Specifies a custom axis title for the column. A `title` can only be used for continuous fields (`tableau.VizImageEncodingType.Continuous`). Custom titles for discrete fields are not supported. | | `showtitle` | Boolean (`true`, `false`). Specifies whether to show or hide the custom column or row title. | | `axisrange` | (Optional) If a custom fixed axis is requested, this structure specifies the extent. The syntax is `axisrange: { fixed: true, min: min_value, max: max_value}`. For more information about setting the axes in Tableau, see [Edit Axes](https://help.tableau.com/current/pro/desktop/en-us/formatting_editaxes.htm#change-an-axis-range).| For example, the following specifies that the "Sales" column has a fixed axis range of 0 to 10,0000. ```javascript columns:[ {field:"Ship Mode", type: tableau.VizImageEncodingType.Discrete}, {field:"Sales", type: tableau.VizImageEncodingType.Continuous, axisrange:{fixed: true, min: 0, max: 100000}}, {field:"Profit", type: tableau.VizImageEncodingType.Continuous} ], ``` --- #### `encodingaxis` Specifies the primary shelf for encoding. The `encodingaxis` determines which continuous measures to use for the axis. The `encodings` property is where you specify the encoding for the continuous fields on that axis. ```javascript encodingaxis: 'columns', ``` For example, if you have multiple panes on columns, you would specify `columns`. Using the following definition for columns, the marks for continuous measures would be Sales and Profit. ```javascript columns:[ {field:"Ship Mode", type: tableau.VizImageEncodingType.Discrete}, {field:"Sales", type: tableau.VizImageEncodingType.Continuous, axisrange:{fixed: true, min: 0, max: 100000}}, {field:"Profit", type: tableau.VizImageEncodingType.Continuous} ], ``` #### `defaultencoding` (Required) Specifies the default encoding in Tableau. This is mandatory encoding information that applies to all panes in the viz. The default setting can be overridden with encodings per field. This property corresponds to the "All" encoding on the Marks card in Tableau. The `defaultencoding` is a structure that describes the default mark encoding. Supported mark types include: `tableau.MarkType.Bar`, `tableau.MarkType.Line`, `tableau.MarkType.Area`, `tableau.MarkType.Square`, `tableau.MarkType.Circle`, `tableau.MarkType.Text`. For example, the following sets the default mark type as bar (`tableau.MarkType.Bar`). ```javascript defaultencoding: { mark: tableau.MarkType.Bar }, ``` #### `encodings` (Optional) This property describes how you want to encode the continuous fields on the specified encodings axis, that is, either the rows or columns shelf in Tableau. The encodings shelf is specified with the `encodingaxis` property. You can assign a different mark type to each continuous field to create multiple pane or combination charts. If specified, the number of encoding structures should exactly match the number of continuous measures on the encoding axis. The `endocdings` element corresponds to the Marks card in Tableau and describes how the marks for continuous fields discrete fields are encoded. In Tableau, when you drag fields onto the properties on the Marks card it encodes the data in the view. Similarly, the `encodings` property lets you set the properties of the marks for the image. You can also map fields to the `color`, `size`, and `text` properties, but you can only specify `mark` types for continuous fields on the encoding axis. Note that if there are multiple continuous fields on both columns and rows, only one set of them will get their own marks card: the first set. If you add multiple continuous fields to rows and then add multiple continuous fields to columns, there will only be marks cards for each of the continuous fields on rows. Within these properties, you must specify the field to encode and its type (`tableau.VizImageEncodingType.Continuous` or `tableau.VizImageEncodingType.Discrete`). Some properties allow you to set additional values as shown in the following table. --- ##### encodings: `mark` (Optional) Supported mark types include: `tableau.MarkType.Bar`, `tableau.MarkType.Line`, `tableau.MarkType.Area`, `tableau.MarkType.Square`, `tableau.MarkType.Circle`, `tableau.MarkType.Text`. If no mark type is specified, the generated image will use the `mark` type specified as part of the `defaultencoding` property. ##### encodings: `color` The `color` property corresponds to the Color button on the Marks card. The color can contain additional properties: | Property | Value | |:--- |:--- | |`field` | The name of the field to encode. | |`type`| The way the data is distributed in the view (discrete or continuous).| |`palette` | Specifies color encoding for the field from the Tableau palette. Note that there are separate palettes for discrete or continuous fields. You can also create custom color palettes for continuous fields. See [Create Custom Color Palettes](#create-custom-color-palettes). You specify the palette as a structure `palette: { name: 'string_value'}`. | **`palette` names for continuous fields** You can specify one of the following Tableau color palettes with the `palette` property for continuous fields. Note that the list of available palettes depends upon the version of Tableau that is being used. Be aware that the palette colors are subject to change. The following is an example that shows how you might encode a continuous field with a Tableau palette. You can also create custom color palettes for continuous fields. See [Create Custom Color Palettes](#create-custom-color-palettes). ```javascript encodings: [ { mark: tableau.MarkType.Bar, } { mark: tableau.MarkType.Area, color: { field: 'Measure', type: tableau.VizImageEncodingType.Continuous, palette:{name: 'green_blue_white_diverging_10_0'}}, } ], ``` | Continuous colors palettes | Palette name | |:--- |:--- | | ![Tableau Continuous Palette](./assets/continuous_palette.png) | `blue_10_0` `orange_10_0` `green_10_0` `red_10_0` `purple_10_0` `brown_10_0` `gray_10_0` `gray_warm_10_0` `blue_teal_10_0` `orange_gold_10_0` `green_gold_10_0` `red_gold_10_0` `orange_blue_diverging_10_0` `red_green_diverging_10_0` `green_blue_diverging_10_0` `red_blue_diverging_10_0` `red_black_10_0` `gold_purple_diverging_10_0` `red_green_gold_diverging_10_0` `sunrise_sunset_diverging_10_0` `orange_blue_white_diverging_10_0` `red_green_white_diverging_10_0` `green_blue_white_diverging_10_0` `red_blue_white_diverging_10_0` `red_black_white_diverging_10_0` `tableau-blue-light` `tableau-orange-light` `tableau-orange-blue-light` `tableau-map-blue-green` `tableau-map-temperatur` | **`palette` names for discrete fields** You can specify one of the following Tableau color palettes with the `palette` property for discrete fields. Note that the list of available palettes depends upon the version of Tableau that is being used. Be aware that the palette colors are subject to change. The following is an example that shows how you might encode a discrete field with a Tableau palette. ```javascript encoding: [ { mark: tableau.MarkType.Bar, } { mark: tableau.MarkType.Area, color: { field: 'Category', type: tableau.VizImageEncodingType.Discrete, palette:{name:'seattle_grays_10_0'}}, } ... ], ``` | Discrete color palettes | Palette name | |:--- |:--- | | ![Tableau Discrete Palette](./assets/discrete_palette.png) | `tableau10_10_0` `tableau20_10_0` `color_blind_10_0` `seattle_grays_10_0` `traffic_light_10_0` `superfishel_stone_10_0` `miller_stone_10_0` `nuriel_stone_10_0` `jewel_bright_10_0` `summer_10_0` `winter_10_0` `green_orange_cyan_yellow_10_0` `blue_red_brown_10_0` `purple_pink_gray_10_0` `tableau-10` `tableau-10-medium` `tableau-20` `blue_10_0` `orange_10_0` `green_10_0` `red_10_0` `purple_10_0` `brown_10_0` `gray_10_0` `gray_warm_10_0` `blue_teal_10_0` `orange_gold_10_0` `green_gold_10_0` `red_gold_10_0` `cyclic_10_0` | --- ##### Create custom color palettes You can set the color palette to a custom diverging or custom sequential color palette that you specify, and not just the Tableau defined palates, such as, `green_blue_white_diverging_10_0`. | Custom Palette Property | Value | |:--- |:--- | |`tableau.VizImagePaletteType.CustomDiverging` | Defines a custom diverging palette. Specify the `start` value and an `end` value, each as a hexadecimal value. | | `tableau.VizImagePaletteType.CustomSequential` | Defines a custom sequential palette. Specify the `end` value as a hexadecimal value. | For example, you could set a custom palette as shown in the following examples: ```javascript palette: {name: tableau.VizImagePaletteType.CustomDiverging, start: "#FFB6C1", end: "#90ee90"}, ``` Or ```javascript palette: {name: tableau.VizImagePaletteType.CustomSequential, end: "#FFB6C1"}, ``` --- ## Release Notes for the Tableau Extensions API [Previous Releases](#previous-releases) [Known Issues](./trex_known_issues) --- #### Tableau Extensions API version 1.17.0 *June 2026* * Tableau Dashboard Extensions API library: `tableau.extensions.1.17.0.js` (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api)). * Certain features in this release are only available in Tableau Cloud, Tableau Server, and Tableau Desktop 2026.2 or later. Download [Tableau Desktop](https://www.tableau.com/support/releases). What's new in this release: * Added `DataRole` and `SemanticRole` properties for fields returned in results from the `Worksheet.getVisualSpecificationAsync` method. * Added `WorkbookLocale` to `Environment`. * Added support for exporting extensions on Tableau Cloud and Server platforms. * Added the `reportExtensionRenderComplete` method to `Extensions`, which can be called by an extension to indicate that it is ready for exporting. * Added the `ExportedMediaType` enum property to `Environment`, which indicates the media type an extension is being exported as. * Added the `isExporting` property to `Environment` which indicates if the extension is currently being exported. --- ### Previous Releases #### Tableau Extensions API version 1.16.0 *February 2026* * Tableau Dashboard Extensions API library: `tableau.extensions.1.16.0.js` (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api)). * Certain features in this release are only available in Tableau Cloud and Tableau Desktop 2026.1 or later. Download [Tableau Desktop](https://www.tableau.com/support/releases). What's new in this release: * Added ISO values to `PeriodType` for parameters with `Range` domain type. * Added support for multiple dialogs. In addition to the configuration popup window, you can add other dialog boxes or popup windows that can interact with the extension. See [Add Multiple Dialog Boxes](./core/trex_multiple_dialogs.md). * Added the [sendDialogMessageAsync](pathname:///api/interfaces/UI.html#senddialogmessageasync) and the [sendDialogMessageToParentAsync](pathname:///api/interfaces/UI.html#senddialogmessagetoparentasync) methods to the UI namespace. Use the `sendDialogMessageAsync` method to send messages between any two dialog boxes, or between any dialog box and the extension. Use the `sendDialogMessageToParentAsync` method to send a message from the dialog box to the extension or to the dialog box (the parent) that opened it. See [Send messages between popup dialog boxes and the extension](core/trex_multiple_dialogs#send-messages-between-popup-dialog-boxes-and-the-extension). --- #### Tableau Extensions API version 1.15.0 *September 2025* * Tableau Dashboard Extensions API library: `tableau.extensions.1.15.0.js` (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api)). * Certain features in this release are only available in Tableau Cloud and Tableau Desktop 2025.3 or later. Download [Tableau Desktop](https://www.tableau.com/support/releases). What's new in this release: * Added `Cloud`, `PublicWeb`, and `PublicDesktop` as `Environment.context` values (`ExtensionContext`). The value indicates in which context the extension is currently running. * Added `sendDialogMessageAsync` method and `DialogMessageReceived` event to the UI namespace. * The `closeDialog` method can now be called from the extension frame to forcefully close the dialog. * If you use Tableau Desktop for debugging your extension, there is a new command line argument you need to include when you launch Tableau in debug mode. You need to add `--webEngineArgs` in front of the remote debugging port option. For example, on Windows the command would look something like the following: ```cli "C:\Program Files\Tableau\Tableau \bin\tableau.exe" --webEngineArgs --remote-debugging-port=8696 ``` For more information, see [Debug Extensions in Tableau Desktop](./debug/trex_debugging.md). --- #### Tableau Extensions API version 1.14.0 *June 2025* * Tableau Dashboard Extensions API library: `tableau.extensions.1.14.0.js` (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api)). * Certain features in this release are only available in Tableau Cloud and Tableau Desktop 2025.2 or later. Download [Tableau Desktop](https://www.tableau.com/support/releases). What's new in this release: * Added `hasAlias` and `aliasValue` attributes to [DataValue](pathname:///api/interfaces/DataValue.html). * Fixed a bug that caused an error when calling the `getAllDataSourcesAsync` method on a workbook with no worksheets. * Fixed a bug that caused an error when calling the `applyRangeFilterAsync` method with a `max` or `min` value of `0`. --- #### Tableau Extensions API version 1.13.0 *March 2025* * Tableau Dashboard Extensions API library: `tableau.extensions.1.13.0.js` (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api)) * Certain features in this release are only available in Tableau 2025.1 or later. Download [Tableau Desktop](https://www.tableau.com/support/releases) or [Tableau Server](https://www.tableau.com/support/releases/server). * To preview new features and test your extension with the latest version of Tableau in the Developer Sandbox, join the [Tableau Developer Program](http://www.tableau.com/developer) and request your own Tableau Cloud developer site. What's new in this release: * (Viz Extensions) Added the [`WorksheetFormattingChanged`](pathname:///api/interfaces/WorksheetFormattingChangedEvent.html) event to the [`worksheet`](pathname:///api/interfaces/Worksheet.html). Use this event to take action whenever the worksheet's formatting changes. Note that this event is also raised when the workbook's formatting changes. * Added [`backgroundColor`](pathname:///api/interfaces/Worksheet.html#backgroundcolor) and [`formatting`](pathname:///api/interfaces/Worksheet.html#formatting) properties to the [`worksheet`](pathname:///api/interfaces/Worksheet.html). These properties return the background color and formatting of the worksheet (that is, the formatting sheets that contain the CSS properties). * Added `applyWorksheetFormatting` as a property of [`GetSummaryDataOptions`](pathname:///api/interfaces/GetSummaryDataOptions.html#applyworksheetformatting) and [`GetUnderlyingDataOptions`](pathname:///api/interfaces/GetUnderlyingDataOptions.html#applyworksheetformatting). This property specifies whether to apply worksheet-level formatting to numbers and dates. You can use this option with the get summary and get underlying data APIs (such as, [`getSummaryDataReaderAsync`](pathname:///api/interfaces/Worksheet.html#getsummarydatareaderasync), [`getUnderlyingTableDataReaderAsync`](pathname:///api/interfaces/Worksheet.html#getunderlyingtabledatareaderasync)). #### Tableau Extensions API version 1.12.0 *May 2024* * Tableau Dashboard Extensions API library: `tableau.extensions.1.12.0.js` (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api).) * Certain features in this release are only available in Tableau 2024.2 or later. Download [Tableau Desktop](https://www.tableau.com/support/releases) or [Tableau Server](https://www.tableau.com/support/releases/server). * To preview new features and test your extension with the latest version of Tableau in the Developer Sandbox, join the [Tableau Developer Program](http://www.tableau.com/developer) and request your own Tableau Cloud developer site. What's new in this release: * Support for Viz Extensions. Viz Extensions is a new feature that allows developers to create new viz types that Tableau users can access through the worksheet Marks card. See [Getting Started with Viz Extensions](./vizext/trex_viz_getstarted.md). * Updated the [`Worksheet.selectTuplesAsync`](pathname:///api/interfaces/Worksheet.html#selecttuplesasync) method to now support multiple tuple values. This means you can enable multi-selection scenarios. For example, the viz extension can support mark selection for rectangular, lasso, or other shaped multi-mark selections. You can use this method for marks or zones that represent multiple values. * Added [Keyboard Accessible](https://www.w3.org/TR/UNDERSTANDING-WCAG20/keyboard-operation.html) navigation methods. * You can use the [`Worksheet.getTooltipTextAsync`](pathname:///api/interfaces/Worksheet.html#gettooltiptextasync) method to grab the data of the navigated tuple to read out to a screen reader. * Use the [`Worksheet.leaveMarkNavigationAsync`](pathname:///api/interfaces/Worksheet.html#leavemarknavigationasync) method to escape focus back over to Tableau when you're done with mark navigation. * (Viz Extensions) You can now specify the encoding icons used on the Marks card and provide for localization. You set these options in the `.trex` manifest file. See [Add encoding to the viz manifest](./vizext/trex_viz_manifest.md#add-encoding-in-the-viz-manifest). * (Viz Extensions) Added support for a **Format Extension** button on the Marks card. You can use the Format Extension button to open a configuration popup window to let your users customize your viz extension. You create the button by adding a `` element to your `.trex` manifest file and then creating a `configure()` callback function. For more information, see [Add a Configuration Popup Dialog](./core/trex_configure.md). ```xml ``` * Added support for interactivity in viz extensions. You can add actions and tooltips based on marks selection or hover over interactions. This release includes two new `worksheet` methods. * Use the [`Worksheet.selectTuplesAsync`](pathname:///api/interfaces/Worksheet.html#selecttuplesasync) method to display the Tableau tooltip for the selected marks, or to take some other action based upon the marks selection. * Use the [`Worksheet.hoverTupleAsync`](pathname:///api/interfaces/Worksheet.html#hovertupleasync) method to display a tooltip for the marks currently hovered over. For an example of how you can use these methods, see the [Sankey](https://github.com/tableau/extensions-api/tree/main/Samples/Viz/Sankey?=target="_blank") viz extension sample. Also in this release: * Added `Field.ColumnType`. * Fixed a bug to allow a Field to have `datatype = DataType.Spatial`. * Added an attribute `isGeospatial` to `Field`. --- #### Tableau Dashboard Extensions API version 1.11.0 *April 2024* * Tableau Dashboard Extensions API library: `tableau.extensions.1.11.0.js` (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api).) * Certain features in this release are only available in Tableau 2024.1 or later. Download [Tableau Desktop](https://www.tableau.com/support/releases) or [Tableau Server](https://www.tableau.com/support/releases/server). * To preview new features and test your extension with the latest version of Tableau in the Developer Sandbox, join the [Tableau Developer Program](http://www.tableau.com/developer) and request your own Tableau Cloud developer site. About this release: * Adds the `Environment.uniqueUserId` property. * Adds the `SummaryDataChanged` event type. * Adds the `Worksheet.getVisualSpecificationAsync` method. * Fixes a bug in the `getSelectedMarksAsync` method that would cause `formattedValue` to be incorrect in multi-pane scenarios. * Adds experimental features as part of Viz Extensions Pre-Release. See the blog post [Extend Your Visual Analytics with Tableau Viz Extensions](https://www.tableau.com/blog/visual-analytics-tableau-viz-extensions). The Viz Extensions API is currently under development. Tableau is working to offer the feature in general availability later in 2024. We encourage anyone interested in developing viz extensions to contact Wilson Po at [wpo@salesforce.com](mailto:wpo@salesforce.com). We’re running a program by invitation that focuses on the developer experience for those interested in exploring those tools. An active NDA must be in place to request access to the preview at this time. Sign up to test Tableau Viz Extensions in the [Tableau Beta Preview](https://prerelease.tableau.com/welcome/), as part of the web authoring experience when you register for a Tableau Cloud Beta Site. --- #### Tableau Dashboard Extensions API version 1.10.0 *December 2022* * Tableau Dashboard Extensions API library: `tableau.extensions.1.10.0.js` (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api).) * Certain features in this release are only available in Tableau 2022.4 or later. Download [Tableau Desktop](https://www.tableau.com/support/releases) or [Tableau Server](https://www.tableau.com/support/releases/server). * To preview new features and test your extension with the latest version of Tableau in the Developer Sandbox, join the [Tableau Developer Program](http://www.tableau.com/developer) and request your own Tableau Cloud developer site. About this release: * Updates for Tableau Viz, an easy way for you to add visualizations to your dashboard extensions using a declarative description. This release includes support for combination charts, charts with multiple mark types in the same visualization. Tableau Viz has a new input specification that supports these new visualizations, see the [Tableau Viz v2 inputSpec](./trex_tableau_viz_ref_v2.md). For information about using Tableau Viz in your extensions, see [Add Tableau Viz to your Dashboard Extensions](./core/trex_tableau_viz.md). ![Tableau Viz v2 SVG image](./assets/vizapiV2.svg) ---- * Adds support for a [DataTableReader](pathname:///api/interfaces/DataTableReader.html) to support pagination. Created with [Worksheet.getSummaryDataReaderAsync](pathname:///api/interfaces/Worksheet.html#getsummarydatareaderasync), [Worksheet.getUnderlyingTableDataReaderAsync](pathname:///api/interfaces/Worksheet.html#getunderlyingtabledatareaderasync), and [DataSource.getLogicalTableDataReaderAsync](pathname:///api/interfaces/DataSource.html#getlogicaltabledatareaderasync). For more information, see [Get Data from the View](./core/trex_getdata.md). * Deprecated `getSummaryDataAsync`. Use [Worksheet.getSummaryDataReaderAsync](pathname:///api/interfaces/Worksheet.html#getsummarydatareaderasync) instead. * The [UI.displayDialogAsync](pathname:///api/interfaces/UI.html#displaydialogasync) now supports different dialog styles (window, modal or modeless dialog boxes). * Adds support for annotating marks with [Worksheet.annotateMarkAsync](pathname:///api/interfaces/Worksheet.html#annotatemarkasync), [Worksheet.getAnnotationsAsync](pathname:///api/interfaces/Worksheet.html#getannotationsasync), and [Worksheet.removeAnnotationAsync](pathname:///api/interfaces/Worksheet.html#removeannotationasync). See the code sample, [Annotation](https://github.com/tableau/extensions-api/tree/dev/Samples/Dashboard/Annotation) (on GitHub). --- #### Tableau Dashboard Extensions API version 1.9.0 *June 2022* * Tableau Dashboard Extensions API library: `tableau.extensions.1.9.0.js` (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api).) * Download [Tableau Desktop](https://www.tableau.com/support/releases) or [Tableau Server](https://www.tableau.com/support/releases/server). * To preview new features and test your extension with the latest version of Tableau in the Developer Sandbox, join the [Tableau Developer Program](http://www.tableau.com/developer) and request your own Tableau Cloud developer site. About this release: * Added support for [`Filter.getAppliedWorksheets()`](pathname:///api/interfaces/Filter.html#getappliedworksheetsasync) and [`Filter.setAppliedWorksheets()`](pathname:///api/interfaces/Filter.html#setappliedworksheetsasync). * Added support for [`Dashboard.getFiltersAsync()`](pathname:///api/interfaces/Dashboard.html#getfiltersasync) and [`Dashboard.applyFilterAsync()`](pathname:///api/interfaces/Dashboard.html#applyfilterasync). * Added support for [`Worksheet.applyRelativeDateFilterAsync()`](pathname:///api/interfaces/Worksheet.html#applyrelativedatefilterasync). * Starting with this release, you can now load Benton Sans fonts and Tableau fonts by default during extension initialization. You can set the Tableau and Benton Sans fonts in the style portion of your extension. To see how you can use the fonts in a dashboard extension, see the [Formatting](https://github.com/tableau/extensions-api/tree/master/Samples/Dashboard/Formatting?=target="_blank") sample. ```css body { font-family: 'Benton Sans', Arial, Helvetica, sans-serif; } ``` ---- #### Tableau Dashboard Extensions API version 1.8.1 *February 2022* * Tableau Dashboard Extensions API library: `tableau.extensions.1.8.1.js` (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api).) * Download [Tableau Desktop 2021.4](https://www.tableau.com/support/releases) or [Tableau Server 2021.4](https://www.tableau.com/support/releases/server). * To preview new features and test your extension with the latest version of Tableau in the Developer Sandbox, join the [Tableau Developer Program](http://www.tableau.com/developer) and request your own Tableau Cloud developer site. About this release: * Minor updates and bug fixes. * Minor corrections and updates to the documentation. See [Add Tableau Workbook Formatting](./core/trex_format.md). * New versions of the JavaScript library and TypeScript types (`1.8.1`). See [Use TypeScript with the Extensions API](./core/trex_typescript.md). ---- #### Tableau Dashboard Extensions API version 1.8 *November 2021* * Tableau Dashboard Extensions API library: `tableau.extensions.1.8.0.js` (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api).) * Certain features in this release are only available in Tableau 2021.4 or later. Preview the features and test your extension with the latest version of Tableau in the Developer Sandbox. To gain access to the Developer Sandbox, join the [Tableau Developer Program](http://www.tableau.com/developer) and request your own Tableau Cloud developer site. About this release: This release contains updates for [Tableau Viz](./core/trex_tableau_viz.md)., including: * Added support for setting the size of a bar mark to be manual (`VizImageSizeSettingType.Manual`) or fixed (`VizImageSizeSettingType.Fixed`). If the type is manual, you can set the mark’s size. If the type is fixed, you can set the alignment (`VizImageSizeSettingAlignmentType`). * Added support for sorting. You can sort a field (continuous or discrete) by ascending or descending values (`VizImageSortDirectionType.Ascending`, `VizImageSortDirectionType.Descending`). ```javascript sort: { field: "Category", sortby: "Weather", direction: tableau.VizImageSortDirectionType.Ascending } ``` * For continuous fields, you can set the color palette to a custom-diverging, or custom-sequential color palette. You are not restricted to using only a Tableau defined palate, such as, `green_blue_white_diverging_10_0`. For example, you could set the custom palette as shown in the following examples: ```javascript palette: tableau.VizImagePaletteType.CustomDiverging, start: "#FFB6C1", end: "#90ee90" ``` Or ```javascript palette: tableau.VizImagePaletteType.CustomSequential, end: "#FFB6C1" ``` * Added support to show or hide grid lines in the view for rows or columns, or both. * Starting with the v1.8 release of the Dashboard Extensions API library and Tableau 2021.4, Tableau Viz now uses Tableau fonts as the default font for text in the output SVG image. For more information, see [Tableau Viz Reference](./trex_tableau_viz_ref.md). ---- #### Tableau Dashboard Extensions API version 1.7 *October 2021* * Tableau Dashboard Extensions API library: `tableau.extensions.1.7.0.js` (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api).) * Certain features in this release are only available in Tableau 2021.4 or later. Preview the features and test your extension with the latest version of Tableau in the Developer Sandbox. To gain access to the Developer Sandbox, join the [Tableau Developer Program](http://www.tableau.com/developer) and request your own Tableau Cloud developer site. About this release: * Added a new method, [`moveAndResizeDashboardObjectsAsync`](pathname:///api/interfaces/Dashboard.html#moveandresizedashboardobjectsasync). you can use to set the position and size of one or more floating dashboard objects. This can be useful for creating overlays, annotations, popups, or dynamic layouts. * Added a new method that can replay an animation in a dashboard. You can control the replay speed (`tableau.ReplaySpeedType.Slow`, `tableau.ReplaySpeedType.Normal`, or `tableau.ReplaySpeedType.Fast`). For more information, see the [`replayAnimationAsync`](pathname:///api/interfaces/Dashboard.html#replayanimationasync) method. * Dashboard extensions can now use workbook formatting by setting the appropriate class on the HTML elements. The specific Tableau classes to use are defined in the [`ClassNameKey`](pathname:///api/enums/ClassNameKey.html) enum. To apply the formatting in the body of your HTML page, use the string literal `tableau-*` for the enum. For example, to apply the worksheet title formatting you set the `class` for the HTML element in your extension (`div`, `h2`, etc.) to `"tableau-worksheet-title"`. ```html

Subheader, using tableau-worksheet-title class

``` To reference the workbook formatting in places outside of the HTML body, use the enum directly (for example, `tableau.ClassNameKey.WorksheetTitle`). ```html ``` You can access the formatting in the Tableau workbook from `tableau.extensions.environment.workbookFormatting`. The property `formattingSheets` contains the array of CSS properties for the workbook, organized by `ClassNameKey`. For more information about using workbook formatting, see the [Formatting](https://github.com/tableau/extensions-api/tree/main/Samples/Dashboard/Formatting) sample in the Samples folder. Also see [Add Tableau Workbook Formatting](./core/trex_format.md). * You can now set an event listener on changes to the dashboard layout and to the dashboard formatting. The new event types are `DashboardLayoutChanged` and `WorkbookFormattingChanged`. The `DashboardLayoutChanged` event is triggered whenever a dashboard object is added, removed, repositioned or resized, or whenever the floating state, visibility, object name, or dashboard size changes. See the [DashboardLayoutChanged](pathname:///api/interfaces/Dashboard.html#dashboardlayoutchanged). event. The `WorkbookFormattingChanged` event is triggered whenever the workbook text formatting is changed in Tableau authoring mode. This includes changes in the font, the font size, whether it is bold, italic, or underlined, and the color. For more information about workbook formatting, see [workbookFormatting](pathname:///api/interfaces/Environment.html#workbookformatting). * Transparency - Tableau now supports dashboard extension transparency for Sandboxed extensions. To take advantage of extension transparency, set your background style to a transparent or partially transparent color. * Added a new method (`setClickThroughAsync`) that allows clicks to pass through the dashboard extension window. You can use this method in conjunction with transparency. See the [setClickThroughAsync](pathname:///api/interfaces/Extensions.html#setclickthroughasync) method. ---- #### Tableau Dashboard Extensions API version 1.6 *September 2021* * Tableau Dashboard Extensions API library: `tableau.extensions.1.6.0.js` (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api).) * Download [Tableau Desktop 2021.3](https://www.tableau.com/support/releases) or [Tableau Server 2021.3](https://www.tableau.com/support/releases/server). About this release: * Tableau Viz is here! ![Tableau Viz SVG image](./assets/vizapi_demo3.svg) Starting with version 1.6 of the Dashboard Extensions API library and Tableau 2021.3, you can now add Tableau visualizations to your dashboard extensions. Tableau Viz takes a declarative description of your visualization and renders it as an SVG image that you can embed in your extension. Version 1.6 of the Dashboard Extensions library adds the [`tableau.extensions.createVizImageAsync`](pathname:///api/interfaces/Extensions.html#createvizimageasync) method, which takes a JavaScript object describing the image as an input. For more information about using Tableau Viz, see: - [Add Tableau Viz to Your Dashboard Extensions](./core/trex_tableau_viz.md) - [Tableau Viz Reference](./trex_tableau_viz_ref.md) - [Tableau Viz Sample - VizImage](https://github.com/tableau/extensions-api/tree/main/Samples/Dashboard/VizImage). New Dashboard Extension API methods in this release: * Added the `getAllDataSourcesAsync()` method to get the data sources for a workbook. * Added the `createVizImageAsync()` method to support Tableau Viz. ---- #### Tableau Dashboard Extensions API version 1.5 *June 2021* * Tableau Dashboard Extensions API library: `tableau.extensions.1.5.0.js` (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api).) About this release: * The `Filter.getFieldAsync` method now works as expected and properly returns the field. This fix requires Tableau 2019.2 and later. * Show/Hide (`setZoneVisibilityAsync`) can now be applied to any dashboard zone. * The `selectMarksByValueAsync` method now supports combined selection criteria types (bug fixed). * The following are all improvements to the [`getSummaryDataAsync`](pathname:///api/interfaces/Worksheet.html#getsummarydataasync) method: * `getSummaryDataAsync` now has a smaller and faster payload. * `maxRows` can be applied to `getSummaryDataAsync` to restrict the number of rows fetched. * `columnsToIncludeById` can be applied to `getSummaryDataAsync` to restrict the columns fetched. * `includeDataValuesOnly` or `includeFormattedValuesOnly` can be applied to `getSummaryDataAsync` to restrict the amount of information returned to what you really need. * The `getSummaryColumnsInfoAsync` method is new in this release. It returns the column information for each column that will be returned in `getSummaryDataAsync`. * The column information now includes the `fieldId` as well as the field name. For more information about changes in this release, see [Tableau Extensions v1.5.0](https://github.com/tableau/extensions-api/releases/tag/v1.5.0). ---- #### Tableau 2021.1 Updates *March 2021* * You can now use Chrome version 80 and later to debug your dashboard extension in Tableau Desktop. If you are using Tableau 2021.1, or the latest maintenance releases of Tableau 2020.2, 2020.3, or 2020.4, you no longer need to use Chromium (version 79 or earlier) for debugging. For more information, see [Debug Extensions in Tableau Desktop](./debug/trex_debugging.md) and [Download the Chromium Browser](./debug/trex_debugging.md#download-the-chromium-browser). * If you plan to implement OAuth in your dashboard extension, you'll want to check out [Add OAuth to Dashboard Extensions](./security/trex_oauth.md), and the OAuth sample ([datadev-oauth-sign-in](https://glitch.com/~datadev-oauth-sign-in).) on Glitch. * Because of browser changes in Tableau, dashboard extensions running with self-signed certificates (SSL) might not work in Tableau 2021.1, or in the most recent Tableau maintenance releases: 2020.2.7+, 2020.3.6+, and 2020.4.2+. For more information, see [Known Issues](./trex_known_issues.md#unable_self_signed_cert). #### Tableau Dashboard Extensions API version 1.4 *May 2020* * Tableau Dashboard Extensions API library: `tableau.extensions.1.4.0.js` (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api).). About this release: * To support the logical and physical tables introduced in Tableau 2020.2, the Tableau Dashboard Extensions API (version 1.4) provides new APIs and data structures. Use these new methods to get the underlying data from data sources and worksheets. The new methods replace `getUnderlyingDataAsync`. Starting in Tableau 2020.2, a data source could have multiple logical tables, and logical tables can contain one or more physical tables. If you have an existing extension that uses one of the deprecated methods to get underlying data, the method call could fail if the data source contains more than one logical table. You should update your extensions to use these new methods. The new methods are backward compatible with previous versions of Tableau. | Interface | Deprecated method (v1.3 and earlier) | New method (v1.4 and later) | | :------------------| :-------------- |:-----------| | `Datasource` | `datasource.getActiveTablesAsync` | `datasource.getLogicalTablesAsync` | | `Datasource` | `datasource.getUnderlyingDataAsync` | `datasource.getLogicalTableDataAsync` | | `Worksheet` | Not Applicable | `worksheet.getUnderlyingTablesAsync` | | `Worksheet` | `worksheet.getUnderlyingDataAsync` | `worksheet.getUnderlyingTableDataAsync` | To support the data model, the API also includes the `LogicalTable` object that has two properties: `caption` and `id`. The `caption` is the name of the logical table as it appears in Tableau. For more information about getting underlying data from data sources and worksheets, see [Get Data from the Dashboard](./core/trex_getdata.md). For information about the data model, see [The Tableau Data Model](https://help.tableau.com/current/pro/desktop/en-us/datasource_datamodel.htm). * `DataValue` now has a `nativeValue` member. This member represents the raw native value as a JavaScript type, which is one of string, number, boolean, or Date object. Note that special values are returned as null. The `nativeValue` helps simplify error checking as all values will either be their native type value or null. The `nativeValue` exists for *ALL* `DataValue` objects, including those returned from parameters, filters, selections, and underlying or summary data. Dates values are in UTC. * Added documentation for the [clearSelectedMarksAsync()](pathname:///api/interfaces/Worksheet.html#clearselectedmarksasync) method, which clears the selected marks in the current worksheet. Bugs fixed in this release: * Range filters now work correctly when the minimum or maximum values are equal to zero (0). Previously, calls to the `applyRangeFilterAsync()` method would ignore the `RangeFilterOptions` if the `min` or `max` properties were equal to zero (0). * The `isVisible` attribute for dashboard zones is now set properly to true or false when the extension is initialized. * The `setZoneVisibilityAsync()` method now supports ES6 map objects for the `zoneVisibilityMap` parameter. ---- #### Tableau Sandboxed Extensions Development Environment *September 2019* * Sandboxed Extensions are Tableau dashboard extensions that are not permitted to make external network requests. Available for testing with Tableau 2019.3. Fully supported in Tableau 2019.4. * The Extensions API SDK provides a local development environment that replicates the Tableau Hosting Cloud Service for Sandboxed Extensions. You can test your Sandboxed extensions locally with the same sandbox policies before submitting the extension to Tableau for publication. See [Create and Test Sandboxed Extensions](./security/trex_sandbox_test.md) and [Publish Sandboxed Extensions](./publish/trex_sandbox_publish.md). ---- #### Extensions API library v1.3 *July 2019* - Tableau Extensions API library: `tableau.extensions.1.3.0.js` (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api).) About this release: - The Extensions API library version 1.3 (`tableau.extensions.1.3.0.js`) is backward compatible with previous releases of the library. - Now available: Extensions API type definitions and new TypeScript samples. The latest release provides the TypeScript type definitions so that you can author your extension using TypeScript. See [Use TypeScript with the Extensions API](./core/trex_typescript.md) and [TypeScript Sample Extensions](https://github.com/tableau/extensions-api/tree/master/Samples-Typescript). on GitHub. - New all-values-selected property for categorical filters (`filter.isAllSelected`). You can use this new property to determine when all values of categorical filters are selected. The `isAllSelected` property is a Boolean and returns True or False. Prior to this release, there was no way to tell if all values of categorical filters were selected. The `filter.appliedValues` method returns empty array when **(All)** is selected, so there is no way to use that method to determine if all values are selected or if no values are selected. The `isAllSelected` property is available starting with Tableau 2019.2 and the Extensions API library version 1.3 (`tableau.extensions.1.3.0.js`). ```javascript worksheet.getFiltersAsync().then((filters) => { let filter = filters[0]; if (filter.filterType === tableau.filterType.Categorical) { console.log(filter.isAllSelected); } } ``` ---- #### Extensions API library v1.2 *April 2019* * Tableau Extensions API library: `tableau.extensions.1.2.0.js` (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api).) About this release: * The Extensions API library version 1.2 (`tableau.extensions.1.2.0.js`) is backward compatible with previous releases of the library. You can use the Extensions API library version 1.2 for extensions on Tableau 2018.2 and later. The library contains logic to handle any necessary conversions for the supported version of Tableau the extension is running in. For the best experience, you should always use the latest version of the library with the extensions you create. * The names of the Extension API library files have changed. The hyphens (-) have been removed from the file name (was `tableau-extensions-*`, now `tableau.extensions.*`). Starting with the 1.2 library, the names of the library files are as follows: ``` tableau.extensions.1.2.0.js tableau.extensions.1.2.0.min.js tableau.extensions.1.latest.js tableau.extensions.1.latest.min.js ``` **Note** If you have previously been referencing `tableau-extensions-1.latest.js` in your code, you will need to use the new naming convention when you upgrade to the 1.2 library (`tableau.extensions.1.latest.js`). Bugs fixed in this release: * Fixed in the Extensions API library 1.2, the type of `DataValue.value` is now the raw native value as a JavaScript type, rather than always defaulting to **String**. A `DataValue.value` can be one of the following JavaScript types: **String**, **Number**, **Boolean**, or **Date**. A `DataValue` is returned as a property of a `DataTable` in methods, such as `getSummaryDataAsync()` or `getUnderlyingDataAsync()`. Note that special values, regardless of type, are always returned as **String** values surrounded by percent signs, such as `%null%`, or `%no-access%`. **Important!** If your code depended on the type of `DataValue.value` always being a **String**, that code will now break with this fix. * The `environment.apiVersion` property now correctly reports the version of the Extensions API library that the extension is using. * The documentation for the selectMarksByValueAsync method has been corrected. If you are calling the method, be sure to specify the complete namespace for the `SelectionUpdateType` enum that is passed to the method as the `updateType` parameter. For example, use `tableau.SelectionUpdateType.Replace`, to replace the currently selected marks with the values you specify in the method call. ---- #### Tableau 2019.1 *February 2019* * Tableau Extensions API library: `tableau-extensions-1.1.0.js` (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api).) * Download [Tableau Desktop 2019.1](https://www.tableau.com/support/releases) or [Tableau Server 2019.1](https://www.tableau.com/support/releases/server). Changes in this release: * Upgrade to the Chromium browser, which allows modern web technologies to be used with dashboard extensions (HTML 5, CSS, native ES6 support). Tableau 2019.1 now uses Qt 5.10, The Qt WebEngine is based upon Chromium 61.0.3163.99, with additional security fixes from newer versions. With this update, you no longer need to download and use a specific version of Chromium (47.0.2526.0) to debug dashboard extensions on Tableau Desktop. You can now debug extensions in Tableau Desktop using Chrome. * Show and hide capabilities for extensions (now you see it, now you don't). For more information, see [Show and Hide Objects in the Dashboard](./core/trex_show_hide.md). Bugs fixed in this release: * Select dropdown fixed on Macintosh. (TFSID 758234) * The `applyRangeFilterAsync` method allows full range of options, and doesn't break when a user selects "all". (TFSID 766488) * Fixed “Access is denied” error encountered when switching from a sheet containing an extension to any other sheet on a tabbed workbook on server (fixed in Tableau 2019.1, 2018.3.2, 2018.2.5). * Full support for IE11 now starts in 2018.2.3, 2018.2.3. * Fixed in Tableau Desktop 2019.1: Extension API synchronization issue. In previous version of Tableau Desktop (2018.2, 2018.3), the execution of extension API calls was not properly synchronized with longer running actions. These issues would most often occur with a worksheet that took multiple seconds to refresh. This could manifest itself in various ways: * The `intializeAsync` method could return the promise before the dashboard was properly loaded in Tableau. * A `FilterChanged` event could be triggered before the data was actually refreshed. As a result, calls to `getSummaryDataAsync` could return the data before the filter was changed. * If an extension API was called from a `setInterval` or similar function, while other actions were going on, Tableau could occasionally crash. Customers who upgrade to Tableau Desktop 2019.1 will not have these synchronization issues with extensions. --- #### Tableau 2018.3 *November 2018* - Tableau Extensions API library: `tableau-extensions-1.0.0.js` *No change for this release* (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api).) - Download [Tableau Desktop 2018.3](https://www.tableau.com/support/releases) or [Tableau Server 2018.3](https://www.tableau.com/support/releases/server). New in this release: - Updated documentation. [Getting Started](./dashext/trex_getstarted.md), [Create a "Hello World" Dashboard Extension](./dashext/trex_create.md), [Debugging Extensions on Tableau Desktop](./debug/trex_debugging.md), [Debugging Extensions on Tableau Server and Tableau Cloud](./debug/trex_debug_server.md), [Error Codes and Error Handling for Extensions](./debug/trex_error_handling.md). --- #### TC18 *October 2018* - Tableau Extensions API library: `tableau-extensions-1.0.0.js` *No change for this release* New in this release: - Use the [Design Guidelines for Dashboard Extensions](./ux_design.md) as a roadmap for designing great dashboard extensions. - Create extensions with the look-and-feel of Tableau, using the [Tableau UI](https://tableau.github.io/tableau-ui/.md), a React component library. - New and updated documentation. See [Publishing a Dashboard Extension](./publish/trex_publish.md). For information about developing and running an extension locally on `http://localhost` and testing it on Tableau Cloud or Tableau Server (over HTTPS), see [Load and view localhost content on sites that use secure connections](./security/trex_security.md#load-and-view-localhost-content-on-sites-that-use-secure-connections). Bugs fixed in this release: - Extensions are now fully supported in Internet Explorer (IE 11). --- #### Tableau 2018.2 *July 2018* Release of the Tableau Extensions API - Tableau Extensions API library: `tableau-extensions-1.0.0.js` (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api).) - Download [Tableau Desktop 2018.2](https://www.tableau.com/support/releases) or [Tableau Server 2018.2](https://www.tableau.com/support/releases/server). Bugs fixed in this release: - Extensions are now fully supported in Internet Explorer (IE 11). #### Tableau 2018.2 (Beta 2) *June 4, 2018* Update of the Tableau Extensions API - Tableau Extensions API library: `tableau-extensions-0.16.0.js` - Download Tableau Desktop, Tableau Server from [Tableau 2018.2 Beta](https://prerelease.tableau.com/project/home.html?cap=c43269484c1f45a68f5ad4fc4660b2ab). Changes in this release: - XML Schema: This release introduces two changes to the XML schema for the extensions manifest file (`.trex`). If you have an existing `.trex` file, you need to make a couple of corrections. - The first change is to the URL of the extensions namespace (`xmlns`). The URL is now `www.tableau.com...` instead of `wwww.tableau.com...` ```xml ... ``` - The second change is to the author's web site. This link to your web site must now be over HTTPS for security. This link to your web site will become the **Get Support** link in the **About** dialog box for your extension. Users will be able to click the link to get to the help page that you provide. ```xml ``` - Extensions settings and permissions in Tableau Server Server administrators can manage dashboard extensions on the **Settings > Extensions** tab (for each site and for the server). By default, only extensions that do not require full data access are allowed to run. HTTPS is required. Server administrators can enable dashboard extensions that are trusted to access full data by adding them to a safe list for a site. Server administrators can control whether or not the users will see prompts (asking them to allow the extension to access data) when users are adding an extension to a dashboard, or when they are interacting with a view that has an extension. For more information, see [Dashboard Extensions in Tableau Server](https://onlinehelp.tableau.com/current/server/en-us/dashboard_extensions_server.htm). - The **About** dialog box. Users can now find out about an extension in the dashboard by selecting the layout container and then clicking **About** from the **More Options** menu. Information from the extension manifest file (`.trex`) is used to populate a dialog box. (Note that the dialog box you see might look slightly different from this example.) ![](./assets/about_extension_dialog.png) --- #### Tableau 2018.2 (Beta 1) *April 26, 2018* Download Tableau Desktop, Tableau Server from [Tableau 2018.2 Beta](https://prerelease.tableau.com/project/home.html?cap=c43269484c1f45a68f5ad4fc4660b2ab). --- #### Developer Preview (0.12.8) *April 13, 2018* Update of the Tableau Extensions API - Tableau Extensions API library: `tableau-extensions-0.12.8.js` - Tableau Desktop, Tableau Server (from [Extensions API Developer Preview](https://prerelease.tableau.com/project/home.html?cap=52e2710a0793434d82142736c7ab3029).) Changes in this release: - This release of Tableau introduces a minor change in the workbook format that affects extensions. If you saved a workbook with an extension using an earlier version of Tableau, and then open the workbook with this current Tableau release, the workbook will open, but it will not have the extension. You will have to add the extension back in using the latest release of Tableau. Bugs fixed in this release: - Certain keyboard shortcuts were intercepted by Tableau and not passed on to the extension. This is now fixed, with the excecption of **cmd + V** on Mac, which will be fixed in a later release. ([Issues #76](https://github.com/tableau/extensions-api/issues/76)) - Calls to `getSummaryDataAsync()` or `getUnderlyingDataAsync()` would not return the correct data types for the columns. Column property `datatype` returned `string` for all columns, regardless of actual data type of column. - Web Authoring would throw an exception when an extension is added. - XSD validation of `minApiVersion` accepted only single digit version numbers (for example, `0.12` would fail). - Permissions denied error message would disappear after the dashboard zone was reloaded. #### Developer Preview (0.12.8) *April 13, 2018* Update of the Tableau Extensions API - Tableau Extensions API library: `tableau-extensions-0.12.8.js` - Tableau Desktop, Tableau Server (from [Extensions API Developer Preview](https://prerelease.tableau.com/project/home.html?cap=52e2710a0793434d82142736c7ab3029).) Changes in this release: - This release of Tableau introduces a minor change in the workbook format that affects extensions. If you saved a workbook with an extension using an earlier version of Tableau, and then open the workbook with this current Tableau release, the workbook will open, but it will not have the extension. You will have to add the extension back in using the latest release of Tableau. Bugs fixed in this release: - Certain keyboard shortcuts were intercepted by Tableau and not passed on to the extension. This is now fixed, with the excecption of **cmd + V** on Mac, which will be fixed in a later release. ([Issues #76](https://github.com/tableau/extensions-api/issues/76)) - Calls to `getSummaryDataAsync()` or `getUnderlyingDataAsync()` would not return the correct data types for the columns. Column property `datatype` returned `string` for all columns, regardless of actual data type of column. - Web Authoring would throw an exception when an extension is added. - XSD validation of `minApiVersion` accepted only single digit version numbers (for example, `0.12` would fail). - Permissions denied error message would disappear after the dashboard zone was reloaded. --- #### Developer Preview (0.12.7) *March 28, 2018* Update of the Tableau Extensions API - Tableau Extensions API library: `tableau-extensions-0.12.7.js` - Tableau Desktop, Tableau Server (from [Extensions API Developer Preview](https://prerelease.tableau.com).) Updated in this release: - Extensions API library goes to `12` (one better than `11`). The library has been refactored to be smaller, faster, lighter. - Dashboard authors and users of your extension can decide whether to allow the extension to run or not. When users add an extension that can access the underlying data in a dashboard, they now see a prompt that lets them allow the extension to run. In addition, when someone opens a dashboard that contains extensions, they see a dialog box that lists information about all the extensions in the dashboard, and a prompt to allow the extensions to run. For more information, see [Accessing Underlying Data](./security/trex_data_access.md) - Starting with the `0.12.7` release, the Extensions API library supports versioning. Future versions of Tableau will be able to run extensions that use earlier versions of the Extensions API library (`0.12.7` and later). You will no longer need to roll the version number of the library in your extension at every release just to enable it to run in Tableau. For example, a dashboard extension that uses the Extensions API `0.12.7` library should run in a future release of Tableau without modification. And Tableau will provide a meaningful error message if you try to run an extension that requires a later version of the Extensions API library than the version of the API that a particular Tableau release supports. For example, if the extension uses the `0.14.0` library but the version of Tableau only supports an earlier version (`0.12.7`), users of the extension will see a message informing them that they need a later version of Tableau. Bug fixes: - Canceling extensions selection causes error - Parameters (Desktop): Tableau crashes if you add a filter based off of a parameter to a dashboard - Saving and opening a workbook that has an extension throws error - Parameter Changed Notification not working on server - Extension dialog box height and width are reversed --- #### Developer Preview (0.10.0) *February 28, 2018* - Update of the Tableau Extensions API - Tableau Extensions API library: `tableau-extensions-0.10.0.js` - Tableau Desktop, Tableau Server (from [Extensions API Developer Preview](https://prerelease.tableau.com).) Updates in this release: - New *configure feature*, which allows you to register a custom JavaScript callback for a context menu item in the extension zone. See [Adding a configuration dialog box](#adding-a-configuration-menu-item) and the [UINamespace](https://github.com/tableau/extensions-api/tree/master/Samples/Dashboard/UINamespace?=target="_blank") sample. - A fix for a problem that existed in the 0.9.0 release that caused extension initialization to break on Tableau Server. For other changes with this release, see [Known Issues](https://prerelease.tableau.com/project/article/default.html?cap=52e2710a0793434d82142736c7ab3029&arttypeid=f592dc03830d480a862740e4a6bde998) on the [Extensions API Developer Preview](https://prerelease.tableau.com). site. --- ##### Adding a configuration menu item You can use a new callback function option to `initializeAsync()` as a way to create a configuration option that opens a window or dialog box for your extension. To do this you first add the context-menu option to the extensions manifest file (`.trex`). **Add `` to the .trex file** ```xml ``` **Create a configuration function** When you initialize an extension, you can now pass an optional `contextMenuCallbacks` object to the `initializeAsync()` function. This object maps a special ID or key (which must be `'configure'`) to a function you create. The function you create, in conjunction with adding a `` item to the manifest, adds a new **Configure...** context menu item to the zone of the extension inside a dashboard. When the user clicks the context menu item, the configuration function you specified is executed. For example, you could use the UI namespace and have the configuration function call the `displayDialogAsync()` function to create a dialog box that can be used to change settings for the extension. The parent (or initial window) for your extension, might have the following JavaScript code. ```javascript $(document).ready(function () { // ... // pass the object to initializeAsync() to map 'configure' key to a function called configure() // ... tableau.extensions.initializeAsync({'configure': configure}).then(function() { // ... // ... code to set up event handlers for changes to configuration }); }); }); function configure() { // ... code to configure the extension // for example, set up and call displayDialogAsync() to create the configuration window // and set initial settings and handle the return payload // ... tableau.extensions.ui.displayDialogAsync(popupUrl, defaultIntervalInMin, { height: 500, width: 500 }).then((closePayload) => { // The promise is resolved when the dialog has been expectedly closed, meaning that // the popup extension has called tableau.extensions.ui.closeDialog. // ... // The close payload is returned from the popup extension via the closeDialog() method. // .... }).catch((error) => { // ... // ... code for error handling }); } ``` To better understand how to use the context menu, and to see it in action, check out the updated [UINamespace](https://github.com/tableau/extensions-api/tree/master/Samples/Dashboard/UINamespace?=target="_blank") sample. --- #### Developer Preview (0.9.0) *February 14, 2018* - Update of the Tableau Extensions API - Tableau Extensions API library: `tableau-extensions-0.9.0.js` - Tableau Desktop (from [Extensions API Developer Preview](https://prerelease.tableau.com).) Updates in this release: - [Updates to the UI namespace](#updates-to-the-ui-namespace) - [Permissions added to access full data](#permissions-added-to-access-full-data) - [Error codes for extensions](#error-codes-for-extensions) ##### Updates to the UI namespace This preview release introduces more options for the UI namespace. You can now control the initial sizing (height, width) of a modal dialog box (or *popup*). The modal dialog itself is an extension. Using the `displayDialogAsync()` and `closeDialog()` methods you can pass payloads between the calling extension and the extension running in the modal dialog box. For an example of how you can use the UI namespace to create a configuration dialog box, see the [UINamespace](https://github.com/tableau/extensions-api/tree/master/Samples/Dashboard/UINamespace?=target="_blank") sample. The sample also shows how to use the settings event to capture the new configuration. The sample source code has extensive comments that describe how to use these new features in the Extensions API. - New sample: [UINamespace](https://github.com/tableau/extensions-api/tree/master/Samples/Dashboard/UINamespace?=target="_blank") ##### Permissions added to access full data To access the underlying data along with information about the data source, the extension must declare that it requires full data access in the extension manifest file (`.trex`). An extension requires full data access, if the extension uses any of the following four APIs: `Worksheet.getUnderlyingDataAsync()` `Datasource.getUnderlyingDataAsync()` `Datasource.getActiveTablesAsync()` `Datasource.getConnectionSummariesAsync()` If you use any of these APIs, you need to add a `` element to the manifest file (`.trex`) and specify full data permission. The XML looks like the following: ```xml full data ``` The `` element must be added under `` in the manifest file. For a complete description of the manifest, see the [Tableau Extensions Manifest File](./dashext/trex_manifest.md). If full data is not declared in the manifest file, and the extensions calls one of the APIs that accesses any underlying data or data source information, the API call fails. In addition, an error is written to the Tableau log file (`log.txt`). If you are debugging the extension with the Chromium web browser, an error is reported the console pane. The error message would look similar to the following: ``` PermissionValidation.ts:26 Extension (name = DataSources Sample, ID = com.tableau.extensions.demo.local) is missing required permission: full-data Error: internal-error: permission-denied: Missing required permission to run get-underlying-data(...) ``` ##### Error codes for extensions Errors that are returned from the Extensions API are custom Tableau Error objects that extends the standard JavaScript error object. The Extensions API wraps the standard error object with an `errorCode` property. Any time you encounter an error when you are developing your extension, you can look at this `errorCode` to determine the cause. See [Error Codes](pathname:///api/enums/ErrorCodes.html). For an example of how to handle error conditions, see the [UINamespace](https://github.com/tableau/extensions-api/tree/main/Samples/Dashboard/UINamespace?=target="_blank") sample. The sample shows how you could handle the error condition that occurs if a user dismisses a modal dialog box (`DialogClosedByUser`). The following snippet illustrates this pattern: ```javascript tableau.extensions.ui.displayDialogAsync(args... ).then((args... ) => { // // code that sets up the extension in the modal dialog box // }).catch((error) => { // One expected error condition is when the popup is closed by the user // (meaning the user clicks the 'X' in the top right of the dialog). // This can be checked for with: switch(error.errorCode) { case tableau.ErrorCodes.DialogClosedByUser: console.log("Dialog was closed by user"); break; default: console.error(error.message); } }); ``` --- #### Developer Preview (0.8.0) *January 10, 2017* - Update of the Tableau Extensions API. - Tableau Extensions API library: `tableau-extensions-0.8.0.js` - Tableau Desktop 10.5 RC, Tableau Server 10.5 (from [Extensions API Developer Preview](https://prerelease.tableau.com).) **New desktop authoring experience** You no longer need to place the `.trex` file for the extension in a predetermined folder, you now do the following: 1. In the dashboard, under **Objects** on the left, select **Extension** and drag it to the dashboard sheet on the right. The **Select an Extension** dialog box appears. 2. The first time you open the dialog box to add an extension, you will see a link to **Choose an Extension**. Click the link and browse to the directory where you have the `.trex` file. Subsequently, when you drag the **Extension** on the dashboard, the dialog box shows you the most recently used list, choose from the list, or click **Browse** to select another extension. **New UI namespace** - You can now launch a new modal dialog using the function: `tableau.extensions.ui.displayDialogAsync(dialogExtensionURL)`. - The URL you want to load (`dialogExtensionURL`) will be an extension itself. - The extension in the dialog will have full access to the extensions API. When ready to close to the dialog, from the dialog extension you can call `tableau.extensions.ui.closeDialog(string)`. See the documentation for details. - Note that the UI namespace is work is still in progress and has some upcoming additions. *Stay tuned for more.* **HTTPS and security** For information about the HTTPS requirements for extensions, see [Security and Tableau Extensions](./security/trex_security) **Remote Debugging** Due to changes in this release, remote debugging does not work as expected in Tableau Desktop. To enable debugging, you must add the `--remote-debugging-port=8696` option to the command used to start Tableau. The easiest way to do this is to open the Tableau shortcut on the **Start** menu. Open the file location of the Tableau shortcut. Right-click the Tableau shortcut and click **Properties**. In the Target text box, append the remote debugging option to the command. Do not enclose the option in quotation marks. ``` "C:\Program Files\Tableau\Tableau main\bin\tableau.exe" --remote-debugging-port=8696 ``` For information about debugging extensions, see [Remote Debugging of JavaScript and HTML](./debug/trex_debugging.md). --- #### Developer Preview (0.7.0) *November 29, 2017* - Update of the Tableau Extensions API. - Tableau Extensions API library: `tableau-extensions-0.7.0.js` - Tableau Desktop 10.5 RC, Tableau Server 10.5 (from [Extensions API Developer Preview](https://prerelease.tableau.com).) **Breaking change** - Schema change - Updated XSD file for the dashboard extensions manifest file (`.trex`). If you have an existing extension, you must update the `.trex` file to follow the new schema. There is a script you can run that converts the manifest file for you. Or you can manually make the changes. For more information about the manifest, see [Tableau Extension Manifest File](./dashext/trex_manifest.md). You can download the manifest conversion script from the **Extensions API Developer Preview** on [https://prerelease.tableau.com](https://prerelease.tableau.com). - Existing workbooks - if you have an existing workbook that uses a dashboard extension, you will not be able to open it with this (`0.7.0`) release. To get around this issue, update the manifest file (`.trex`), update your extension to use `tableau-extensions-0.7.0.js`, and then open a new workbook and re-create the dashboard. **New features** - Tableau Server. You can publish dashboards containing extensions and run them on Tableau Server. You can download a version of Tableau Server 10.5 that supports dashboard extensions from the **Extensions API Developer Preview** on [https://prerelease.tableau.com](https://prerelease.tableau.com). - Security - Your dashboard extension must use an HTTPS connection. If you are using `localhost` for development, you can still use HTTP. - Sharing dashboards - the dashboard extension now gets saved with the workbook, so you can share your workbooks that use the extension with others. - New method `DataSource.getConnectionSummariesAsync` gets a summary object for each underlying connection in a data source. - New method `DataSource.getActiveTablesAsync` gets all tables used to create the data source (what you would see in the join canvas). - Logging - You can view dashboard extension activity in Tableau log files. Tableau records extension events that you can use to troubleshoot registration errors and command execution. See [Use Log files to Troubleshoot Dashboard Extensions](./debug/trex_logging.md). **Bug fixes** - The `Worksheet.clearFiltersAsync` method no longer removes filters from your worksheets, but properly resets the filters to a default state. - The name of the selected dashboard extension now appears instead of "other" in the dashboard Layout pane. --- #### Developer Preview (0.6.0) *Oct 10, 2017* Initial release of the Tableau Extensions API. Provides support for dashboard extensions. Tableau Extensions API library: `tableau-extensions-0.6.0.js` Tableau Desktop 10.5 beta --- ## Known Issues for the Tableau Extensions API The following section describes some issues in the current release of the Extensions API where the API or the platform does not behave as expected. For information about what is new or has changed in each release, see the [Release Notes for the Tableau Extensions API](./trex_release-notes.md). #### Extensions that share the same identifiers will not load properly 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). --- #### Tableau Viz - Known Issues Tableau Viz provides a way to create visualizations in dashboard extensions. The following is a list of issues with the current release of Tableau Viz. * The vertical header text appears slightly cropped in the SVG output. * Tableau fonts aren't available in the SVG output. For information about Tableau Viz, see [Add Tableau Viz to Your Dashboard Extension](./core/trex_tableau_viz.md). --- #### Unable to debug extensions using Chrome version 80 or later Because of incompatibilities between Chrome and the internal Chromium-based browser used in Tableau, you can't use Chrome version 80 or later to debug your extensions. If you are using Tableau Desktop 2019.1 or later, you can debug extensions using Chrome version 79 or Chromium version 79. If you are using Tableau Desktop versions 2018.2 or 2018.3, you can use Chromium version 47. For more information about debugging extensions and using the Chromium browser, see [Debug Extensions in Tableau Desktop](./debug/trex_debugging.md) and [Download the Chromium Browser](./debug/trex_debugging.md#download-the-chromium-browser). --- #### Unable to run dashboard extension using self-signed certificates {#unable_self_signed_cert} Tableau now uses Qt WebEngine 5.15, which is based on Chromium version 87.0.4280, with additional security fixes from newer versions of Chromium. Because of this update, dashboard extensions hosted on web servers that use self-signed certificates (SSL) might not work in Tableau 2021.1, or in the most recent Tableau maintenance releases: 2020.2.7+, 2020.3.6+, and 2020.4.2+. You might see one of the following errors: * `Failed to load resource: net::ERR_CERT_COMMON_NAME_INVALID` * `Error: Subject Alternative Name Missing` * `Your connection is not private` You can avoid these errors if you specify the `subjectAlternativeName` (SAN) in the extended certificate parameters when you sign your certificate. For more information, see [Google Chromium Enterprise Known Issues - Error "Subject Alternative Name Missing"](https://support.google.com/chrome/a/answer/9813310?hl=en#zippy=%2Cerror-subject-alternative-name-missing-or-neterr-cert-common-name-invalid-or-your-connection-is-not-private) and the following discussion on Stack Overflow: [Invalid self signed SSL cert - “Subject Alternative Name Missing” on StackOverflow](https://stackoverflow.com/questions/43665243/invalid-self-signed-ssl-cert-subject-alternative-name-missing). --- #### Time zone not persisted when updating date parameter When you update a date or date-time parameter using `changeValueAsync()`, the time zone information is not kept. The date/time is still correct, however, it is just that the data/time is converted to UTC. --- #### The getDataSourcesAsync method is slow If your extension uses the `getDataSourcesAsync()` method, calling this method might negatively impact performance and responsiveness of the viz that your extension is added to. The method is not entirely asynchronous and includes some serial operations. --- #### Unable to print or save image of the extension in a dashboard * If you print a dashboard to a `.pdf` file, or save the dashboard as an image (or receive an image of the dashboard, as part of subscription) the zone that contains the extension will be blank. --- #### HTML drop-down menus in popup dialog windows * **Fixed in Tableau 2019.1** HTML drop-down menus in popup dialog windows do not work as expected on MacOS. Users will not be able to select menu items using the mouse. They can select items with the cursor keys. To avoid issues on MacOS, use radio buttons or another method for user selection in the popup dialog. --- #### Decimal separators in parameters - Decimal separators in parameters are not handled as expected for some locales. If your operating system locale uses commas for decimal separators, the `parameter.changeValueAsync` function expects a string that uses a comma as the decimal separator; however, the `parameter.currentValue` function will return a string using a period as the decimal separator, regardless of locale settings. --- #### Full data access and permission errors When an extension needs full data access and the user does not have full data permission on the workbook, Tableau currently allows the extension to run. However, Tableau will throw a console error when the extension calls `getUnderlyingData()` method. See [Handle full data access and permission errors](./core/trex_getdata.md#handle-full-data-access-and-permission-errors). --- #### Tableau Extensions API library version 1.0.0 If you are debugging your extension, you might see this message in the Debugging Tools console window if you are using the released version of the 1.0.0 library (for example, `tableau-extensions-1.0.0.js`) with a version of Tableau that is newer than Tableau 2018.2. ```cli This is an alpha version of the Extensions API. Please upgrade to an official release. ``` You can safely ignore this warning. However, if you are using the 1.0.0 library, be sure to upgrade to the latest version. To avoid having to update your code to reference a new version of the 1.x library every time you download a new version, you can specify `tableau.extensions.1.latest.js`. That way, when you replace the previous version of the library with the most recent update, your extension should just work. ```html ``` --- ## About Tableau Help ### Addressing Implicit Bias in Technical Language In an effort to align with one of our core company values, equality, we have changed terminology to be more inclusive where possible. Because changing terms in code can break current implementations, we maintain the current terminology in the following places: * Tableau APIs: methods, parameters, and variables * Tableau CLIs: commands and options * Installers, installation directories, and terms in configuration files * (Undefined variable: `Variables.PT_server_long`) (we plan to make changes to non-inclusive terminology in the web interface, error messages, and related documentation soon.) * Third-party systems documentation For more information about our ongoing effort to address implicit bias, see [Salesforce Updates Technical Language in Ongoing Effort to Address Implicit Bias](https://www.salesforce.com/news/stories/salesforce-updates-technical-language-in-ongoing-effort-to-address-implicit-bias/?_ga=2.61225580.1994005306.1652119972-235774019.1630077324) on the Salesforce website.