Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface Worksheet

Hierarchy

Index

All Extensions Properties

name

name: string
returns

The name of the sheet.

sheetType

sheetType: SheetType
returns

The type of the sheet.

size

size: Size
returns

Size of the sheet.

Dashboard Extensions Properties

parentDashboard

parentDashboard: Dashboard
returns

The dashboard object to which this worksheet belongs.

All Extensions Methods

addEventListener

  • 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

    Parameters

    • eventType: TableauEventType

      The type of event to register for. The type of event is a TableauEventType enumeration.

    • handler: TableauEventHandlerFn

      The function which will be called when an event happens.

    Returns TableauEventUnregisterFn

    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();
    

annotateMarkAsync

  • annotateMarkAsync(mark: MarkInfo, annotationText: string): Promise<void>
  • 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.

    since

    1.10.0 and Tableau 2022.4

    The following example shows how you might call this method using a MarkInfo object.

       const markCollection = await worksheet.getSelectedMarksAsync();
       const markToAnnotate = marksCollection.data[0].marksInfo[0];
       await worksheet.annotateMarkAsync(markToAnnotate, 'Manufacturing line #2 shutdown triggered');

    Parameters

    • mark: MarkInfo

      The mark to annotate.

    • annotationText: string

      The text to display in the annotation.

    Returns Promise<void>

    Empty promise that resolves when the annotation is complete.

applyFilterAsync

  • Applies the list of provided categorical filter values.

    Parameters

    • fieldName: string

      The name of the field to filter on.

    • values: Array<string>

      The list of values to filter on.

    • updateType: FilterUpdateType

      The update type of this filter (add, all, remove, replace).

    • filterOptions: FilterOptions

      Advanced filter options (isExcludeMode).

    Returns Promise<string>

    The field name that the filter is applied on.

applyHierarchicalFilterAsync

  • Applies the list of provided hierarchial filter values.

    since

    1.10.0 and Tableau 2022.3

    Parameters

    • fieldName: string

      The name of the field to filter on.

    • values: Array<string> | HierarchicalLevels

      The list of values or levels to filter on.

    • updateType: FilterUpdateType

      The update type of this filter (add, all, remove, replace).

    • options: FilterOptions

    Returns Promise<string>

    The field name that the filter is applied on.

applyRangeFilterAsync

  • applyRangeFilterAsync(fieldName: string, filterOptions: RangeFilterOptions): Promise<string>
  • Applies a range filter to a quantitative or date field.

    since

    1.10.0 Errors will now be thrown for invalid fields or values.

    Parameters

    • fieldName: string

      The name of the field to filter on

    • filterOptions: RangeFilterOptions

      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))).

    Returns Promise<string>

    The field name that the filter is applied on.

applyRelativeDateFilterAsync

  • Applies a relative date filter.

    since

    version 1.9.0 and Tableau 2022.2

    The following example shows how to apply a relative date filter from a worksheet.

     worksheet.applyRelativeDateFilterAsync(
       'Order Date',
       {
         anchorDate: new Date(Date.UTC(2022, 4, 13)),
         periodType: PeriodType.Years,
         rangeType: DateRangeType.LastN,
         rangeN: 1,
       }
     );

    Parameters

    • fieldName: string

      The name of the field to filter on.

    • options: RelativeDateFilterOptions

      The relative date filter options (anchorDate, periodType, rangeType, rangeN). When the rangeType is LASTN or NEXTN, the rangeN is required.

    Returns Promise<string>

    The field name that the filter is applied on.

clearFilterAsync

  • clearFilterAsync(fieldName: string): Promise<string>
  • 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.

    Parameters

    • fieldName: string

      The name of the field to clear filter on.

    Returns Promise<string>

    The field to clear filter on.

clearSelectedMarksAsync

  • clearSelectedMarksAsync(): Promise<void>
  • Clears selected marks in the current worksheet.

    Returns Promise<void>

    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!');
       })

findParameterAsync

  • findParameterAsync(parameterName: string): Promise<Parameter | undefined>
  • Searches for a parameter with the given name.

    Parameters

    • parameterName: string

      The name of the parameter to find.

    Returns Promise<Parameter | undefined>

    The parameter with the given name, or undefined if it does not exist.

getAnnotationsAsync

  • getAnnotationsAsync(): Promise<Array<Annotation>>
  • Retrieves a list of the annotations in the worksheet.

    since

    1.10.0 and Tableau 2022.4

    The following example shows how you might call this method.

       let annotations = await worksheet.getAnnotationsAsync();
       console.log(annotations);

    Returns Promise<Array<Annotation>>

    A list annotations in the worksheet.

getDataSourcesAsync

  • getDataSourcesAsync(): Promise<Array<DataSource>>
  • 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.

    Returns Promise<Array<DataSource>>

    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...
    });
    

getFiltersAsync

  • getFiltersAsync(): Promise<Array<Filter>>
  • Gets the list of filters on a worksheet. Hierarchical filters are not yet supported

    Returns Promise<Array<Filter>>

    A promise that resolves to the collection of filters used in this worksheet.

getHighlightedMarksAsync

  • 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.

    Returns Promise<MarksCollection>

    The marks which are selected.

getParametersAsync

  • getParametersAsync(): Promise<Array<Parameter>>
  • Returns Promise<Array<Parameter>>

    A collection of all the Tableau parameters that are used in this workbook.

getSelectedMarksAsync

  • 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.

    Returns Promise<MarksCollection>

    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.
    
    });

getSummaryColumnsInfoAsync

  • getSummaryColumnsInfoAsync(): Promise<Array<Column>>
  • Gets the columns that are returned with getSummaryDataAsync.

    since

    1.5.0

    Returns Promise<Array<Column>>

    The array of columns that describe the data in the worksheet.

getSummaryDataAsync

  • Gets the summary data table for this worksheet. Warning: getSummaryDataAsync can fail with a worksheet with many rows of data and is now deprecated.

    deprecated

    since 1.10.0 Use getSummaryDataReaderAsync to avoid failures with many rows of data.


    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 following example shows how to replace unsafe usage of getSummaryDataAsync with getSummaryDataReaderAsync and getAllPagesAsync, assuming you have less than 4,000,000 rows of data.

    const dataTableReader = await worksheet.getSummaryDataReaderAsync();
    const dataTable = await dataTableReader.getAllPagesAsync();
    await dataTableReader.releaseAsync();
    // ... process data table ...

    The following example shows how to replace unsafe usage of getSummaryDataAsync with getSummaryDataReaderAsync and getPageAsync and work with individual pages.


    const dataTableReader = await worksheet.getSummaryDataReaderAsync();
    for (let currentPage = 0; currentPage < dataTableReader.pageCount; currentPage++) {
      const dataTablePage = await dataTableReader.getPageAsync(currentPage);
      // ... process current page ....
    }
    await dataTableReader.releaseAsync();

    Parameters

    Returns Promise<DataTable>

    A data table containing the summary data for the worksheet.

getSummaryDataReaderAsync

  • 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.


    Parameters

    • Optional pageRowCount: undefined | number

      The number of rows per page. The default and maximum is 10,000 rows.

    • Optional options: GetSummaryDataOptions

      Collection of options to change the behavior of the reader.

    Returns Promise<DataTableReader>

    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();

getUnderlyingDataAsync

getUnderlyingTableDataAsync

  • Gets the underlying data table for the given logical table id. Use the getUnderlyingTablesAsync method to identify the logical tables.

    since

    1.4.0


    Note: Use the getUnderlyingTableDataAsync 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.


    You can use the getUnderlyingDataOptions.maxRows property to request the number of rows of data to return. If unspecified (maxRows == '0'), the call to getUnderlyingTableDataAsync requests all rows in the logical table. Note that the maximum number of rows returned from the getUnderlyingTableDataAsync() method is limited to 10,000 rows. You can use the DataTable property, isTotalRowCountLimited, to test whether there is more data. A value of true indicates that the calling function requested more rows than the limit (10,000) and the underlying data source contains more rows than can be returned.

    since

    1.5.0 You can use the GetUnderlyingDataOptions.includeDataValuesOption property to optimize performance by restricting the properties included in the returned DataValues.

    see

    getUnderlyingTableDataReaderAsync to read more than 10,000 rows.

    const logicalTables = await worksheet.getUnderlyingTablesAsync();
    const dataTable = await worksheet.getUnderlyingTableDataAsync(logicalTables[0].id)
    // process the dataTable...

    Parameters

    • logicalTableId: string

      logical table id.

    • Optional options: GetUnderlyingDataOptions

      Collection of options to change the behavior of the call.

    Returns Promise<DataTable>

    A data table containing the underlying data for the given logical table id

getUnderlyingTableDataReaderAsync

  • 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.

    Parameters

    • logicalTableId: string

      logical table id.

    • Optional pageRowCount: undefined | number

      The number of rows per page. The default and maximum is 10,000 rows.

    • Optional options: GetUnderlyingDataOptions

      Collection of options to change the behavior of the reader.

    Returns Promise<DataTableReader>

    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();

getUnderlyingTablesAsync

  • 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.

    since

    1.4.0

    Returns Promise<Array<LogicalTable>>

    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)
    
    });

getVisualSpecificationAsync

  • 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

    since

    1.11.0 and Tableau 2024.1

    Returns Promise<VisualSpecification>

    Promise containing the VisualSpecification

removeAnnotationAsync

  • removeAnnotationAsync(annotation: Annotation): Promise<void>
  • Removes the corresponding annotation from the worksheet it belongs to. This is intended to be passed a Annotation object received from getAnnotationsAsync.

    since

    1.10.0 and Tableau 2022.4

    The following example shows how you might call this method using an annotation.

       for (const annotation of annotations) {
         await worksheet.removeAnnotationAsync(annotation);
       }

    Parameters

    • annotation: Annotation

      The annotation to remove.

    Returns Promise<void>

    Empty promise that resolves when the annotation is removed.

removeEventListener

  • 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.

    Parameters

    Returns boolean

    Whether or not an event listener was removed.

selectMarksByValueAsync

  • Selects the marks specified by value using the SelectionCriteria interface. This is intended for manual construction of the desired selections.

    since

    1.10.0 Errors will now be thrown for invalid fields or values.


    The following example shows how you might call this method using state names as the SelectionCriteria. The SelectionUpdateType is replace (tableau.SelectionUpdateType.Replace), so these values replace the marks that are currently selected.

       worksheet.selectMarksByValueAsync([{
            fieldName: 'State',
            value: ['Texas', 'Washington', 'California']
        }], tableau.SelectionUpdateType.Replace );
    

    Parameters

    Returns Promise<void>

    Empty promise that resolves when the selection is complete.

Viz Extensions Methods

getTooltipTextAsync

  • getTooltipTextAsync(tupleId: number): Promise<String>
  • Method to get the text of the tooltip that would be displayed for a given tuple id. Currently supported for web only.

    You can find the tuple id for a row of data by subtracting the index of the row from the total number of rows. For example, if you have 10 rows, and want to know the tuple id associated with the third row, it will be 7 (10 - 3 = 7). The last row of data will always have the tuple id of 1.

    Passing in an invalid tuple id will not throw.

    let navigatedTuple = -1;
    let updateScreenReaderElement = (screenReadertext) => {
      // updates an element to be read out by screen readers
    };
    
    let updateNavigatedTuple = (keyboardEvent) => {
      switch (keyboardEvent.key) {
        case 'ArrowLeft':
          navigatedTuple = navigatedTuple - 1;
          break;
        case 'ArrowRight':
          navigatedTuple = navigatedTuple + 1;
          break;
        default:
          break;
      }
      // do any work to show visual indication of a mark being navigated to
    };
    
    svg.on('keydown', (keyboardEvent) => {
      updateNavigatedTuple(keyboardEvent);
      tableau.extensions.worksheetContent.worksheet
        .getTooltipTextAsync(navigatedTuple)
        .then((response) => {
          console.log(response.result);
          updateScreenReaderElement(response.result);
        })
        .catch((error) => console.log('Failed to get tooltip text because of: ', error));
    });
    since

    1.12.0 and Tableau 2024.2

    Parameters

    • tupleId: number

    Returns Promise<String>

    Returns promise that resolves to a string describing the tooltip text for a given tuple id and rejects on error

hoverTupleAsync

  • hoverTupleAsync(hoveredTuple: number, tooltip?: TooltipContext | null, allowHoverActions?: undefined | false | true): Promise<void>
  • 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 null or no tooltip parameter is passed, no tooltip is shown. Hover actions are run by default, but passing false for the allowHoverActions parameter will prevent their execution.

    The hoveredTuple parameter is a tuple id. You can find the tuple id for a row of data by subtracting the index of the row from the total number of rows. For example, if you have 10 rows, and want to know the tuple id associated with the third row, it will be 7 (10 - 3 = 7). The last row of data will always have the tuple id of 1.

    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));
     });
    since

    1.12.0 and Tableau 2024.2

    Parameters

    • hoveredTuple: number
    • Optional tooltip: TooltipContext | null
    • Optional allowHoverActions: undefined | false | true

    Returns Promise<void>

    Returns empty promise that resolves when the extension host has successfully been informed of the request and rejects on error

leaveMarkNavigationAsync

  • leaveMarkNavigationAsync(): Promise<void>
  • Notifies the scene of a desire to leave mark-level keyboard navigation and return to scene-level keyboard navigation. Used when implementing keyboard navigation within a visualization, an integral part of building accessibility into a visualization. Currently supported for the web only.

    svg.on('keyup', (keyboardEvent) => {
      if (keyboardEvent.key == "Escape") {
        tableau.extensions.worksheetContent.worksheet
          .leaveMarkNavigationAsync()
          .then(() => console.log('Done'))
          .catch((error) => console.log('Failed to leave mark-level keyboard navigation because of: ', error));
      }
    });
    since

    1.12.0 and Tableau 2024.2

    Returns Promise<void>

    Returns empty promise that resolves when the extension host has successfully been informed of the request and rejects on error

selectTuplesAsync

  • 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.

    The selectedTuples parameter is an array of tuple ids. You can find the tuple id for a row of data by subtracting the index of the row from the total number of rows. For example, if you have 10 rows, and want to know the tuple id associated with the third row, it will be 7 (10 - 3 = 7). The last row of data will always have the tuple id of 1.

    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));
    });
    since

    1.12.0 and Tableau 2024.2

    Parameters

    Returns Promise<void>

    Returns empty promise that resolves when the extension host has successfully been informed of the request and rejects on error