Skip to main content

Create a "Hello World" Workspace Extension

A workspace extension is still just a web page. This walkthrough is the smallest useful one: load the library, initialize, show the active workbook, and update when that workbook (or its active sheet) changes.

The type of extension comes from the .trex (<workspace-extension>), not from a special initializeAsync() argument. <entry-points> add the authoring toolbar button and the authoring menu item. Both open a side pane. The Hello World manifest is on Get Started with Workspace Extensions.

<entry-points>
<authoring-toolbar region="primary">
<label resource-id="name"/>
<on-click><side-pane/></on-click>
</authoring-toolbar>
<authoring-menu>
<label resource-id="name"/>
<on-click><side-pane/></on-click>
</authoring-menu>
</entry-points>

The web page​

Same pattern as other Tableau extensions — an HTML page that links the Extensions API library.

<!DOCTYPE html>
<html>
<head>
<!-- Tableau Extensions API library -->
<!-- <script src="https://tableau.github.io/extensions-api/lib/tableau.extensions.1.latest.js"></script> -->
<script src="./tableau.extensions.1.latest.js"></script>
<script src="workspace-extension.js"></script>
</head>
<body>
<h1>Workspace Extension Example</h1>
<div id="status">Initializing...</div>
<div id="workbook-info"></div>
</body>
</html>

Initialize​

Same initializeAsync() entry point as dashboard and viz extensions. You do not pass { context: 'workspace' }. Optional context-menu callbacks ({ configure: fn }) work the same way as for other extensions if your manifest includes <context-menu>.

(async () => {
await tableau.extensions.initializeAsync();
document.getElementById('status').textContent = 'Ready!';
})();

Read the active workbook​

After init, use tableau.extensions.workspaceContent. The active workbook is a property, not a getter. There might not be one — that's normal.

const workspaceContent = tableau.extensions.workspaceContent;

const updateWorkbookInfo = () => {
const workbook = workspaceContent.workbook;
const infoDiv = document.getElementById('workbook-info');

if (workbook) {
const sheet = workbook.activeSheet;
const sheetLabel = sheet ? ` (${sheet.name})` : '';
infoDiv.textContent = `Current workbook: ${workbook.name}${sheetLabel}`;
} else {
infoDiv.textContent = 'No workbook open';
}
};

updateWorkbookInfo();

When a workbook is open, workbook exposes name, sheets, and activeSheet. Each sheet in sheets has a name, a sheetType, an optional url, and an optional stable id. activeSheet is a full sheet: a worksheet, a dashboard, or a story. Filters, parameters, and sheet events are on that object.

Listen for workbook and sheet changes​

The extension outlives any one workbook. Listen on workspaceContent so your UI stays in sync. Every running workspace extension receives these events.

One event covers workbook open, close, and switch: tableau.TableauEventType.WorkbookChanged ("workbook-changed"). event.workbook is missing when nothing is open. A second event, tableau.TableauEventType.ActiveSheetChanged ("active-sheet-changed"), fires when the active sheet in that workbook changes. Both events include the workbook. event.sheetName is the new active sheet's name. workspaceContent.workbook is already updated when your listener runs.

workspaceContent.addEventListener(tableau.TableauEventType.WorkbookChanged, (event) => {
console.log('Workbook changed:', event.workbook ? event.workbook.name : '(none)');
updateWorkbookInfo();
});

workspaceContent.addEventListener(tableau.TableauEventType.ActiveSheetChanged, (event) => {
console.log('Active sheet:', event.sheetName);
updateWorkbookInfo();
// Read workbook.activeSheet again and re-bind sheet listeners.
// The previous Sheet is no longer the active one.
});

Settings​

Use the shared tableau.extensions.settings namespace (not workspaceContent.settings). Dashboard and viz settings are saved with the workbook. Workspace settings are scoped to the extension, so they survive opening a different workbook.

tableau.extensions.settings.set('lastUsed', Date.now().toString());
await tableau.extensions.settings.saveAsync();

tableau.extensions.environment and tableau.extensions.ui are also available.