Skip to content

Commit 5166d80

Browse files
dzucker-tabdzucker-tab
committed
Claude stub structure and content.
1 parent a344cba commit 5166d80

10 files changed

Lines changed: 329 additions & 2 deletions

‎website/docs/index.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
# Tableau Extensions API
22

3-
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.
3+
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.
44

55
:::note
66

77
If you are looking for information about how to extend Tableau calculations to include popular data science programming languages and external tools, see the [Tableau Analytics Extensions API](https://tableau.github.io/analytics-extensions-api/).
88

99
:::
1010

11-
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).
11+
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).
1212

1313
Details on the supported platforms and hardware requirements can be found in the [Installation instructions](installation.md).
1414

@@ -19,3 +19,5 @@ Details on the supported platforms and hardware requirements can be found in the
1919
* [Get Started with Viz Extensions](./vizext/trex_viz_getstarted.md)
2020

2121
* [Get Started with Dashboard Extensions](./dashext/trex_getstarted.md)
22+
23+
* [Get Started with Workspace Extensions](./workspaceext/trex_workspace_getstarted.md)

‎website/docs/installation.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,14 @@ For viz extensions:
9292
* Tableau Server 2024.1 and later
9393
* Tableau Cloud
9494

95+
For workspace extensions:
96+
97+
:::warning[TODO: REVIEW]
98+
<mark>Add the Tableau version requirements for workspace extensions (Tableau Desktop, Server, and Cloud).</mark>
99+
100+
Flagged because: supported environments and minimum versions for workspace extensions are release information and are not yet confirmed.
101+
:::
102+
95103

96104

97105
### Security requirements

‎website/docs/trex_api_about.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ The Tableau Extensions API is organized by namespaces. The type of extension you
1010
| ----- | ------- |
1111
| 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. |
1212
| 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.|
13+
| 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. |
1314

1415
## Navigating the top-level `tableau` and `extensions` namespaces
1516

@@ -19,6 +20,14 @@ The `extensions` namespace is the namespace for Tableau extensions. A dashboard
1920

2021
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`.
2122

23+
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.
24+
25+
:::warning[TODO: REVIEW]
26+
<mark>Confirm the namespace a workspace extension uses to access workspace and workbook content (for example, <code>tableau.extensions.workspace</code>).</mark>
27+
28+
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.
29+
:::
30+
2231
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.
2332

2433
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
3342
class extensions
3443
class dashboardContent
3544
class worksheetContent
45+
class workspace
3646
class environment
3747
class settings
3848
class ui
@@ -41,13 +51,20 @@ classDiagram
4151
class extensions
4252
extensions ..> dashboardContent
4353
extensions ..> worksheetContent
54+
extensions ..> workspace
4455
extensions ..> environment
4556
extensions ..> settings
4657
extensions ..> ui
4758
extensions: initializeAsync()
4859
4960
```
5061

62+
:::warning[TODO: REVIEW]
63+
<mark>Confirm the workspace namespace name shown in the diagram above (currently <code>workspace</code>).</mark>
64+
65+
Flagged because: the source material is inconsistent about the workspace namespace name. Update the diagram once the canonical name is confirmed.
66+
:::
67+
5168
## Registering and accessing dashboard extensions
5269

5370
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 () => {
101118
102119
```
103120

121+
## Registering and accessing workspace extensions
122+
123+
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).
124+
125+
```xml
126+
127+
<workspace-extension id="com.example.extensions.name" extension-version="0.1.0">
128+
129+
```
130+
131+
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.
132+
133+
:::warning[TODO: REVIEW]
134+
<mark>Confirm the workspace extension initialization call and the namespace used to access workspace and workbook content.</mark>
135+
136+
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.
137+
:::
138+
104139
## Using properties and methods in the `dashboard` and `worksheet` namespace
105140

106141
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
126161
class extensions
127162
class dashboardContent
128163
class worksheetContent
164+
class workspace
129165
class worksheet
130166
class dashboard
131167
class environment
@@ -137,6 +173,7 @@ classDiagram
137173
class extensions
138174
extensions ..> dashboardContent
139175
extensions ..> worksheetContent
176+
extensions ..> workspace
140177
extensions ..> environment
141178
extensions ..> settings
142179
extensions ..> ui

‎website/docs/workspaceext/index.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Workspace Extensions
2+
3+
```mdx-code-block
4+
import DocCardList from '@theme/DocCardList';
5+
6+
<DocCardList />
7+
```

‎website/docs/workspaceext/trex_workspace_create.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
title: Create a "Hello World" Workspace Extension
3+
description: Build a simple workspace extension
4+
---
5+
6+
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.
7+
8+
## The web page
9+
10+
Like other Tableau extensions, a workspace extension is a web page that links to the Tableau Extensions API library.
11+
12+
```html
13+
<!DOCTYPE html>
14+
<html>
15+
<head>
16+
<!-- Tableau Extensions API library -->
17+
<script src="https://tableau.github.io/extensions-api/lib/tableau.extensions.1.latest.js"></script>
18+
<script src="workspace-extension.js"></script>
19+
</head>
20+
<body>
21+
<h1>Workspace Extension Example</h1>
22+
<div id="status">Initializing...</div>
23+
<div id="workbook-info"></div>
24+
</body>
25+
</html>
26+
```
27+
28+
## Initialize the extension
29+
30+
A workspace extension initializes through the same `initializeAsync()` entry point used by other extensions, identifying itself as a workspace extension.
31+
32+
```javascript
33+
(async () => {
34+
await tableau.extensions.initializeAsync({ context: 'workspace' });
35+
document.getElementById('status').textContent = 'Ready!';
36+
})();
37+
```
38+
39+
:::warning[TODO: REVIEW]
40+
<mark>Confirm how a workspace extension is initialized, including the exact <code>initializeAsync()</code> argument (for example, <code>{'{'} context: 'workspace' {'}'}</code>) and whether any argument is required.</mark>
41+
42+
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.
43+
:::
44+
45+
## Access the active workbook
46+
47+
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.
48+
49+
```javascript
50+
const workspace = tableau.extensions.workspace;
51+
52+
const updateWorkbookInfo = () => {
53+
const workbook = workspace.getWorkbook();
54+
const infoDiv = document.getElementById('workbook-info');
55+
56+
if (workbook) {
57+
infoDiv.textContent = `Current workbook: ${workbook.name}`;
58+
} else {
59+
infoDiv.textContent = 'No workbook open';
60+
}
61+
};
62+
63+
updateWorkbookInfo();
64+
```
65+
66+
:::warning[TODO: REVIEW]
67+
<mark>Confirm the workspace namespace name (for example, <code>tableau.extensions.workspace</code> versus <code>tableau.workspace</code>) and the members it exposes.</mark>
68+
69+
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.
70+
:::
71+
72+
## Respond to workbook changes
73+
74+
A workspace extension can listen for changes to the active workbook so it can update as the user opens, closes, or switches workbooks.
75+
76+
```javascript
77+
workspace.addEventListener('workbook-opened', (event) => {
78+
console.log('Opened:', event.workbook.name);
79+
updateWorkbookInfo();
80+
});
81+
82+
workspace.addEventListener('workbook-closed', () => {
83+
console.log('Workbook closed');
84+
updateWorkbookInfo();
85+
});
86+
87+
workspace.addEventListener('workbook-switched', (event) => {
88+
console.log('Switched to:', event.workbook.name);
89+
updateWorkbookInfo();
90+
});
91+
```
92+
93+
:::warning[TODO: REVIEW]
94+
<mark>Confirm the workbook lifecycle event names and their event payloads.</mark>
95+
96+
Flagged because: the source material uses two different naming styles for these events (for example, <code>workbook-opened</code> versus <code>workbookOpened</code>). The canonical event names and payload shapes need to be confirmed.
97+
:::

‎website/docs/workspaceext/trex_workspace_examples.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: Workspace Extension Examples
3+
description: Examples of workspace extensions
4+
---
5+
6+
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:
7+
8+
* A utility that displays information about the active workbook and updates as you switch workbooks.
9+
10+
* A persistent tool that tracks workbook activity across a session by responding to workbook opened, closed, and switched events.
11+
12+
For a minimal, end-to-end starting point, see [Create a "Hello World" Workspace Extension](./trex_workspace_create.md).
13+
14+
:::warning[TODO: REVIEW]
15+
<mark>Add concrete, runnable workspace extension samples and links once they are available.</mark>
16+
17+
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.
18+
:::

‎website/docs/workspaceext/trex_workspace_getstarted.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: Get Started with Workspace Extensions
3+
description: Get started with Workspace Extensions
4+
tags: [Getting started]
5+
---
6+
7+
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.
8+
9+
This section takes you through setting up your environment and adding a workspace extension so you can start developing your own.
10+
11+
:::info
12+
13+
**What's in a Tableau extension?**
14+
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.
15+
16+
:::
17+
18+
### What you need to get started
19+
20+
If you want to create an extension or work with sample code, make sure you have followed the instructions for [installation](../installation.md).
21+
22+
:::warning[TODO: REVIEW]
23+
<mark>Confirm the Tableau version requirements for workspace extensions.</mark>
24+
25+
Flagged because: minimum supported versions for Tableau Desktop, Server, and Cloud are release information and are not yet confirmed.
26+
:::
27+
28+
### Add a workspace extension
29+
30+
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.
31+
32+
:::warning[TODO: REVIEW]
33+
<mark>Confirm the exact steps and Tableau UI entry points for registering and opening a workspace extension, and how the running extension is presented.</mark>
34+
35+
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).
36+
:::
37+
38+
## What's next?
39+
40+
* For information about creating a simple workspace extension, see [Create a "Hello World" Workspace Extension](./trex_workspace_create.md).
41+
42+
* For details on the workspace extension manifest, see [Tableau Workspace Extension Manifest File](./trex_workspace_manifest.md).
43+
44+
* To get familiar with the programming interface for the Extensions API, see the [API Reference](pathname:///api/).

‎website/docs/workspaceext/trex_workspace_manifest.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: Tableau Workspace Extension Manifest File
3+
description: Components of the workspace extension manifest file
4+
---
5+
6+
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 `<workspace-extension>` element.
7+
8+
## Registering a workspace extension
9+
10+
To register an extension as a workspace extension, you specify the `<workspace-extension>` element in the manifest file (`.trex`).
11+
12+
```xml
13+
<workspace-extension id="com.example.extensions.name" extension-version="0.1.0">
14+
```
15+
16+
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.
17+
18+
:::warning[TODO: REVIEW]
19+
<mark>Confirm the manifest wrapper element and manifest version for workspace extensions.</mark>
20+
21+
Flagged because: the existing dashboard and viz manifests use a `<manifest manifest-version="0.1">` root wrapper, while the workspace source material shows an `<extension-manifest manifest-version="1.0">` wrapper. The correct wrapper element and version value need to be confirmed before publishing.
22+
:::
23+
24+
## Sample manifest file
25+
26+
```xml
27+
<?xml version="1.0" encoding="utf-8"?>
28+
<manifest manifest-version="0.1" xmlns="http://www.tableau.com/xml/extension_manifest">
29+
<workspace-extension id="com.example.extensions.name" extension-version="0.1.0">
30+
<default-locale>en_US</default-locale>
31+
<name resource-id="name"/>
32+
<description>Extension Description</description>
33+
<author name="USERNAME" email="USER@example.com" organization="My Company" website="https://www.example.com"/>
34+
<min-api-version>1.0</min-api-version>
35+
<source-location>
36+
<url>SCHEME://SERVER[:PORT][/PATH]</url>
37+
</source-location>
38+
<icon>Base64-Encoded ICON</icon>
39+
</workspace-extension>
40+
<resources>
41+
<resource id="name">
42+
<text locale="en_US">name in English</text>
43+
</resource>
44+
</resources>
45+
</manifest>
46+
```
47+
48+
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.
49+
50+
:::warning[TODO: REVIEW]
51+
<mark>Confirm whether workspace extensions support any manifest elements that dashboard and viz extensions do not, or omit any that the others use.</mark>
52+
53+
Flagged because: only the core shared elements are confirmed from the source material; any workspace-specific manifest elements still need to be verified.
54+
:::

0 commit comments

Comments
 (0)