- [Add Tableau Viz to Your Dashboard Extensions](./core/trex_tableau_viz) - [Tableau Viz Reference](./trex_tableau_viz_ref) - - [Tableau Viz Sample - VizImage](https://github.com/tableau/extensions-api/tree/main/Samples/VizImage). + - [Tableau Viz Sample - VizImage](https://github.com/tableau/extensions-api/tree/main/Samples/Dashboard/VizImage). New Dashboard Extension API methods in this release: @@ -666,7 +666,7 @@ Bug fixes: 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/UINamespace?=target="_blank") sample. +- 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. @@ -735,7 +735,7 @@ $(document).ready(function () { }); } ``` -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/UINamespace?=target="_blank") sample. +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. --- @@ -756,9 +756,9 @@ Updates in this release: #### 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/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. + 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/UINamespace?=target="_blank") +- New sample: [UINamespace](https://github.com/tableau/extensions-api/tree/master/Samples/Dashboard/UINamespace?=target="_blank") #### Permissions added to access full data @@ -805,7 +805,7 @@ Errors that are returned from the Extensions API are custom Tableau 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/tableau.errorcodes.html). -For an example of how to handle error conditions, see the [UINamespace](https://github.com/tableau/extensions-api/tree/main/Samples/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: +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... ) => { diff --git a/website/docs/vizext/trex_viz_create.md b/website/docs/vizext/trex_viz_create.md index 27a3d53f..5d49368b 100644 --- a/website/docs/vizext/trex_viz_create.md +++ b/website/docs/vizext/trex_viz_create.md @@ -21,7 +21,7 @@ To create a Tableau viz extension you need the following components. These instructions assume that you have already cloned or download the Extensions API SDK. For information about setting up your environment and the Tableau requirements, see [Get Started](./trex_viz_getstarted). -For convenience, you might want to create a folder for your "Hello World" viz extension in the same location where you installed or cloned the GitHub repository. Create your folder, for example, **HelloVizExtension** in the Samples folder, under `/extensions-api-preview`. That way, you can use the same web server (`http-server`) that is used for the samples. +For convenience, you might want to create a folder for your "Hello World" viz extension in the same location where you installed or cloned the GitHub repository. Create your folder, for example, **HelloVizExtension** in the Samples folder, under `/extensions-api/Samples`. That way, you can use the same web server (`http-server`) that is used for the samples. --- @@ -63,7 +63,7 @@ Name the manifest file for your extension (for example, `HelloVizExtension` and - In this file, you need to provide values for a few elements. Some key pieces are: - For `
The URL of the server must match the `SERVER` in the manifest file for the extension. Be sure to include the `http://` or `https://` in the URL. If you are using your `localhost` for development work, you might want to use the same lightweight web server that is used for the Extensions API samples and tutorial. Assuming that you've cloned or downloaded the repository, and that you've created a folder under `/extensions-api-preview`, you can start the server by using the `npm start` command. Or if you need to use a different port and location, you can install and start the `http-server` yourself (replacing PORT with the port you need and that matches the port you specified in the manifest file): +1. Start the web service to verify you have the web app and files configured.
The URL of the server must match the `SERVER` in the manifest file for the extension. Be sure to include the `http://` or `https://` in the URL. If you are using your `localhost` for development work, you might want to use the same lightweight web server that is used for the Extensions API samples and tutorial. Assuming that you've cloned or downloaded the repository, and that you've created a folder under `/extensions-api`, you can start the server by using the `npm start` command. Or if you need to use a different port and location, you can install and start the `http-server` yourself (replacing PORT with the port you need and that matches the port you specified in the manifest file): ```bash @@ -162,9 +169,13 @@ For this developer preview, it makes your life easier if you place your own exte After you have created the manifest file (`.trex`) and have hosted your web app you can test it in Tableau. It's a good idea to do this even if your application isn't completed. +:::note +If you are using Tableau Cloud or Tableau Server, you need to make sure you've added the URL of your extension to the allow list. See this [note about location](#location-location-location). +::: + 1. Start up your web page or application (or make sure it is running). -1. Log on to Tableau Cloud [https://us-west-2a.online.tableau.com](https://us-west-2a.online.tableau.com) and open a workbook, for example, Superstore. Click **Edit** and create a new worksheet (from the Worksheet menu, select **New Worksheet**), or open a new workbook in your Personal Space and connect to the **Superstore Datasource**. +1. Start Tableau Desktop, or log on to Tableau Cloud or Tableau Server and open a workbook, for example, Superstore. Click **Edit** and create a new worksheet (from the Worksheet menu, select **New Worksheet**), or open a new workbook in your Personal Space and connect to the **Superstore Datasource**. 1. On the **Marks** card, expand the Mark Type drop-down menu. Under Viz Extensions, select **Add Extensions**. @@ -182,7 +193,6 @@ After you have created the manifest file (`.trex`) and have hosted your web app --- - ### Add code to initialize the extension and call Tableau Extensions API functions The next step is to create the JavaScript that calls the Extensions API. In your JavaScript code (either in your HTML page or in a separate JavaScript file), you first need to initialize the extension. To do this, you call `tableau.extensions.initializeAsync()`. The function returns after the initial bootstrap operation is complete and the extension is available for use. The Extensions API follows the [CommonJS Promises/A standard](http://wiki.commonjs.org/wiki/Promises/A) for asynchronous method calls. @@ -268,7 +278,7 @@ The next step is to create the JavaScript that calls the Extensions API. In your 1. In the Add an Extension dialog box that appears, select **Access Local Extensions**. -1. Browse to the directory where your extension is located. For example, if you downloaded or cloned the GitHub repository, go to `\extensions-api-preview\Samples\HelloVizExtension` and select the `HelloVizExtension.trex file`. +1. Browse to the directory where your extension is located. For example, if you downloaded or cloned the GitHub repository, go to `\extensions-api\Samples\HelloVizExtension` and select the `HelloVizExtension.trex` file. 1. Drag some fields on to the **Drop** tile on the Marks card. The name of the fields that you've added to the Marks card are displayed in the worksheet. Every time you add or remove a field, the names are updated. @@ -308,7 +318,7 @@ Our sample code follows the [Semi-Standard Style](https://github.com/Flet/semist ## What's next? -- For more information about how you can use the Extensions API, go look at the [Samples](https://github.com/tableau/extensions-api-preview/tree/main/Samples/). Study the sample, connectedScatterPlot, to see a full implementation of a viz extension. +- For more information about how you can use the Extensions API, go look at the [Samples](https://github.com/tableau/extensions-api/tree/main/Samples/). Study the sample, connectedScatterPlot, to see a full implementation of a viz extension. - Get familiar with the programming interface of the Extensions API, see [API Reference](pathname:///api/). diff --git a/website/docs/vizext/trex_viz_examples.md b/website/docs/vizext/trex_viz_examples.md index 8a875bba..c30d264e 100644 --- a/website/docs/vizext/trex_viz_examples.md +++ b/website/docs/vizext/trex_viz_examples.md @@ -8,7 +8,7 @@ The best way to learn how to build your own extensions is to look at the sample - To download the Extensions API SDK, if you have not already done so, see [Get Started](./trex_viz_getstarted). -- You can browse the sample code for the extensions in the [Samples](https://github.com/tableau/extensions-api-preview/tree/master/Samples?=target="_blank") folder on GitHub. +- You can browse the sample code for the extensions in the [Samples](https://github.com/tableau/extensions-api/tree/master/Samples?=target="_blank") folder on GitHub. --- @@ -17,48 +17,47 @@ The following instructions assume that you have already downloaded and extracted ### About the viz extension samples -The viz extension samples are in the `Samples` folder. +The viz extension samples are in the `Samples\Viz` folder. -- **[ConnectedScatterplot](https://github.com/tableau/extensions-api-preview/tree/main/Samples/ConnectedScatterplot?=target="_blank")** +- **[ConnectedScatterplot](https://github.com/tableau/extensions-api/tree/main/Samples/Viz/ConnectedScatterplot?=target="_blank")** Shows how to create a viz extension. -- **[DataSources](https://github.com/tableau/extensions-api-preview/tree/main/Samples/DataSources?=target="_blank")** +- **[DataSources](https://github.com/tableau/extensions-api/tree/main/Samples/Viz/DataSources?=target="_blank")** Shows how to use the `getDataSourcesAsync` function to find the names of the data sources for the worksheet. Like the Filtering sample, the DataSources sample makes use the `Promise.all` function to combine the promises from the asynchronous calls together, and then waits for them to resolve. -- **[Filtering](https://github.com/tableau/extensions-api-preview/tree/main/Samples/Filtering?=target="_blank")** +- **[Filtering](https://github.com/tableau/extensions-api/tree/main/Samples/Viz/Filtering?=target="_blank")** Demonstrates how to use the `getFiltersAsync` function to find and display the active filters in the worksheet and calls the `addEventListener` function to set a `FilterChanged` event on the worksheet. Any time a filter value is changed, the extension refreshes the table that displays the active filters. -- **[Parameters](https://github.com/tableau/extensions-api-preview/tree/main/Samples/Parameters?=target="_blank")** +- **[Parameters](https://github.com/tableau/extensions-api/tree/main/Samples/Viz/Parameters?=target="_blank")** Finds and displays all the parameters in the worksheet and then sets an event listener that waits for a parameter to change, which triggers a refresh. -- **[Sankey](https://github.com/tableau/extensions-api-preview/tree/main/Samples/Sankey?=target="_blank")** +- **[Sankey](https://github.com/tableau/extensions-api/tree/main/Samples/Viz/Sankey?=target="_blank")** Sankey diagrams or charts - named after their creator, Matthew Henry Phines Riall Sankey, who first used this chart type in 1898. Somewhat similar to the Sankey viz type Tableau had offered in the recent Sankey and Radial new chart types pilot (June 2023). -- **[Settings](https://github.com/tableau/extensions-api-preview/tree/main/Samples/Settings?=target="_blank")** +- **[Settings](https://github.com/tableau/extensions-api/tree/main/Samples/Viz/Settings?=target="_blank")** Uses the `settings` namespace to save settings (key-value pairs) for the extension. Demonstrates how you can save settings for each instance of an extension, which enables sharing common views of a workbook. -- **[UINamespaces](https://github.com/tableau/extensions-api-preview/tree/main/Samples/UINamespace?=target="_blank")** +- **[UINamespaces](https://github.com/tableau/extensions-api/tree/main/Samples/Viz/UINamespace?=target="_blank")** Demonstrates how you can use the `UI` namespace to create a modal dialog box (or popup) that runs another extension, which allows users to interact and change the settings for the parent extension. This sample controls the background auto-refresh interval for data sources in a worksheet. -- **[VizImage](https://github.com/tableau/extensions-api-preview/tree/main/Samples/VizImage?=target="_blank")** +- **[VizImage](https://github.com/tableau/extensions-api/tree/main/Samples/Viz/VizImage?=target="_blank")** Shows how you can use Tableau Viz to add visualizations to your extensions. This sample demonstrates the effects of different mark types and color palettes. For more information about Tableau Viz, see [Add Tableau Viz to Your Extensions](../core/trex_tableau_viz). - --- ### Start a web server to host the sample viz extensions -To use the extension samples, you need to start up a web server on your computer to host the HTML pages. If you downloaded or cloned the Extensions API repository, you can start the web service in the root directory of the repository on your computer. These commands start the Node.js basic service `http-server`. +To use the viz extension samples, you need to start up a web server on your computer to host the HTML pages. If you downloaded or cloned the Extensions API repository, you can start the web service in the root directory of the repository on your computer. These commands start the Node.js basic service `http-server`. -1. Go to the `extensions-api-preview` folder. +1. Go to the `extensions-api` folder. 1. To install the web server components, run the following command: ```cli @@ -75,7 +74,7 @@ To use the extension samples, you need to start up a web server on your computer The samples are set up so that the web server is using port `8765`. If you need to specify a different port instead of `8765`, you can change ports using another Node.js or `http-server` command. -From the `extensions-api-preview` folder, you can start the `http-server` using one of the following commands. Replace `PORT` with the port you are using (for example, `8000`). +From the `extensions-api` folder, you can start the `http-server` using one of the following commands. Replace `PORT` with the port you are using (for example, `8000`). To install the `http-server`on your computer globally and to also start the server: @@ -94,7 +93,7 @@ The port you use for the web server also has to match the port specified in the ```html
-Every Tableau extension has a manifest file (`.trex`) that describes the extension and identifies the location of the web application. +Every Tableau extension has a manifest file (`.trex`) that describes the extension and identifies the location of the web application. The extension should appear in the worksheet. Play around with the extension. Examine the HTML and JavaScript source files to see how things work. diff --git a/website/docs/vizext/trex_viz_getstarted.md b/website/docs/vizext/trex_viz_getstarted.md index be279efe..aaab1bd1 100644 --- a/website/docs/vizext/trex_viz_getstarted.md +++ b/website/docs/vizext/trex_viz_getstarted.md @@ -19,7 +19,7 @@ If you are looking for information about how to use viz extensions in Tableau, s :::info **What's in a Tableau extension?** -A Tableau extension consists of an XML manifest file (`.trex`), an web page (`.html`) that uses a Tableau-provided JavaScript library, and the JavaScript file (`.js`) (or files) that contain your extension logic. The Tableau extensions are supported on Tableau Desktop, Tableau Server, and Tableau Cloud. +A Tableau extension consists of an XML manifest file (`.trex`), a web page (`.html`) that uses a Tableau-provided JavaScript library, and the JavaScript file (`.js`) (or files) that contain your extension logic. The Tableau extensions are supported on Tableau Desktop, Tableau Server, and Tableau Cloud. ::: @@ -29,42 +29,6 @@ A Tableau extension consists of an XML manifest file (`.trex`), an web page (`.h If you want to create an extension or work with the sample code, make sure you have followed the instructions for [installation](../installation). - - - ----- - - - ### Start a web server to host the sample viz extensions To use the viz extension samples, you need to start up a web server on your computer to host the HTML pages. If you downloaded or cloned the Extensions API repository, you can start the web service in the root directory of the repository on your computer. For example, if you downloaded the `extensions-api-main.zip` file to your `Downloads` directory, after you extract the files, the directory would be `extensions-api-main`. If you cloned the repository, the directory would be `extensions-api`. @@ -90,7 +54,7 @@ To use the viz extension samples, you need to start up a web server on your comp :::note - The web server just serves the extension samples, which have URLs similar to the following: `http://localhost:8765/Samples/ConnectedScatterplot/connectedScatterplot.html` This local web server is not intended to serve the Viz Extensions API Help pages. View the Help on GitHub at [https://tableau.github.io/extensions-api-preview](https://tableau.github.io/extensions-api-preview). + The web server just serves the extension samples, which have URLs similar to the following: `http://localhost:8765/Samples/Viz/ConnectedScatterplot/connectedScatterplot.html` This local web server is not intended to serve the Viz Extensions API Help pages. View the Help on GitHub at [https://tableau.github.io/extensions-api](https://tableau.github.io/extensions-api). ::: @@ -98,7 +62,11 @@ To use the viz extension samples, you need to start up a web server on your comp ### Sign in to Tableau and add a viz extension to the worksheet -1. Sign into Tableau and open the Superstore workbook. Alternatively, open a new workbook in your Personal Space and connect to the **Superstore Datasource**. +1. Start Tableau Desktop or sign in to Tableau Cloud or Tableau Server and open the Superstore workbook. Alternatively, open a new workbook in your Personal Space and connect to the **Superstore Datasource**. + + :::note + If you are using Tableau Cloud or Tableau Server to view the samples, you'll need to make sure that the extension is on the Allow list (safe list) for Tableau Server or Tableau Cloud. See [Add extensions to the safe list and configure user prompts](https://help.tableau.com/current/online/en-us/dashboard_extensions_server.htm#add-extensions-to-the-safe-list-and-configure-user-prompts) (Tableau Cloud) or [Add extensions to the safe list and configure user prompts](https://help.tableau.com/current/server/en-us/dashboard_extensions_server.htm#add-extensions-to-the-safe-list-and-configure-user-prompts) (Tableau Server). So you can use all the sample extensions, use the following URL and wildcard: `http://localhost:.*/Samples/.*` + ::: 1. In a worksheet, on the Marks card, expand the Mark Type drop-down menu. @@ -113,13 +81,13 @@ To use the viz extension samples, you need to start up a web server on your comp Every Tableau extension has a manifest file (.trex) that describes the extension and identifies the location of the web application. For more information on creating a `.trex` manifest file, see [Tableau Viz Extension Manifest File](./trex_viz_manifest). 1. Navigate to the directory where the connectedScatterplot manifest file (`.trex`) is located -`\extensions-api\Samples\ConnectedScatterplot`. +`\extensions-api\Samples\Viz\ConnectedScatterplot`. 1. Open the `connectedScatterplot.trex` file. If prompted, click OK to allow the Viz Extension to run in the workbook. The extension is a network-enabled extension, which means it has access to resources outside of Tableau and it is not hosted on the Tableau Sandbox. When the extension loads, the worksheet is blank, but the Marks card will show the name of the viz extension and any custom encoding tiles the extension uses. -  +  ### Configure the connectedScatterplot viz extension @@ -148,10 +116,11 @@ Some slight modifications have been made to make it able to be used with Workboo ## What's next? -* Start developing your extension by modifying an existing sample. See [samples (GitHub)](https://github.com/tableau/extensions-api-preview/tree/main/Samples/). If you cloned or downloaded the repository, create a copy of one of the existing samples in the Samples directory and start with that. For example, if you make the copy of the ConnectedScatterplot directory, rename the copy and place it in the Samples directory. You will need to change the URL in the `.trex` file so that the source location URL shows the new path. +* Start developing your extension by modifying an existing viz extension sample. See [samples (GitHub)](https://github.com/tableau/extensions-api/tree/main/Samples/Viz/). If you cloned or downloaded the repository, create a copy of one of the existing samples in the Samples directory and start with that. For example, if you make the copy of the ConnectedScatterplot directory, rename the copy and place it in the Samples directory. You will need to change the URL in the `.trex` file so that the source location URL shows the new path. - Keeping your own extensions in the Samples folder has two advantages. The first is that you can host the extensions using the same web server you started with `npm start` command. The second is that the Tableau preview test site has been configured so that all extensions that use the path `http://localhost:8765/Samples` are included on the safe list (or allowlist). Because the extension is running on your local computer (`http://localhost`) and uses the URL that is allowed on the site, you are good to go. In general, when you are creating your own viz extensions, you will need to ensure that that the extension URL has been added to the safe list. For more information, see [Add extensions to the safe list and configure user prompts](https://help.tableau.com/current/online/en-us/dashboard_extensions_server.htm#add-extensions-to-the-safe-list-and-configure-user-prompts). + Keeping your own extensions in the Samples folder has two advantages. The first is that you can host the extensions using the same web server you started with `npm start` command. The second advantage is that you won't need to add your extension to the allow list (or safe list) if you configured your Tableau Cloud or Tableau Server site so that all extensions under the path `http://localhost:8765/Samples`. For example, if you added this URL and wildcard to the safe list: `http://localhost:.*/Samples/.*`, the URL allows all extensions (on any port) under the Samples folder. Because the extension is running on your local computer (`http://localhost`) and uses the URL that is allowed on the site, you are good to go. In general, when you are creating your own viz extensions, you will need to ensure that that the extension URL has been added to the safe list. For more information, see [Add extensions to the safe list and configure user prompts](https://help.tableau.com/current/online/en-us/dashboard_extensions_server.htm#add-extensions-to-the-safe-list-and-configure-user-prompts). * For information about creating a simple "Hello World" Tableau viz extension, see [Create a "Hello World" Viz Extension](./trex_viz_create). -* To get familiar with the programming interface for the Extensions API, see the API Reference. + +* To get familiar with the programming interface for the Extensions API, see the [API Reference](pathname:///api/). diff --git a/website/docs/vizext/trex_viz_manifest.md b/website/docs/vizext/trex_viz_manifest.md index 2b562693..692be8b1 100644 --- a/website/docs/vizext/trex_viz_manifest.md +++ b/website/docs/vizext/trex_viz_manifest.md @@ -199,7 +199,7 @@ To add custom encoding, you provide definitions for the encoding in the manifest These encodings are rendered on the Marks card as tiles, with the X, Y and Text icons. - + :::note @@ -422,7 +422,7 @@ The following table shows the list of icons you can use.
Tableau Extensions API
Dashboard extensions
The following diagram shows the relationship between the extensions namespace and the worksheets in - the dashboard. For more information, see Tableau Extensions API Basics.
+ the dashboard. For more information, see Tableau Extensions API Basics.