Select Marks in the View

You can use the Embedding API v3 to select marks or to get the marks in a view that the user has selected. From the marks selected, you can also access the marks data and create interactive experiences.

In this section

• Import the SelectionUpdateType and other classes you need
• Select marks in the worksheet
  • Specify dates for selected marks
• Get data from selected marks in the worksheet
• Get marks data from a mark selection change event
• What’s next

Import the SelectionUpdateType and other classes you need

Be sure to import the classes you need in your JavaScript. For example, include SelectionUpdateType so that you can use the enums for replacing, adding, or removing the selected marks from the view.

<script type="module">
    // SelectionUpdateType is an enum for specifying the selection type for the select marks api.
    // TableauEventType represents the type of Tableau embedding event that can be listened for.
    import { SelectionUpdateType, TableauEventType } from "https://public.tableau.com/javascripts/api/tableau.embedding.3.latest.js";

    // code goes here....

</script>  

Select marks in the worksheet

Using the Embedding API v3 to select marks is another way to filter a view. For filtering, you use one of the worksheet apply filter methods (applyFilterAsync, applyHierarchicalFilterAsync, etc.). To select marks, you use the Worksheet.selectMarksByValueAsync method. The parameters for mark selection are similar to those used for filtering. The SelectionCriteria parameter maps the fieldName to values for hierarchical-, categorical-, and range-based selections.

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

// assumes this code is in an async function 
await worksheet.selectMarksByValueAsync([{
    fieldName: 'State',
    value: ['Texas', 'Washington', 'California']
}], SelectionUpdateType.Replace );

Specify dates for selected marks

You can specify dates for the marks selection, using the fieldName and value pair. The following examples shows how you could specify a date range for the marks. To specify a single day, provide the same value for the min and max values.

await worksheet.selectMarksByValueAsync([{
  fieldName: 'Report Date',
  value: {
    min: "2022-01-19",
    max: "2022-01-19",
  }
}], SelectionUpdateType.Replace);

You can also specify the dates using UTC values. The following example shows how you could use Date.UTC() method to create the date range for the selected marks.

await worksheet.selectMarksByValueAsync([{
  fieldName: 'Report Date',
  value: {
    min: new Date(Date.UTC(2020, 5, 1)),
    max: new Date(Date.UTC(2020, 5, 26)),
  }
}], SelectionUpdateType.Add);

Get data from selected marks in the worksheet

To get the selected marks in a worksheet, you call the Worksheet.getSelectedMarksAsync method. The method returns a MarksCollection, which contains the collection of data tables that represent the marks selected. Each row in a data table represents a single mark on the view.

// assumes you have the viz object
// assumes this code is in an async function 

let vizActiveSheet = viz.workbook.activeSheet;
if (vizActiveSheet.sheetType === "worksheet") {
   // Call to get the selected marks for the worksheet
   let selectedMarks = await vizActiveSheet.getSelectedMarksAsync();
   // Get the first DataTable for our selected marks (usually there is just one)
   const marksDataTable = selectedMarks.data[0];
   // Map the data into a format for display, etc.
   console.log(marksDataTable);
}

Get marks data from a mark selection change event

The following code snippets show how you might get the mark selection data when a mark selection change occurs. When a user selects marks in a view, the event is raised.

1. Add an event listener. You first need to add an event listener and provide an event handler for the MarkSelectionChanged event. The following specifies that the getSelectedMarks() function is the event handler.

   
    // assumes you have the viz object  
    viz.addEventListener(TableauEventType.MarkSelectionChanged, getSelectedMarks);
   
   

2. Create the event handler. The event payload contains the MarksSelectedEvent in the event.detail. Use the event.detail to call the getMarksAsync method. The method returns the MarksCollection. From the MarksCollection you can retrieve the data from the DataTable for the selected marks.

    async function getSelectedMarks(event) {
        const marksSelected =  await event.detail.getMarksAsync();
        // Get the first DataTable for our selected marks (usually there is just one)
        const marksData = marksSelected.data[0].data;
        // Map the data into a format for display, etc.
        console.log(marksData); 
    }
   
   

What’s next

To see sample code that shows uses the selectMarksByValueAsync method, see the Select Data sample on GitHub (embedding-api-v3-samples).