Add Event Listeners

You can use event listeners to create actions based on events that happen with the view. The event listener registers a callback handler, that handler method gets called when an event occurs.

The viz object acts as the central event hub. This way you only have to go to one place for all events. It also means that events can be raised on an object that might not have been created yet. For example, the MarkSelectionChanged event can be raised for a particular sheet even though the sheet object hasn’t been created yet. Each event contains an anonymous object with information relating to that event, such as the sheet the event occurred on.

Listening to an event is done by calling viz.addEventListener(type, callback) and passing in a callback function. Here’s an example of listening to an event, where the name of the custom function is handleFirstInteractive(). You would define this function in your JavaScript code:

      const tableauViz = document.getElementById('tableauViz');
      tableauViz.addEventListener(TableauEventType.FirstInteractive, handleFirstInteractive);

There is an even easier way to add an event listener by adding an attribute to the <tableau-viz> or <tableau-authoring-viz> web component. Both of these methods are described in the following section.

In this section

• Supported events
• Using simplified event handling
• Add an event listener using the addEventListener() method
• Remove an event listener
• Add an event listener after the viz is first loaded

Supported events

The Embedding API supports the following event types (TableauEventType). The type of event you can listen for depends upon whether you’re embedding a view (using a <tableau-viz> web component or TableauViz object, for example) or embedding web authoring (using a<tableau-authoring-viz> web component or TableauAuthoringViz object). Some events are available when you’re embedding a view in viewing mode. Others apply only for embedded web authoring. And some apply to both viewing and authoring.

Note Use the TableauEventType enum (for example, TableauEventType.MarkSelectionChanged) when you add or remove the event listener using the Tableau Embedding API and the addEventListener and removeEventLister methods.

Using simplified event handling

Starting in Embedding API v3 (version 3.3), you can link your custom event handler to an event declaratively in the <tableau-viz> or <tableau-authoring-viz> web component by specifying the event type attribute.

The following example calls a JavaScript function to handle the onMarkSelectionChanged event. When a onMarkSelectionChanged event occurs, the handleMarksSelection() event handler is called. You define the event handler in your JavaScript code.

  ...

<tableau-viz id="tableauViz"
    src="http://my-server/views/my-workbook/my-view"
    onMarkSelectionChanged="handleMarksSelection">
</tableau-viz>

...

The following example shows a web authoring component that adds an event listener to handle a published event.

  ...

<tableau-authoring-viz id="tableauAuthoringViz"
    src="http://my-server/views/my-workbook/my-view"
    onWorkbookPublished="handleWorkbookPublish">
</tableau-authoring-viz>

...

Before v3.3, you could only configure an event listener in JavaScript using the addEventListener method. The event type attribute makes it easy to add custom event handlers.

Add an event listener using the addEventListener() method

1. Get the viz object.

2. Add the event listener by calling addEventListener and specifying the type of event and the callback method to call. The name of the event must be one of the supported types defined in the TableauEventType enumeration. The callback method must handle the event object raised.

   
    async function getSelectedMarks(event) {
        const marksSelected = await event.detail.getMarksAsync();
        const numMarks = marksSelected.data[0].data.length;
        console.log(`${numMarks} marks Selected`);
    }
   
    let viz = document.getElementById('tableauViz');
    viz.addEventListener(TableauEventType.MarkSelectionChanged, getSelectedMarks);
   
   

Remove an event listener

1. Get the viz object.
2. Remove the event listener from the specified event using the

3. Remove the event listener by using the removeEventListener method and specifying the name of your event handler. For example, to remove the event handler for the TableauEventType.MarkSelectionChanged event called, getSelectedMarks you might use something like the following:

    
    let viz = document.getElementById('tableauViz');
    viz.removeEventListener(TableauEventType.MarkSelectionChanged, getSelectedMarks);
   
   

Add an event listener after the viz is first loaded

In some cases you might want to take actions right after the view is first loaded. For example, you might want to set the filtering or perform some other customization for the person who is viewing the embedded viz. You can do this by adding an event listener on TableauEventType.FirstInteractive event type. In addition, you can wrap the call in a window.onload event handler, so that your FirstInteractive event is called after all the dependent resources have been loaded.

window.onload = function () {
   let viz = document.getElementById('tableauViz');

    viz.addEventListener(TableauEventType.FirstInteractive, async (event) => {
        console.log(`Event type is ${eventType}`);
        // call methods to run immediately after loading
    
     });
}