Merge pull request #390 from tableau/dev

Update docs for v1.5 library; doc bug fixes

Author: d45

_config.yml

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

_includes/head.html

@@ -14,5 +14,13 @@
   <script src="{{ site.baseurl }}/assets/js/redirect-to-search.js"></script>
   <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
   <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.4.1/js/bootstrap.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
+  <script>
+    mermaid.initialize({
+      startOnLoad:true,
+      sequence: { showSequenceNumbers: true }, 
+    });
+  </script>
+
 
 {% if jekyll.environment == "production" %}{% include analytics.html %}{% endif %}

docs/trex_debugging.md

@@ -100,7 +100,7 @@ This command enables remote debugging of extensions for this session of Tableau.
 
 ## Debugging Tableau Desktop using Chrome/Chromium
 
-After you install the Chromium browser and enable debugging in Tableau, you can start debugging your extension.
+After you install the Chrome (or Chromium) browser and enable debugging in Tableau, you can start debugging your extension.
 
 1. Open the dashboard with the extension you want to debug in Tableau. 
 2. Start Chromium and set the URL to [`http://localhost:8696`](http://localhost:8696)  
@@ -115,9 +115,24 @@ Note that you can only debug one extension, or instance of an extension, at a ti
 
 ---
 
-## Debugging loading and initialization issues
+## Debugging loading and initialization issues (Tableau 2021.1 and later)
 
-It can be difficult to hit breakpoints that occur during the loading of your page because of the remote debugging process. To help with this, you can select a menu option that causes your extension to wait to load until you trigger it to proceed.
+If you need to troubleshoot or debug issues that prevent your extension from loading or initializing, you can set breakpoints that trigger when your JavaScript code is loaded.
+
+1. Start the debugging session as described in [Debugging Tableau Desktop using Chrome/Chromium](#debugging-tableau-desktop-using-chromechromium).
+
+1. Click the **Sources** tab in Chrome/Chromium, under **Event Listener Breakpoints**, click **Script** and enable the **Script First Statement** breakpoint. You just have to do this one time.
+
+1. In Tableau Desktop, select the extension in the dashboard and click **Reload** from the **More Options** shortcut menu. <br/>
+The debugger will pause each time the first statement of a script runs, allowing you to debug the startup process.
+
+1. To get to your JavaScript code, click **Continue** several times. After your JavaScript is loaded, you can set a breakpoint in your startup code.
+
+---
+
+## Debugging loading and initialization issues (Tableau 2020.4 and earlier)
+
+It can be difficult to hit breakpoints that occur during the loading of your page because of the remote debugging process, and because of the way loading was handled prior to Tableau 2021.1. To help with this, you can select a menu option that causes your extension to wait to load until you trigger it to proceed.
 
 1. Select the extension in the dashboard and select **Debug Options** > **Pause Before Loading** from the shortcut menu.
 2. Reload your extension. Select **Reload** from the shortcut menu.

docs/trex_error_handling.md

@@ -13,7 +13,7 @@ Errors that are returned from the Extensions API are custom Tableau error object
 
 ## Using Extensions API error codes
 
-The Extensions API wraps the standard error object with an `errorCode` property. You can use this error code for debugging or troubleshooting your extension. Any time you encounter an error when you are running your extension, you can look at this `errorCode` to determine the cause. See [Error Codes]({{site.baseurl}}/docs/enums/errorcodes.html). 
+The Extensions API wraps the standard error object with an `errorCode` property. You can use this error code for debugging or troubleshooting your extension. Any time you encounter an error when you are running your extension, you can look at this `errorCode` to determine the cause. See [Error Codes]({{site.baseurl}}/docs/enums/tableau.errorcodes.html){:target="_blank"}.
 
 As you create your extension, you want to be sure to catch potential error conditions. For example, you should validate user input and make use of `try`  ... `catch` statements. The Extensions API makes use of JavaScript promises. You can use the `.catch` method to field the errors that could be returned in the promise and any subsequent `.then` methods. 
 

docs/trex_manifest.md

@@ -3,8 +3,8 @@ title: Tableau Extension Manifest File
 layout: docs
 ---
 
-The extension manifest file (`.trex`) contains metadata for the extension and is used for registration. 
- 
+The extension manifest file (`.trex`) contains metadata for the extension and is used for registration.
+
 For details about a manifest or its fields, see the [Sample Manifest File](#sample-manifest-file) and [Elements of the Manifest File](#elements-of-the-manifest-file).  
 
 
@@ -13,19 +13,19 @@ For details about a manifest or its fields, see the [Sample Manifest File](#samp
 * TOC
 {:toc}
 
+---
 
+## Tableau TREX Generator
 
-## XSD Validation
-The manifest is an XML-based file. We have provided an XSD (an XML schema definition file) that can be used to validate the manifest file you have created for your extension. The XSD is available from the  [Extensions API Developer Preview](https://prerelease.tableau.com/project/version/item.html?cap=52e2710a0793434d82142736c7ab3029&arttypeid={0DD668AE-472C-4E70-B465-35F7AE0DEB6D}&artid={939493D2-8000-4192-857A-67624CBCC35A}){:target="_blank"} site. You are strongly encouraged to validate your extensions manifest file before using it for the first time. 
+To create a new manifest file (`.trex`) for your extension the easy way, use the [Tableau TREX Generator](https://trex-generator.glitch.me/){:target="_blank"} on [Glitch](https://glitch.com){:target="_blank"}. The Tableau TREX Generator allows you to create the manifest file by filing in a form. You can also upload an existing `.trex` file and use that as a starting point. You can use the generator to edit and modify your `.trex` file as needed. When you are finished, just download the file to use with your extension.
 
 ## Manifest Versioning
+
 The versioning of the manifest is designed to be semantically simple and support compatibility. The version follows the [Major].[Minor] format. Minor upgrades are backwards compatible while major upgrades involve breaking changes. 
 
 ## Error Reporting
-At start up, Tableau checks the manifest file. If any errors are found while parsing the file, Tableau writes these errors to the `log.txt` file in the `My Tableau Repository (Beta)/Logs` folder. This is the same location that Tableau Desktop uses to report other errors and activity. 
-
-If a workbook is saved with an extension and then later opened on another computer that does not have the extension installed, Tableau displays a message in the dashboard zone where the extension would have appeared that states the extension is not available. 
 
+At start up, Tableau checks the manifest file. If any errors are found while parsing the file, Tableau writes these errors to the `log.txt` file in the `My Tableau Repository/Logs` folder. This is the same location that Tableau Desktop uses to report other errors and activity.
 
 ## Sample Manifest File
 

docs/trex_oauth.md

@@ -32,6 +32,30 @@ The following outlines some of the basic steps in using a secondary window for O
 
 * In response to the signal, the extension retrieves and stores the OAuth token in local storage on the client's computer. The extension can then use the access token to send subsequent requests for services from the OAuth provider.
 
+---
+<div class="mermaid">
+sequenceDiagram
+    participant User
+    participant E as Extension (client)
+    participant S as Server (web host)
+    participant O as OAuth provider
+    User->>E: Load dashboard extension
+    E->>S: Open communication channel
+    S-->>E: Use this socket session ID (socket.id)
+    E->>O: Request the OAuth login page (with client ID)
+    O-->>User: Prompt user: Allow or deny access?
+    User->>O: Allow!
+    O-->>S: Here's the auth code
+    S->>O: Auth code request + client ID, client secret, session ID
+    O-->>S: Here's the access token
+    Note right of E: Route the access token based on session ID
+    S->>E: This access token is for this session ID.
+    Note right of E: Use the access token to request data
+
+</div>
+
+
+
 ---
 
 ## An example of the OAuth code path using Socket.IO

docs/trex_release-notes.md

@@ -11,9 +11,44 @@ layout: docs
 ----
 See also: [Known Issues]({{site.baseurl}}/docs/trex_known_issues.html)
 
+----
+
+### Tableau Dashboard Extensions API version 1.5
+
+*June 2021*
+
+* Tableau Dashboard Extensions API library: `tableau.extensions.1.5.0.js` <br>(download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api){:target="_blank"}.) <br/>
+
+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`](https://tableau.github.io/extensions-api/docs/interfaces/worksheet.html#getsummarydataasync){:target="_blank"} 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){:target="_blank"}.
+
+
+
 ----
 
 ### 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]({{site.baseurl}}/docs/trex_debugging.html) and [Download the Chromium Browser]({{site.baseurl}}/docs/trex_debugging.html#download-the-chromium-browser).