diff --git a/_config.yml b/_config.yml index aaea41ab..b4fe8d3e 100644 --- a/_config.yml +++ b/_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 diff --git a/_includes/docs_menu.html b/_includes/docs_menu.html index 96d8282b..bd1ba765 100644 --- a/_includes/docs_menu.html +++ b/_includes/docs_menu.html @@ -35,6 +35,9 @@
  • Add a Configuration Popup Dialog
    • +
  • + Add a Tableau Viz to an Extension +
  • Show and Hide Objects in the Dashboard
    • @@ -86,6 +89,9 @@
  • Reference
  • API Reference +
    • +
  • + Tableau Viz Reference
  • Release Notes diff --git a/assets/continuous_palette.png b/assets/continuous_palette.png new file mode 100644 index 00000000..45987b8d Binary files /dev/null and b/assets/continuous_palette.png differ diff --git a/assets/discrete_palette.png b/assets/discrete_palette.png new file mode 100644 index 00000000..e7fc5508 Binary files /dev/null and b/assets/discrete_palette.png differ diff --git a/assets/vizapi_demo3.svg b/assets/vizapi_demo3.svg new file mode 100644 index 00000000..e232ae2d --- /dev/null +++ b/assets/vizapi_demo3.svg @@ -0,0 +1,2783 @@ + + +Rendered by Tableau + + + + + + + + + + + + + + + + + + + + + + +Category + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +A + + + + + + +B + + + + + + +C + + + + + + +D + + + + + + +E + + + + + + +F + + + + + + +G + + + + + + +H + + + + + + +I + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +I + + + + + + +H + + + + + + +G + + + + + + +F + + + + + + +E + + + + + + +D + + + + + + +C + + + + + + +B + + + + + + +A + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +19.00 + + + + + + +91.00 + + + + + + +Sales + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Category + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +A + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +B + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +C + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +D + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +E + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +F + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +G + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +H + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +I + + + + + + diff --git a/docs/trex_create.md b/docs/trex_create.md index 3e6fef26..a2fef5ff 100644 --- a/docs/trex_create.md +++ b/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`.
    -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 `` 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 @@ -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.
    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**
    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 diff --git a/docs/trex_known_issues.md b/docs/trex_known_issues.md index 056157cb..687c5f4b 100644 --- a/docs/trex_known_issues.md +++ b/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). diff --git a/docs/trex_release-notes.md b/docs/trex_release-notes.md index 07bdb72f..a5a93060 100644 --- a/docs/trex_release-notes.md +++ b/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`
    (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api){:target="_blank"}.)
    + +* 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!
    + +![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.
    +For more information about using Tableau Viz, see:
    + - [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* diff --git a/docs/trex_tableau_viz.md b/docs/trex_tableau_viz.md new file mode 100644 index 00000000..49951fc0 --- /dev/null +++ b/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 + + +
    +graph LR + A:[Create input specification] --> B:[Call createVizImageAsync] --> C:[Display SVG in dashboard extension] +
    + +## 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). + diff --git a/docs/trex_tableau_viz_ref.md b/docs/trex_tableau_viz_ref.md new file mode 100644 index 00000000..9d0d2ce7 --- /dev/null +++ b/docs/trex_tableau_viz_ref.md @@ -0,0 +1,216 @@ +--- +title: Tableau Viz Reference +layout: docs +--- +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 section describes the components and syntax of the `inputSpec`. For information about how to add a Tableau Viz, see [Add Tableau Viz to your Dashboard Extensions]({{site.baseurl}}/docs/trex_tableau_viz.html). + +**In this section** + +* TOC +{:toc} + + + +## 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`]({{site.baseurl}}/docs/interfaces/extensions.html#createvizimageasync){:target="_blank"} in the Dashboard Extensions API reference. + + +## Specification for `inputSpec` 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"}, + 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} + } +} + + +``` + +--- +## Descripion of `inputSpec` 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. + +--- + +#### `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. | +|`title` | Specifies a custom field label (x-axis, or header) or custom axis title (y-axis) for the columns and rows. | +| `showtitle` | Boolean (`true`, `false`). Specifies whether to show or hide the custom column or row title. | + +The following is an example 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: false}, + rows: {field: "Category", type: tableau.VizImageEncodingType.Discrete } +} + +``` + +#### `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. | +|`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. + +```javascript + +encoding: { + ... + color: { field: 'Measure', type: tableau.VizImageEncodingType.Continuous, palette: 'green_blue_white_diverging_10_0'}, + ... +} + +``` + + +| Continuous colors palettes | Palette name | +|:--- |:--- | +| ![Tableau Continuous Palette]({{site.baseurl}}/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]({{site.baseurl}}/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` | + +--- diff --git a/index.html b/index.html index 45bbfa2a..0ae7f301 100644 --- a/index.html +++ b/index.html @@ -34,7 +34,7 @@

    Get Started

    Extensions API Reference

    -

    Consult the Tableau Extensions API Reference while you build your extensions.

    +

    Consult the Tableau Extensions API Reference and Tableau Viz Reference while you build your extensions.