add multiple dialog boxes

Author: d45

website/docs/Interaction_Guidelines/ux_controls_ui_patterns.md

@@ -191,7 +191,7 @@ Dropdown controls allow multiple options to be expanded from a menu. Dropdowns h
 | --- | --- |
 | **Outline** | The outline style is the primary variation that should be used. It can be used by itself, on forms, or within dialogues.  |
 | **Line**<br/>(label optional) &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; | Line style dropdowns are useful in areas that have cramped vertical space. This dropdown style can be stacked within panels to avoid a boxy wireframe feel. While the label is optional, we encourage using it to better inform users about the category of items. |
-| **Text** | This style allows the user to access options from a dropdown or flyout menu. This style works well in tool and start bars, as well as in dialogs and menus. |
+| **Text** | This style allows the user to access options from a dropdown or flyout menu. This style works well in tool and start bars, as well as in dialogs and menus. |
 | **Icon** | The icon style works best in small regions such as tool bars, and is great for switches that have several options. |
 
 &nbsp;

website/docs/core/trex_configure.md

@@ -1,16 +1,15 @@
 ---
-title: Add a Configuration Popup Dialog
+title: Add a Configuration Popup Dialog Box
 description: How to add a configuration dialog box to the extension
 ---
 
-If you want users to be able to configure settings for your extension, you can use an optional callback function when you initialize your dashboard or viz extension. The callback function creates a configuration option that can be used to open a popup window (a modal dialog box) for your extension. You can use this popup window to allow users to set and save settings for the extension.
-
+If you want users to be able to configure settings for your extension, you can use an optional callback function when you initialize your dashboard or viz extension. The callback function creates a configuration option that can be used to open a popup window (dialog box) for your extension. The Extensions API supports different dialog box styles: modal, modeless, or window. You can use the dialog box to allow users to set and save settings for the extension. Starting with Tableau 2026.1 (and the v1.16 library), you can create multiple dialog boxes and send messages between them. 
 
 ## Add the context menu to the `.trex` file
 
-The first step is to add the `<context-menu>` option to the extension's manifest file (`.trex`). The `<context-menu>` element only contains one item:  `<configure-context-menu-item />`.
+The first step is to add the `<context-menu>` option to the extension's manifest file (`.trex`). The `<context-menu>` element only contains one item: `<configure-context-menu-item />`.
 
-* The context menu option must follow the `<icon>` and `<permissions>` elements in the  manifest file in the `<dashboard-extension>` or `<worksheet-extension>` section:
+* The context menu option must follow the `<icon>` and `<permissions>` elements in the manifest file in the `<dashboard-extension>` or `<worksheet-extension>` section:
 
 ```xml
 <!-- add to <dashboard-extension> or <worksheet-extension> section
@@ -36,7 +35,6 @@ with adding a `<context-menu>` item to the manifest, adds a new **Format Extensi
 
 When the user selects the context menu item, or selects **Format Extensions** button, the configuration function you specified is executed.
 
-
 **Dashboard extensions configuration menu**
 
 ![](../assets/extension_configure_menu.png)
@@ -69,7 +67,6 @@ $(document).ready(function () {
 
 
 
-
    function configure() { 
     // ... code to configure the extension
     // for example, set up and call displayDialogAsync() to create the configuration window 
@@ -82,9 +79,11 @@ $(document).ready(function () {
     // to be updated if the extension is deployed to a new location.
     const popupUrl = `${window.location.origin}/Samples/Dashboard/UINamespace/uiNamespaceDialog.html`;
     // 
+    // Specify the style of dialog box: modal, modeless, or window
+    let dialogStyle = tableau.DialogStyle.Modeless;
     // ...
     // initial payload string value, `defaultIntervalInMin` set 
-    tableau.extensions.ui.displayDialogAsync(popupUrl, defaultIntervalInMin, { height: 500, width: 500 }).then((closePayload) => {
+    tableau.extensions.ui.displayDialogAsync(popupUrl, defaultIntervalInMin, { height: 500, width: 500, dialogStyle }).then((closePayload) => {
       // The promise is resolved when the dialog has been expectedly closed, meaning that
       // the popup extension has called tableau.extensions.ui.closeDialog.
       // ...
@@ -136,3 +135,105 @@ In your code to close the popup window, you must pass a *non-empty* string value
 ```
 
 To better understand how to use the context menu or configuration window, and to see it in action, check out the [UINamespace](https://github.com/tableau/extensions-api/tree/master/Samples/Dashboard/UINamespace?=target="_blank") sample.
+
+## Create multiple popup dialog boxes or windows 
+
+Starting with Tableau 2026.1, you can create more than one popup window or dialog box for your extension. In addition to the optional configuration popup that you can create when you initialize the extension, you can have your extension open other dialog boxes, by adding buttons and controls to your extension. If you are creating multiple dialog boxes, you need to consider how you want them to interact with each other and the user. You can control whether the popup windows are modal or modeless, and whether they need to share information and payloads. If you have multiple popup windows, you'll need to track which popup window is active, so you can control their interactions.
+
+### The default configuration window
+
+By design, there can be only one context configuration item. For dashboard extensions, this is the popup dialog box that appears when users select the **Configure..** option from the context menu. For viz extensions, this is the dialog box that appears when users select the **Format Extension** button on the Marks card. 
+
+The configuration item is specified in the `.trex` file for the extension. 
+
+```xml
+<!-- add to <dashboard-extension> or <worksheet-extension> section
+  after <icon></icon> 
+  and <permissions></permissions> -->
+
+<context-menu>
+    <configure-context-menu-item />
+</context-menu>
+
+```
+
+And by specifying a callback function (`configure()`) that gets called when the `'configure'` option is specified in the call to initialize the extension (`initializeAsync()`).
+
+```javascript
+  $(document).ready(function () {
+    tableau.extensions.initializeAsync({'configure': configure}).then(function() {
+    // When the user clicks the Configure... context menu item,
+    // or Format Extension, the configure() function specified 
+    // as the argument here is executed.
+    //
+   });
+
+```
+
+If you are creating additional popup windows, you'll need to call those popup windows from other methods, and you'll need to add controls to call those methods. For example, you could add a button or toolbar item in the main extension window, and use that button to open another popup window. The content and logic of the dialog boxes or windows are typically in HTML and JavaScript files that are separate from the main extension files.
+
+### Create additional popup windows
+
+Starting in Tableau 2026.1, you can create multiple popup windows. While you can't display these additional dialog boxes or windows when the user selects the configure context item, you can display them when users click buttons and controls in your extension. 
+
+* Determine how you want the pop windows to interact (if at all). Should they be modal or modeless? Do they need to share information or content? 
+
+* To create additional dialog boxes or popup windows, add controls (buttons, toolbars) to your extension. 
+
+* Create the HTML and JavaScript code that define the content and features of your additional popup windows. 
+
+* In your extension JavaScript or TypeScript code, define your popup windows: the `popupURL`, the dialog style, and dimensions, and any initial payload you want to send to the popup window. Pass in these values when you call the `displayDialogAsync()` method.
+
+Like the configuration popup, the URL of the additional popup windows must belong to the same domain as the parent extension. The relative paths must resolve to the directory, or a child directory, of the extension. Root-relative paths are not allowed. For example, `./config.html` or `config.html` are allowed, but not the root-relative path `/config.html`.
+
+For example, you could add another dialog box to the uiNamespace sample that lets users set the background color of the extension. In the `uiNamespace.html` file, you could add a button to display the popup window. When the user clicks the button, a color formatting dialog opens. The user can select the background color. When the user clicks a Save button, it calls the `closeDialog()` method and closes the popup window, which returns the new background color as the payload and it is applied. 
+
+```html
+<button id="openColorDialog" class="btn btn-secondary" style="margin-top: 10px; margin-left: 6px">Set Background Color</button>
+```
+
+In the `uiNamespace.js` file, you would add code to set the default background color and then call the `displayDialogAsync()`. You would need to create the HTML and Javascript code for the popup window (for example, uiNamespaceColorDialog.html and uiNamespaceColorDialog.js). 
+
+```javascript
+
+/**
+* Sets the default background color
+* Sets the current color to match as the initial payload
+*/
+
+  const defaultBgColor = '#FFFFFF';
+  let currentBgColor = defaultBgColor;
+
+/**
+* Opens the background color picker dialog (always modal).
+* Passes the current background color as the initial payload so the dialog
+* can pre-select it.  The closePayload returned is the chosen hex color,
+* which is then applied to the extension body.
+*/
+
+  function openColorDialog () {
+    const popupUrl = new URL('uiNamespaceColorDialog.html', window.location.href).href;
+
+    tableau.extensions.ui
+      .displayDialogAsync(popupUrl, currentBgColor, { height: 500, width: 360, dialogStyle: tableau.DialogStyle.Modal })
+      .then((closePayload) => {
+        currentBgColor = closePayload;
+        $('body').css('background-color', currentBgColor);
+      })
+      .catch((error) => {
+        if (error.errorCode === tableau.ErrorCodes.DialogClosedByUser) {
+          console.log('Color dialog was closed by user');
+        } else {
+          console.error(error.message);
+        }
+      });
+  }
+```
+
+
+
+
+
+
+
+## Send messages between configuration windows and the extension

website/docs/dashext/trex_create.md

@@ -17,7 +17,7 @@ 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 the Tableau requirements, see [Installation](../installation.md) and [Get Started with Dashboard Extensions](trex_getstarted.md).
+These instructions assume that you already have cloned or downloaded the Extensions API SDK. For information about setting up your environment and the Tableau requirements, see [Installation](../installation.md) and [Get Started with Dashboard Extensions](trex_getstarted.md).
 
 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.