Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface Worksheet

Hierarchy

Index

Properties

name

name: string
returns

The name of the sheet.

parentDashboard

parentDashboard: Dashboard
returns

The dashboard object to which this worksheet belongs.

sheetType

sheetType: SheetType
returns

The type of the sheet.

size

size: Size
returns

Size of the sheet.

Methods

addEventListener

  • Adds a new event listener to the object. If this object does not support the specified eventType, the method throws an exception. Note that you can't add an event listener to a dashboard. This is because the Dashboard object does not support any event types, even though the Dashboard object inherits the event listener methods from EventListenerManager. For more information, see Events and Event Handling. The following table shows the event types supported by objects.

    object eventType
    Worksheet FilterChanged , MarkSelectionChanged
    Parameter ParameterChanged
    Settings SettingsChanged
    Dashboard None available

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

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.

applyRangeFilterAsync

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

    Parameters

    • fieldName: string

      The name of the field to filter on

    • filterOptions: RangeFilterOptions

      Filter Options: min, max, nullOption. Atleast one of of min and max is required. For applying date filters, UTC Date objects are expected. (i.e., var min = new Date(Date.UTC(1999, 0, 1)))

    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 in the dashboard.

    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.

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.

    tableau.extensions.dashboardContent.dashboard.worksheets.find(w => w.name === "Sale Map").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.

    since

    1.5.0 You can use the GetSummaryDataOptions.maxRows property to request the number of rows of data to return. If unspecified, the call to getSummaryDataAsync requests all rows.

    since

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

    since

    1.5.0 You can specify the desired columns by field id with columnsToIncludeById.

    Example showing the method call to get the summary data from a worksheet.

    // After getting the worksheet,
     // get the summary data for the sheet
     worksheet.getSummaryDataAsync().then(function (sumdata) {
    
      const worksheetData = sumdata;
    
      // Map the worksheetData into a format for display, etc.
    
     });
    

    Parameters

    Returns Promise<DataTable>

    A data table containing the summary data for the worksheet.

getUnderlyingDataAsync

  • Gets the underlying data table for this worksheet.

    deprecated

    since version 1.4.0. Use Worksheet.getUnderlyingTableDataAsync.

    Parameters

    Returns Promise<DataTable>

    A data table containing the underlying data for the worksheet.

    You can use the GetUnderlyingDataOptions.maxRows property to request the number of rows of data to return. If unspecified (maxRows == '0'), the call to getUnderlyingDataAsync requests all rows in the data source. Note that the maximum number of rows returned from the getUnderlyingDataAsync() method is currently 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 current limit (10,000) and the underlying data source contains more rows than can be returned.

    In the following example, the getUnderlyingDataAsync() method is used to get the underlying data for a specific column in a workbook.

    tableau.extensions.dashboardContent.dashboard.worksheets.find(w => w.name === "Sale Map").getUnderlyingDataAsync().then(dataTable => {
      let field = dataTable.columns.find(column => column.fieldName === "State");
      let list = [];
      for (let row of dataTable.data) {
        list.push(row[field.index].value);
      }
      let values = list.filter((el, i, arr) => arr.indexOf(el) === i);
      console.log(values)
    });
    

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

    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 currently 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 current 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.

     var worksheet = tableau.extensions.dashboardContent.dashboard.worksheets.find(w => w.name === "Sale Map");
     worksheet.getUnderlyingTablesAsync().then(function (logicalTables) {
         worksheet.getUnderlyingTableDataAsync(logicalTables[0].id).then((dataTable) => {
           // 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

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

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 and returns them. This version selects by value, using the SelectionCriteria interface. This is intended for manual construction of the desired selections.

    Parameters

    Returns Promise<void>

    Empty promise that resolves when the selection is complete.

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