You can use parameters to add interactivity and flexibility to a view. A parameter is a Tableau workbook variable that can replace a constant value in a calculation, filter, or reference line. You can either apply parameters before a visualization has been loaded (at initialization) or after it has been rendered (interactively). The Embedding API provides methods for getting the parameters in a workbook and for changing parameter values. You can also set up event handlers to take action whenever a parameter change occurs (TableauEventType.ParameterChanged). You can set parameter values using the <tableau-viz> web components or using the TableauViz JavaScript object. The Tableau parameters (VizParameter attribute or <viz-parameter> element) can be set when you are embedding a view in viewing mode, but not when embedding a view in web authoring mode.
In addition to the parameters found in a Tableau workbook, you can add some custom parameters that get passed to the view. These custom parameters (CustomParameter or <custom-parameter>) provide attributes that are not officially supported by Embedding API, but are supported by Tableau Server and Tableau Cloud. Only a specific set of custom parameters can be used. For more information, see About custom parameters.
In this section
When you set parameter values, either during initialization or after the view has loaded, the value you specify for a parameter must fall within the allowable values defined for the parameter. If the new value is out of range, the updated value will be set to either the minValue or the maxValue of the allowable range. If a step size is also specified and the new value does not fall on the step intervals, the updated value will be set to the closest, lower step, or closest, earlier date. If the domain restriction is type ParameterValueType.List, and there are aliases defined for the list, the aliased value should be specified.
For more information about parameter values, see Create Parameters in Tableau Help.
You can use the Embedding API to query a parameter object to find out the name, the allowableValues, the currentValue, and the dataType for the parameter. You can also use the changeValueAsync method to change a parameter value. See Get and change parameters from the workbook.
You can initialize the view with parameters settings the same way you can initialize the view by adding filter elements to the <tableau-viz> web component. To specify a parameter, you add a <viz-parameter> element and provide a name and value pair.
<viz-parameter name="parameter-name" value="parameter-value"></viz-parameter>
For example, the following shows how you might set a parameter using the <tableau-viz> web component. The parameter value is applied when the view is first rendered. In this example, the Base Salary is set to 75,000.
<tableau-viz id="tableauViz"
src='https://https://public.tableau.com/views/Superstore_embedded_800x800/CommissionModel'
toolbar="bottom" hide-tabs>
<viz-parameter name="Base Salary" value="75000"></viz-parameter>
</tableau-viz>
If you are using JavaScript to initialize your embedding view, you can add parameters by creating a viz-parameter child node. You add the vizParameter node to the viz object before adding the viz object to the HTML page.
The following example shows the syntax you would use to create a parameter element that you can add to the viz object.
const vizParameter = document.createElement("viz-parameter");
vizParameter.setAttribute("name", "parameter-name");
vizParameter.setAttribute("value", "parameter-value");
viz.appendChild(vizParameter);
The following example sets the Base Salary parameter to 75,000. To do this, you create the vizParameter element and then add attributes for name and a value, in this case, Base Salary and 75000 respectively. You then can append the vizParameter to the viz.
You should add the viz-parameter child node before setting the viz.src URL.
import {
TableauViz,
TableauEventType
} from "https://public.tableau.com/javascripts/api/tableau.embedding.3.latest.js";
const viz = new TableauViz();
const vizParameter = document.createElement("viz-parameter");
vizParameter.setAttribute("name", "Base Salary");
vizParameter.setAttribute("value", "75000");
viz.appendChild(vizParameter);
viz.src = "https://public.tableau.com/views/Superstore_800_600/CommissionModel";
viz.toolbar = "hidden";
document.getElementById("tableauViz").appendChild(viz);
You can change the value of a parameter after the embedded view has loaded by using the workbook method changeParameterValueAsync().
To use this method, you must first access the embedded viz object. As described in Interact with the View, you can get the viz object using the document.getElementbyId() method.
The Workbook.changeParameterValueAsync() method takes two arguments, the name of the parameter and the new value. Note that the new value must match the allowable values for the parameter.
For example, the following code example is a standalone web page that embeds a Tableau view. The example uses an input form that allows a users to change the Base Salary parameter values in increments of 1000. The minimum value (0) and the step interval match the allowable values for the Base Salary parameter.
<!DOCTYPE html>
<html>
<head>
<title>Change Parameters</title>
<script type="module" src="https://public.tableau.com/javascripts/api/tableau.embedding.3.latest.js"></script>
<script>
async function setVizParam() {
let viz = document.getElementById("tableauViz");
try {
let newBase = document.getElementById("newSalary").value;
await viz.workbook.changeParameterValueAsync("Base Salary", newBase);
} catch (error) {
console.log (error);
};
}
</script>
</head>
<body>
<h1>Embedding API v3 Demo - Change Parameters</h1>
<form id="resizeForm">
<input type="number" min="0" step="1000" id="newSalary" placeholder="Base Salary">
<button type="button" onClick="setVizParam();">Change Parameter</button>
</form>
<div id="main" >
<tableau-viz
id="tableauViz"
src="https://public.tableau.com/views/Superstore_800_600/CommissionModel"
toolbar="hidden" hide-tabs>
</tableau-viz>
</div>
</body>
</html>
Here’s what that code looks like when it is embedded in a web page.
You can use the Workbook.getParametersAsync() method to access all the parameters available in a workbook. The method returns an array of parameter objects.
For example, the following code snippet assumes that you have already created a Viz object and have used tableauViz as the identifier. The example uses the Workbook.getParametersAsync() method to access the parameters. The snippet then prints the names of all the parameters and their current values in the debugging tools console.
async function getParameterNames() {
let viz = document.getElementById("tableauViz");
const parameters = await viz.workbook.getParametersAsync();
parameters.forEach( (p) => {
console.log(p.name, p.currentValue.value);
});
};
You could also use the getParametersAsync() method to get a specific parameter object, and then use that object and the Parameter.changeValueAsync() method to assign the parameter a new value.
async function setParamFunc() {
let viz = document.getElementById("tableauViz");
try {
const parameters = await viz.workbook.getParametersAsync();
const baseSalary = parameters.find( (p) => p.name == "Base Salary");
newVal = await baseSalary.changeValueAsync("75000");
console.log(newVal);
} catch (error) {
console.log (error);
};
}
Using the Embedding API, you can add custom parameters. These are not like the parameters in a Tableau workbook. These custom parameters (CustomParameter or <custom-parameter>) provide attributes that are not officially supported by Embedding API, but are supported by Tableau Server and Tableau Cloud. Specifically, you can use some of the URL parameters for iframe tags for views that you might have used with previous versions of the embedding JavaScript API. Note that the parameters listed in the URL parameters for iframe tags might not work or might not be supported in the future. Custom parameters can be used when you are embedding a viz in viewing mode and in web authoring mode.
Setting custom parameters is relatively easy when you use the Tableau viz web components. Just add the <custom-parameter> element to the web component. The element takes two attributes, the name of the parameter and its value. Note that when you specify the name of the parameter, you must use the URL parameter name as listed in the URL parameters for iframe tags. These names take a colon prefix (:), for example :tooltip. Note that the URL parameters listed in the URL parameters for iframe tags were used with previous versions of the embedding JavaScript API, and might not work or might not be supported in the future.
Syntax for custom parameters:
<tableau-viz id="tableauViz">
<custom-parameter name="parameter-name" value="parameter-value"></custom-parameter>
</tableau-viz>
Example of setting custom parameters using a web component:
The following example shows a Tableau web component that uses custom parameters to prevent tooltips from appearing in the view and to hide the Data Details button in the toolbar.
<tableau-viz
id="tableauViz"
src="https://public.tableau.com/views/Superstore_800_600/Overview">
<viz-filter field="State/Province" value="California,Utah,Oregon,Washington">
</viz-filter>
<custom-parameter name=":tooltip" value="no"></custom-parameter>
<custom-parameter name=":dataDetails" value="no"></custom-parameter>
</tableau-viz>
If you are using JavaScript to initialize your embedding view, you can add custom parameters by creating a custom-parameter child node. You should add the custom parameter child node before you add the src URL. The following example shows the syntax you would use to create a custom parameter element that you can add to the viz object.
const customParameter = document.createElement("custom-parameter");
customParameter.setAttribute("name", "parameter-name");
customParameter.setAttribute("value", "parameter-value");
viz.appendChild(customParameter);
The following example sets a custom URL parameter that hides the Share button on the toolbar. This might be something you’d do if you wanted to keep users from using the links provided by the Share button. You add the custom parameters before assigning the src URL to the viz. Note that you must use the URL parameter name as listed in the URL parameters for iframe tags. These names have a colon (:) prefix.
import {
TableauViz
} from "https://public.tableau.com/javascripts/api/tableau.embedding.3.latest.js";
// create viz object
const viz = new TableauViz();
// add custom parameter
const customParameter = document.createElement("custom-parameter");
customParameter.setAttribute("name", ":showShareOptions");
customParameter.setAttribute("value", "false");
viz.appendChild(customParameter);
// set src URL
viz.src="https://public.tableau.com/views/Superstore_800_600/Overview";
// add viz to HTML page
document.getElementById("tableauViz").appendChild(viz);