diff --git a/.gitignore b/.gitignore
index 7b4370df..2cf930a8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,6 +8,9 @@ website/build
website/.docusaurus
website/.cache-loader
+# Working/scratch files for in-progress docs
+website/docs/workspaceext/working/
+
# Misc
**/.DS_Store
.env.local
diff --git a/website/docs/index.md b/website/docs/index.md
index 4f4e499e..c9cf54a8 100644
--- a/website/docs/index.md
+++ b/website/docs/index.md
@@ -1,6 +1,6 @@
# Tableau Extensions API
-The Tableau Extensions API allows developers to create dashboard extensions and viz 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. A Tableau viz extension creates new viz types that Tableau users can access through the worksheet Marks card.
+The Tableau Extensions API allows developers to create dashboard extensions, viz extensions, and workspace 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. A Tableau viz extension creates new viz types that Tableau users can access through the worksheet Marks card. A workspace extension runs at the workspace level and stays available as you open, close, and switch between workbooks.
:::note
@@ -8,7 +8,7 @@ If you are looking for information about how to extend Tableau calculations to i
:::
-The Tableau Extensions API is a JavaScript library that is organized into namespaces that contain the classes and methods for communicating with Tableau components. The Tableau Extensions API library supports both dashboard extensions and viz extensions, although not all interfaces and methods apply to both extensions. For an overview of how the API is organized, see [Tableau Extensions API Basics](./trex_api_about.md).
+The Tableau Extensions API is a JavaScript library that is organized into namespaces that contain the classes and methods for communicating with Tableau components. The Tableau Extensions API library supports dashboard extensions, viz extensions, and workspace extensions, although not all interfaces and methods apply to every extension type. For an overview of how the API is organized, see [Tableau Extensions API Basics](./trex_api_about.md).
Details on the supported platforms and hardware requirements can be found in the [Installation instructions](installation.md).
@@ -19,3 +19,5 @@ Details on the supported platforms and hardware requirements can be found in the
* [Get Started with Viz Extensions](./vizext/trex_viz_getstarted.md)
* [Get Started with Dashboard Extensions](./dashext/trex_getstarted.md)
+
+* [Get Started with Workspace Extensions](./workspaceext/trex_workspace_getstarted.md)
diff --git a/website/docs/installation.md b/website/docs/installation.md
index 43d6ee86..9f88fdb4 100644
--- a/website/docs/installation.md
+++ b/website/docs/installation.md
@@ -92,6 +92,14 @@ For viz extensions:
* Tableau Server 2024.1 and later
* Tableau Cloud
+For workspace extensions:
+
+:::warning[TODO: REVIEW]
+Add the Tableau version requirements for workspace extensions (Tableau Desktop, Server, and Cloud).
+
+Flagged because: supported environments and minimum versions for workspace extensions are release information and are not yet confirmed.
+:::
+
### Security requirements
diff --git a/website/docs/trex_api_about.md b/website/docs/trex_api_about.md
index d829e8c1..4dddcc75 100644
--- a/website/docs/trex_api_about.md
+++ b/website/docs/trex_api_about.md
@@ -10,6 +10,7 @@ The Tableau Extensions API is organized by namespaces. The type of extension you
| ----- | ------- |
| Dashboard extensions | For example, if you create and register a dashboard extension, the extension will have access to the `dashboardContent` namespace, which provides access to the dashboard object. When you have the dashboard object, you have access to all elements in the dashboard, including the worksheets, marks, filters, parameters, and data sources. |
| Viz extensions | If you create and register a viz extension, the extension will have access to the `worksheetContent` namespace, which provides access to the worksheet object. When you have the worksheet object, you have access to all elements in the worksheet, including the marks, filters, parameters, and data sources.|
+| Workspace extensions | If you create and register a workspace extension, the extension runs at the workspace level rather than inside a single workbook. It can access information about the currently active workbook (which can be empty when no workbook is open) and is notified when the active workbook changes. |
## Navigating the top-level `tableau` and `extensions` namespaces
@@ -19,6 +20,14 @@ The `extensions` namespace is the namespace for Tableau extensions. A dashboard
A viz extension is another type of extension. When a extension is registered as a viz extension, it has access to the `worksheetContent` namespace, and all of the objects and classes of the worksheet. A viz extension does not have access to the `dashboardContent`.
+A workspace extension is another type of extension. A workspace extension runs at the workspace level instead of inside a single workbook, so it is not bound to a specific dashboard or worksheet. It can access information about the currently active workbook and is notified when the active workbook changes.
+
+:::warning[TODO: REVIEW]
+Confirm the namespace a workspace extension uses to access workspace and workbook content (for example, tableau.extensions.workspace).
+
+Flagged because: the source material is inconsistent about the workspace namespace name and notes it may not be finalized. The canonical namespace needs to be confirmed.
+:::
+
The type of extension you have registered determines what namespaces will be available. Some namespaces, like the `settings`, `environment`, and `ui` are available to all extensions.
The `extensions` namespace has one method `initializeAsync()` that is used to initialize the extension. When this method is called, it also triggers Tableau to configure the Extensions API. Like the Tableau JavaScript API, the Extensions API follows the [CommonJS Promises/A standard](http://wiki.commonjs.org/wiki/Promises/A) for asynchronous method calls.
@@ -33,6 +42,7 @@ classDiagram
class extensions
class dashboardContent
class worksheetContent
+ class workspace
class environment
class settings
class ui
@@ -41,6 +51,7 @@ classDiagram
class extensions
extensions ..> dashboardContent
extensions ..> worksheetContent
+ extensions ..> workspace
extensions ..> environment
extensions ..> settings
extensions ..> ui
@@ -48,6 +59,12 @@ classDiagram
```
+:::warning[TODO: REVIEW]
+Confirm the workspace namespace name shown in the diagram above (currently workspace).
+
+Flagged because: the source material is inconsistent about the workspace namespace name. Update the diagram once the canonical name is confirmed.
+:::
+
## Registering and accessing dashboard extensions
The dashboard extension is one type of extension in the Tableau extensions namespace (and it is accessed using `tableau.extensions`). To register the extension, you declare the type of extension in the manifest file (`.trex`). For more information about what goes in the file, see [Tableau Manifest File](./dashext/trex_manifest.md).
@@ -101,6 +118,24 @@ window.onload = tableau.extensions.initializeAsync().then(async () => {
```
+## Registering and accessing workspace extensions
+
+The workspace extension is another type of extension in the Tableau extensions namespace (and it is accessed using `tableau.extensions`). To register the workspace extension, you specify the extension as a `workspace-extension` in the manifest file (`.trex`). For more information about what goes in the file, see [Tableau Workspace Extension Manifest File](./workspaceext/trex_workspace_manifest.md).
+
+```xml
+
+
+
+```
+
+Unlike dashboard and viz extensions, a workspace extension runs at the workspace level and is not bound to a single workbook. After it is initialized, it has access to the namespaces that are common to all extensions, such as `tableau.extensions.environment` and `tableau.extensions.settings`. It can also access information about the currently active workbook, which can be empty when no workbook is open, and is notified when the active workbook changes.
+
+:::warning[TODO: REVIEW]
+Confirm the workspace extension initialization call and the namespace used to access workspace and workbook content.
+
+Flagged because: the source material shows initialization with a `context: 'workspace'` option and is inconsistent about the workspace namespace name, and notes both may not be finalized. These need to be confirmed before adding a code sample here.
+:::
+
## Using properties and methods in the `dashboard` and `worksheet` namespace
The Tableau Extensions API is similar to the Tableau Embedding API. The `dashboard` and `worksheet` class or namespace inherit from an abstract `sheet` class. You can use the [Extensions API Reference](pathname:///api/) to find the properties and methods that are available for dashboard and worksheet objects.
@@ -126,6 +161,7 @@ classDiagram
class extensions
class dashboardContent
class worksheetContent
+ class workspace
class worksheet
class dashboard
class environment
@@ -137,6 +173,7 @@ classDiagram
class extensions
extensions ..> dashboardContent
extensions ..> worksheetContent
+ extensions ..> workspace
extensions ..> environment
extensions ..> settings
extensions ..> ui
diff --git a/website/docs/workspaceext/index.md b/website/docs/workspaceext/index.md
new file mode 100644
index 00000000..aa2af75d
--- /dev/null
+++ b/website/docs/workspaceext/index.md
@@ -0,0 +1,7 @@
+# Workspace Extensions
+
+```mdx-code-block
+import DocCardList from '@theme/DocCardList';
+
+
+```
diff --git a/website/docs/workspaceext/trex_workspace_create.md b/website/docs/workspaceext/trex_workspace_create.md
new file mode 100644
index 00000000..3921df3f
--- /dev/null
+++ b/website/docs/workspaceext/trex_workspace_create.md
@@ -0,0 +1,97 @@
+---
+title: Create a "Hello World" Workspace Extension
+description: Build a simple workspace extension
+---
+
+This walkthrough shows the basic shape of a workspace extension: an HTML page that loads the Tableau Extensions API library, initializes as a workspace extension, and reads information about the active workbook.
+
+## The web page
+
+Like other Tableau extensions, a workspace extension is a web page that links to the Tableau Extensions API library.
+
+```html
+
+
+
+
+
+
+
+
+ Workspace Extension Example
+ Initializing...
+
+
+
+```
+
+## Initialize the extension
+
+A workspace extension initializes through the same `initializeAsync()` entry point used by other extensions, identifying itself as a workspace extension.
+
+```javascript
+(async () => {
+ await tableau.extensions.initializeAsync({ context: 'workspace' });
+ document.getElementById('status').textContent = 'Ready!';
+})();
+```
+
+:::warning[TODO: REVIEW]
+Confirm how a workspace extension is initialized, including the exact initializeAsync() argument (for example, {'{'} context: 'workspace' {'}'}) and whether any argument is required.
+
+Flagged because: the source material shows initialization with a `context: 'workspace'` option, but it also notes this entry point is still being finalized. The exact call signature needs to be confirmed.
+:::
+
+## Access the active workbook
+
+After initialization, a workspace extension can read information about the currently active workbook. Because a workspace extension is not tied to a single workbook, the current workbook can be `null` when no workbook is open.
+
+```javascript
+const workspace = tableau.extensions.workspace;
+
+const updateWorkbookInfo = () => {
+ const workbook = workspace.getWorkbook();
+ const infoDiv = document.getElementById('workbook-info');
+
+ if (workbook) {
+ infoDiv.textContent = `Current workbook: ${workbook.name}`;
+ } else {
+ infoDiv.textContent = 'No workbook open';
+ }
+};
+
+updateWorkbookInfo();
+```
+
+:::warning[TODO: REVIEW]
+Confirm the workspace namespace name (for example, tableau.extensions.workspace versus tableau.workspace) and the members it exposes.
+
+Flagged because: the source material is inconsistent about the namespace name and notes that the namespace may not be finalized. The canonical namespace and its API surface need to be confirmed.
+:::
+
+## Respond to workbook changes
+
+A workspace extension can listen for changes to the active workbook so it can update as the user opens, closes, or switches workbooks.
+
+```javascript
+workspace.addEventListener('workbook-opened', (event) => {
+ console.log('Opened:', event.workbook.name);
+ updateWorkbookInfo();
+});
+
+workspace.addEventListener('workbook-closed', () => {
+ console.log('Workbook closed');
+ updateWorkbookInfo();
+});
+
+workspace.addEventListener('workbook-switched', (event) => {
+ console.log('Switched to:', event.workbook.name);
+ updateWorkbookInfo();
+});
+```
+
+:::warning[TODO: REVIEW]
+Confirm the workbook lifecycle event names and their event payloads.
+
+Flagged because: the source material uses two different naming styles for these events (for example, workbook-opened versus workbookOpened). The canonical event names and payload shapes need to be confirmed.
+:::
diff --git a/website/docs/workspaceext/trex_workspace_examples.md b/website/docs/workspaceext/trex_workspace_examples.md
new file mode 100644
index 00000000..dccfc575
--- /dev/null
+++ b/website/docs/workspaceext/trex_workspace_examples.md
@@ -0,0 +1,18 @@
+---
+title: Workspace Extension Examples
+description: Examples of workspace extensions
+---
+
+Workspace extensions are well suited to tools and utilities that need to stay available throughout a Tableau session, independent of any single workbook. The following are illustrative scenarios:
+
+* A utility that displays information about the active workbook and updates as you switch workbooks.
+
+* A persistent tool that tracks workbook activity across a session by responding to workbook opened, closed, and switched events.
+
+For a minimal, end-to-end starting point, see [Create a "Hello World" Workspace Extension](./trex_workspace_create.md).
+
+:::warning[TODO: REVIEW]
+Add concrete, runnable workspace extension samples and links once they are available.
+
+Flagged because: a public sample set for workspace extensions is not yet available, so this page currently describes scenarios rather than linking to working samples.
+:::
diff --git a/website/docs/workspaceext/trex_workspace_getstarted.md b/website/docs/workspaceext/trex_workspace_getstarted.md
new file mode 100644
index 00000000..bc9de5c7
--- /dev/null
+++ b/website/docs/workspaceext/trex_workspace_getstarted.md
@@ -0,0 +1,44 @@
+---
+title: Get Started with Workspace Extensions
+description: Get started with Workspace Extensions
+tags: [Getting started]
+---
+
+The Tableau Extensions API allows developers to create workspace extensions, web applications that run at the workspace level of Tableau and stay available as you open, close, and switch between workbooks.
+
+This section takes you through setting up your environment and adding a workspace extension so you can start developing your own.
+
+:::info
+
+**What's in a Tableau extension?**
+A Tableau extension consists of an XML manifest file (`.trex`), a web page (`.html`) that uses a Tableau-provided JavaScript library, and the JavaScript file (`.js`) (or files) that contain your extension logic.
+
+:::
+
+### What you need to get started
+
+If you want to create an extension or work with sample code, make sure you have followed the instructions for [installation](../installation.md).
+
+:::warning[TODO: REVIEW]
+Confirm the Tableau version requirements for workspace extensions.
+
+Flagged because: minimum supported versions for Tableau Desktop, Server, and Cloud are release information and are not yet confirmed.
+:::
+
+### Add a workspace extension
+
+Every Tableau extension has a manifest file (`.trex`) that describes the extension and identifies the location of the web application. To use a workspace extension, you register it for your Tableau environment and then open it when you want to use it. Once registered, a workspace extension remains available across workbooks.
+
+:::warning[TODO: REVIEW]
+Confirm the exact steps and Tableau UI entry points for registering and opening a workspace extension, and how the running extension is presented.
+
+Flagged because: the available source material describes adding the extension and opening it from a menu, but the specific UI navigation and the way the extension is surfaced are not yet confirmed for public documentation, and depend on the open UI-model question (see the overview).
+:::
+
+## What's next?
+
+* For information about creating a simple workspace extension, see [Create a "Hello World" Workspace Extension](./trex_workspace_create.md).
+
+* For details on the workspace extension manifest, see [Tableau Workspace Extension Manifest File](./trex_workspace_manifest.md).
+
+* To get familiar with the programming interface for the Extensions API, see the [API Reference](pathname:///api/).
diff --git a/website/docs/workspaceext/trex_workspace_manifest.md b/website/docs/workspaceext/trex_workspace_manifest.md
new file mode 100644
index 00000000..34213ea9
--- /dev/null
+++ b/website/docs/workspaceext/trex_workspace_manifest.md
@@ -0,0 +1,54 @@
+---
+title: Tableau Workspace Extension Manifest File
+description: Components of the workspace extension manifest file
+---
+
+The extension manifest file (`.trex`) contains metadata for the extension and is used for registration. A workspace extension uses the same manifest format as dashboard and viz extensions, but declares the extension with the `` element.
+
+## Registering a workspace extension
+
+To register an extension as a workspace extension, you specify the `` element in the manifest file (`.trex`).
+
+```xml
+
+```
+
+Unlike dashboard and viz extensions, a workspace extension is not placed inside a dashboard zone or a worksheet, so its manifest does not include layout or encoding information.
+
+:::warning[TODO: REVIEW]
+Confirm the manifest wrapper element and manifest version for workspace extensions.
+
+Flagged because: the existing dashboard and viz manifests use a `` root wrapper, while the workspace source material shows an `` wrapper. The correct wrapper element and version value need to be confirmed before publishing.
+:::
+
+## Sample manifest file
+
+```xml
+
+
+
+ en_US
+
+ Extension Description
+
+ 1.0
+
+ SCHEME://SERVER[:PORT][/PATH]
+
+ Base64-Encoded ICON
+
+
+
+ name in English
+
+
+
+```
+
+The manifest fields shared with other extension types (such as `id`, `extension-version`, `name`, `description`, `author`, `source-location`, `icon`, and `min-api-version`) behave the same way as they do for dashboard extensions. For details on these shared elements, see the [Tableau Extension Manifest File](../dashext/trex_manifest.md) reference for dashboard extensions.
+
+:::warning[TODO: REVIEW]
+Confirm whether workspace extensions support any manifest elements that dashboard and viz extensions do not, or omit any that the others use.
+
+Flagged because: only the core shared elements are confirmed from the source material; any workspace-specific manifest elements still need to be verified.
+:::
diff --git a/website/docs/workspaceext/trex_workspace_overview.md b/website/docs/workspaceext/trex_workspace_overview.md
new file mode 100644
index 00000000..56b12c59
--- /dev/null
+++ b/website/docs/workspaceext/trex_workspace_overview.md
@@ -0,0 +1,48 @@
+---
+title: What is a Tableau Workspace Extension
+description: Describes a workspace extension and how it differs from dashboard and viz extensions
+---
+
+A workspace extension is a web application that runs at the *workspace* level of Tableau, the overall authoring and viewing environment, rather than inside a single workbook. Unlike a dashboard extension (which lives in a dashboard) or a viz extension (which lives in a worksheet), a workspace extension is not tied to one workbook. It stays available as you open, close, and switch between workbooks. A workspace extension is one type of extension that can be built using the Tableau Extensions API.
+
+---
+
+## Components of a Tableau workspace extension
+
+A Tableau extension consists of a manifest file (`.trex`), a web page (`.html`) that uses a Tableau-provided JavaScript library, and the JavaScript file (or files) that contain your extension logic.
+
+## What can you do with a workspace extension?
+
+Because a workspace extension is not bound to a single workbook, it is well suited to tools and utilities that need to be available throughout a Tableau session:
+
+* Provide persistent tooling or utilities that stay available regardless of which workbook is open.
+* Respond to workbook lifecycle changes, such as when a workbook is opened, closed, or switched.
+* Work with the currently active workbook when there is one, and continue to run when there is none.
+
+:::warning[TODO: REVIEW]
+Confirm the surface(s) a workspace extension can present in the Tableau UI (for example, persistent toolbars and menus versus a standalone extension window).
+
+Flagged because: the available source material describes the workspace extension being opened from a menu and shown in its own window, but the intended feature description also mentions persistent toolbars and menus. These need to be reconciled before this section can state what authors can build.
+:::
+
+## How a workspace extension differs from dashboard and viz extensions
+
+All three extension types are web applications built on the same Tableau Extensions API and share a common library, but they operate at different scopes:
+
+* A **dashboard extension** runs inside a dashboard and is saved as part of the workbook.
+* A **viz extension** runs inside a worksheet and is added from the Marks card.
+* A **workspace extension** runs at the workspace level, independent of any single workbook, and remains available as you move between workbooks.
+
+A few distinctions:
+
+* A workspace extension can run with or without an active workbook. When a workbook is open, the extension can access information about it; when no workbook is open, the extension continues to run.
+
+* A workspace extension is registered for your Tableau environment rather than being saved inside a specific workbook.
+
+* A workspace extension receives notifications when the active workbook changes, so it can update itself as you open, close, or switch workbooks.
+
+:::warning[TODO: REVIEW]
+Confirm where workspace extensions are supported (Tableau Desktop, Server, Cloud) and any availability requirements.
+
+Flagged because: supported-environment details are release information and are not yet confirmed for public documentation.
+:::
diff --git a/website/sidebars.js b/website/sidebars.js
index 60755481..67205cec 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -31,6 +31,18 @@ const sidebars = {
'dashext/trex_examples',
],
},
+ {
+ type: 'category',
+ label: 'Workspace Extensions',
+ link: { type: 'doc', id: 'workspaceext/index' },
+ items: [
+ 'workspaceext/trex_workspace_getstarted',
+ 'workspaceext/trex_workspace_create',
+ 'workspaceext/trex_workspace_overview',
+ 'workspaceext/trex_workspace_manifest',
+ 'workspaceext/trex_workspace_examples',
+ ],
+ },
/* {
type: 'category',
label: 'Basic Concepts',