Tableau Viz Extension Manifest File

The viz extension manifest file (.trex) contains metadata for the extension and is used for registration. The manifest file for viz extensions is similar to the file used for dashboard extensions in structure, but instead of the dashboard-extension element, you define a worksheet-extension element. The manifest files are not interchangeable.

For details about a manifest or its fields, see the Sample Manifest File and Elements of the Viz Manifest File.

Manifest Versioning

The versioning of the manifest is designed to be semantically simple and support compatibility. The version follows the [Major].[Minor] format. Minor upgrades are backwards compatible while major upgrades involve breaking changes.

Error Reporting

At start up, Tableau checks the manifest file. If any errors are found while parsing the file, Tableau writes these errors to the log.txt file in the My Tableau Repository/Logs folder. This is the same location that Tableau Desktop uses to report other errors and activity.

Sample Viz Manifest File

<?xml version="1.0" encoding="utf-8"?>
<manifest manifest-version="0.1" xmlns="http://www.tableau.com/xml/extension_manifest">
  <worksheet-extension id="com.example.extensions.name" extension-version="0.1.0">
    <default-locale>en_US</default-locale>
    <name resource-id="name"/>
    <description>Viz extension description</description>
    <author name="USERNAME" email="USER@example.com" organization="MyCo" website="https://www.example.com"/>
    <min-api-version>1.1</min-api-version>
    <source-location>
      <url>SCHEME:SERVER:PORT/PATH</url>
    </source-location>
    <icon>Base64-Encoded ICON</icon>
    <permissions>
      <permission>full data</permission>
    </permissions>
    <encoding id="Encoding-id">
      <display-name resource-id="encoding-name">Encoding display name</display-name>
      <data-spec>
        <data-type>Encoding-type</data-type>
      </data-spec>
      <role-spec>
        <role-type>Encoding-role</role-type>
      </role-spec>
      <fields max-count="n"/>
      <encoding-icon token="letter-m" />
      <tooltip resource-id="tooltip-id">Default tooltip text for encoding</tooltip>
    </encoding>
  </worksheet-extension>
  <resources>
    <resource id="name">
      <text locale="en_US">name in English</text>
      <text locale="fr_BE">name in French</text>
      <text locale="de_DE">name in German</text>
    </resource>
    <resource id="encoding-name">
      <text locale="en_US">EnglishEncoding</text>
      <text locale="fr_BE">FrenchEncoding</text>
      <text locale="de_DE">GermanEncoding</text>
    </resource>
    <resource id="tooltip-id">
      <text locale="fr_BE">French tooltip text</text>
    </resource>
  </resources>
</manifest>

Elements of the Viz Manifest File

Name of element	Description
`manifest`	The root element that contains the manifest options.
`manifest-version`	The version of the manifest. Leave this as version 0.1.
`worksheet-extension`	The root element that contains the options for the viz extension. The `worksheet-extension` includes the `id` attribute, which follows the reverse domain name pattern (`com.example.extension`), and `extension-version` number attribute. These attributes are required.
`extension-version`	The version of the your extension. For example, `extension-version="0.1.0"`
`default-locale`	Specifies the default locale to use for localized text. Here both the locale format (en_US) and language code (en) are accepted. The default locale specified here is converted to one of the supported languages in the Tableau UI. If the language is unsupported or invalid, English is set as default.
`name`	The name of the extension as it appears on the Marks card under Viz Extensions. To provide localized text, specify the name of the resource-id and provide the text strings in the resources element of the manifest (see the manifest example). You can provide localized strings for name and description.
`description`	A short description of the extension.
`author`	Specifies metadata about the author of the extension, including `name`, `email` address, `organization`, and `website`. The `name` and `website` attributes are required. The `website` URL must use HTTPS. The `website` .
`source-location`	Contains the `url` of the server that hosts the web page you create that interacts with Tableau.
`url`	Specifies the scheme (HTTPS, HTTTP), the name of the server, the port (optional) and the path to extension (optional). The `url` must use HTTPS. For example: `https://example.com/extension`. The exception is for `localhost`. In this case, HTTP is allowed. For example: `http://localhost:8080`.
`icon`	Not currently used. The icon is a 70x70 pixel PNG file that is Base64 encoded. If you need an encoder, see https://www.base64-image.de/
`permissions`	Declares the types of permissions that this extension requires. The only option is `full data`. If your extension can access the underlying data or information about the data sources, you must declare full data permission in the manifest. Full data permissions are required if you use any one of the following APIs: `Worksheet.getUnderlyingDataAsync()`, `Worksheet.getUnderlyingTablesAsync()`, `Worksheet.getUnderlyingTableDataAsync()`, `Worksheet.getUnderlyingTableDataReaderAsync()`, `Datasource.getLogicalTables()`, `Datasource.getLogicalTableData()`, `Datasource.getUnderlyingDataAsync()`, `Datasource.getActiveTablesAsync()`, `Datasource.getConnectionSummariesAsync()`. If your extension does not use one of these APIs, you do not need include permissions element. For more information, see Accessing Underlying Data.
`encoding`	Adds tiles to the Marks card for encoding. This is an optional element. By default, the Detail and Tooltip tiles appear on the Marks card. You can use the encoding element to add additional tiles for the fields you want to encode. See the Encoding section for more information.
`resources`	Specifies the resources that can be localized.
`min-api-version`	Specifies the minimum API version required to run the extension.

Constraints

String-based fields: 1000 characters
URI-based fields: 2084 characters
Icon field: size of images are restricted to 70x70

Add encoding in the viz manifest

By default, the viz extension has access to the Detail and Tooltip tiles on the Marks card. You can specify additional encoding tiles for the fields you use in your viz extension by adding <encoding> elements. Adding encoding elements is optional.

To add custom encoding, you provide definitions for the encoding in the manifest file. For example, the following XML code defines three encoding tiles: an X and Y encoding for continuous numeric measures, and a text encoding for string values. The value of attribute named id inside the <encoding> element can be used to map to a variable in your JavaScript code. That code then generates the visualization based upon your data.

<encoding id="x">
  <display-name>X</display-name>
  <data-spec>
    <data-type>numeric</data-type>
  </data-spec>
  <role-spec>
    <role-type>continuous-measure</role-type>
  </role-spec>
  <fields max-count="1"/>
  <tooltip resource-id="tooltip-x-id">Default tooltip text for X encoding</tooltip>
  <encoding-icon token="letter-x" />
</encoding>
<encoding id="y">
  <display-name>Y</display-name>
  <data-spec>
    <data-type>numeric</data-type>
  </data-spec>
  <role-spec>
    <role-type>continuous-measure</role-type>
  </role-spec>
  <fields max-count="1"/>
  <encoding-icon token="letter-y" />
  <tooltip resource-id="tooltip-y-id">Default tooltip text for Y encoding</tooltip>
</encoding>
<encoding id="text">
  <display-name>Text</display-name>
  <data-spec>
    <data-type>string</data-type>
  </data-spec>
  <encoding-icon token="text" />
  <tooltip>Only tooltip text for TEXT encoding</tooltip>
</encoding>

These encodings are rendered on the Marks card as tiles, with the X, Y and Text icons.

note

The Tooltip and Details tiles encoding are always part of a viz extension.

The following table lists the elements and values you can use to add encoding tiles to the Marks card.

Name of element	Description
`encoding`	(Optional) The element that contains the encoding definition. By default, all viz extensions will have the Tooltip and Details encoding tiles. If you want to add your own encoding tile, add this <encoding> element to the manifest file and specify a unique `id` for the encoding. The `id` corresponds to a variable in your code that is used to generate the visualization from the data. For example, the encoding with the `id` of `'x'` could be used to map fields to the x-axis of the visualization. You can add up to four custom encodings.
`display-name`	(Required) The text string to display on the encoding tile on the Marks card. You can localize this text string by adding an optional `resource-id` for the encoding. For example, `<display-name resource-id="encoding1">Encoding Name<display-name>`. You provide localized strings for this `resource-id` in the `resources` section of the manifest file.
`data-spec`	(Optional) Includes the list of data types supported by this encoding. If a <data-spec> element is included, only fields of the specified data types are accepted for this encoding. If the `data-spec` attribute is omitted, all supported data types will be accepted. The supported data types are defined in this table.
`data-type`	There are four possible data types. `numeric`, which supports integer and decimal numeric fields. `temporal`, which supports the three temporal related fields, date, time, and date/time. `string`, any text string field. `boolean`, which supports a boolean (true/false) field. Geographic and cluster group data types are not supported. For more information, see Data Types in Tableau.
`role-spec`	(Optional) Includes the list of role types supported by this encoding. Role types correspond to the dimensions and measures in Tableau (indicated by the blue and green pills you place on the visualization). If omitted, all four possible values are supported. For more information, see Dimensions and Measures, Blue and Green.
`role-type`	(Required) Specifies whether the encoding is for a continuous or discrete dimension or measure. The options are: `continuous-measure`, `discrete-dimension`, `continuous-dimension`, `discrete-measure`.
`fields`	(Optional) The maximum number of fields that can use this encoding. Use the `max-count` attribute to specify the maximum number of fields. If not specified, there is no limit on the number of fields that can use this encoding.
`encoding-icon`	(Optional) Specify the icon to use in the Encoding tile and next to fields when associated to your encoding. Select from one of the many predefined icons which Tableau offers to Viz Extension developers. If none is specified, the next available default icon which hasn't been used yet will be associated with your encoding. The defaults are the Ⓐ, Ⓑ, Ⓒ, or Ⓓ icons.
`tooltip`	(Optional) The text string to display as a tooltip when the mouse is hovering over this particular encoding tile. You can localize this tooltip text by adding an optional `resource-id`. You provide localized strings for this `resource-id` in the `resources` section of the manifest file. With no `resource-id` xml attribute, the value will be used as the tooltip in all locales.

Icons

Custom encodings can be assigned a specific icon by using the <encoding-icon> XML tag inside each <extension> entry in the .trex manifest file.

<encoding-icon token="letter-x" />

The following table shows the list of icons you can use.

keyword	keyword	Icon
color	letter-a
size	letter-b
text	letter-c
line	letter-d
shape	letter-e
angle	...	..
detail	letter-z
tooltip
level	digit-0
level-radial	digit-1
edge	digit-2
	digit-3
dot	digit-4
favorite	digit-5
filter	digit-6
flow	digit-7
forecast	digit-8
globe	digit-9
grid
highlight	hash
image	dollar
join	percentage
link	ampersand
metric	exclamation
delta-down	smaller-than
delta-up	equal
three-dots	larger-than
arrow-down	question
arrow-up	at-symbol
arrow-left	function
arrow-right
thumbnail-even

Manifest Versioning​

Error Reporting​

Sample Viz Manifest File​

Elements of the Viz Manifest File​

Add encoding in the viz manifest​

Icons​