The Embedding API v3 provides a rich set of properties that you can apply to the embedding view or embedded web authoring view. These properties can control the device layout and dimensions of the view, or whether buttons and the toolbar are hidden or visible.
You can set properties during initialization, or later interactively, by accessing the JavaScript TableauViz
or TableauAuthoringViz
object.
In this section
TableauViz
and TableauAuthoringViz
objects and components
TableauViz
and TableauAuthoringViz
objects and componentsTo configure the embedded viz, you can use a set of HTML attributes on the <tableau-viz>
and
<tableau-authoring-viz>
web components, or as JavaScript (JS) properties on the corresponding
TableauViz
and TableauAuthoringViz
JavaScript objects. For HTML attributes that accept a value,
such as width
, height
, and device
, the syntax is <property>="<value>"
.
For Boolean properties, such as hide-tabs
, hide-close-button
, or disable-url-actions
, you can either include the
flag to effectively set it to true, or omit it to effectively set it to false. Note that the values of Boolean
properties are ignored. For example, if you were to add hide-tabs="false"
, this actually sets the hide-tabs
value to true, because the presence of the attribute sets it to true even if the value is false.
Some attributes and properties apply to both embedded views and embedding authoring views.
<tableau-viz>
component configurationsThe following example shows how you can specify options to initialize the viz by setting attributes
on the <tableau-viz>
element:
<tableau-viz id="tableauViz"
src="https://my-server/views/my-workbook/my-view"
device="phone" toolbar="bottom" hide-tabs>
</tableau-viz>
<tableau-authoring-viz>
component configurationThe following example shows how you can specify options to initialize the viz by setting attributes
on the <tableau-authoring-viz>
element:
<tableau-authoring-viz id="authoringViz"
src='https://my-server/views/my-workbook/my-view'
width="800" height="600">
</tableau-authoring-viz>
The following table lists the properties you can add to the <tableau-viz>
and
<tableau-authoring-viz>
web components, or as JavaScript (JS) properties on the corresponding
TableauViz
and TableauAuthoringViz
JavaScript objects.
HTML Property | JS Property | Accepted Values | Description | Applies to |
---|---|---|---|---|
src | Viz.src | string | Specifies the URL of the view. For security, alway use HTTPS when you specify the URL. | <tableau-viz> , <tableau-authoring-viz> |
hide-tabs | Viz.hideTabs | boolean | Indicates whether tabs are hidden or shown. | <tableau-viz> |
toolbar | Viz.toolbar | “top”, “bottom”, “hidden” | Indicates the position of the toolbar or if it should be hidden | <tableau-viz> |
height | Viz.height | (e.g. “800px”) | Can be any valid CSS size specifier. If not specified, defaults to the published height of the view. See Size of the embedded view. | <tableau-viz> , <tableau-authoring-viz> |
width | Viz.width | (e.g. “800px”) | Can be any valid CSS size specifier. If not specified, defaults to the published width of the view. See Size of the embedded view. | <tableau-viz> , <tableau-authoring-viz> |
device | Viz.device | “default”, “desktop”, “tablet”, or “phone” | Specifies a device layout for a dashboard, if it exists. If not specified, defaults to loading a layout based on the smallest dimension of the hosting iframe element. |
<tableau-viz> |
instance-id-to-clone | Viz.instanceIdToClone | Specifies the ID of an existing instance to make a copy (clone) of. This is useful if the user wants to continue analysis of an existing visualization without losing the state of the original. If the ID does not refer to an existing visualization, the cloned version is derived from the original visualization. | <tableau-viz> |
|
disable-url-actions | Viz.disableUrlActions | boolean | Indicates whether to suppress the execution of URL actions. This option does not prevent the URL action event from being raised. | <tableau-viz> |
hide-close-button | Viz.hideCloseButton | boolean | Indicates whether the Close button is shown or hidden. If not specified, defaults to false (the button is shown). This property also includes the “File/Close” menu item. |
<tableau-authoring-viz> |
hide-edit-button | Viz.hideEditButton | boolean | Indicates whether the Edit button is shown or hidden. If not specified, defaults to false (the button is shown). |
<tableau-viz> |
hide-edit-in-desktop-button | Viz.hideEditInDesktopButton | boolean | Indicates whether the Edit in Desktop button is shown or hidden. If not specified, defaults to false (the button is shown). |
<tableau-viz> , <tableau-authoring-viz> |
suppress-default-edit-behavior | Viz.suppressDefaultEditBehavior | boolean | Indicates whether the default edit behavior should be suppressed. If not specified, defaults to false (the default edit behavior is preserved). When set to true, this property suppresses what is normally done when the Close button, Edit button, or Edit in Desktop buttons are clicked. |
<tableau-viz> , <tableau-authoring-viz> |
Note: When adding properties to the
<tableau-viz>
or<tableau-authoring-viz>
components, use the HTML Property name. Use the JS Property names for theTableauViz
andTableauAuthoringViz
objects.
<tableau-viz>
web componentIn addition to the attributes shown in the table for the web components, you can also apply a <viz-filter>
element to the <tableau-viz>
web component to filter the view during initialization. The <viz-filter>
element has two attributes: the field
and its value
. For more information, see Filter during initialization.
<tableau-viz>
web componentIn addition to the attributes shown in the table for the <tableau-viz>
web component, you can also apply a <viz-parameter>
element to the web component during initialization. The <viz-parameter>
element has two attributes: the name
and its value
. The parameter settings take effect at start up. Additionally, the Embedding API v3 library supports the methods Workbook.getParametersAsync()
and Workbook.changeParameterValueAsync()
. For more information, see Use Parameters in Embedded Views.
<tableau-viz>
, <tableau-authoring-viz>
, and <tableau-ask-data>
web componentsIn addition to the attributes shown in the table for the <tableau-viz>
and <tableau-authoring-viz>
web components, you can also apply a <custom-parameter>
element to the web component during initialization. You can also use custom parameters when you are embedding Ask Data. The <custom-parameter>
element allows you to pass parameters to the viz that aren’t supported by the Embedding API, but are supported in Tableau. The <custom-parameter>
has two attributes: the name
and its value
. The parameter settings take effect at start up. The custom parameters can be used to add URL parameters, as listed under Embed Code Parameters for Views. For more information, see Use Parameters in Embedded Views.
The height and width of the embedded view is determined in the following order:
By the height
and width
attributes set on the <tableau-viz>
or <tableau-authoring-viz>
components, or corresponding properties on the TableauViz
and TableauAuthoringViz
objects.
If not specified, the size (width and height) of the view is based upon the content area specified by the enclosing HTML element (for example <div>
or <body>
).
If the size of the content area specified by the HTML element is invalid (for example, height=0
), the default size of the view is 800 (width) by 600 (height) pixels.