Embedding Tableau Views with the vdl-tableau Component

Configuring the vdl-tableau component

The vdl-tableau component is available from the View Designer Palette in Xpress Workbench. It can also be directly added as code to the VDL source:

<vdl-tableau
      mirror-tables="mirror_data_1,mirror_data_2,factory_supply_demand"
      workbook="vdl_language"
      view="Factories"
      height="270">
</vdl-tableau>

The mirror-tables attribute is a comma-separated list of names matching those defined in the companion file. This attribute should be populated with the tables that the Tableau view requires to render.

The workbook attribute is the name of the Tableau workbook file (without file extension) containing the view to be embedded.

The view attribute is the case-sensitive name of the sheet or dashboard within the workbook.

The height attribute sets the height of the rendered Tableau view in pixels.

There are several other attributes available to configure the behaviour of the component. See the Javascript API Reference for more information.

The lifecycle of the vdl-tableau component

The vdl-tableau component is a container for the Tableau view and will render that view when all the pre-requisites are met. It also communicates the state of the system when the view is not yet able to be displayed.

When the system is deploying a new mirror database, updating its schema, or publishing workbooks then the vdl-component displays a system status message:

When the required data is being expanded into the mirror database, the vdl-component shows the message "Preparing Data…" and a scrollbar with its value proportional to the completed effort to mirror the data:

When the component is waiting for the Tableau Embedding API to initialize and has been waiting for more than 2 seconds, the component shows a 100% progress bar and the message "Preparing Visualization..."

When the data that the view is dependent on is invalidated by a change, the component shows a placeholder message. This is most apparent when the scenario is executing, and the system is waiting for the new scenario data before it can begin updating the mirror.

When the workbook and view attributes are empty, the vdl-tableau component displays the selection id. This id is essential to the development of new Tableau views as the data need to be filtered by this id to select the correct set of scenario data for the view under development in Tableau Desktop.

Note: Note: A component will always display the selection_id if the Server environment type is "development" and the URL has "?debug=true" added. The component will not display the selection_id if the Insight Server environment type is set to "production".

Positioning the Tableau component in a VDL view

By default, the Tableau visualization will display inline in the page content. You can control the height and width of the vdl-tableau component, or by default it will take the width of its container (for example a vdl-column of size 6 would be half the page). The default height is 400px, but you can change this to whatever suits your application. The example below sets the height of the vdl-tableau component to be 50vh, which is 50% of the overall view height (50vh).

<vdl-tableau
      workbook="vdl_language"
      view="Factories"
      mirror-tables="mirror_data_1,mirror_data_2,factory_supply_demand"
      height="50vh"
      width="270px"
></vdl-tableau>

The component can also be configured to occupy the entire width and height of the Web Client view by adding the "vdl-tableau-full-page" class to the component.

<vdl-tableau 
      workbook="vdl_language"
      view="Factories"
      mirror-tables="factory_supply_demand"
      scenarios="=scenarios"
      class="vdl-tableau-full-page">
</vdl-tableau>

Including multiple Tableau components in a VDL view

Multiple vdl-tableau components can be included in the same view and there are no special considerations. The example below duplicates a Tableau visualization for each scenario on the shelf:

<vdl-row vdl-repeat="=s,i in scenarios">
    <vdl-column size="10" heading="='Scenario: ' + s.props.name">
        <vdl-tableau workbook="vdl_language"
                     view="Factories"
                     scenarios="=i"
                     mirror-tables="mirror_data_1,mirror_data_2,factory_supply_demand"
                     height="270px"></vdl-tableau>
    </vdl-column>
</vdl-row>

Persisting and sharing visualization filter values between views

Tableau Global Filters are a feature provided by the Xpress Insight integration with Tableau. View developers can specify filters within a Tableau view as global. Global filter values are persisted per user between sessions, and applied to any other Tableau view that declares the same filter as global.

Global filters are declared with the global-filters attribute and consist of a comma separated list of Tableau filter names. Their values are stored in the local storage of the browser using the app id and user as their key. In cases where these need to be separated further within an app ( for example so two groups of Tableau view can have different values for the same filter), the storage-namespace attribute should be used to define a further element to add to the key.

There are some rules on what Tableau filters can be defined as global:

• Only String, Boolean and Numeric data types are supported. Tableau Global Filters using an unsupported data type will be ignored.
• Only categorical filters are supported. i.e., filters that are applied by selecting one or more values via a drop-down, radio button, check boxes or wildcard.
• When defining a Tableau Global Filter ensure that the selection criteria (single, multiple or wildcard) for the any displayed Tableau Quick Filter is the same for all views within the scope of the Tableau Global Filter. The Tableau Global Filter values are applied irrespective to the selection criteria of the Quick Filter as it is not possible for Xpress Insight to discover this from the view. For example on ViewA a Tableau Quick Filter is shown where a user can select multiple values. On ViewB the same Tableau Quick Filter is shown but the user can only select one value. If on ViewA the user changes the filtered values and selects multiple items and then moves to ViewB, the Tableau Quick Filter will only show one item selected in the Tableau Quick Filter but will filter based on the multiple items selected in ViewA.
• When defining a Tableau Global Filter ensure that any Tableau Quick Filters relating to a Tableau Global Filter shows all filter values and not just the filter values that relate to the data shown on the view. This is controlled via the Tableau 'Show More/Fewer' feature against a Quick Filter. As the Tableau Global Filter may act across several views it may cause confusion if a user cannot see exactly which filter values have been applied to the view.
• Care must be taken to avoid the situation where the combination of global filter values on one Tableau visualization eliminates those filter values as valid/available values for the global filters of another visualization on the same page. The system will not be able to achieve a consistent filter value across both visualizations.