Hosting and Contributing to the Community Portal
diff --git a/assets/Ext_API.png b/assets/Ext_API.png
new file mode 100644
index 00000000..d4d4922e
Binary files /dev/null and b/assets/Ext_API.png differ
diff --git a/assets/Extensions_Safe_List_Block_List_Evaluation_2x.png b/assets/Extensions_Safe_List_Block_List_Evaluation_2x.png
new file mode 100644
index 00000000..fb352a0b
Binary files /dev/null and b/assets/Extensions_Safe_List_Block_List_Evaluation_2x.png differ
diff --git a/assets/onload_debugging.gif b/assets/onload_debugging.gif
new file mode 100644
index 00000000..3c775201
Binary files /dev/null and b/assets/onload_debugging.gif differ
diff --git a/assets/remote_debugging.gif b/assets/remote_debugging.gif
new file mode 100644
index 00000000..2e7c4780
Binary files /dev/null and b/assets/remote_debugging.gif differ
diff --git a/assets/server_dbg_chrome.png b/assets/server_dbg_chrome.png
new file mode 100644
index 00000000..063cd17e
Binary files /dev/null and b/assets/server_dbg_chrome.png differ
diff --git a/docs/trex_create.md b/docs/trex_create.md
index fac30459..588478d9 100644
--- a/docs/trex_create.md
+++ b/docs/trex_create.md
@@ -1,15 +1,15 @@
---
-title: Create a Tableau Extension
+title: Create a 'Hello World" Dashboard Extension
layout: docs
---
To create a Tableau extension you need the following components.
-- A manifest file that identifies and describes the extension.
-- The Tableau Extensions API JavaScript library (`tableau-extensions-N.N.N.js`)
-- A web page that uses the library. The web page provides controls that interact with Tableau objects and data in the dashboard.
-- Additional JavaScript and HTML and CSS files as needed for your web app.
-- A web server to host your web app.
+- A manifest file that identifies and describes the extension.
+- The Tableau Extensions API JavaScript library (`tableau-extensions-N.N.N.js`)
+- A web page that uses the library. The web page provides controls that interact with Tableau objects and data in the dashboard.
+- Additional JavaScript and HTML and CSS files as needed for your web app.
+- A web server to host your web app.
---
**In this section**
@@ -20,51 +20,58 @@ To create a Tableau extension you need the following components.
### What you need to get started
-These instructions assume that you already have cloned or download the Extensions API SDK. For information about setting up your environment and downloading Tableau Desktop for the Developer Preview, see [Get Started]({{site.baseurl}}/docs/trex_getstarted.html).
+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.
### 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. When they are installed, the registered extensions appear under **Extensions** on the left side of the dashboard.
+The manifest file (`EXTENSION-NAME.trex`) is an XML file that describes the extension and provides information to register the extension with Tableau.
+
+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"}.
-- Create a manifest file for your extension.
-Name the manifest file for your extension (for example, `HelloExtensions` 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). An XSD is available for validation on the pre-release website [here](https://prerelease.tableau.com/project/version/item.html?cap=52e2710a0793434d82142736c7ab3029&arttypeid={0DD668AE-472C-4E70-B465-35F7AE0DEB6D}&artid={939493D2-8000-4192-857A-67624CBCC35A}).
+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.
```xml
-
-
-
- en_US
-
- Extension Description
-
- 1.0
-
- SERVER:PORT/PATH
- iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEwAACxMBAJqcGAAAAlhJREFUOI2Nkt9vy1EYh5/3bbsvRSySCZbIxI+ZCKsN2TKtSFyIrV2WuRCJuBiJWxfuxCVXbvwFgiEtposgLFJElnbU1SxIZIIRJDKTrdu+53Uhra4mce7Oe57Pcz7JOULFisViwZ+29LAzOSjQYDgz1ZcCvWuXV11MJpN+OS/lm6179teqH0yDqxPTCyKSA8DcDsyOmOprnCaeP7459pdgy969i0LTC3IO/RQMyoHcQN+3cnljW3dNIFC47qDaK3g7BwdTkwBaBELT4ZPOUVWgKl4ZBnjxJPUlMDnTDrp0pmr6RHFeEjjcUUXPDGeSEwDN0Xg8sivxMhJNjGzbHd8PkM3eHRfkrBM5NkcQaY2vUnTlrDIA0NoaX+KLXFFlowr14tvVpqb2MICzmQcKqxvbumv+NAhZGCCIPwEw6QWXKYRL/VUXO0+rAUJiPwAk5MIlgVfwPjjHLCL1APmHN94ZdqeYN+NW/mn6I4BvwQYchcLnwFhJMDiYmlRxAzjpKWZkYkUCcZ2I61wi37tLbYyjiN0fHk5Oz3nGSLSzBbNHCF35R7f6K1/hN9PRhek11FrymfQQQKB4+Gl05P2qNRtmETlXW7e+b2z01dfycGNbfFMAbqNyKp9Jp4rzOT8RYFs0njJkc2iqsCObvTsOsDWWqA5C1uFy+Uz/oXJeKwVT4h0RmPUXhi79vuC0Ku6yOffTK3g9lfxfDQAisY516sg5kfOCiJk7HoLt2cf9b/9LANAc7dznm98PagG1fUOZ9IP5uMB8Q4CPoyNvausapkTt3rNMuvdf3C/o6+czhtdwmwAAAABJRU5ErkJggg==
-
-
-
-
- name in English
- name in French
- name in German
-
-
-
+
+
+
+ en_US
+
+ Extension Description
+
+ 1.0
+
+ SERVER:PORT/PATH
+
+
+ iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEwAACxMBAJqcGAAAAlhJREFUOI2Nkt9vy1EYh5/3bbsvRSySCZbIxI+ZCKsN2TKtSFyIrV2WuRCJuBiJWxfuxCVXbvwFgiEtposgLFJElnbU1SxIZIIRJDKTrdu+53Uhra4mce7Oe57Pcz7JOULFisViwZ+29LAzOSjQYDgz1ZcCvWuXV11MJpN+OS/lm6179teqH0yDqxPTCyKSA8DcDsyOmOprnCaeP7459pdgy969i0LTC3IO/RQMyoHcQN+3cnljW3dNIFC47qDaK3g7BwdTkwBaBELT4ZPOUVWgKl4ZBnjxJPUlMDnTDrp0pmr6RHFeEjjcUUXPDGeSEwDN0Xg8sivxMhJNjGzbHd8PkM3eHRfkrBM5NkcQaY2vUnTlrDIA0NoaX+KLXFFlowr14tvVpqb2MICzmQcKqxvbumv+NAhZGCCIPwEw6QWXKYRL/VUXO0+rAUJiPwAk5MIlgVfwPjjHLCL1APmHN94ZdqeYN+NW/mn6I4BvwQYchcLnwFhJMDiYmlRxAzjpKWZkYkUCcZ2I61wi37tLbYyjiN0fHk5Oz3nGSLSzBbNHCF35R7f6K1/hN9PRhek11FrymfQQQKB4+Gl05P2qNRtmETlXW7e+b2z01dfycGNbfFMAbqNyKp9Jp4rzOT8RYFs0njJkc2iqsCObvTsOsDWWqA5C1uFy+Uz/oXJeKwVT4h0RmPUXhi79vuC0Ku6yOffTK3g9lfxfDQAisY516sg5kfOCiJk7HoLt2cf9b/9LANAc7dznm98PagG1fUOZ9IP5uMB8Q4CPoyNvausapkTt3rNMuvdf3C/o6+czhtdwmwAAAABJRU5ErkJggg==
+
+
+
+
+ name in English
+ name in French
+ name in German
+
+
+
```
- In this file, you need to provide values for a few elements. Some key pieces are:
-- For `` use reverse domain name notation to uniquely identify the extension (`com.example.extension.demo`)
-- For `` make sure that this specifies the URL of your web application. You must use the HTTPS protocal. The exception to this requirement is `localhost`, where you can use HTTP. For example, if you are doing development work and want to host the file locally on your computer using port 8765, you might use: `http://localhost:8765/myExtension.html`
+- For `` use reverse domain name notation to uniquely identify the extension (`com.example.extension.hello.demo`)
+- For `` make sure that this specifies the URL of your web application. You must use the HTTPS protocol. The exception to this requirement is `localhost`, where you can use HTTP. For example, if you created a `HelloDemo` folder and want to host the file locally on your computer using port 8765, you might use: `http://localhost:8765/HelloDemo/HelloExtension.html`
- The `` element that specifies the minimum version of the Extensions API library that is required to run the extension.
- For `` you must use a Base64-encoded icon. To use the default icon, copy and paste the `` example here, or copy one of the manifest files (`.trex`) from the samples.
+- Provide the `name` for your extension (`Hello Extensions!`). The manifest file can be localized, so provide the name (or names) in the appropriate `` elements in the `` section.
+- 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.
-
-
-- To add the extension to a Tableau dashboard, you need to drag the **Extension** object on to the dashboard, and then use the **Choose an Extension** dialog box to locate and open the manifest file. For information about validating the manifest and adding version information, see the [Tableau Extension Manifest]({{site.baseurl}}/docs/trex_manifest.html).
+- For information about validating the manifest and adding version information, see the [Tableau Extension Manifest]({{site.baseurl}}/docs/trex_manifest.html).
@@ -78,54 +85,88 @@ The web app you create controls and interacts with the Tableau dashboard objects
#### Create the HTML page
-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.
-
-1. In the HTML page, add a link to the JavaScript library (for example, `tableau-extensions-1.latest.js`).
- ```
-
-
-```
-2. Add links to additional JavaScript files and code that you need. 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. The following code is from a simple sample.
- ```html
-
-
-
-
-
-
- `Hello Extensions`
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Hello Extensions!
-
Not Initialized
-
-
-
-
-
- ```
-
-3. Save the HTML file and any other files your web app needs.
-
-4. 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 add-in. Be sure to include the `http://` or `https://` in the URL. If you are using your `localhost` for development work, you might want to set up a lightweight web server, for example, you could use Python 2.7 and the SimpleHTTPServer module:
-
- python -m SimpleHTTPServer [PORT]
+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`.
+
+
+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
+
+
+
+
+
+
+ Hello Extensions`
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Hello Extensions!
+
Not Initialized
+
+
+
+
+
+ ```
+
+ 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
+
+
+
+
+ ```
+
+4. The sample code also includes a link to `hello-extension.js`, this is a JavaScript file that you will need to create. The path assumes that the JavaScript file is in the same directory as your HTML file. Adjust the path and name as necessary and save the file.
+
+ ```html
+
+
+
+
+ ```
+
+#### 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):
+
+ ```bash
+
+ npm install http-server -g && http-server -p PORT
+ ```
+
+2. Check the HTML page to make sure that your web server is working. Place the URL in the address bar of your browser. This is the URL from the `` you specified in the manifest file. Be sure to include the full path to the web page.
+
+ ```html
+
+ http://localhost:8765/HelloDemo/HelloExtension.html
+
+ ```
### Test your extension in Tableau
@@ -135,7 +176,7 @@ After you have created the manifest file (`.trex`) and have hosted your web app
1. Start up your web page or application (or make sure it is running).
2. Start Tableau and open a workbook with a dashboard or create a new dashboard.
-3. In the dashboard, under **Objects**, select **Extension** and drag it on to the dashboard. In the **Choose an Extension** dialog box, click **Choose** and browse to directory where you have your manifest file.
+3. In the dashboard, under **Objects**, select **Extension** and drag it on to the dashboard. In the **Choose an Extension** dialog box, click **My Extensions** and browse to directory where you have your manifest file.
After you select the manifest file, your web page should appear in the dashboard zone.
@@ -148,58 +189,61 @@ After you have created the manifest file (`.trex`) and have hosted your web app
### Add code to initialize the extension and call Tableau Extensions API functions
-In your JavaScript code (either in your HTML page or in a separate JavaScript file), you first need to initialize the extension. To do this, you call `tableau.extensions.initializeAsync()`. The function returns after the initial bootstrap operation is complete and the extension is available for use. The Extensions API follows the [CommonJS Promises/A standard](http://wiki.commonjs.org/wiki/Promises/A) for asynchronous method calls.
+The next step is to create the JavaScript that calls the Extensions API. In your JavaScript code (either in your HTML page or in a separate JavaScript file), you first need to initialize the extension. To do this, you call `tableau.extensions.initializeAsync()`. The function returns after the initial bootstrap operation is complete and the extension is available for use. The Extensions API follows the [CommonJS Promises/A standard](http://wiki.commonjs.org/wiki/Promises/A) for asynchronous method calls.
+
+1. In the same directory as your HTML page, create a file called `hello-extension.js`. The name just needs to match the name of the file that you specified in your HTML page
+(``).
-**Syntax:**
+2. Copy the following example code and paste it into the file.
-`tableau.extensions.initializeAsync()`
+ ```javascript
+ $(document).ready(function() {
-**Example**
+ // Hook up an event handler for the load button click.
+ // Wait to initialize until the button is clicked.
+ $("#initializeButton").click(function() {
-The following code 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.
-```javascript
-$(document).ready(function() {
+ // Disable the button after it's been clicked
+ $("#initializeButton").prop('disabled', true);
- // Hook up an event handler for the load button click.
- // Wait to initialize until the button is clicked.
- $("#initializeButton").click(function() {
+ tableau.extensions.initializeAsync().then(function() {
- // Disable the button after it's been clicked
- $("#initializeButton").prop('disabled', true);
+ // Initialization succeeded! Get the dashboard
+ var dashboard = tableau.extensions.dashboardContent.dashboard;
- tableau.extensions.initializeAsync().then(function() {
+ // Display the name of dashboard in the UI
+ $("#resultBox").html("I'm running in a dashboard named " + dashboard.name + "");
+ }, function(err) {
- // Initialization succeeded! Get the dashboard
- var dashboard = tableau.extensions.dashboardContent.dashboard;
+ // something went wrong in initialization
+ $("#resultBox").html("Error while Initializing: " + err.toString());
+ });
+ });
+ });
- // Display the name of dashboard in the UI
- $("#resultBox").html("I'm running in a dashboard named " + dashboard.name + "");
- }, function(err) {
+ ```
- // something went wrong in initialization
- $("#resultBox").html("Error while Initializing: " + err.toString());
- });
- });
-});
-```
+|**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
-After you have your extension installed and showing up in Tableau, you can continue to work on your web application and see the changes without leaving Tableau.
-Reload the extension in Tableau.
+After your extension is installed and showing up in Tableau, you can continue to work on your web application and see the changes without leaving Tableau.
-Use the **Reload** option to refresh and reload the extension in the dashboard.
+1. Make changes to your HTML and JavaScript files and save those changes.
+2. When you want to see those changes, select the extension in the dashboard.
-{:height="25%" width="25%"}
+3. In the shortcut menu, click **Reload** to refresh and reload the extension in the dashboard.
+ {:height="25%" width="25%"}
-For information about debugging your extension, see [Remote Debugging of JavaScript and HTML]({{site.baseurl}}/docs/trex_debugging.html).
+
+For information about debugging your extension, see [Debug Extensions in Tableau Desktop]({{site.baseurl}}/docs/trex_debugging.html) and [Debug Extensions in Tableau Server and Tableau Online]({{site.baseurl}}/docs/trex_debug_server.html).
You can also use the Tableau log files to identify issues, see [Use Log files to Troubleshoot Dashboard Extensions]({{site.baseurl}}/docs/trex_logging.html).
-------------------------------------------------------------------------
+---
## What's next?
diff --git a/docs/trex_debug_server.md b/docs/trex_debug_server.md
new file mode 100644
index 00000000..81dc7ac7
--- /dev/null
+++ b/docs/trex_debug_server.md
@@ -0,0 +1,109 @@
+---
+title: Debug Extensions in Tableau Server and Tableau Online
+layout: docs
+---
+
+A dashboard extension is a web app inside of a dashboard on Tableau Server and Tableau Online. If you add an extension to a dashboard in web authoring, or publish a dashboard that contains a dashboard extension to Tableau Server or Tableau Online, you can debug the extension using the debugging tools that are built into the browser that you are using.
+
+The following section describes how you could debug your extension using Chrome. The same principles generally apply if you are using other browsers and their developer tools. For more information about the Chrome developer tools, see [Chrome DevTools](https://developers.google.com/web/tools/chrome-devtools/){:target="_blank"}. For more information about debugging JavaScript with the DevTools, see [Debug JavaScript](https://developers.google.com/web/tools/chrome-devtools/javascript/).
+
+
+
+---
+**In this section**
+
+* TOC
+{:toc}
+
+
+
+---
+
+## Open the debugging tools in the browser
+
+1. Open the workbook containing the extension in Tableau Server or Tableau Online.
+ **Note:** If the extension fails to load and you are using `localhost` to serve your extension, you might encounter the mixed content security setting. To get past this issue, see [Load and view localhost content on sites that use secure connections]({{site.baseurl}}/docs/trex_debug_server.html#load-and-view-localhost-content-on-sites-that-use-secure-connections).
+
+2. Open the debugging tools.
+The process varies by browser. If you are using Chrome, enter **CTRL** + **SHIFT** + **i** (Windows) or **COMMAND** + **OPTION** + **i** (MacOS).
+
+3. Locate the source code for your extension.
+For example, if you were using Chrome for debugging, you can open the Source pane. Under folders shown on the navigation pane, you will find one for the extension. For example, you might see something like `extension_frame_37 (filtering.html)`.
+Under this, you will find the name of the server (for example `localhost`), and you can drill down to your JavaScript source files.
+
+---
+
+## Set breakpoints and explore the code
+
+If you need to debug your extension, setting a breakpoint in your source code is a good way to get started. When the breakpoint is hit, the code execution is paused in the debugger. You can then use the debugger controls to step through your code. You can use the debugging tools to see the values of local variables, and the call stack. You can also hover over in-scope variables in source window and see the current values.
+
+1. Locate the line in your source code and set the breakpoint.
+ For example, you want to set this early in your code after the `initializeAsync()` function call.
+
+2. Refresh or reload the browser window.
+You might see the permission dialog box prompt as the extension gets loaded.
+
+3. Step through your code or set other breakpoints.
+You can examine variables to see what information the extension has access to. For example, if you step or stop on the source line where you have access to the dashboard object, you can examine the values of the available resources in the dashboard.
+
+ ```javascript/
+ // To get filter info, first get the dashboard.
+ const dashboard = tableau.extensions.dashboardContent.dashboard;
+ ```
+
+4. Explore the dashboard extension namespace using the Console window.
+For example, entering the following in the Console window (while you are paused in your extension code) will print out the names of all the worksheets in the dashboard.
+
+
+ ```javascript
+
+ tableau.extensions.dashboardContent.dashboard.worksheets.forEach(function (worksheet){console.log(worksheet.name)})
+
+ ```
+ The following screenshot illustrates what your debugging session might look like if you use the Chrome DevTools. A breakpoint was set and the extension's JavaScript code is paused in the debugger.
+
+
+ 
+
+
+
+---
+
+## Debugging during initialization
+
+If you need to troubleshoot or debug issues that prevent your extension from loading or initializing on Tableau Server or Tableau Online, you can set breakpoints that trigger when your JavaScript code is loaded.
+
+1. In the Chrome browser, select **Event Listener Breakpoint > Script > Script First Statement**.
+After you select the event breakpoint and refresh or reload the browser window, code execution will stop when every script is loaded.
+
+2. Reload or refresh the browser.
+
+3. In the debugger, click **Continue** to get to your JavaScript code.
+You might need to click **Continue** many times, as code execution stops for all the scripts in the dashboard. If you are just looking to debug general initialization problems and haven't tested your extension in Tableau Desktop, you might want to start there first.
+
+In Tableau Desktop, there is a debugging option you can set to pause the extension when it is loading. For more information, see [Debugging loading and initialization issues]({{site.baseurl}}/docs/trex_debugging.html#debugging-loading-and-initialization-issues).
+
+If your extension fails to load at all on Tableau Server or Tableau Online, check the console window of the debugger to see if there is an error message of some kind. The console messages can give you clues about where to begin investigating when something goes wrong. If the error is caused by mixed content (trying to load an HTTP web page inside of a secure HTTPS server), see [Load and view localhost content on sites that use secure connections]({{site.baseurl}}/docs/trex_debug_server.html#load-and-view-localhost-content-on-sites-that-use-secure-connections).
+
+
+---
+
+## Load and view localhost content on sites that use secure connections
+
+*Mixed Content Warning*
+
+If you want to test and debug your extension (running on `http://localhost`) with Tableau Online, or with a Tableau Server site that is using HTTPS, you might find that your extension fails to load. You won't see any error message in the dashboard if this happens. There will just be an empty `iframe` where the extension should appear. The reason for this is that the default settings of many browsers blocks the extension from loading because the extension is not using a secure connection (HTTPS).
+
+To temporarily get around these safety settings for the session, you can click the shield icon (or lock icon) in the browser's address bar. The alert dialog box will allow you to either load the scripts, or allow you to view the full content of the page. As soon as you load the unsafe scripts or allow the blocked content, the extension will load and will continue to be available for the duration of your session. Be sure to close the browser completely when you are finished testing. The following example shows what you might see in Chrome.
+
+
+
+
+
+During the session, anytime you refresh or reload the web page, you will see the extensions dialog box requesting permission to run. And in the debugger console, you might see a warning message about mixed content.
+
+```
+Mixed Content: The page at 'https:/some_URLs#4' was loaded over HTTPS, but requested an insecure resource 'http://localhost:8765/Samples/Filtering/filtering.html'. This content should also be served over HTTPS.
+
+```
+
diff --git a/docs/trex_debugging.md b/docs/trex_debugging.md
index 687d9b08..a23b91e0 100644
--- a/docs/trex_debugging.md
+++ b/docs/trex_debugging.md
@@ -1,9 +1,13 @@
---
-title: Remote Debugging of JavaScript and HTML
+title: Debug Extensions in Tableau Desktop
layout: docs
---
-A dashboard extension embeds a web page and runs a Chromium-based browser inside of Tableau. Fortunately, you can debug this embedded web browser using the remote debugging abilities built into Chromium.
+A dashboard extension embeds a web page and runs a Chromium-based browser inside of Tableau Desktop. Fortunately, you can debug this embedded web browser using the remote debugging abilities built into Chromium.
+
+Debugging an extension involves starting Tableau with a command option to enable remote debugging (over a debug port). You can then run a specific version of the Chromium debugger and connect to Tableau Desktop using the debug port.
+
+
---
**In this section**
@@ -11,81 +15,115 @@ A dashboard extension embeds a web page and runs a Chromium-based browser inside
* TOC
{:toc}
-
-## Set up Tableau for debugging (Windows)
+---
+
+## Download the Chromium Browser
+
+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)
+* [Chromium for macOS (47.0.2526.0)](https://www.googleapis.com/download/storage/v1/b/chromium-browser-snapshots/o/Mac%2F352221%2Fchrome-mac.zip?generation=1443838516381000&alt=media)
+
+---
+
+## Start Tableau Desktop and enable debugging (Windows)
-If you are using Tableau Desktop on Windows, you need to open a Command Prompt window and run a command to start Tableau with debugging enabled.
-1. Open a Command Prompt window.
-2. Start Tableau using the following command:
+1. Exit Tableau if it is already running on your computer.
+2. Open a Command Prompt window.
+2. Start Tableau using the following command.
+ Replace `` with the version of Tableau you are using (for example, `Tableau 2018.3`).
```
-"C:\Program Files\Tableau\Tableau\bin\tableau.exe" --remote-debugging-port=8696
+"C:\Program Files\Tableau\Tableau \bin\tableau.exe" --remote-debugging-port=8696
```
-This command enables remote debugging for all extensions.
+This command enables remote debugging of extensions for this session of Tableau.
+
+**Note:** The remote debugging port (for example, `8696`) must match the port address you use with Chromium for debugging. This is *not* the HTTP port that you are using to host your extension, the port that is specified in the manifest file (`.trex`).
+
+---
+
+#### Optional - Create a Tableau shortcut for debugging (Windows)
+
+For convenience, you could also create a shortcut for Tableau and add the remote debugging option to Properties dialog box.
-For convenience, you could also create a shortcut for Tableau and add the remote debugging option to Properties dialog box. Select Tableau from the **Start** menu, and then right-click and select **Properties** or select **Open file location**. If you open the file location, you can create a new shortcut to `Tableau.exe` (call it something like *Tableau - Debug* ). Open the Properties for the new shortcut and append `-remote-debugging-port=8696` at the end of the command in the **Target** text box. The debugging option goes after the closing quotation mark for `"Tableau.exe"`.
+1. Select Tableau from the **Start** menu, and then right-click and select **Properties** or select **Open file location**.
+If you open the file location, you can create a new shortcut to `Tableau.exe` (call it something like *Tableau - Debug* ). Right click the shortcut to open the Properties dialog box.
+3. In the Properties dialog box, append `-remote-debugging-port=8696` at the end of the command in the **Target** text box. The debugging option goes after the closing quotation mark for `"Tableau.exe"`.
-{:height="40%" width="40%"}
+ {:height="40%" width="40%"}
-## Set up Tableau for debugging (macOS)
+---
+## Start Tableau Desktop and enable debugging (macOS)
-If you are using Tableau Desktop on macOS, you need to open a Terminal window and run a command to enable debugging.
-1. Open a Terminal window.
-2. Start Tableau using the following command:
+1. Open a Terminal window.
+2. Start Tableau using the following command.
+ Replace `` with the version of Tableau you are using (for example,`2018.3.app`).
```
- open /Applications/Tableau\ Desktop\ main.app --args --remote-debugging-port=8696
+ open /Applications/Tableau\ Desktop\ .app --args --remote-debugging-port=8696
+
```
-**Note:** The remote debugging port (for example, `8696`) must match the port address you use with Chromium for debugging. This is not the HTTP port that you are using to host your extension, the port that is specified in the manifest file (`.trex`).
+This command enables remote debugging of extensions for this session of Tableau.
+**Note:** The remote debugging port (for example, `8696`) must match the port address you use with Chromium for debugging. This is *not* the HTTP port that you are using to host your extension, the port that is specified in the manifest file (`.trex`).
+
+
+---
-## Download the Chromium Browser
-In order to actually do any debugging, you'll need to use a Chromium-based browser. You can use a normal install of 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)
-* [Chromium for macOS (47.0.2526.0)](https://www.googleapis.com/download/storage/v1/b/chromium-browser-snapshots/o/Mac%2F352221%2Fchrome-mac.zip?generation=1443838516381000&alt=media)
+## Debugging Tableau Desktop using Chrome/Chromium
-## Debugging using Chrome/Chromium
-After you have installed the Chromium browser and have enabled debugging in Tableau, you can start debugging your extension.
+After you install the Chromium browser and enable debugging in Tableau, you can start debugging your extension.
-1. Start Tableau and open the dashboard with the extension you want to debug.
+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)
- This will bring up the page selector UI.
-3. Pick the extension you want to debug from this page, and debug just like you would any other web application.
+ This will bring up the page selector UI. The port (for example, `8696`) must match the port address you specified as the remote debugging port when you started Tableau.
+3. Pick the extension you want to debug from this page, and debug just like you would any other web application (set breakpoints, step through the code, and examine variables).
+Note that the name of the extension is based on the title of the web page that was loaded for the extension. If the extension hasn't loaded yet the name might be blank. See [Debugging loading and initialization issues](#debugging-loading-and-initialization-issues).
-
+
-### Debugging Loading / Initialization Issues
-It can be difficult to hit breakpoints which occur during the loading of your page due to the remote debugging process. To help with this, we've included a menu option which causes your extension to wait to load until you trigger it to.
+ 
-1. In the **Debug Options** dropdown menu, select **Pause Before Loading**.
-2. Reload your extension (**Debug Options** > **Reload**)
-3. In Chromium, go to the debugging homepage ([http://localhost:8696](http://localhost:8696)).
-4. To attach to the browser instance, click the first item listed (it will be completely blank, but it is really there. The cursor changes so you can select it).
-4. Click the **Sources** tab in Chromium, under **Event Listener Breakpoints**, click **Script** and enable the **Script First Statement** breakpoint.
-5. Back in Tableau, click the extension zone to load your page.
-6. The debugger will pause each time the first statement of a script runs, allowing you to debug the startup process. To get to your JavaScript code, click **Continue** several times. Once your JavaScript is loaded, you can set a breakpoint in your startup code.
+Note that you can only debug one extension, or instance of an extension, at a time. However, you can open a new Chromium tab or window to debug additional extensions.
+
+---
+
+## Debugging loading and initialization issues
-
+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.
+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.
+3. In Chromium, go to the debugging homepage ([http://localhost:8696](http://localhost:8696)).
+4. Click the *second item* listed to attach to the browser instance of your extension.
+**Note:** When you click the list item, it will be completely blank, but it is really there. The cursor changes so you can select it.
+5. Click the **Sources** tab in Chromium, under **Event Listener Breakpoints**, click **Script** and enable the **Script First Statement** breakpoint. You just have to do this one time.
+6. In Tableau Desktop, click the extension zone to load your page.
+The debugger will pause each time the first statement of a script runs, allowing you to debug the startup process.
+7. To get to your JavaScript code, click **Continue** several times. After your JavaScript is loaded, you can set a breakpoint in your startup code.
+
+
+
---
-## Known issues with debugging extensions
+## Known issues with debugging extensions in Tableau Desktop
---
-#### Enabling debugging from the Debug Options menu
-Due to changes in the start-up sequence, you can no longer enable remote debugging by selecting **Debugging Enabled** from the **Debug Options** menu in the dashboard. To enable debugging, you must add the `--remote-debugging-port=8696` option to the command used to start Tableau. You can still select the **Pause before Loading** option and set breakpoints to debug initialization and loading issues.
+#### Reload closes debugging connection
+
+While you are debugging your extension, there are times you might want to reload or refresh your web page to execute and debug different parts of your code. However, when you click **Reload** from the shortcut menu to reload your extension, the remote debugger loses the connection with the extension. The reason for this is that **Reload** option tears down and re-creates the browser control, which means you'll need to establish a new debugging session.
+
+Note that you do not need to close and reopen the Chromium browser every time you click **Reload**. You can start another debugging session by entering the URL (`http://localhost:8696`) in the Chromium address bar and selecting the extension from the page selector.
-#### Refreshed Page Fails
-Unfortunately, due to a bug with our embedded browser, refreshing a loaded page doesn't properly setup the communication between Tableau and the extension. This means that triggering a page reload will cause your extension to stop working. It's important to note that the **Reload** menu option actually tears down and re-creates the browser control, which means you'll need to establish a new debugging sessions whenever you click **Reload**. For more information, see [What Happens When You Reload an Extension]({{site.baseurl}}/docs/trex_reload.html).
+For more information, see [What Happens When You Reload an Extension]({{site.baseurl}}/docs/trex_reload.html).
diff --git a/docs/trex_error_handling.md b/docs/trex_error_handling.md
index ab9a0564..b32d6701 100644
--- a/docs/trex_error_handling.md
+++ b/docs/trex_error_handling.md
@@ -3,13 +3,25 @@ title: Error Codes for Extensions
layout: docs
---
+Errors that are returned from the Extensions API are custom Tableau error objects that extends the standard JavaScript error object.
-Errors that are returned from the Extensions API are custom Tableau Error objects that extends the standard JavaScript error object.
+---
+**In this section**
+
+* TOC
+{:toc}
+
+## 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).
+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.
-The Extensions API wraps the standard error object with an `errorCode` property. Any time you encounter an error when you are developing your extension, you can look at this `errorCode` to determine the cause. See [Error Codes]({{site.baseurl}}/docs/enums/errorcodes.html).
-For an example of how to handle error conditions, see the [UINamepace](https://github.com/tableau/extensions-api/tree/master/Samples/UINamepace?=target="_blank") sample. The sample shows how you could handle the error condition that occurs if a user dismisses a modal dialog box (`DialogClosedByUser`). The following snippet illustrates this pattern:
+
+## Handle extensions.ui dialog box errors
+
+For an example of how to handle an extension dialog box error, see the [UINamepace](https://github.com/tableau/extensions-api/tree/master/Samples/UINamepace?=target="_blank") sample. The sample shows how you could handle the error condition that occurs if a user dismisses a modal dialog box (`DialogClosedByUser`). In this extension, the user is expected to click the **Start Auto Refresh** button, which saves the configuration settings and closes the dialog box, by calling the `tableau.extensions.ui.closeDialog()` method with the return payload. If a user clicks the dialog box control (the **X** in the upper-right corner) instead, the error occurs. The following snippet illustrates how you could handle this error:
```javascript
@@ -30,4 +42,5 @@ tableau.extensions.ui.displayDialogAsync(args... ).then((args... ) => {
}
});
-```
\ No newline at end of file
+```
+
diff --git a/docs/trex_examples.md b/docs/trex_examples.md
index 923902d0..e1499d15 100644
--- a/docs/trex_examples.md
+++ b/docs/trex_examples.md
@@ -3,7 +3,7 @@ title: Dashboard Extension Samples
layout: docs
---
-The best way to learn how to build your own extensions is to look at the sample code. To examine the sample source files to see how Tableau dashboard extensions work, you can clone or download the [Extensions API](https://github.com/tableau/extensions-api) SDK on GitHub and run the samples.
+The best way to learn how to build your own extensions is to look at the sample code. To examine the sample source files to see how Tableau dashboard extensions work, you can clone or download the [Extensions API](https://github.com/tableau/extensions-api) SDK on GitHub and run the samples or the tutorial.
- To download the Extensions API SDK, if you have not already done so, see [Get Started]({{ site.baseurl }}/doc/trex_getstarted.html).
- You can browse the sample code for the dashboard extensions in the [Samples](https://github.com/tableau/extensions-api/tree/master/Samples?=target="_blank") and the [Tutorial](https://github.com/tableau/extensions-api/tree/master/Tutorial?=target="_blank") folders on GitHub.
@@ -28,7 +28,7 @@ The following instructions assume that you have already downloaded and extracted
### About the dashboard extension samples
-The dashboard extension samples are in the `Samples` folder. There is also a step-by-step tutorial you can follow in the `Tutorial` folder.
+The dashboard extension samples are in the `Samples` folder. There is also a step-by-step tutorial you can follow in the `Tutorial` folder.
@@ -52,14 +52,19 @@ The dashboard extension samples are in the `Samples` folder. There is also a ste
- **[UINamespaces](https://github.com/tableau/extensions-api/tree/master/Samples/UINamespace?=target="_blank")**
Demonstrates how you can use the `UI` namespace to create a modal dialog box (or popup) that runs another extension, which allows users to interact and change the settings for the parent extension. This sample controls the background auto-refresh interval for data sources in a dashboard.
+
+
+- **[Tutorial](https://github.com/tableau/extensions-api/tree/master/Tutorial?=target="_blank")**
+ Walks you through the step-by-step process of creating and refining an extension that displays a summarized table of the currently selected marks.
+
---
### Start a web server to host the sample dashboard extensions
-To use the dashboard extension samples, you need to start up a web server on your computer to host the HTML pages. If you downloaded or cloned the Extensions API repository, you can start the web service in the root directory of the repository on your computer.
+To use the dashboard extension samples, you need to start up a web server on your computer to host the HTML pages. If you downloaded or cloned the Extensions API repository, you can start the web service in the root directory of the repository on your computer. These commands start the Node.js basic service `http-server`.
1. Go to the `extensions-api` folder.
2. To install the web server components, run the following command:
@@ -73,17 +78,22 @@ To use the dashboard extension samples, you need to start up a web server on you
-
### Instructions for starting a web server on a different port
-The samples are set up so that the web server is using port `8765`. If you need to specify a different port instead of `8765`, you can change ports using Python, if you have Python installed, or you can run another Node.js command.
+The samples are set up so that the web server is using port `8765`. If you need to specify a different port instead of `8765`, you can change ports using another Node.js or `http-server` command.
-From the `extensions-api` folder, start an HTTP server using one of the following commands. Replace `PORT` with the port you are using (for example, `8000`):
+From the `extensions-api` folder, you can start the `http-server` using one of the following commands. Replace `PORT` with the port you are using (for example, `8000`).
-* Python 2.x : `python -m SimpleHTTPServer PORT`
-* Python 3.x : `python -m http.server PORT`
-* Node.js : `npm install http-server -g && http-server -p PORT`
+To install the `http-server`on your computer globally and to also start the server:
+```
+npm install http-server -g && http-server -p PORT
+```
+If you have already installed `http-server`, you can start the server directly:
+
+```
+http-server -p PORT
+```
The port you use for the web server also has to match the port specified in the manifest file (`.trex`) for the server.
```
@@ -100,8 +110,9 @@ After you start the web server to host the sample extensions, you can try the ex
1. Start Tableau and open a workbook that has a dashboard, or open a workbook and create a new dashboard.
2. In the dashboard, under **Objects**, select **Extension** and drag it on to the dashboard.
-3. In the **Select an Extension** dialog box, click **Choose an Extension**.
- Every Tableau extension has a manifest file (`.trex`) that describes the extension and identifies the location of the web application.
+3. In the **Choose an Extension** dialog box, click **My Extensions**.
4. Browse to the directory where the samples are located. For example, if you downloaded or cloned the GitHub repository, go to `\extensions-api\Samples`.
-5. Select one of the folders for the samples and open the `.trex` file (for example, `DataSources.trex`).
+5. Select one of the folders for the samples and open the `.trex` file (for example, `DataSources.trex`).
+Every Tableau extension has a manifest file (`.trex`) that describes the extension and identifies the location of the web application.
+
The extension should appear in the dashboard. Play around with the extension. Examine the HTML and JavaScript source files to see how things work.
diff --git a/docs/trex_getdata.md b/docs/trex_getdata.md
index 9a5da07b..d49f410a 100644
--- a/docs/trex_getdata.md
+++ b/docs/trex_getdata.md
@@ -171,3 +171,4 @@ Worksheet.getUnderlyingDataAsync().then(function(success) {
An error is also printed to the console. If you use the `getUnderlyingData()` method, be sure to add error handling for the promise in case of failure.
+
diff --git a/docs/trex_getstarted.md b/docs/trex_getstarted.md
index dec46252..0a48722e 100644
--- a/docs/trex_getstarted.md
+++ b/docs/trex_getstarted.md
@@ -1,12 +1,13 @@
---
-title: Get Started
+title: Get Started with Dashboard Extensions
layout: docs
---
-The Tableau Extensions API allows developers to create extensions for Tableau. Tableau extensions are web applications that can interact and communicate with Tableau.
+The Tableau Extensions API allows developers to create extensions for Tableau. Tableau extensions are web applications that can interact and communicate with Tableau. A dashboard extension can be placed in the dashboard like any other dashboard object.
-This section will take you through the process of setting up Tableau to use one of the sample dashboard extensions. A dashboard extension is a web application that can be placed in the dashboard like any other dashboard object.
+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"}.
@@ -18,7 +19,7 @@ This section will take you through the process of setting up Tableau to use one
----
*What's in a Tableau extension?
-A Tableau extension consists of a manifest file (`.trex`), a web page that uses a Tableau-provided JavaScript library, and the JavaScript file (or files) that contain your extension logic. The Tableau extensions are supported on Tableau Desktop and Tableau Server.*
+A Tableau extension consists of a manifest file (`.trex`), a web page that uses a Tableau-provided JavaScript library, and the JavaScript file (or files) that contain your extension logic. The Tableau extensions are supported on Tableau Desktop, Tableau Server, and Tableau Online.*
---
@@ -32,9 +33,16 @@ If you want to create an extension or work with the sample code, make sure you h
* [Git](https://git-scm.com/downloads)
* [Node.js and npm](https://nodejs.org/en/download/)
-You need Node.js and nmp to run the dashboard extension demos. Node.js is a JavaScript runtime. npm is a package manager for Node.js and is installed when you install Node.js.
+You need Node.js and npm to run the dashboard extension demos. Node.js is a JavaScript runtime. npm is a package manager for Node.js and is installed when you install Node.js.
+Requirements for using dashboard extensions in Tableau:
+* Tableau Desktop 2018.2 and later
+* Tableau Server 2018.2 and later
+* Tableau Online
+
+To run extensions on Tableau Server or Tableau Online, support for extensions must be enabled, and depending upon the extension and the data access it requires, the extension might need to be added to the safe list for the site. 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.
----
@@ -51,15 +59,6 @@ You can get the Tableau Extensions API SDK in two ways. Clone the repository if
-
----
-### Download and install Tableau
-
-Dashboard extensions are supported in Tableau 2018.2 and later.
-* Download [Tableau Desktop 2018.2](https://www.tableau.com/support/releases){:target="_blank"} or [Tableau Server 2018.2](https://www.tableau.com/support/releases/server){:target="_blank"}
-
-
-
---
### Start a web server to host the sample dashboard extensions
@@ -67,21 +66,19 @@ To use the dashboard extension samples, you need to start up a web server on you
1. Navigate to the `extensions-api` directory.
2. To install the web server components, run the following npm command to install the package:
- ```
- npm install
- ```
+ **npm install**
+
+
3. To start the web server, run the following npm command:
- ```
- npm start
- ```
- The start command runs a script to start the web server over port `8765`. You only need to install the web server components the first time. Subsequently, you can just start the web server.
-
+
+ **npm start**
+ The start command runs a script to start the web server over port `8765`. You only need to install the web server components the first time. Subsequently, you can just start the web server, using **npm start**.
+ The start commands uses the npm [http-server](https://www.npmjs.com/package/http-server){:target="_blank"} package, a simple HTTP server that uses Node.js for serving static files to the browser.
- **Note** The web server just serves the extension samples, which have URLs similar to the following: `http://localhost:8765/Samples/DataSources/datasources.html`
- This local web server is not intended to serve the Help pages.
- View the Help on GitHub at [https://tableau.github.io/extensions-api](https://tableau.github.io/extensions-api).
+
+ | **Note:** The web server just serves the extension samples, which have URLs similar to the following: `http://localhost:8765/Samples/DataSources/datasources.html` This local web server is not intended to serve the Extensions API Help pages. View the Help on GitHub at [https://tableau.github.io/extensions-api](https://tableau.github.io/extensions-api).
@@ -94,30 +91,82 @@ To use the dashboard extension samples, you need to start up a web server on you
3. In the **Choose an Extension** dialog box, click **My Extensions**.
Every Tableau extension has a manifest file (`.trex`) that describes the extension and identifies the location of the web application.
-4. Browse to the directory where the samples are located. For example, if you downloaded or cloned the GitHub repository, go to `\extensions-api\Samples`.
+4. Browse to the directory where the samples are located. For example, if you downloaded or cloned the GitHub repository, go to `\extensions-api\Samples\DataSources`.
5. Open the `DataSources.trex` file.
- The sample extension (web application) appears in the dashboard frame. The DataSources sample finds and displays the data source for each worksheet in the dashboard.
+ The sample extension (web application) appears in the dashboard frame. The DataSources sample finds and displays the data source for each worksheet in the dashboard.
6. In the DataSources extension, click the **Info** (**i**) button. This action opens a dialog box that displays more details about the selected data source.

-
---
-### Using dashboard extensions in a workbook
+### Examine the source code for the extension
+
+Looking at the files that make up an extension will give you an idea of how an extension is constructed.
+
+1. Browse to the directory where the DataSources sample is located. For example, if you downloaded or cloned the GitHub repository, go to `\extensions-api\Samples\DataSources`.
+
+2. Open the `datasources.html` file in your favorite Text or Code editor. This HTML page provides the interface that users see when they load the extension. This file includes links to the Extensions API library file and to the file that contains all the JavaScript code for the extension.
+
+ ```html
+
+
+
+
+
+ ```
+3. Open the `datasources.js` file. This file contains code to initialize the Extensions API, and contains functions to gather all the data sources used by the workbooks in the dashboard. Read through the code and the code comments to get an understanding about how this extension works. The Extensions API makes use of JavaScript Promises to collect the data returned from the asynchronous function calls. Look for the code that initializes the extension. An extension will often place the initialization code in the JQuery `$(document).ready()` function so that it will run when the page is loaded.
+
+ ```javascript
+ (function () {
+ $(document).ready(function () {
+ tableau.extensions.initializeAsync().then(function () {
+ /* body of function */
+ /* controls what the extension does */
+ /* extension calls other functions here */
+ } function (err) {
+ // Something went wrong in initialization.
+ console.log('Error while Initializing: ' + err.toString());
+ });
+ });
+ /* extension can define other functions here as needed */
+ })();
+
+ ```
+
+4. Open the `DataSources.trex` file. This is the manifest file for the extension. This is the file that you selected to add the extension to the dashboard. This file defines certain properties for the extension, such as the name, and author, and the location (URL) of the extension.
+
+ ```xml
+
+ http://localhost:8765/Samples/DataSources/datasources.html
+
+ ```
+ If you make a copy of the sample directory so that you can start to modify the code and experiment with the Extensions API, you just need to modify this path so that the URL reflects the new location.
+
+ ```xml
+
+ http://localhost:8765/_your-new-folder-here_/DataSources/datasources.html
+
+ ```
+
+
+
------------------------------------------------------------------------
## What's next?
-- For more information about how you can use Extensions API, go look at the [Samples (GitHub)](https://github.com/tableau/extensions-api/tree/master/Samples/), or follow the [Tutorial (GitHub)](https://github.com/tableau/extensions-api/tree/master/Tutorial) and learn how to build a dashboard extension, step by step. If you downloaded or cloned the repository, look in the `Samples` and `Tutorial` folder on your computer.
+* Start developing your extension by modifying an existing sample. See [samples (GitHub)](https://github.com/tableau/extensions-api/tree/master/Samples/). If you cloned or downloaded the repository, create a copy of the Samples directory. For example, if you make the copy in `\extensions-api\` directory, and call it `MySamples`, you just need to modify the URL in the `.trex` files so that you host the extensions using the same web server you created with `npm start` command.
+
+* Follow the [Tutorial (GitHub)](https://github.com/tableau/extensions-api/tree/master/Tutorial) and learn how to build a dashboard extension, step by step. If you downloaded or cloned the repository, look in the `Tutorial` folder on your computer.
-- For general information about creating Tableau extensions, see [Creating a Tableau Extension]({{site.baseurl}}/docs/trex_create.html).
-- To get familiar with the programming interface for the Extensions API, see the API Reference.
+* For information about creating a simple "Hello World" Tableau extension, see [Create a "Hello World" Dashboard Extension]({{site.baseurl}}/docs/trex_create.html).
+* To get familiar with the programming interface for the Extensions API, see the API Reference.
-For information about debugging your extension, see [Remote Debugging of JavaScript and HTML]({{site.baseurl}}/docs/trex_debugging.html).
+* For information about debugging your extension, see [Debug Extensions in Tableau Desktop]({{site.baseurl}}/docs/trex_debugging.html) and [Debug Extensions in Tableau Server and Tableau Online]({{site.baseurl}}/docs/trex_debug_server.html).
diff --git a/docs/trex_manifest.md b/docs/trex_manifest.md
index e36201e0..ec112bb8 100644
--- a/docs/trex_manifest.md
+++ b/docs/trex_manifest.md
@@ -16,7 +16,7 @@ For details about a manifest or its fields, see the [Sample Manifest File](#samp
## 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}) site. You are strongly encouraged to validate your extensions manifest file before using it for the first time.
+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.
## 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.
diff --git a/docs/trex_publish.md b/docs/trex_publish.md
index 2277c650..19d52ea9 100644
--- a/docs/trex_publish.md
+++ b/docs/trex_publish.md
@@ -1,5 +1,5 @@
---
-title: Publishing a Dashboard Extension
+title: Publish a Dashboard Extension
layout: docs
---
@@ -34,12 +34,16 @@ However, to run on Tableau Server or Tableau Online, your extension must:
Tableau Server and Tableau Online have settings that control whether dashboard extensions are allowed to run and whether specific extensions can access the the underlying data in a dashboard.
- To enable a dashboard extension on Tableau Server or Tableau Online, the server administrator or the site administrator (Tableau Online) must allow extensions for the site. The administrators can then choose to enable the default policy that allows extensions that only request summary data to run, provided users grant the extension permission.
+ To enable a dashboard extension on Tableau Server or Tableau Online, the server administrator or the site administrator (Tableau Online) must allow extensions for the site. The administrators can then choose to enable the default policy that allows *unknown* extensions that only request summary data to run, provided users grant the extension permission. These extensions are unknown in the sense that they have not been explicitly added to the safe list or to the blocked list on Tableau Server or Tableau Online.
If your extension requires access to full data (underlying data) the server or site administrator must add the URL of your extension to a safe list and must explicitly grant the extension access to full data. The server or site administrator can also configure whether users of your extension will see prompts requesting permission to run.
+
+The following flowchart shows how the settings on Tableau Server or Tableau Online determine whether an extension is allowed or denied permission to run.
+
+ 
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.
+ [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_release-notes.md b/docs/trex_release-notes.md
index ef559960..31e39b98 100644
--- a/docs/trex_release-notes.md
+++ b/docs/trex_release-notes.md
@@ -13,6 +13,23 @@ See also: [Known Issues]({{site.baseurl}}/docs/trex_known_issues.html)
----
+
+### Tableau 2018.3
+*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"})
+
+- Download [Tableau Desktop 2018.3](https://www.tableau.com/support/releases){:target="_blank"} or [Tableau Server 2018.3](https://www.tableau.com/support/releases/server){:target="_blank"}
+
+
+
+
+New in this release:
+
+- Updated documentation. [Getting Started]({{site.baseurl}}/docs/trex_getstarted.html), [Create a "Hello World" Dashboard Extension]({{site.baseurl}}/docs/trex_create.html), [Debugging Extensions on Tableau Desktop]({{site.baseurl}}/docs/trex_debugging.html), [Debugging Extensions on Tableau Server and Tableau Online]({{site.baseurl}}/docs/trex_debug_server.html), [Error Codes and Error Handling for Extensions]({{site.baseurl}}/docs/trex_error_handling.html).
+
+---
+
### TC18
*October, 2018*
@@ -20,7 +37,7 @@ See also: [Known Issues]({{site.baseurl}}/docs/trex_known_issues.html)
New in this release:
-- Use the [Design Guidelines for Dashboard Extensions]({{site.baseurl}}/docs/ux_design.html){:target="_blank"} as roadmap for designing great dashboard extensions.
+- Use the [Design Guidelines for Dashboard Extensions]({{site.baseurl}}/docs/ux_design.html){:target="_blank"} as a roadmap for designing great dashboard extensions.
- Create extensions with the look-and-feel of Tableau, using the [Tableau UI](https://tableau.github.io/tableau-ui/){:target="_blank"}, a React component library.
diff --git a/docs/trex_security.md b/docs/trex_security.md
index 91e2c7b0..3745d32d 100644
--- a/docs/trex_security.md
+++ b/docs/trex_security.md
@@ -12,7 +12,8 @@ A Tableau extension is essentially a web application that runs inside a Tableau
- 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 how to configure the prompts to allow or deny access, see the Tableau Server documentation (*work in progress*).
+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.
+
**In this section**
@@ -142,24 +143,13 @@ For example, you can author a workbook in Tableau Desktop that uses an extension
Note the following considerations:
-- If Tableau Server is using HTTPS, your extension might not load if it is using `http://localhost`. The same situation occurs with Tableau Online. This is because it is generally not a good practice to embed an HTTP `