API Reference

This reference documentation is divided into 3 major sections:

1. Connecting to the dashboard

How to initially connect to the Tableau dashboard

2. Tableau objects

Classes that represent things you can see on the dashboard (filters, parameters, marks, etc.)

3. Change event classes

Classes that represent change events on the dashboard (mark selection, filter change, parameter change, etc.)

Connecting to the dashboard

api.get_dashboard is the recommended way to connect to the Tableau Dashboard.

client_code.api.get_environment()

Returns a dictionary of useful information about the environment the extension is currently running in.

See a description of each here: https://tableau.github.io/extensions-api/docs/interfaces/environment.html#apiversion

Returns: A dictionary containing items such as the Tableau API version, Tableau version, operating system, and others.
Return type: dict

Example

>>> from trexjacket import api
>>> print(api.get_environment())
{'apiVersion': '1.9.0', 'context': 'desktop', 'country': None, 'language': 'en', 'locale': 'en-us', 'mode': 'authoring', 'operatingSystem': 'win', 'tableauVersion': '2022.1.8'}

client_code.api.get_dashboard()

Gets the instance of Tableau Dashboard that represents the current connection. This is the recommended entry point to the Tableau Extensions API.

Returns: The Dashboard instance associated with the current session. It is recommended that this is the only way you ‘get’ the current dashboard.
Return type: Dashboard

Example

>>> from trexjacket import api
>>> mydashboard = api.get_dashboard()

Tableau objects

These are the things you can see on the dashboard (filters, parameters, worksheets, etc.).

class client_code.model.proxies.Filter(proxy)

Bases: TableauProxy

A base class to represent a filter in Tableau.

property field_name: The name of the field that has the filter applied.

property filter_type: The type of filter.

property worksheet_name: The name of the parent worksheet that the filter is on.

property parent_worksheet

The parent worksheet.

Worksheet

property field: The field that has the filter applied.

clear(): This is helper method that clears a filter from it’s parent worksheet.

class client_code.model.proxies.Parameter(proxy)

Bases: TableauProxy

identifier = 'id': Represents a parameter in Tableau. Parameter values can be modified and read using this class.

Note

A full listing of all methods and attributes of the underlying JS object can be viewed in the Tableau Docs and accessed through the Parameter object’s ._proxy attribute.

property name

The display name for this parameter.

Type: str

property value: The current value of the parameter.

property data_type

Type: str

property allowable_values

Returns the allowable set of values this parameter can take.

Return type: The allowable set of values this parameter can take.

change_value(new_value)

Modifies this parameter and assigns it a new value.

The new value must fall within the domain restrictions defined by allowableValues.

Parameters: new_value (string | number | boolean | Date) – The new value to assign to this parameter. Note: For changing Date parameters, UTC Date objects are expected.

register_event_handler(handler)

Register an event handler that will be called whenever the parameter is changed.

Note that the handler must take a ParameterChangedEvent instance as an argument.

Parameters: handler (function) – Function that is called whenever the parameter is changed.

class client_code.model.proxies.Datasource(proxy)

Bases: TableauProxy

Represents a Tableau data source.

Note that Datasources in Tableau are often comprised of multiple logical tables. If your Datasource contains multiple logical tables you’ll need to specify the id when using some methods.

Note

A full listing of all methods and attributes of the underlying JS object can be viewed in the Tableau Docs and accessed through the Datasource object’s ._proxy attribute.

property columns: The columns in the datasource, if the datasource contains a single logical table. If the datasource contains more than one logical table, a MultipleTablesException error is raised.

get_underlying_table(id=None) → DataTable

Returns the underlying DataTable from the datasource by id.

Parameters: (optional) (id) –
Raises: ValueError if an id is not provided and there are more than 1 logical table in the datasource. –

get_underlying_data(id=None)

Return the underlying data as a list of dictionaries.

Parameters: (optional) (id) –

property underlying_table_info

Information on each table contained in the datasource.

type : list of tuple (caption, id)

“caption” is the name of the table in the Tableau UI, while “id” is the unique identifier for the table in Tableau, which can be used in functions like “get_underlying_table”.

Example

>>> ds = self.worksheet.datasources[0]
>>> ds.underlying_table_info
[('Orders', 'Orders_6D2EF74F348B46BDA976A7AEEA6FB5C9'), ('People', 'People_37AF7429D04E4916914EED91681E5975'), ('Returns', 'Returns_11818460B7524AB795D23E763C65D6BC')]

refresh(): Refreshes data source

class client_code.model.proxies.Worksheet(proxy)

Bases: TableauProxy

Represents an individual Tableau worksheet that exists in a Tableau dashboard. Contains methods to get underlying data, filters, and parameters.

Note

A full listing of all methods and attributes of the underlying JS object can be viewed in the Tableau Docs and accessed through the Worksheet object’s ._proxy attribute.

property columns

Returns the columns of the worksheet as a dictionary with {colname: coltype}.

Type: dict

Example

>>> ws = self.dashboard.get_worksheet('Sales Summary')
>>> ws.columns
{'Customer Name': 'string', 'AGG(Profit Ratio)': 'float', 'SUM(Profit)': 'float', 'SUM(Sales)': 'float'}

get_selected_marks(collapse_measures=False)

The data for the marks which are currently selected on the worksheet. If there are no marks currently selected, an empty list is returned.

Parameters: collapse_measures (bool) – Whether or not to try and collapse records on worksheets that use measure names / measure values. This often happens when getting summary data for dual axis visualizations.
Returns: records – Data for the currently selected marks on the worksheet
Return type: list

get_highlighted_marks(collapse_measures=False)

The data for the marks which are currently highlighted on the worksheet. If there are no marks currently highlighted, an empty list is returned.

Parameters: collapse_measures (bool) – Whether or not to try and collapse records on worksheets that use measure names / measure values. This often happens when getting summary data for dual axis visualizations.
Return type: list of dicts

get_underlying_data(table_id=None)

Get the underlying data as a list of dictionaries (records).

If more than one “underlying table” exists, the table id must be specified.

Parameters: table_id (str) – The table id for which to get the underlying data. Required if more than one logical table exists.
Return type: list of dicts
Raises: ValueError – If more than one table_id exists, then a table must be specified.

get_summary_data(ignore_selection=True, collapse_measures=False)

Returns the summary data from a worksheet.

Parameters

ignore_selection (bool) – Whether or not to ignore the selected marks when getting summary data.
collapse_measures (bool) – Whether or not to try and collapse records on worksheets that use measure names / measure values. This often happens when getting summary data for dual axis visualizations.

Return type

list of dict

select_marks(dimension, selection_type='select-replace')

Selects the marks and returns them.

This version selects by value, using the SelectionCriteria interface.

Note that this doesnt work on scatter plots.

Parameters

dimension (dict or list of dict) –
selection_type (optional) – The type of enum to be applied to the marks

Example

If Bar Chart is a standard Tableau bar chart:

>>> bc = self.dashboard.get_worksheet('Bar Chart')
>>> bc.select_marks({'Region': 'Asia'})

And the Bar with the “Asia” Region will become selected.

clear_selection(): Clears the current marks selection.

property filters

A list of all currently selected filters.

Returns

The currently selected filters. Valid types of filters include:: Categorical, Hierarchical, Range, RelativeDate

Return type

list of Filter

get_filter(filter_name)

Returns information on a given selected filter.

Parameters: filter_name (str) – Name of the filter
Returns: specified_filter – The selected filter
Return type: FieldName

clear_filter(filter)

Resets existing filters on the given field.

Parameters: filter (str or Filter) – The name or Filter Object of the field to clear filter on.

apply_categorical_filter(field_name, values, update_type='replace')

Applies the list of provided categorical filter values.

Parameters

field_name (str) – Name of the field in Tableau
values (list) – List of values to filter on
update_type (optional) – The type of update to be applied to the filter

apply_range_filter(field_name, min, max)

Applies a range filter.

Parameters

field_name (str) – Name of the field in Tableau
min (float) – Minimum value for the filter
max (float) – Maximum value for the filter

property parameters

All the Tableau parameters that are used in this workbook.

Type: list

get_parameter(parameter_name)

Getting the parameter information for the given parameter name.

Parameters: parameter_name (str) – Name of the desired parameter name
Return type: Parameter
Raises: KeyError – If no matching parameter is found.

property datasources: list[client_code.model.proxies.Datasource]

The data sources for this worksheet.

Returns: data_sources – The primary data source and all of the secondary data sources for this worksheet.
Return type: list of Datasource

property underlying_table_info

Returns information on each table contained in the datasource.

“caption” is the name of the table in the Tableau UI, while “id” is the unique identifier for the table in Tableau.

type : list of tuple (caption, id)

register_event_handler(event_type, handler)

Register an event handling function for a given event type.

You can register selection_changed and filter_changed events at the worksheet level.

The handler function will be called when selections or filters (depending on event_type) are changed in the worksheet.

If filters in another worksheet affect the filter on this worksheet, this event will be called.

The function you pass to register_event_handler must take an event instance as an argument (either a ParameterChangedEvent or FilterChangedEvent depending on event_type).

Parameters

event_type ('selection_changed', 'filter_changed', 'parameter_changed') – The event type to register the handler for.
handler (function) – The function to call when the event is triggered. handler must take an event instance as an argument.

class client_code.model.proxies.Settings(proxy)

Bases: TableauProxy

Dict-like representation of Tableau Settings. Settings are persisted in the workbook between sessions but can only be modified in authoring mode.

Typically accessed through dashboard.settings.

Settings behaves like a dict and can be accessed and set through standard dict notation:

>>> settings = get_dashboard().settings
>>> my_setting = settings['my_setting']
>>> settings['my_new_setting'] = 'a_new_value'

Most of the standard dict methods are implemented. pop is not implemented; settings cannot be changed when the dashboard is not in ‘author’ mode, so probably, this isn’t what you want.

Non-standard dict methods

Settings.delete: Removes that key from settings if it exists.
Settings.setdefaults: Similar to setdefault and update, where all of the keys in the passed dictionary are updated only if they don’t exist. This avoids repeated writes to the dashboard if many defaults need setting at once.

Note

A full listing of all methods and attributes of the underlying JS object can be viewed in the Tableau Docs and accessed through the Setting object’s ._proxy attribute.

keys(): Identical to dict.keys().

values(): Identical to dict.values().

items(): Identical to dict.items().

get(item, default=None): Identical to dict.get(key, default_value).

update(update_dict): Identical to dict.update(dict). This is a little more efficient than updating many keys one at a time, since setting each key requires writing to the dashboard.

delete(key)

This deletes the key from settings.

Parameters: key (str) – They key to be deleted.

clear(): Identical to dict.clear().

dict()

Converts settings to a dictionary.

Returns: settings_dict – Note that this makes a copy of settings. Changing settings_dict will not affect the settings in the dashboard.
Return type: a dictionary copy of settings.

setdefault(key, default_value=''): Identical to dict.setdefault(key, default_value).

setdefaults(defaults_dict)

Sets all the defaults in the defaults_dict provided. If a key does not exist in settings, it is set to the default provided; otherwise, the value is not changed.

Parameters: defaults_dict (dict) – Key value pairs representing the setting key and the default value to use if the key does not exist in settings.

class client_code.model.proxies.Dashboard(proxy)

Bases: TableauProxy

This represents the Tableau dashboard within which the extension is embedded. Contains methods to retrieve parameters, filters, and data sources.

Note

A full listing of all methods and attributes of the underlying JS object can be viewed in the Tableau Docs and accessed through the Dashboard object’s ._proxy attribute.

refresh(): Refreshes the worksheets in the live Tableau Instance.

property name

The name of the Tableau dashboard (as it appears in the Tableau UI).

Type: str

property worksheets

All worksheets within the Tableau dashboard.

Type: list of Worksheet

get_worksheet(sheet_name)

Gets a dashboard worksheet by name.

Parameters: sheet_name (str) – Name of the worksheet.
Return type: Worksheet
Raises: KeyError – If no matching worksheet is found

property filters

All filters within all worksheets in the Tableau dashboard.

Type: list of Filter

property parameters

All parameters within the Tableau dashboard.

Type: list of Parameter

get_parameter(parameter_name)

Returns the parameter matching the provided parameter_name.

Parameters: parameter_name (str) – Name of the parameter
Return type: Parameter
Raises: KeyError – If no matching parameter is found

property datasources

All data sources in the Tableau dashboard.

Type: list of Datasource

get_datasource(datasource_name)

Returns a Tableau data source by its name (case sensitive).

Parameters: datasource_name (str) – Name of the data source
Return type: Datasource
Raises: KeyError – If no data source matching datasource_name is found.

get_datasource_by_id(datasource_id)

Returns a Tableau data source object by id.

Parameters: datasource_id (str) – ID of the data source
Return type: Datasource
Raises: KeyError – If no datasource matching datasource_id is found.

refresh_data_sources()

Refresh all data sources for the Tableau dashboard.

This call has the same functionality as clicking the Refresh option on a data source in Tableau.

register_event_handler(event_type, handler)

Register an event handling function for a given event type.

You can register selection_changed and filter_changed events at the dashboard level.

Selections or filters changed anywhere in the dashboard will be handled.

Parameters

event_type (str) – The event type to register the handler for.
handler (function) – The function to call when the event is triggered.

property settings

The current dashboard settings. Dashboard settings provide a simple way to persist configuration variables in the workbook. Using Settings you can make your Extensions flexible and adaptable between workbooks. Settings cannot be changed unless the Dashboard is opened in edit-mode or through Tableau Desktop.

Type: Settings object.

property author_mode

Whether or not the dashboard in which the Extension is embedded is in author-mode. Dashboards are in author-mode when web-authoring or opened in Tableau Desktop.

Settings can only be changed or updated when the workbook is in author_mode.

Type: bool

Change event classes

You will encounter these classes when registering event handlers. For example, when registering the ‘filter_changed’ event:

# in some form code
def __init__(self):
   # setup code omitted
   self.dashboard.register_event_handler('filter_changed', self.my_event_handler)

def my_event_handler(self, event):
   filter = event.filter

event in this case will be an instance of the FilterChangedEvent class.

class client_code.model.proxies.MarksSelectedEvent(proxy)

Triggered when a user selects a mark on the Tableau dashboard.

Note

A full listing of all methods and attributes of the underlying JS object can be viewed in the Tableau Docs and accessed through the MarksSelectedEvent object’s ._proxy attribute.

property worksheet

The Tableau worksheet associated with generating the Selection Event.

Type: Worksheet

get_selected_marks(collapse_measures=False)

The data for the marks which were selected. If a deselection occured, an empty list is returned.

Parameters: collapse_measures (bool) – Whether or not to try and collapse records on worksheets that use measure names / measure values. This often happens when getting summary data for dual axis visualizations.
Returns: records – Data for the currently selected marks
Return type: list

class client_code.model.proxies.FilterChangedEvent(proxy)

Triggered when a user changes a filter on a dashboard.

Note

A full listing of all methods and attributes of the underlying JS object can be viewed in the Tableau Docs and accessed through the FilterChangedEvent object’s ._proxy attribute.

property filter

The filter that was changed.

Type: Filter

property worksheet

The worksheet that the filter is on.

Type: Worksheet

class client_code.model.proxies.ParameterChangedEvent(proxy)

Triggered when a user changes a parameter on a dashboard.

Note

A full listing of all methods and attributes of the underlying JS object can be viewed in the Tableau Docs and accessed through the ParameterChangedEvent object’s ._proxy attribute.

property parameter

The parameter that was changed.

Type: Parameter

Displaying Dialogues

exception client_code.dialogs.DialogAlreadyOpenError: Bases: Exception

client_code.dialogs.show_form(form_str, *args, width=None, height=None, **kwargs)

Pop up the form specified by form_str as a dialog in Tableau.

The string form_str can either specify a form using the same string as used by open_form, or, can be the name of a form decorated with @dialogs.dialog_form("{your_dialog_name}").

Example

# in your Form code:
@dialogs.dialog_form("my_dialog_form")
def UserDialogForm(UserDialogFormTemplate):
    def __init__(self, my_argument, **properties):
        ...
    def button_click_event(self, **event_args):
        self.raise_event('x-close-alert', value="my_return_value")

# Where you want to raise the dialog:
response = dialogs.show_form("my_dialog_form", my_argument=my_value)

# This will pop up UserDialogForm for the user, and wait until that dialog closes,
# i.e. the x-close-alert event occurs (and optionally returns a value through the
# `value` argument.)
print(response)

client_code.dialogs.alert(text, buttons=None, width=None, height=None, large=False)

If you want to simply show some text, you can specify the text to show and use this helper method to raise a simple alert.

Unlike the anvil.alert, you cannot pass an instance of a form object.

Parameters

text (str) – The text to show in the popup window
width (int) – Width of the window
height (int) – Height of the window
large (bool) – Whether or not to make the window large.

Return type

None

Example

from trexjacket import dialogs
dialogs.alert('Hello from an alert!')

client_code.dialogs.confirm(text, width=None, height=None, large=False)

If you want to simply show an okay/cancel dialog, you can use this method use this helper method to raise a simple confirm dialog.

This dialog will return True if the user clicks okay, False if the user clicks Cancel, and None if the user closes the dialog (i.e. hits the X button).

Parameters

text (str) – The text to show in the popup window
width (int) – Width of the window
height (int) – Height of the window
large (bool) – Whether or not to make the window large.

Return type

bool

Example

from trexjacket import dialogs
if dialogs.confirm('Are you sure about that?'):
    print('User clicked yes')
else:
    print('User clicked no')

client_code.dialogs.open_start_form(start_form)

Routes the form to the start_form, unless this has been opened as a dialog.

The start_form should be a string pointing to the default start-up form, just as you would specify a form using anvil.open_form.

If this is opening as a dialog, then the form specified by the show_form call from the main session is used.

Parameters: start_form (str) – A string identifier used in the dialog_form decorator
Return type: None

Example

from trexjacket import dialogs
from .ShowMe import ShowMe

dialogs.open_start_form('Home')

Technical Reference

class client_code.model.proxies.TableauProxy(proxy)

A base class for those requiring a Tableau proxy object.

Allows for access of the underlying Tableau JS object using the _proxy attribute.