diff --git a/_includes/docs_menu.html b/_includes/docs_menu.html index 93ccf88b..5427e3d0 100644 --- a/_includes/docs_menu.html +++ b/_includes/docs_menu.html @@ -24,30 +24,34 @@
  • Tableau Extension Manifest File
    • +
  • + What Happens When you Reload an Extension +
    • +
  • Basic How To
    • +
  • Get Data from the Dashboard
  • Add a Configuration Popup Dialog
    • -
  • - What Happens When you Reload an Extension +
  • + Show and Hide Objects in the Dashboard
  • Events and Event Handling
  • Security and Data Access
  • - Security and Tableau Extensions + HTTPS and Tableau Extensions
  • Accessing Underlying Data
  • Cross-Site Scripting and Extension Security -
    • - -
  • Debugging and Troubleshooting
    • + +
  • Debugging and Troubleshooting
  • Debug Extensions in Tableau Desktop
    • diff --git a/assets/dashboard_layout_obj.png b/assets/dashboard_layout_obj.png new file mode 100644 index 00000000..36c028de Binary files /dev/null and b/assets/dashboard_layout_obj.png differ diff --git a/assets/ext_visibility_err_console.png b/assets/ext_visibility_err_console.png new file mode 100644 index 00000000..b9da6009 Binary files /dev/null and b/assets/ext_visibility_err_console.png differ diff --git a/assets/ext_visibility_error_dialog.png b/assets/ext_visibility_error_dialog.png new file mode 100644 index 00000000..474abbdb Binary files /dev/null and b/assets/ext_visibility_error_dialog.png differ diff --git a/docs/trex_debugging.md b/docs/trex_debugging.md index be37a2b3..2a00fdfc 100644 --- a/docs/trex_debugging.md +++ b/docs/trex_debugging.md @@ -18,7 +18,9 @@ Debugging an extension involves starting Tableau with a command option to enable --- -## Download the Chromium Browser +## Download the Chromium Browser (Tableau 2018.2, 2018.3) + +
    Note If you are using Tableau 2019.1, you no longer need to use the Chromium browser. You can now debug extensions in Tableau Desktop using the latest versions of Chrome. If you are using Tableau 2018.2 or 2018.3, you still need the specific version of the Chromium browser for debugging.
    In order to actually do any debugging, you'll need to use a Chromium-based browser (Chromium is the open-source version of Chrome). You can use Chrome, but because of some version incompatibilities in the debugging protocol, we recommend using build 47.0.2526.0 of Chromium, which matches the version of the browser running inside Tableau (just download and unzip the file). * [Chromium for Windows (47.0.2526.0)](https://www.googleapis.com/download/storage/v1/b/chromium-browser-snapshots/o/Win%2F352221%2Fchrome-win32.zip?generation=1443839123039000&alt=media) diff --git a/docs/trex_error_handling.md b/docs/trex_error_handling.md index b32d6701..317e2efc 100644 --- a/docs/trex_error_handling.md +++ b/docs/trex_error_handling.md @@ -44,3 +44,51 @@ tableau.extensions.ui.displayDialogAsync(args... ).then((args... ) => { ``` +## Handle Extensions API errors when the dashboard is not visible + + In Tableau Server or Tableau Online version 2018.3 and later, when the browser window is not visible (that is, when the browser window Tableau is running in is minimized or in the background), the Extensions API method calls are blocked and an error object is returned. If you have code that might run when the dashboard is not visible, you should add code to check if the window is visible so that you can handle the error. If you are using `tableau-extensions-1.1.0.js` or later, the error code returned in this case is `VISIBILITY_ERROR`. + +### What happens when the error occurs + + This error can occur if an Extensions API method is called while Tableau is not in the foreground. For example, this could happen if the user switches tabs or minimizes the browser window and there is a timer that triggers the API call. When the user subsequently returns to the dashboard view, an error dialog box will appear. + + ![]({{site.baseurl}}/assets/ext_visibility_error_dialog.png) + + +### Identifying the error as a visibility-error + + To find out the cause, you can use the debugging tools in the browser. If you check the Console window, in Chrome for example, you might see an error message similar to the following. + + ![]({{site.baseurl}}/assets/ext_visibility_err_console.png) + + +### Add a check for visibility and add an event listener + +The Extensions API methods are intended to be used in scenarios where some manual interaction is required. However, there might be cases where a method is called on an interval, or there is a delay in execution, and the browser window that contains the extension is no longer visible when the method call is made. In these cases, you could use the [Page Visibility API](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API) and an event handler to avoid having your users encounter the `visibility-error`. + + +The following example shows how this error could be handled using an event listener for `visibilitychange`. You can create your own `visibilityhandlermethod` method if you need to wrap your Extensions API calls when the browser window is visible. + + +```javascript + + + document.addEventListener('visibilitychange', visibilityhandlermethod, false); + + + // + function visibilityhandlermethod() { + if (document.hidden) { + // do something while you pause the extension execution + } else { + // do stuff + // call the Extensions API + } + } + + + + + + +``` \ No newline at end of file diff --git a/docs/trex_events.md b/docs/trex_events.md index 5840056b..6deab1dc 100644 --- a/docs/trex_events.md +++ b/docs/trex_events.md @@ -3,9 +3,9 @@ title: Events and Event Handling layout: docs --- -In Tableau dashboard extensions, event handling operates at the sheet level. In the Extensions API, the `sheet` is an abstract class that both `dashboard` and `worksheet` inherit from. You can add event listeners on individual sheets in a dashboard or on the entire dashboard itself. If you have an event listener, when the specified event is raised, the callback method you provide is called to handle the event. You can use event listeners to trigger specific actions based upon dashboard interactions. +In Tableau dashboard extensions, event handling operates at the sheet level. In the Extensions API, the `sheet` is an abstract class that both `dashboard` and `worksheet` inherit from. You can add event listeners on individual sheets in a dashboard. However, you can't add an event listener on the entire dashboard itself. If you have an event listener, when the specified event is raised, the callback method you provide is called to handle the event. You can use event listeners to trigger specific actions based upon worksheet interactions. -The Tableau Extension API supports a range of events and provides methods for adding and removing event listeners. To manage the event listener, each sheet has an *event listener manager*. The manager provides a way to add or remove multiple events on sheets independently. +The Tableau Extension API supports a range of events and provides methods for adding and removing event listeners. To manage the event listener, each sheet has an *event listener manager*. The manager provides a way to add or remove multiple events on sheets independently. For example, a marks selection event can be raised for a particular sheet in a dashboard. Because a dashboard is also a sheet, a marks selection event could be raised on any marks selection in the entire dashboard. Each event contains an anonymous object with information pertaining to that event, such as the type or name of event and sheet the event occurred on. Listening to an event is done by calling the `addEventListener(type, callback)` method and passing in a callback function to handle the event. diff --git a/docs/trex_getstarted.md b/docs/trex_getstarted.md index 0a48722e..f5ef03b0 100644 --- a/docs/trex_getstarted.md +++ b/docs/trex_getstarted.md @@ -7,7 +7,8 @@ The Tableau Extensions API allows developers to create extensions for Tableau. T This section will take you through the process of setting up your environment to use one of the sample dashboard extensions. Using one of the sample extensions is a great way to learn and great way to get started developing your own extensions. In this section, you will start a simple web server on your computer to host the sample. You can use the same process for hosting the extension when you start developing your own. -| If you are looking for information about how to add an extension to a dashboard in Tableau, see [Use Dashboard Extensions](https://onlinehelp.tableau.com/current/pro/desktop/en-us/dashboard_extensions.htm){:target="_blank"}. If you are looking for extensions that you can use, see the [Tableau Extension Gallery](https://extensiongallery.tableau.com/){:target="_blank"}. +
    Note If you are looking for information about how to add an extension to a dashboard in Tableau, see Use Dashboard Extensions. If you are looking for extensions that you can use, see the Tableau Extension Gallery. +
    diff --git a/docs/trex_known_issues.md b/docs/trex_known_issues.md index ef20b4fd..29177b22 100644 --- a/docs/trex_known_issues.md +++ b/docs/trex_known_issues.md @@ -19,7 +19,7 @@ For information about what is new or has changed in each release, see the [Relea ### HTML drop-down menus in popup dialog windows -- HTML drop-down menus in popup dialog windows do not work as expected on MacOS. Users will not be able to select menu items using the mouse. They can select items with the cursor keys. To avoid issues on MacOS, use radio buttons or another method for user selection in the popup dialog. +- **Fixed in Tableau 2019.1** HTML drop-down menus in popup dialog windows do not work as expected on MacOS. Users will not be able to select menu items using the mouse. They can select items with the cursor keys. To avoid issues on MacOS, use radio buttons or another method for user selection in the popup dialog. ### Decimal separators in parameters @@ -29,3 +29,14 @@ For information about what is new or has changed in each release, see the [Relea When an extension needs full data access and the user does not have full data permission on the workbook, Tableau currently allows the extension to run. However, Tableau will throw a console error when the extension calls `getUnderlyingData()` method. See [Handle full data access and permission errors]({{ site.baseurl }}/docs/trex_getdata.html#handle-full-data-access-and-permission-errors). + +### Tableau Extensions API library version 1.0.0 + +If you are debugging your extension, you might see this message in the Debugging Tools console window if you are using the released version of the 1.0.0 library (for example, `tableau-extensions-1.0.0.js`) with a version of Tableau that is newer than Tableau 2018.2. + +``` +This is an alpha version of the Extensions API. Please upgrade to an official release. + +``` + +You can safely ignore this warning. However, if you are using the 1.0.0 library, be sure to upgrade to the latest version, or use or `tableau-extensions-1.latest.js`, so that you always pick up the most recent update of that version of the library when it becomes available. \ No newline at end of file diff --git a/docs/trex_release-notes.md b/docs/trex_release-notes.md index a551177f..77a8fe2e 100644 --- a/docs/trex_release-notes.md +++ b/docs/trex_release-notes.md @@ -13,10 +13,49 @@ See also: [Known Issues]({{site.baseurl}}/docs/trex_known_issues.html) ---- +### Tableau 2019.1 +*February 2019* +* Tableau Extensions API library: `tableau-extensions-1.1.0.js`
    (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api){:target="_blank"})
    + +* Download [Tableau Desktop 2019.1](https://www.tableau.com/support/releases){:target="_blank"} or [Tableau Server 2019.1](https://www.tableau.com/support/releases/server){:target="_blank"} + +Changes in this release: + +* Upgrade to the Chromium browser, which allows modern web technologies to be used with dashboard extensions (HTML 5, CSS, native ES6 support). Tableau 2019.1 now uses Qt 5.10, The Qt WebEngine is based upon Chromium 61.0.3163.99, with additional security fixes from newer versions. With this update, you no longer need to download and use a specific version of Chromium (47.0.2526.0) to debug dashboard extensions on Tableau Desktop. You can now debug extensions in Tableau Desktop using Chrome. + +* Show and hide capabilities for extensions (now you see it, now you don't). For more information, see [Show and Hide Objects in the Dashboard]({{site.baseurl}}/docs/trex_show_hide.html). + +* Starting in Tableau Server and Tableau Online 2019.1, when the dashboard is not visible (minimized or in the background), Extensions API method calls are blocked. If you have code that might run when the browser window is not visible, you should add code to check the state of the window Tableau is running in and then handle that condition appropriately. If you don't check the state, and your extension makes an API call, a `"visibility-error"` could be thrown because of the blocked state. Be sure to use the latest version of the library (`tableau-extensions-1.1.0.js`). For more information, see [Handle Extensions API errors when the dashboard is not visible]({{site.baseurl}}/docs/trex_error_handling.html#handle-extensions-api-errors-when-the-dashboard-is-not-visible). + + + +Bugs fixed in this release: + +* Select dropdown fixed on Macintosh. (TFSID 758234) +* The `applyRangeFilterAsync` method allows full range of options, and doesn't break when a user selects "all". (TFSID 766488) +* Fixed “Access is denied” error encountered when switching from a sheet containing an extension to any other sheet on a tabbed workbook on server (fixed in Tableau 2019.1, 2018.3.2, 2018.2.5). + +* Full support for IE11 now starts in 2018.2.3, 2018.2.3. + +* Fixed in Tableau Desktop 2019.1: Extension API synchronization issue.
    + In previous version of Tableau Desktop (2018.2, 2018.3), the execution of extension API calls was not properly synchronized with longer running actions. These issues would most often occur with a worksheet that took multiple seconds to refresh. This could manifest itself in various ways: + * The `intializeAsync` method could return the promise before the dashboard was properly loaded in Tableau. + * A `FilterChanged` event could be triggered before the data was actually refreshed. As a result, calls to `getSummaryDataAsync` could return the data before the filter was changed. + * If an extension API was called from a `setInterval` or similar function, while other actions were going on, Tableau could occasionally crash. + + Customers who upgrade to Tableau Desktop 2019.1 will not have these synchronization issues with extensions. + + + + + + + +--- ### Tableau 2018.3 -*November, 2018* +*November 2018* - Tableau Extensions API library: `tableau-extensions-1.0.0.js` *No change for this release*
    (download or clone the Extensions API repository on [GitHub](https://github.com/tableau/extensions-api){:target="_blank"}) @@ -33,7 +72,7 @@ New in this release: ### TC18 -*October, 2018* +*October 2018* - Tableau Extensions API library: `tableau-extensions-1.0.0.js` *No change for this release*
    @@ -55,7 +94,7 @@ Bugs fixed in this release: --- ### Tableau 2018.2 -*July, 2018* +*July 2018* Release of the Tableau Extensions API diff --git a/docs/trex_security.md b/docs/trex_security.md index 0f89c304..2d4a8bef 100644 --- a/docs/trex_security.md +++ b/docs/trex_security.md @@ -1,15 +1,15 @@ --- -title: Security and Tableau Extensions +title: HTTPS and Tableau Extensions layout: docs --- A Tableau extension is essentially a web application that runs inside a Tableau dashboard. The extension can interact with other components in the dashboard and potentially has access to the visible and underlying data in the workbook (through a well-defined API). In addition, the web application can be running code on a server that sits outside of the domain where Tableau Server or Tableau Desktop are located. For security, Tableau requires the following: -- All extensions must use the HTTP Secure (HTTPS) protocol. +* All extensions must use the HTTP Secure (HTTPS) protocol. -- To run on Tableau Server, the URL of the extension must be added to a safe list. The Tableau Server site administrator manages this list. +* To run on Tableau Server, the URL of the extension must be added to a safe list. The Tableau Server site administrator manages this list. -- By default, anyone using the extension will be prompted and asked to allow or deny the extension access. The Tableau Server site administrator can control whether the prompt appears for each extension. +* By default, anyone using the extension will be prompted and asked to allow or deny the extension access. The Tableau Server site administrator can control whether the prompt appears for each extension. This section covers options for setting up your extension to use HTTPS. For information about adding an extension to the safe list on Tableau Server or Tableau Online, or how to configure the prompts to allow or deny access, see [Manage Dashboard Extensions on Tableau Server](https://onlinehelp.tableau.com/current/server/en-us/dashboard_extensions_server.htm) or [Manage Dashboard Extensions on Tableau Online](https://onlinehelp.tableau.com/current/online/en-us/dashboard_extensions_server.htm) for more information. diff --git a/docs/trex_show_hide.md b/docs/trex_show_hide.md new file mode 100644 index 00000000..3b57f9d5 --- /dev/null +++ b/docs/trex_show_hide.md @@ -0,0 +1,153 @@ +--- +title: Show and Hide Objects in the Dashboard +layout: docs +--- + +Starting with Tableau 2019.1, you can use the `ZoneVisibilityType` enum and `setZoneVisibilityAsync` method to control whether objects in a dashboard are visible or hidden. You can use this feature to create tooltip-like popup dialog boxes, or to create animated slide-show effects by toggling the visibility of the objects in the dashboard. + +**In this section** + +* TOC +{:toc} + +## Requirements for show and hide + +* Tableau 2019.1 or later (Desktop, Server, Online) +* Tableau Extensions API library: `tableau-extensions-1.1.0.js` or later +* The object in the dashboard you want to show and hide must be floating (not tiled) + + + + +## Find the objects and object ids in the dashboard + +A dashboard contains a group of objects. These objects are worksheets, web pages, UI components like text, vertical or horizontal layout containers, or blank zones for spacing. To be able to show or hide an object in the dashboard, you need to have information to identify the object. Starting with the `tableau-extensions-1.1.0.js` library, objects in the dashboard have properties for `name`, `id`, and `isVisible`. + + +
    Note A dashboard object has another property called isfloating. If the dashboard zone (or object) that contains the extension is not floating, attempting to change the visibility of the object by calling setZoneVisibilityAsync on the the object will fail and cause an error. +
    + +This might be obvious, but you first need to place the items you want to show or hide in the dashboard. One of these items could be the extension you are adding. If you want to hide the extension, so that it is not visible while it's running, you first need to add it to the dashboard. + +For example, a worksheet in a dashboard fits inside a layout zone. To be able to show or hide a worksheet in a dashboard, you first need to find to find the `id` of the object (or zone) that contains the worksheet. +The following code example iterates through the objects in the dashboard and prints out information to the console. + +```js + + tableau.extensions.dashboardContent.dashboard.objects.forEach(function(object){ + console.log(object.name + ":" + object.type + ":" + object.id + ":" + object.isVisible); + }); + +``` + +## Create a map of the zone and its show or hide state + +If you know the name of the zone you want to hide, you can find the zone object and from that set the zone's `ZoneVisibilityType` properties. You can find and change the names of the zones in the dashboard using the Layout pane in Tableau, under **Item Hierarchy**. You want to make sure that the zones you want to show and hide are floating. + + ![]({{site.baseurl}}/assets/dashboard_layout_obj.png){:height="25%" width="25%"} + + +The following code example iterates though the objects in the dashboard to locate two named objects. The `setZoneVisibilityAsync` method that we use to show or hide a zone takes a `zoneVisibilityMap` as a parameter. This is a map of the zone (`object.id`) and a `ZoneVisibilityType` property, which can be set to `show` or `hide`(`tableau.ZoneVisibilityType.Hide`). + +In this example, the zones Wiki and ShowHide have their properties set to hide. +ShowHide is the zone that contains the dashboard extension. The example creates two `zoneVisibilityMap` objects: `extensionVisibilityObject` and `wikiVisibilityObject`. The Wiki zone is also added to the `extensionVisibilityObject`, where it can be passed to the `setZoneVisibilityAsync` method when the dashboard extension is first hidden. You can toggle the visibility of multiple zones in a `zoneVisibilityMap`. + +```javascript + + let wikiZone = ["Wiki"]; + let extensionName = ["ShowHide"]; + let extensionVisibilityObject = {}; + let wikiVisibilityObject = {}; + + tableau.extensions.dashboardContent.dashboard.objects.forEach(function(object){ + if(extensionName.includes(object.name)){ + extensionVisibilityObject[object.id] = tableau.ZoneVisibilityType.Hide; + }else if(wikiZone.includes(object.name)){ + wikiVisibilityObject[object.id] = tableau.ZoneVisibilityType.Hide; + extensionVisibilityObject[object.id] = tableau.ZoneVisibilityType.Hide; + } + }); + +``` + + +## Set the visibility of the zone in the dashboard + +After you have built the map of zone id and the zone's show or hide state, you can call the `setZoneVisibilityAsync` method and pass it the zone visibility map you created. +The following code example, hides the zone that contains the dashboard extension (`ShowHide`) and the zone (`Wiki`) that is used to contain the wiki page and the City Map worksheet, and then prints a message to the console. + + +```javascript + + tableau.extensions.dashboardContent.dashboard.setZoneVisibilityAsync(extensionVisibilityObject).then(() => { + console.log("done"); + }) + +``` + + +## Troubleshooting and debugging show and hide + +So you have hidden your extension, great! So how do you access the shortcut menu so that you can reload the extension while you are developing and testing your extension? It might not be obvious, but you can access the shortcut menu in the Layout pane in the dashboard, under **Item Hierarchy**. If you right click the extension, you have access to the shortcut menu. + +If you want to use the Debug Option, **Pause Before Loading**, you should make sure the extension is visible. If the extension is hidden, you won't be able to click in the extension zone to continue loading the extension. + + +## Complete listing of a show and hide example + +The following code shows how an extension can be used to create a tool-tip like dialog box, by showing and hiding zones in a dashboard. This example uses the Superstore sample as a starting point. The dashboard has actions to call the wikipedia page for the state selected and an action to filter the City Map based on the state selected. This example assumes that there is a zone called `Wiki` that contains the City Map worksheet and a web page (wikipedia.org). The example also hides the extension itself (`ShowHide`) and then sets an event listener on a `MarkSelectionChanged` event in the State Map worksheet. An event occurs when a user clicks a state in the map. If a single state is selected, the event handler method sets the zone visibility and calls `setZoneVisibilityAsync` to show the zone with the city map and wikipedia page for the state. + +```js + + tableau.extensions.initializeAsync().then(function() { + tableau.extensions.dashboardContent.dashboard.objects.forEach(function(object){ + console.log(object.name + ":" + object.type + ":" + object.id + ":" + object.isVisible); + }); + + let wikiZone = ["Wiki"]; + let extensionName = ["ShoWHide"]; + let extensionVisibilityObject = {}; + let wikiVisibilityObject = {}; + + tableau.extensions.dashboardContent.dashboard.objects.forEach(function(object){ + if(extensionName.includes(object.name)){ + extensionVisibilityObject[object.id] = tableau.ZoneVisibilityType.Hide; + }else if(wikiZone.includes(object.name)){ + wikiVisibilityObject[object.id] = tableau.ZoneVisibilityType.Hide; + extensionVisibilityObject[object.id] = tableau.ZoneVisibilityType.Hide; + } + }); + + tableau.extensions.dashboardContent.dashboard.setZoneVisibilityAsync(extensionVisibilityObject).then(() => { + console.log("done"); + }).then(()=>{ + worksheet = tableau.extensions.dashboardContent.dashboard.worksheets.find(ws => ws.name === "State Map"); + worksheet.addEventListener(tableau.TableauEventType.MarkSelectionChanged, selection) + }) + + function selection(data) { + data.getMarksAsync().then(marks => { + if (marks.data[0].data.length === 1) { + toggleWikiVisibility(tableau.ZoneVisibilityType.Show); + } else { + toggleWikiVisibility(tableau.ZoneVisibilityType.Hide); + } + }) + } + + function toggleWikiVisibility(visibility) { + for(let key in wikiVisibilityObject) { + wikiVisibilityObject[key] = visibility; + } + tableau.extensions.dashboardContent.dashboard.setZoneVisibilityAsync(wikiVisibilityObject).then(() => { + console.log("done"); + }); + } + + }); + + + + + +``` \ No newline at end of file