Tableau JavaScript API Help

The Tableau JavaScript API uses an object model. The entry point into the object model is to instantiate a new Viz object as follows:

var viz = new tableau.Viz( /* params omitted */ );

For most Tableau objects you can navigate back to the object's parent by means of parent properties.

Create a Viz Object

There is only one entry point into the API: instantiating a new Viz object, which creates the HTML necessary to embed a Tableau visualization. To instantiate a new Viz object, call the Viz constructor and pass a reference to the div container on the HTML page, the URL of the visualization on Tableau Server, and a set of options.

var placeholderDiv = document.getElementById("tableauViz");
var url = "http://my-server/views/my-workbook/my-view";
var options = {
   hideTabs: true,
   width: "800px",
   height: "700px",
   onFirstInteractive: function() {
     // The viz is now ready and can be safely used.
   }
};
var viz = new tableau.Viz(placeholderDiv, url, options);

Get the visualization URL

Not sure where to get the visualization URL? Navigate to your visualization on Tableau Server and then edit the URL from this:

http://my-server/#/views/my-workbook/my-view

To this:

http://my-server/views/my-workbook/my-view

If you do not remove the # symbol from the URL, you might see the following browser error:
Refused to display 'http://my-server/#/views/my-workbook/my-view' in a frame because it set 'X-Frame-Options' to 'SAMEORIGIN'.

Specify Options

When you initialize a Viz object, you can pass options that specify how the view is initially rendered. The following list describes some of the some of the types of options that you can specify:

• Set a width and height for the visualization.
• Show or hide the toolbar and tabs.
• Apply filters.
• Call a callback function when the visualization becomes interactive or when the width and height are known.

For a full reference of the options that you can specify, see the VizCreateOptions record of the Viz constructor.

Copy (Clone) an Existing Instance

When you initialize a Viz object, you can specify that the new instance should be copied (cloned) from an existing instance. This is useful if a user is working with a visualization but wants to try some new options or filters without affecting the state of the original visualization.

To clone an instance, you specify the instanceIdToClone option in the VizCreateOptions record for the Viz constructor. The cloned instance is assigned a new ID. The following example shows how you can use this option.

function clone(instanceId) {
    var url = "http://MY-SERVER/views/clone/demo";
    var newVizElement = $('<div class="viz-container"><button>Clone</button></div>')
               .appendTo('.content');

    var viz = new tableau.Viz(newVizElement[0], url, {
      instanceIdToClone: instanceId,
      usePublishedSize: true,
      hideToolbar: true
    });

    newVizElement.find('button').click(function() { clone(viz.getInstanceId())});
  }
  $(function() {
    clone(0);
  });

Get Notification When the Viz Object is Ready

One of the options you can pass when you instantiate a Viz object is the onFirstInteractive parameter. This parameter references a callback function that's invoked when the Viz object has finished instantiating. This is an asynchronous callback, so your code can continue to run while the Viz object is instantiating.

The state of the Viz object is not valid until after the onFirstInteractive function is called. If you want to perform operations on the Viz object that require it to be fully initialized (for example, counting the number of sheets in the workbook), run your code after the onFirstInteractive callback has been invoked, like this:

var viz;
var options = {
  hideTabs: true,
  onFirstInteractive: function () {
    var sheetCount = viz.getWorkbook().getPublishedSheetsInfo().length;
};
viz = new tableau.Viz(div, url, options); 

Some operations that you might do with the Viz object do not require it to be completely initialized, such as adding event listeners to a Viz object. In those cases, you don't need to wait until the onFirstInteractive callback in order to run code to add the listeners. The following example shows code that adds a listener for the event that occurs when marks are selected. Notice that the code can run right after the Viz object initialization code, and doesn't need to be in the onFirstInteractive function.

var viz = new tableau.Viz(...);
viz.addEventListener(tableau.TableauEventName.MARKS_SELECTION, function (e) {
  // do something with the marks
});