Adding Tableau Viz to dashboard extensions

_config.yml

@@ -23,7 +23,7 @@ github: [metadata]
 kramdown:
     toc_levels: 1..3
 
-gems: [jekyll-mermaid]
+plugins: [jekyll-mermaid]
 mermaid: https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js 
 
 # Exclude

_includes/docs_menu.html

@@ -35,6 +35,9 @@
         <li>
             <a href="{{ site.baseurl }}/docs/trex_configure.html">Add a Configuration Popup Dialog</a>
         </li>
+        <li>
+            <a href="{{ site.baseurl }}/docs/trex_tableau_viz.html">Add a Tableau Viz to an Extension</a>
+        </li>
         <li>
             <a href="{{ site.baseurl }}/docs/trex_show_hide.html">Show and Hide Objects in the Dashboard</a>
         </li>
@@ -86,6 +89,9 @@
         <li class="nav-header">Reference</li>
         <li>
             <a href="{{ site.baseurl }}/docs/index.html" target="_blank">API Reference</a>
+        </li>
+        <li>
+            <a href="{{ site.baseurl }}/docs/trex_tableau_viz_ref.html" target="_blank">Tableau Viz Reference</a>
         </li>
 		 <li>
             <a href="{{ site.baseurl }}/docs/trex_release-notes.html">Release Notes</a>

docs/trex_create.md

@@ -22,17 +22,16 @@ To create a Tableau extension you need the following components.
 
 These instructions assume that you already have cloned or download the Extensions API SDK. For information about setting up your environment and the Tableau requirements, see [Get Started]({{site.baseurl}}/docs/trex_getstarted.html).
 
-For convenience, you might want to create a folder for your "Hello World" dashboard extension in the same location where you installed or cloned the GitHub repository (for example, `HelloDemo` under `/extensions-api`). That way, you can use the same web server (`http-server`) that is used for the samples. 
-
+For convenience, you might want to create a folder for your "Hello World" dashboard extension in the same location where you installed or cloned the GitHub repository (for example, `HelloDemo` under `/extensions-api`). That way, you can use the same web server (`http-server`) that is used for the samples.
 
+---
 
 ### Create a manifest file
 
-The manifest file (`EXTENSION-NAME.trex`) is an XML file that describes the extension and provides information to register the extension with Tableau. 
+The manifest file (`EXTENSION-NAME.trex`) is an XML file that describes the extension and provides information to register the extension with Tableau. For a description of the contents of this file, see [Elements of the manifest file]({{site.baseurl}}/docs/trex_manifest#elements-of-the-manifest-file).
 
 1.  In the `HelloDemo` folder (or where ever you want to put your files), create a manifest file for your extension.
-Name the manifest file for your extension (for example, `HelloExtension` and save it with the file name extension `.trex`. <br/>
-The manifest file is an XML file that contains elements and attributes that describe the extension. For a description of the contents of this file, see [Elements of the manifest file]({{site.baseurl}}/docs/trex_manifest#elements-of-the-manifest-file). The XSD that is used for validation is available on the [Tableau Pre-Release website](https://prerelease.tableau.com/project/version/item.html?cap=52e2710a0793434d82142736c7ab3029&arttypeid={0DD668AE-472C-4E70-B465-35F7AE0DEB6D}&artid={939493D2-8000-4192-857A-67624CBCC35A}){:target="_blank"}.
+Name the manifest file for your extension (for example, `HelloExtension` and save it with the file name extension `.trex`.
 
 2. Copy the following XML code into your new file. Make sure that the `<?xml ...>` declaration appears as the first element in the file (line 1, column 1). Any blank spaces in front of the declaration will cause an error when you load the extension.  
 
@@ -71,11 +70,10 @@ The manifest file is an XML file that contains elements and attributes that desc
 
 - After you have created the HTML and JavaScript files for your extension, you use this `.trex` file to add the extension to a Tableau dashboard. To do that, you drag the **Extension** object on to the dashboard. In the **Choose an Extension** dialog box, click **My Extensions** to locate and open the manifest file you just created.
 
-- For information about validating the manifest and adding version information, see the [Tableau Extension Manifest]({{site.baseurl}}/docs/trex_manifest.html).
-
-
+- For information about the manifest file and about adding version information, see the [Tableau Extension Manifest]({{site.baseurl}}/docs/trex_manifest.html).
 
 
+---
 
 ### Create your web app
 
@@ -87,13 +85,11 @@ The web app you create controls and interacts with the Tableau dashboard objects
 
 Your web application must include an HTML page. This page should link to the Extensions API JavaScript library and to any other JavaScript, CSS, or HTML resources your web app requires. You could add the JavaScript code to initialize and call Extensions API functions directly in the HTML page. However, in most cases you want to keep this code in a separate file. 
 
-1.  In the `HelloDemo` folder (or where ever you put your `.trex` file), create a file called `HelloExtension.html`. 
-
+1. In the `HelloDemo` folder (or where ever you put your `.trex` file), create a file called `HelloExtension.html`.
 
 2. You can copy and paste the following code into your file. This code creates a very simple page with a button that when clicked will initialize and use the API to get the name of the dashboard the extension is running in. This HTML code assumes that you are creating your extension in a folder (for example, `HelloDemo`) under the `/extensions-api` directory. 
 
 
-
    ```html
    <!DOCTYPE html>
     <html>
@@ -131,7 +127,6 @@ Your web application must include an HTML page. This page should link to the Ext
 
    The sample code includes a link to the JavaScript library (`tableau.extensions.1.latest.js`), which is available in the `/lib` folder. The sample code also includes links to jQuery and Bootstrap libraries. 
 
-
 3. If necessary, adjust the relative path to the Extensions API JavaScript library (`tableau.extensions.1.latest.js`), which is available in the `/lib` folder. 
 
    ```html
@@ -150,6 +145,8 @@ Your web application must include an HTML page. This page should link to the Ext
 
    ```
 
+---
+
 #### Start the web service to host the extension
 
 1. Start the web service to verify you have the web app and files configured. <br/> 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): 
@@ -168,6 +165,9 @@ Your web application must include an HTML page. This page should link to the Ext
 
    ```
 
+
+---
+
 ### Test your extension in Tableau
 
 After you have created the manifest file (`.trex`) and have hosted your web app you can test it in Tableau. It's a good idea to do this even if your application isn't completed.
@@ -185,7 +185,7 @@ After you have created the manifest file (`.trex`) and have hosted your web app
    - Tableau parses the `.trex` file when you add the extension to the dashboard. If you make changes to the `.trex` file after you have added it to the dashboard, you need to remove the extension and re-add it. See [What Happens When you Reload an Extension]({{site.baseurl}}/docs/trex_reload.html)
 
 
-
+---
 
 ### Add code to initialize the extension and call Tableau Extensions API functions
 
@@ -225,6 +225,7 @@ The next step is to create the JavaScript that calls the Extensions API. In your
 
 |**About the example code** <br/>The JavaScript example uses the jQuery document ready function to detect when the web page is loaded and ready. The code also uses an event handler to delay the initialization until the user clicks the `initializeButton`. When the page is ready and the user clicks the button, the initialization function (`initializeAsync`) instantiates a dashboard extension. To handle the promise, the `then` method calls two callback functions to handle successful initialization or failure. In case of success, the example gets the dashboard object from the extension, and then accesses the `name` property  to display the name of the dashboard sheet in the hosting web page. In case of an error, the error message is displayed.
 
+---
 
 ### Debugging and testing your extension in Tableau
 

docs/trex_known_issues.md

@@ -12,6 +12,15 @@ For information about what is new or has changed in each release, see the [Relea
 * TOC
 {:toc}
 
+### 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 are not available in the SVG output.
+
+For information about Tableau Viz, see [Add Tableau Viz to Your Dashboard Extension]({{site.baseurl}}/docs/trex_tableau_viz.html).
+
 ### 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]({{site.baseurl}}/docs/trex_debugging.html) and [Download the Chromium Browser]({{site.baseurl}}/docs/trex_debugging.html#download-the-chromium-browser).

docs/trex_release-notes.md

@@ -13,6 +13,27 @@ See also: [Known Issues]({{site.baseurl}}/docs/trex_known_issues.html)
 
 ----
 
+### Tableau Dashboard Extensions API version 1.6
+
+*September 2021*
+
+* Tableau Dashboard Extensions API library: `tableau.extensions.1.6.0.js` <br>(download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api){:target="_blank"}.) <br/>
+
+* Download [Tableau Desktop 2021.3](https://www.tableau.com/support/releases){:target="_blank"} or [Tableau Server 2021.3](https://www.tableau.com/support/releases/server){:target="_blank"}.
+
+About this release:
+
+* Tableau Viz is here! <br/>
+
+![Tableau Viz SVG image]({{site.baseurl }}/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`]({{site.baseurl}}/docs/interfaces/extensions.html#createvizimageasync){:target="_blank"} method, which takes the JSON description of the image as an input.<br/> 
+For more information about using Tableau Viz, see: <br/>
+  - [Add Tableau Viz to Your Dashboard Extensions]({{site.baseurl}}/docs/trex_tableau_viz.html)
+  - [Tableau Viz Reference]({{site.baseurl}}/docs/trex_tableau_viz_ref.html)
+
+----
+
 ### Tableau Dashboard Extensions API version 1.5
 
 *June 2021*

docs/trex_tableau_viz.md

@@ -0,0 +1,170 @@
+---
+title: Add Tableau Viz to your Dashboard Extensions
+layout: docs
+---
+
+Tableau Viz provides a lightweight method for creating visualizations in Tableau. You provide a declarative description of graph or chart, and then call a method to render the description as an SVG image that you can embed in your dashboard extension. The description includes the data (or programmatically adds the data) and specifies the type of chart you wish to create and how it should be encoded. This feature is available through the Dashboard Extensions API and employs the same visualization pipeline that Tableau uses.
+
+
+
+**In this section**
+
+* TOC
+{:toc}
+
+---
+
+## What you need to get started
+
+Tableau Viz is integrated with the Tableau Dashboard Extensions API. To add visualizations to your extension requires the following versions of Tableau and the Dashboard Extensions JavaScript library.
+
+* Tableau 2021.3 and later
+
+* Dashboard Extensions API library (version 1.6 and later)
+
+
+---
+
+
+## The components of a Tableau Viz
+
+There are three main steps in creating a Tableau Viz image.
+
+* Provide the description (or specification) of the image
+
+* Call the Dashboard Extensions method to create the image
+
+* Display the SVG image in the dashboard extension
+
+
+<div class="mermaid">
+graph LR
+   A:[Create input specification] --> B:[Call createVizImageAsync] --> C:[Display SVG in dashboard extension]
+</div>
+
+## Input specification
+
+A Tableau Viz is defined by a specification. This is the `inputSpec` that you pass as an argument to the `createVizImageAsync` method. The `inputSpec` is a JavaScript object that contains the embedded data and visual specification details. There are two main parts to the `inputSpec`:
+
+* the `data:` (an array of objects, for example, the selected measures and dimensions in the dashboard)
+
+* information about how to format that data (size of viz, mark type, mark color, encoding)
+
+The `inputSpec` is a structured JavaScript object. The following example shows a specification that creates a simple bar chart. In this example, the data values are statically assigned as part of the specification. In many cases, you would probably programmatically assign the values based upon mark selection in the dashboard or based on some other selection criteria.
+
+
+```javascript
+
+            var yourEmbeddedDataSpec = {
+                description: 'A simple chart with embedded data.',
+                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: tableau.MarkType.Bar,
+                encoding: {
+                    columns: { field: 'Category', type: tableau.VizImageEncodingType.Discrete },
+                    rows: { field: 'Sales', type: tableau.VizImageEncodingType.Continuous, hidden: true},
+                    color: { field: 'Sales', type: tableau.VizImageEncodingType.Continuous, palette: 'tableau-map-temperatur'},
+                    text: { field: 'Category', type: tableau.VizImageEncodingType.Discrete },
+                    size: { field: 'Category', type: tableau.VizImageEncodingType.Discrete}
+                }
+            };
+
+```
+
+For more information about the `inputSpec`, see [Tableau Viz Reference]({{site.baseurl}}/docs/trex_tableau_viz_ref.html).
+
+---
+
+## Call createVizImageAsync
+
+After you create the `inputSpec` you pass it as an argument to the `createVizImageAsync` method. The method returns an SVG image that can be used by the extension. This example takes the `yourEmbeddedDataSpec` that was defined in the previous step, and uses that to describe the chart to create.
+
+ ```javascript
+ tableau.extensions.createVizImageAsync(yourEmbeddedDataSpec).then((svg) => {
+     ...         
+            });
+
+  ```
+
+
+## Display the SVG image in the dashboard extension
+
+The asynchronous method returns an SVG image as the promise. Here is one way of taking that SVG and embedding it as a an element in your extension web page. In this example, the `svg` is converted to a JavaScript `Blob`, and the `Blob` is used as the image data source in the hosting dashboard extensions page.
+
+```javascript
+            tableau.extensions.createVizImageAsync(yourEmbeddedDataSpec).then((svg) => {
+                console.log(svg);
+                var blob = new Blob([svg], { type: 'image/svg+xml' });
+                var url = URL.createObjectURL(blob);
+                var image = document.createElement('img');
+                image.src = url;
+                image.style.maxWidth = '100%';
+                var vizApiElement = document.getElementById('viz-container');
+                vizApiElement.appendChild(image);
+                image.addEventListener('load', function () { return URL.revokeObjectURL(url); }, { once: true });
+            }, (err) => {
+                console.log(err);
+            });
+
+```
+
+Tableau renders an image that looks something like this:
+
+
+![Tableau Viz SVG image]({{site.baseurl }}/assets/vizapi_demo3.svg)
+
+
+
+----
+
+## What's next?
+
+Now that you have seen the basic steps for adding a Tableau Viz to a dashboard extension, you can try adding Tableau Viz to your own dashboard extensions, or to one of the samples.
+
+* For information about the Tableau Viz `inputSpec` and all the options for specifying the visualization, see [Tableau Viz Reference]({{site.baseurl}}/docs/trex_tableau_viz_ref.html).
+
+* Review the [`tableau.extensions.createVizImageAsync`]({{site.baseurl}}/docs/interfaces/extensions.html#createvizimageasync){:target="_blank"} method for information about the API.
+
+---
+
+## Troubleshoot Tableau Viz images in dashboard extensions
+
+You can use the same tools that you use to debug dashboard extensions to debug problems that occur when you use Tableau Viz to create images. For information about debugging your extension, see [Debug Extensions in Tableau Desktop](https://tableau.github.io/extensions-api/docs/trex_debugging.html){:target="_blank"} and [Debug Extensions in Tableau Server and Tableau Online](https://tableau.github.io/extensions-api/docs/trex_debug_server.html){:target="_blank"}.
+
+
+
+### Tableau Viz Error Messages
+
+The following is a list of common error messages that you might encounter and includes steps for fixing those errors. The error messages appear in the Console window when you use the Chrome or Chromium debugging tools.
+
+For specific issues with the current release, see [Tableau Viz - Known Issues]({{site.baseurl}}/docs/trex_known_issues.html#tableau-viz---known-issues).
+
+#### Invalid Palette Name
+
+`Error: internal-error: {"vizapiErrorMsg":"Invalid Palette Name"}`
+
+Be sure that you use one of the palette names listed for the `color` key under encoding in the `inputSpec`. See [Encoding]({{site.baseurl}}/docs/viz_reference.html#encoding). Note that the palette must be supported by the version of Tableau that you are using, and that the palette colors are subject to change. In addition, there are some palette colors can only be used for continuous or discrete fields, but not for both.
+
+
+#### Encoding column (or row) has invalid type
+
+`Error: internal-error: {"vizapiErrorMsg":"Encoding columns has invalid type. Accepted values are Continuous and Discrete"}`
+
+When you encode the fields in the `inputSpec`, you need to make sure that the discrete fields (blue pills) and continuous fields (green pills) are mapped to the correct types: `tableau.VizImageEncodingType.Discrete` and `tableau.VizImageEncodingType.Continuous`.
+
+
+#### Invalid JSON
+
+The `inputSpec` is a JavaScript object that Tableau converts to JSON for processing. The `inputSpec` needs to be in the correct format and must include all required elements. You must encode columns and fields. For the list of required elements, see [Tableau Viz Reference]({{site.baseurl}}/docs/trex_tableau_viz_ref.html).
+