Adds a new event listener to the object. If this object does not support the specified eventType,
the method throws an exception.
The following table shows the event types supported by objects.
| object | eventType |
|---|---|
| Worksheet | FilterChanged , MarkSelectionChanged, SummaryDataChanged |
| Parameter | ParameterChanged |
| Settings | SettingsChanged |
| Dashboard | DashboardLayoutChanged, WorkbookFormattingChanged |
The type of event to register for. The type of event is a TableauEventType enumeration.
The function which will be called when an event happens.
A helper function which can be called to remove this registration.
The following example sets up a listener in a worksheet for a mark selection event (MarkSelectionChanged).
When the event occurs, the data is reloaded. The addEventListener method returns a function that un-registers
the event handler. Call that function, in this case, unregisterEventHandlerFunction() to remove the registration.
// Add an event listener for the selection changed event on this sheet.
// Assigning the event to a variable just to make the example fit on the page here.
const markSelection = tableau.TableauEventType.MarkSelectionChanged;
//
unregisterEventHandlerFunction = worksheet.addEventListener(markSelection, function (selectionEvent) {
// When the selection changes, reload the data
loadSelectedMarks(worksheetName);
});
// remove the event listener when done
unregisterEventHandlerFunction();
Add an annotation to the specified mark. This is intended to be passed a MarkInfo object received from a DataTable. MarkInfo can be found in the DataTable returned from getSelectedMarksAsync or getHighlightedMarksAsync.
The mark to annotate.
The text to display in the annotation.
Empty promise that resolves when the annotation is complete.
Applies the list of provided categorical filter values.
The name of the field to filter on.
The list of values to filter on.
The update type of this filter (add, all, remove, replace).
Advanced filter options (isExcludeMode).
The field name that the filter is applied on.
Applies the list of provided hierarchial filter values.
The name of the field to filter on.
The list of values or levels to filter on.
The update type of this filter (add, all, remove, replace).
The field name that the filter is applied on.
Applies a range filter to a quantitative or date field.
The name of the field to filter on
Filter Options: min, max, nullOption. At least one of of min and max is required.
For applying date filters, UTC Date objects are expected (that is, var min = new Date(Date.UTC(1999, 0, 1))).
The field name that the filter is applied on.
Applies a relative date filter.
The name of the field to filter on.
The relative date filter options (anchorDate, periodType, rangeType, rangeN). When the rangeType is LASTN or NEXTN, the rangeN is required.
The field name that the filter is applied on.
Resets existing filters on the given field. Categorical filters are reset to "All," and range filters are reset to the full range Relative date filters can not be reset, consider using the applyRelativeDateFilterAsync API.
The name of the field to clear filter on.
The field to clear filter on.
Clears selected marks in the current worksheet.
Empty promise that resolves when the selection has been cleared.
The following example assumes that you have some marks already selected in the worksheet. After it has run, you should have no marks selected, and you should see the console message.
worksheet.clearSelectedMarksAsync().then(function () {
console.log('Your marks selection has been cleared!');
})Searches for a parameter with the given name.
The name of the parameter to find.
The parameter with the given name, or undefined if it does not exist.
Retrieves a list of the annotations in the worksheet.
A list annotations in the worksheet.
Gets the data sources for this worksheet. Note that calling this method might negatively impact performance and responsiveness of the viz that your extension is added to. The method is not entirely asynchronous and includes some serial operations.
The primary data source and all of the secondary data sources for this worksheet. By convention the first data source in the array is the primary.
The following example shows how you might find a specific data source of a worksheet,
using the getDataSourcesAsync() method. The example then chains the data source returned in the promise
to a call to the getUnderlyingDataAsync() method to access the data table.
worksheet.getDataSourcesAsync().then(datasources => {
dataSource = datasources.find(datasource => datasource.name === "Sample - Superstore");
return dataSource.getUnderlyingDataAsync();
}).then(dataTable => {
// process the dataTable...
});
Gets the list of filters on a worksheet. Hierarchical filters are not yet supported
A promise that resolves to the collection of filters used in this worksheet.
Gets the data for the marks which are currently highlighted on the worksheet. If there are no marks currently highlighted, an empty model is returned.
The marks which are selected.
A collection of all the Tableau parameters that are used in this workbook.
Gets the data for the marks which are currently selected on the worksheet. If there are no marks currently selected, an empty model is returned.
The marks that are selected.
// Call to get the selected marks for the worksheet
worksheet.getSelectedMarksAsync().then(function (marks) {
// Get the first DataTable for our selected marks (usually there is just one)
const worksheetData = marks.data[0];
// Map the data into a format for display, etc.
});Gets the columns that are returned with getSummaryDataAsync.
The array of columns that describe the data in the worksheet.
Gets the summary data table for this worksheet. Warning: getSummaryDataAsync can fail with a worksheet with many rows of data and is now deprecated.
Collection of options to change the behavior of the call.
A data table containing the summary data for the worksheet.
Gets a summary data table reader for this worksheet. Only one active DataTableReader for summary data is supported.
Note: The getSummaryDataAsync and getSummaryDataReaderAsync methods return the data that is currently
in the viz, with parameters, calculated fields, and sorting applied. To access full data, that is
the underlying data without the additional fields and processing you have added in Tableau, use
the Worksheet.getUnderlyingTableDataAsync and Worksheet.getUnderlyingTableDataReaderAsync methods.
The number of rows per page. The default and maximum is 10,000 rows.
Collection of options to change the behavior of the reader.
A data table reader to access the summary data for the worksheet.
The following example shows the methods to get and use the summary data reader for all rows in a worksheet.
const dataTableReader = await worksheet.getSummaryDataReaderAsync();
for (let currentPage = 0; currentPage < dataTableReader.pageCount; currentPage++) {
let dataTablePage = await dataTableReader.getPageAsync(currentPage);
// ... process current page ....
}
await dataTableReader.releaseAsync();Gets the underlying data table for this worksheet.
Collection of options to change the behavior of the call.
A data table containing the underlying data for the worksheet.
Gets the underlying data table for the given logical table id.
Use the getUnderlyingTablesAsync method to identify the logical tables.
logical table id.
Collection of options to change the behavior of the call.
A data table containing the underlying data for the given logical table id
Gets a underlying data table reader for the given logical table id.
Use the getUnderlyingTablesAsync method to identify the logical tables.
Only one active DataTableReader per logical table id is supported.
Note: Use the getUnderlyingTableDataReaderAsync method to access the full data, that is
the underlying data without the parameters, calculated fields, and processing you might
have added in Tableau. To access just the data that is currently in the viz, with parameters,
calculated fields, and sorting applied use the Worksheet.getSummaryDataAsync and
Worksheet.getSummaryDataReaderAsync methods.
The getUnderlyingTableDataReaderAsync method attempts to prepare all the rows of the underlying table to be read as pages.
However, there is a limit to the number of rows that can be prepared. The default limit is 1 million rows of data.
You can change the default limit with the Tableau Server (Cloud) or Tableau Desktop option: ExtensionsAndEmbeddingReaderRowLimit.
If the underlying table has many columns, getUnderlyingTableDataReaderAsync can be sped up by only requesting
native data values in the GetUnderlyingDataOptions.
logical table id.
The number of rows per page. The default and maximum is 10,000 rows.
Collection of options to change the behavior of the reader.
A data table reader to access the underlying data for the given logical table id.
The following example shows getting the first page of underlying data.
// Call to get the underlying logical tables used by the worksheet
const underlyingTablesData = await worksheet.getUnderlyingTablesAsync();
const logicalTableId = underlyingTablesData[0].id;
// Use the above logicalTableId to get the underlying data reader on the active sheet
const dataTableReader = await worksheet.getUnderlyingTableDataReaderAsync(logicalTableId);
const page = await dataTableReader.getPageAsync(0);
// ... process first page of data table ...
await dataTableReader.releaseAsync();Gets the underlying logical tables used by the worksheet. The resulting logical tables are determined by the measures in the worksheet. If a worksheet's data source contains multiple logical tables and the worksheet contains only measures from one logical table, this API will return one logical table.
An array of logical tables corresponding to the measures referenced by the worksheet.
// Call to get the underlying logical tables used by the worksheet
worksheet.getUnderlyingTablesAsync().then(function (logicalTables) {
// Get the first logical table's id
const logicalTableId = logicalTables[0].id;
// Use the above logicalTableId to then get worksheet's underlying data
// by calling worksheet.getUnderlyingTableDataAsync(logicalTableId)
});Returns the visual specification for the worksheet, which can be used to get the mappings from fields to encodings backing the visual within the worksheet
Promise containing the VisualSpecification
Removes the corresponding annotation from the worksheet it belongs to. This is intended to be passed a Annotation object received from getAnnotationsAsync.
The annotation to remove.
Empty promise that resolves when the annotation is removed.
Removes an event listener if a matching one is found. If no matching listener exists, the method does nothing.
The handler function must the handler function specified in the call to the addEventListener method. Alternatively, use the function
returned from the call to addEventListener to unregister the event listener.
For more information, see Events and Event Handling.
Whether or not an event listener was removed.
Selects the marks specified by value using the SelectionCriteria interface. This is intended for manual construction of the desired selections.
A list of criteria for which marks to select.
The type of selection to make: add, remove, or replace.
Empty promise that resolves when the selection is complete.
Method to execute hover actions and render tooltip for a given tuple representing a mark in the visualization. If the tooltip parameter is included it will show the tooltip when the mark is hovered over. If not, no tooltip is shown.
Passing in an invalid tuple id will not throw and will clear the tooltip.
svg.on('mousemove', (mouseEvent) => {
const myHoveredTuple = 10;
tableau.extensions.worksheetContent.worksheet.hoverTupleAsync(myHoveredTuple, { tooltipAnchorPoint: { x: mouseEvent.pageX, y: mouseEvent.pageY } })
.then(() => console.log('Done'))
.catch((error) => console.log('Failed to hover because of: ', error));
});Returns empty promise that resolves when the extension host has successfully been informed of the request and rejects on error
Method to modify selection, execute select actions, and render tooltip for a given list of tuples representing a mark or marks in the visualization. If the tooltip parameter is included it will show the tooltip when the mark or marks are selected. If not, no tooltip is shown.
Passing in an invalid tuple id will not throw and will clear the tooltip.
svg.on('click', (mouseEvent) => {
const myClickedTuples = [10];
const ctrlKeyPressed = !!mouseEvent.ctrlKey;
const selectOption = ctrlKeyPressed ? tableau.SelectOptions.Toggle : tableau.SelectOptions.Simple;
tableau.extensions.worksheetContent.worksheet.selectTuplesAsync(myClickedTuples, selectOption, { tooltipAnchorPoint: { x: mouseEvent.pageX, y: mouseEvent.pageY } })
.then(() => console.log('Done'))
.catch((error) => console.log('Failed to select because of: ', error));
});Returns empty promise that resolves when the extension host has successfully been informed of the request and rejects on error
The name of the sheet.