This is the entry point for an Extension. This function must first be called
+ in order to interact with any of the other Extension APIs.
+
+
+
Returns Promise<void>
+
A promise that when resolved, the other Extension APIs will be available to use.
+
+
+
+
+
+
initializeDialogAsync
+
+
initializeDialogAsync(): Promise<void>
+
+
+
+
-
This is the entry point for an Extensions. This function must first be called
- in order to interact with any of the other Extensions APIs.
+
This is the entry point for an extension that runs inside a dialog created by the
+ UI namespace. This function must be called first in order to use the rest of the Extension
+ API, and should not be called by extensions that are not displayed in a dialog.
Returns Promise<void>
-
A promise that the developer must run to initiailze their extension.
- When resolved, the other Extensions APIs will be available to use.
+
A promise that when resolved, the other Extension APIs will be available to use.
This namesapce contains functionality that allows an Extensions to display a popup
- dialog window, and communicate between that window and the parent Extensions. This can
- be useful in auth scenarios and when extra situational UI space is needed.
- Only one dialog can be displayed at a time.
-
-
+
+
This namespace contains functionality that allows an Extension to display a popup
+ dialog window. This can be useful in auth scenarios and when extra situational UI space is needed.
+ Only one dialog can be displayed at a time per extension. Inside the popup dialog window,
+ another extension can be loaded and run. This 'dialog extension' will have full access
+ to the functions provided by the Extensions API.
The url of the 'dialog extension' to navigate to in the dialog. The url must
+ belong to the same domain as the parent extension.
+
+
+
+
Optional payload: string
-
The message to send from an Extensions's dialog to its parent frame.
+
optional data to make available to dialog on startup. This will be returned
+ to the dialog extension as the return value of tableau.extensions.ui.initializeDialogAsync
A promise that resolves when the dialog has been closed. It will contain a
+ payload as a string provided by the dialog extension. The promise is rejected if
+ the user manually closes the dialog (for example, by clicking the 'x').
diff --git a/docs/trex_create.md b/docs/trex_create.md
index bacf04c1..ac527a21 100644
--- a/docs/trex_create.md
+++ b/docs/trex_create.md
@@ -80,10 +80,10 @@ The web app you create controls and interacts with the Tableau dashboard objects
Your web application must include an HTML page. This page should link to the Extensions API JavaScript library and to any other JavaScript, CSS, or HTML resources your web app requires.
-1. In the HTML page, add a link to the JavaScript library (for example, `tableau-extensions-0.7.0.js`).
+1. In the HTML page, add a link to the JavaScript library (for example, `tableau-extensions-0.8.0.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
@@ -103,7 +103,7 @@ Your web application must include an HTML page. This page should link to the Ext
-
+
diff --git a/docs/trex_getstarted.md b/docs/trex_getstarted.md
index 502ca263..0dd1a863 100644
--- a/docs/trex_getstarted.md
+++ b/docs/trex_getstarted.md
@@ -78,27 +78,19 @@ To use the dashboard extension samples, you need to start up a web server on you
----
-### Install the dashboard extension manifest file (`.trex`)
-
-
-Every Tableau extension has a manifest file (`.trex`) that describes the extension and identifies the location of the web application.
-
-1. Close Tableau, if you have it opened.
-2. Copy the `.trex` files of the samples you wish to run to `~\Documents\My Tableau Repository (Beta)\Extensions` so they are available to Tableau.
- The `.trex` files for the samples can be found in the folder with the samples. For example, `\extensions-api\Samples\DataSources\DataSources.trex`.
-
-
-
---
### Start Tableau and add an extension to the dashboard
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 **Extensions**, select one of the sample extensions and drag it on to the dashboard. For example, drag **DataSources Sample** to the 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.
+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. 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.
-3. In the DataSources extension, click the **Info** (**i**) button. This action opens a dialog box that displays more details about the selected data source.
+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.
diff --git a/docs/trex_manifest.md b/docs/trex_manifest.md
index f0cb99f0..23aa1231 100644
--- a/docs/trex_manifest.md
+++ b/docs/trex_manifest.md
@@ -39,7 +39,7 @@ If a workbook is saved with an extension and then later opened on another comput
1.1
- SERVER:PORT/PATH
+ SCHEME://SERVER[:PORT][/PATH]Base64-Encoded ICON
@@ -106,7 +106,7 @@ If a workbook is saved with an extension and then later opened on another comput
url
-
Specifies the name and port (optional) of the server. The url must use HTTPS. For example: https://example.com/extension.
+
Specifies the scheme (HTTPS, HTTTP), the name of the server, the port (optional) and the path to extension (optional). The url must use HTTPS. For example: https://example.com/extension.
The exception is for localhost. In this case, HTTP is allowed. For example: http://localhost:8080.
diff --git a/docs/trex_release-notes.md b/docs/trex_release-notes.md
index eb89e0cd..87982f4e 100644
--- a/docs/trex_release-notes.md
+++ b/docs/trex_release-notes.md
@@ -8,6 +8,45 @@ layout: docs
* TOC
{:toc}
+---
+
+### Developer Preview (0.8.0)
+*December 21, 2017*
+
+- Update of the Tableau Extensions API.
+- Tableau Extensions API library: `tableau-extensions-0.8.0.js`
+- Tableau Desktop 10.5 RC, Tableau Server 10.5 (from [Extensions API Developer Preview](https://prerelease.tableau.com){:target="_blank"})
+
+
+**New desktop authoring experience**
+
+You no longer need to place the `.trex` file for the extension in a predetermined folder, you now do the following:
+
+ 1. In the dashboard, under **Objects** on the left, select **Extension** and drag it to the dashboard sheet on the right.
+ The **Select an Extension** dialog box appears.
+ 2. The first time you open the dialog box to add an extension, you will see a link to **Choose an Extension**. Click the link and browse to the directory where you have the `.trex` file.
+Subsequently, when you drag the **Extension** on the dashboard, the dialog box shows you the most recently used list, choose from the list, or click **Browse** to select another extension.
+
+**New UI namespace**
+
+- You can now launch a new modal dialog using the function: `tableau.extensions.ui.displayDialogAsync(dialonExtensionURL)`.
+- The URL you want to load (`dialonExtensionURL`) will be an extension itself.
+- The extension in the dialog will have full access to the extensions API. When ready to close to the dialog, from the dialog extension you can call `tableau.extensions.ui.closeDialog(string)`. See the documentation for details.
+- Note that the UI namespace is work is still in progress and has some upcoming additions. *Stay tuned for more.*
+
+**HTTPS and security**
+
+For information about the HTTPS requirements for extensions, see [Security and Tableau Extensions]({{site.baseurl}}/docs/trex_security.html)
+
+**Remote Debugging**
+
+Due to changes in this release, remote debugging does not work as expected in Tableau Desktop. To enable debugging, you must add the `--remote-debugging-port=8696` option to the command used to start Tableau. The easiest way to do this is to open the Tableau shortcut on the **Start** menu. Open the file location of the Tableau shortcut. Right-click the Tableau shortcut and click **Properties**. In the Target text box, append the remote debugging option to the command. Do not enclose the option in quotation marks.
+```
+ "C:\Program Files\Tableau\Tableau main\bin\tableau.exe" --remote-debugging-port=8696
+```
+For information about debugging extensions, see [Remote Debugging of JavaScript and HTML]({{site.baseurl}}/docs/trex_debugging.html).
+
+
---
### Developer Preview (0.7.0)
diff --git a/docs/trex_security.md b/docs/trex_security.md
new file mode 100644
index 00000000..f5a377f6
--- /dev/null
+++ b/docs/trex_security.md
@@ -0,0 +1,207 @@
+---
+title: Security 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.
+
+- 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.
+
+
+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*).
+
+
+**In this section**
+
+* TOC
+{:toc}
+
+
+---
+## Why HTTPS?
+
+When you use HTTPS, all HTTP data is encrypted prior to transmission by the Transport Layer Security (TLS) and decrypted when it is received. HTTPS ensures a secure channel between the extension (client), running in the Tableau dashboard, and the web server that hosts the extension. The use of HTTPS provides a level of privacy, authentication, and integrity.
+
+If you plan to make your extension available to others, using HTTPS
+ assures your customers that their data is safe and that they are connecting to trusted extension. Because the extension is using HTTPS, Tableau is also able to verify the identity of the server that hosts the extension, which prevents various malicious man-in-the-middle attacks that could occur if the extension were to use HTTP alone.
+
+> Note: For development or internal use, you can run your extension on your local computer as `localhost` and you can use the HTTP protocol.
+
+
+
+---
+## HTTPS and security requirements
+The requirements are pretty straight-forward. If you are distributing your extension so that others can use it, the extension must be hosted on a web server that is configured to support the HTTPS protocol.
+
+- The server that hosts your extension must have a certificate from a Certificate Authority (CA). There are many free and low cost options. Note that self-signed or test-signed certificates are not sufficient. The certificate is sometimes called an SSL certificate, as HTTPS was formerly implemented by the Secure Sockets Layer (SSL).
+- In the `.trex` file for your extension, the `url` you use for the source location must start with `https://`. If the HTTPS protocol is not specified, the extension fails registration and does not appear in list of available extensions in Tableau.
+The exception to this requirement is for `localhost`. If you are developing your extension, you can host it on your computer using HTTP (for example, `http://localhost`). You can also use `http://localhost` if you publish the workbook to Tableau Server. In this case, the extension must be running on the same computer as the browser you are using to access the server.
+- Mixed content is not allowed. If your web application uses other libraries or resources, those assets should also use `https`, or use site-relative links.
+- Redirects are permitted, but if they redirect to any other origin, other than the URL of the extension, those pages cannot interact with the Extensions API. For example, if the URL of your extension is `https://example.com` and you redirect to `https://myexample.com`, the page you were redirecting to (`https://myexample.com`) cannot interact with the Extensions API.
+- To run on Tableau Server, your extension must be added to the safe list for the site. Site administrators can add or remove extensions, and can configure how an extension requests permissions for access to data.
+
+----
+
+## Setting the source location in the .trex file
+
+The source location of the extension is its URL. You specify the URL in the extension manifest (`.trex`) file. The syntax includes the name of the server, which includes the protocol (HTTPS, HTTP), the port used, if any, and the path to the extension web page (optional).
+
+The `` element in the `.trex` file, looks like the following:
+
+```xml
+
+ SCHEME://SERVER[:PORT][/PATH]
+
+
+```
+
+For example, if the extension is hosted on example.com, the entry might look like the following:
+
+```xml
+
+ https://example.com:4043/extension
+
+
+
+```
+
+Or during development, when you can use `localhost`, the entry might look like the following:
+
+```xml
+
+
+ http://localhost:8080/extension
+
+
+
+```
+At startup, Tableau looks for and validates the extension `.trex` files. If the extension source location does not specify HTTPS or localhost, validation fails and the extension is not registered. These errors are written to the log file. The extension will not appear in the list of available extensions. If you examine the log files (for example, with Tableau Log Viewer), you will find something similar to the following:
+
+```
+Error: Registration Failed: XSD Validation Failed
+file: Example.trex
+
+
+Error: Error(11,67): value 'http://example.com/example.html' does not match regular expression facet '[Hh][Tt][Tt][Pp][Ss]://.+|[Hh][Tt][Tt][Pp]://[Ll][Oo][Cc][Aa][Ll][Hh][Oo][Ss][Tt]|[Hh][Tt][Tt][Pp]://[Ll][Oo][Cc][Aa][Ll][Hh][Oo][Ss][Tt][:/].*' (id: C:\Users\\Documents\My Tableau Repository (Beta)\Extensions\example.trex)
+file: Example.trex
+
+
+```
+
+
+## Avoid mixed content - use HTTPS or site-relative paths for resources
+
+The extension should not call any pages over HTTP. If you reference libraries or resources, specify `https` for the files you include.
+
+For example:
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+
+Or use site-relative or protocol-agnostic links (that is, where the protocol is not specified).
+
+```html
+
+
+
+
+
+
+
+```
+
+
+## Use HTTP and localhost for development or internal use
+
+While HTTPS is required, during development, you can run a web server on your local computer (`localhost`) to host the extension over HTTP. This exception also applies to Tableau Server.
+
+For example, you can author a workbook in Tableau Desktop that uses an extension (running as `localhost` on same computer as Tableau Desktop). You can then publish that workbook to Tableau Server. The extension must be running on the same computer as the browser that you are using to connect to Tableau Server. The `localhost` is local to the browser. For example, the source location of an extension might be `http://localhost:8080/extension`. If you publish that extension to Tableau Server, other users can view the dashboard and extension, provided that they also have a local copy of the extension hosted on their computers and the extension is using the same URL.
+
+Note the following considerations:
+
+- If Tableau Server is using HTTPS, your extension won't work with `http://localhost`. This is because you can't embed an HTTP `
DialogClosedByUser
FilterCannotBePerformed
InternalError
InvalidAggregationFieldName
InvalidDateParameter
InvalidDomainDialog
InvalidFilterFieldName
InvalidFilterFieldValue
InvalidParameter
InvalidSelectionDate
InvalidSelectionFieldName
InvalidSelectionValue
NullOrEmptyParameter
UnsupportedEventName
Attr
Avg
Count
Countd
Day
End
Hour
InOut
Kurtosis
Max
Mdy
Median
Min
Minute
Month
MonthYear
None
Qtr
Quart1
Quart3
Second
Skewness
Stdev
Stdevp
Sum
TruncDay
TruncHour
TruncMinute
TruncMonth
TruncQtr
TruncSecond
TruncWeek
TruncYear
User
Var
Varp
Week
Weekday
Year
Dimension
Measure
Unknown
Database
Relevant
AllValues
NonNullValues
NullValues
Categorical
Hierarchical
Range
RelativeDate
Add
All
Remove
Replace
Area
Bar
Circle
GanttBar
Line
Map
Pie
Polygon
Shape
Square
Text
All
List
Range
Days
Hours
Minutes
Months
Quarters
Seconds
Weeks
Years
CompoundGrowthRate
Difference
MovingAverage
PercentDifference
PercentOfTotal
Percentile
Rank
RunningTotal
Undefined
YTDGrowth
YTDTotal
YearOverYearGrowth
Add
Remove
Replace
Dashboard
Story
Worksheet
Decreasing
Increasing
FilterChanged
MarkSelectionChanged
ParameterChanged
Exponential
Linear
Logarithmic
Polynomial
Enumerations
Interfaces
Enumerations
Interfaces
Properties
Methods
Optional dashboardContent
dashboardContent: DashboardContent
@@ -992,7 +996,7 @@ environment: Environment
@@ -1007,7 +1011,7 @@ settings: Settings
@@ -1022,7 +1026,7 @@ ui: UI
@@ -1044,18 +1048,42 @@
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/interfaces/ui.html b/docs/interfaces/ui.html
index d04bab93..991a074c 100644
--- a/docs/interfaces/ui.html
+++ b/docs/interfaces/ui.html
@@ -911,10 +911,10 @@
UI
-
+
@@ -949,8 +948,8 @@
@@ -959,80 +958,78 @@
-
- -
-
+
-
- -
-
diff --git a/docs/trex_create.md b/docs/trex_create.md
index bacf04c1..ac527a21 100644
--- a/docs/trex_create.md
+++ b/docs/trex_create.md
@@ -80,10 +80,10 @@ The web app you create controls and interacts with the Tableau dashboard objects
Your web application must include an HTML page. This page should link to the Extensions API JavaScript library and to any other JavaScript, CSS, or HTML resources your web app requires.
-1. In the HTML page, add a link to the JavaScript library (for example, `tableau-extensions-0.7.0.js`).
+1. In the HTML page, add a link to the JavaScript library (for example, `tableau-extensions-0.8.0.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
@@ -103,7 +103,7 @@ Your web application must include an HTML page. This page should link to the Ext
-
+
diff --git a/docs/trex_getstarted.md b/docs/trex_getstarted.md
index 502ca263..0dd1a863 100644
--- a/docs/trex_getstarted.md
+++ b/docs/trex_getstarted.md
@@ -78,27 +78,19 @@ To use the dashboard extension samples, you need to start up a web server on you
----
-### Install the dashboard extension manifest file (`.trex`)
-
-
-Every Tableau extension has a manifest file (`.trex`) that describes the extension and identifies the location of the web application.
-
-1. Close Tableau, if you have it opened.
-2. Copy the `.trex` files of the samples you wish to run to `~\Documents\My Tableau Repository (Beta)\Extensions` so they are available to Tableau.
- The `.trex` files for the samples can be found in the folder with the samples. For example, `\extensions-api\Samples\DataSources\DataSources.trex`.
-
-
-
---
### Start Tableau and add an extension to the dashboard
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 **Extensions**, select one of the sample extensions and drag it on to the dashboard. For example, drag **DataSources Sample** to the 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.
+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. 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.
-3. In the DataSources extension, click the **Info** (**i**) button. This action opens a dialog box that displays more details about the selected data source.
+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.
diff --git a/docs/trex_manifest.md b/docs/trex_manifest.md
index f0cb99f0..23aa1231 100644
--- a/docs/trex_manifest.md
+++ b/docs/trex_manifest.md
@@ -39,7 +39,7 @@ If a workbook is saved with an extension and then later opened on another comput
1.1
- SERVER:PORT/PATH
+ SCHEME://SERVER[:PORT][/PATH]
Base64-Encoded ICON
@@ -106,7 +106,7 @@ If a workbook is saved with an extension and then later opened on another comput
Specifies the name and port (optional) of the server. The Specifies the scheme (HTTPS, HTTTP), the name of the server, the port (optional) and the path to extension (optional). The
diff --git a/docs/trex_release-notes.md b/docs/trex_release-notes.md
index eb89e0cd..87982f4e 100644
--- a/docs/trex_release-notes.md
+++ b/docs/trex_release-notes.md
@@ -8,6 +8,45 @@ layout: docs
* TOC
{:toc}
+---
+
+### Developer Preview (0.8.0)
+*December 21, 2017*
+
+- Update of the Tableau Extensions API.
+- Tableau Extensions API library: `tableau-extensions-0.8.0.js`
+- Tableau Desktop 10.5 RC, Tableau Server 10.5 (from [Extensions API Developer Preview](https://prerelease.tableau.com){:target="_blank"})
+
+
+**New desktop authoring experience**
+
+You no longer need to place the `.trex` file for the extension in a predetermined folder, you now do the following:
+
+ 1. In the dashboard, under **Objects** on the left, select **Extension** and drag it to the dashboard sheet on the right.
+ The **Select an Extension** dialog box appears.
+ 2. The first time you open the dialog box to add an extension, you will see a link to **Choose an Extension**. Click the link and browse to the directory where you have the `.trex` file.
+Subsequently, when you drag the **Extension** on the dashboard, the dialog box shows you the most recently used list, choose from the list, or click **Browse** to select another extension.
+
+**New UI namespace**
+
+- You can now launch a new modal dialog using the function: `tableau.extensions.ui.displayDialogAsync(dialonExtensionURL)`.
+- The URL you want to load (`dialonExtensionURL`) will be an extension itself.
+- The extension in the dialog will have full access to the extensions API. When ready to close to the dialog, from the dialog extension you can call `tableau.extensions.ui.closeDialog(string)`. See the documentation for details.
+- Note that the UI namespace is work is still in progress and has some upcoming additions. *Stay tuned for more.*
+
+**HTTPS and security**
+
+For information about the HTTPS requirements for extensions, see [Security and Tableau Extensions]({{site.baseurl}}/docs/trex_security.html)
+
+**Remote Debugging**
+
+Due to changes in this release, remote debugging does not work as expected in Tableau Desktop. To enable debugging, you must add the `--remote-debugging-port=8696` option to the command used to start Tableau. The easiest way to do this is to open the Tableau shortcut on the **Start** menu. Open the file location of the Tableau shortcut. Right-click the Tableau shortcut and click **Properties**. In the Target text box, append the remote debugging option to the command. Do not enclose the option in quotation marks.
+```
+ "C:\Program Files\Tableau\Tableau main\bin\tableau.exe" --remote-debugging-port=8696
+```
+For information about debugging extensions, see [Remote Debugging of JavaScript and HTML]({{site.baseurl}}/docs/trex_debugging.html).
+
+
---
### Developer Preview (0.7.0)
diff --git a/docs/trex_security.md b/docs/trex_security.md
new file mode 100644
index 00000000..f5a377f6
--- /dev/null
+++ b/docs/trex_security.md
@@ -0,0 +1,207 @@
+---
+title: Security 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.
+
+- 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.
+
+
+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*).
+
+
+**In this section**
+
+* TOC
+{:toc}
+
+
+---
+## Why HTTPS?
+
+When you use HTTPS, all HTTP data is encrypted prior to transmission by the Transport Layer Security (TLS) and decrypted when it is received. HTTPS ensures a secure channel between the extension (client), running in the Tableau dashboard, and the web server that hosts the extension. The use of HTTPS provides a level of privacy, authentication, and integrity.
+
+If you plan to make your extension available to others, using HTTPS
+ assures your customers that their data is safe and that they are connecting to trusted extension. Because the extension is using HTTPS, Tableau is also able to verify the identity of the server that hosts the extension, which prevents various malicious man-in-the-middle attacks that could occur if the extension were to use HTTP alone.
+
+> Note: For development or internal use, you can run your extension on your local computer as `localhost` and you can use the HTTP protocol.
+
+
+
+---
+## HTTPS and security requirements
+The requirements are pretty straight-forward. If you are distributing your extension so that others can use it, the extension must be hosted on a web server that is configured to support the HTTPS protocol.
+
+- The server that hosts your extension must have a certificate from a Certificate Authority (CA). There are many free and low cost options. Note that self-signed or test-signed certificates are not sufficient. The certificate is sometimes called an SSL certificate, as HTTPS was formerly implemented by the Secure Sockets Layer (SSL).
+- In the `.trex` file for your extension, the `url` you use for the source location must start with `https://`. If the HTTPS protocol is not specified, the extension fails registration and does not appear in list of available extensions in Tableau.
+The exception to this requirement is for `localhost`. If you are developing your extension, you can host it on your computer using HTTP (for example, `http://localhost`). You can also use `http://localhost` if you publish the workbook to Tableau Server. In this case, the extension must be running on the same computer as the browser you are using to access the server.
+- Mixed content is not allowed. If your web application uses other libraries or resources, those assets should also use `https`, or use site-relative links.
+- Redirects are permitted, but if they redirect to any other origin, other than the URL of the extension, those pages cannot interact with the Extensions API. For example, if the URL of your extension is `https://example.com` and you redirect to `https://myexample.com`, the page you were redirecting to (`https://myexample.com`) cannot interact with the Extensions API.
+- To run on Tableau Server, your extension must be added to the safe list for the site. Site administrators can add or remove extensions, and can configure how an extension requests permissions for access to data.
+
+----
+
+## Setting the source location in the .trex file
+
+The source location of the extension is its URL. You specify the URL in the extension manifest (`.trex`) file. The syntax includes the name of the server, which includes the protocol (HTTPS, HTTP), the port used, if any, and the path to the extension web page (optional).
+
+The `` element in the `.trex` file, looks like the following:
+
+```xml
+
+ SCHEME://SERVER[:PORT][/PATH]
+
+
+```
+
+For example, if the extension is hosted on example.com, the entry might look like the following:
+
+```xml
+
+ https://example.com:4043/extension
+
+
+
+```
+
+Or during development, when you can use `localhost`, the entry might look like the following:
+
+```xml
+
+
+ http://localhost:8080/extension
+
+
+
+```
+At startup, Tableau looks for and validates the extension `.trex` files. If the extension source location does not specify HTTPS or localhost, validation fails and the extension is not registered. These errors are written to the log file. The extension will not appear in the list of available extensions. If you examine the log files (for example, with Tableau Log Viewer), you will find something similar to the following:
+
+```
+Error: Registration Failed: XSD Validation Failed
+file: Example.trex
+
+
+Error: Error(11,67): value 'http://example.com/example.html' does not match regular expression facet '[Hh][Tt][Tt][Pp][Ss]://.+|[Hh][Tt][Tt][Pp]://[Ll][Oo][Cc][Aa][Ll][Hh][Oo][Ss][Tt]|[Hh][Tt][Tt][Pp]://[Ll][Oo][Cc][Aa][Ll][Hh][Oo][Ss][Tt][:/].*' (id: C:\Users\\Documents\My Tableau Repository (Beta)\Extensions\example.trex)
+file: Example.trex
+
+
+```
+
+
+## Avoid mixed content - use HTTPS or site-relative paths for resources
+
+The extension should not call any pages over HTTP. If you reference libraries or resources, specify `https` for the files you include.
+
+For example:
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+
+Or use site-relative or protocol-agnostic links (that is, where the protocol is not specified).
+
+```html
+
+
+
+
+
+
+
+```
+
+
+## Use HTTP and localhost for development or internal use
+
+While HTTPS is required, during development, you can run a web server on your local computer (`localhost`) to host the extension over HTTP. This exception also applies to Tableau Server.
+
+For example, you can author a workbook in Tableau Desktop that uses an extension (running as `localhost` on same computer as Tableau Desktop). You can then publish that workbook to Tableau Server. The extension must be running on the same computer as the browser that you are using to connect to Tableau Server. The `localhost` is local to the browser. For example, the source location of an extension might be `http://localhost:8080/extension`. If you publish that extension to Tableau Server, other users can view the dashboard and extension, provided that they also have a local copy of the extension hosted on their computers and the extension is using the same URL.
+
+Note the following considerations:
+
+- If Tableau Server is using HTTPS, your extension won't work with `http://localhost`. This is because you can't embed an HTTP `
environment
settings
ui
initializeAsync
This is the entry point for an Extension. This function must first be called + in order to interact with any of the other Extension APIs.
+Returns Promise<void>
+A promise that when resolved, the other Extension APIs will be available to use.
+initializeDialogAsync
++- initialize
DialogAsync(): Promise<void>
+
++-
+
-
This is the entry point for an Extensions. This function must first be called - in order to interact with any of the other Extensions APIs.
+This is the entry point for an extension that runs inside a dialog created by the + UI namespace. This function must be called first in order to use the rest of the Extension + API, and should not be called by extensions that are not displayed in a dialog.
Returns Promise<void>
-A promise that the developer must run to initiailze their extension. - When resolved, the other Extensions APIs will be available to use.
+A promise that when resolved, the other Extension APIs will be available to use.
-
- display
DialogAsync
+ closeDialog
-
- message
ParentExtensions
+ displayDialogAsync
@@ -924,14 +924,13 @@-- notimplemented
-
+This namesapce contains functionality that allows an Extensions to display a popup - dialog window, and communicate between that window and the parent Extensions. This can - be useful in auth scenarios and when extra situational UI space is needed. - Only one dialog can be displayed at a time.
-This namespace contains functionality that allows an Extension to display a popup + dialog window. This can be useful in auth scenarios and when extra situational UI space is needed. + Only one dialog can be displayed at a time per extension. Inside the popup dialog window, + another extension can be loaded and run. This 'dialog extension' will have full access + to the functions provided by the Extensions API.
+Index
Methods
+- close
Dialog
- display
DialogAsync
- - message
ParentExtensions
Methods
Methods
displayDialogAsync
+ +closeDialog
-- display
DialogAsync(url: string, height?: number, width?: number): Promise<ExtensionsDialog>
+ - close
Dialog(payload?: string): void
-- notimplemented
-
-
+Called from dialog extension in order to close itself.
+Parameters
-
-
-
-
- -
-
-
-
- -
-
-
-url: string
-The url to navigate to in the popup dialog. The Dialog url must - belong to the same domain as the parent Extensions.
-Optional height: number
-Optional height the dialog should try and open with.
-Optional width: number
+Optional payload: string
Optional width the dialog should try and open with.
+optional data to make available to parent extension when this dialog closes.
Returns Promise<ExtensionsDialog>
-A promise resolving to an ExtensionsDialog.
+Returns void
messageParentExtensions
+ +displayDialogAsync
-- message
ParentExtensions(message: string): void
+ - display
DialogAsync(url: string, payload?: string, dialogOptions?: DialogOptions): Promise<string>
-- notimplemented.
-
-
Parameters
-
-
+
+
+ -
+
-
+
+ -
+
+
-message: string
+url: string
+The url of the 'dialog extension' to navigate to in the dialog. The url must + belong to the same domain as the parent extension.
+Optional payload: string
The message to send from an Extensions's dialog to its parent frame.
+optional data to make available to dialog on startup. This will be returned + to the dialog extension as the return value of tableau.extensions.ui.initializeDialogAsync
+Optional dialogOptions: DialogOptions
+configuration options for the dialog appearance
Returns void
+Returns Promise<string>
+A promise that resolves when the dialog has been closed. It will contain a + payload as a string provided by the dialog extension. The promise is rejected if + the user manually closes the dialog (for example, by clicking the 'x').
urlurlmust use HTTPS. For example:https://example.com/extension. +urlmust use HTTPS. For example:https://example.com/extension. The exception is forlocalhost. In this case, HTTP is allowed. For example:http://localhost:8080.