Create Analytics Dashboards

Dashboards are a feature accessible via the Analytics portal that allows for feature-specific, custom pages to a project in the Tator platform.

Overview

In Tator, the concept of Dashboards are custom HTML files that are loaded into an iframe and accessible from the analytics portal's dashboard page. These single html files will include the styles and scripts needed to support the page's features.

Dashboards can be made for a variety of reasons and are very flexible. Typically, dashboards are created for analysis requests to visualize, or manage data that is specific to the project's goals. The following guide describes how to create, register, update, and maintain dashboards.

Creating a dashboard

Developers will need to create the dashboard file, and test. There is a lot of flexibility in what the dashboards may do or display, including import from external data sources. Here are tips on how to develop a dashboard.

Content & Naming

As a best practice, provide a descriptive name and description when registering a dashboard, and where relevant provide helpful notes to users.

Javascript

Developers can use the tator and tator-ui javascript packages available on NPM to develop a dashboard. One provides an intuitive JS client for the Tator REST API, the other provides access to the UI elements used in the core Tator user interface, including the video player. Javascript components and utilities from tator alternatively can be referenced in the head section with:

<script src="/static/components.js" ></script>
<script src="/static/util.js"></script>

Page-specific components from Tator can also be reused. These names generally follow the page name and can be referenced in the head section. Example:

<script src="/static/projects.js"></script>

As mentioned in tator concepts, additional JS libraries can be incorporated, plotting libraries such as D3 or Plotly are both viable additions to create a useful dashboard for your project.

Developers can also include your own custom javascript on page, or in referenced scripts that allow CORS to interact with the page.

CSS

Generally dashboards include the Tator CSS file in addition to custom style tags. Developers can also include external stylesheets to achieve the look and feel desired for the dashboard. Tator's main CSS file can be referenced with:

<link rel="stylesheet" type="text/css" href="/static/components.css"></link>

Local development

Creating a dashboard locally with html, js, and css is the best way to get started with creating a dashboard. If you are relying on any CORS-restricted items, you will hit a point where you will need to register the dashboard to fully test. You can create an empty project for testing or register the dashboard to your project of choice. While iterating you will need to update the dashboard file each time it changes to see your updates.

Register and update

Register your HTML file as an applet one of two ways: using the project settings page, or the tator-py, python client. Once a dashboard is registered it will show up in the list of available dashboards, and to all of the project's users.

Register using ui

Developers with a user account, with access to their project's Project Settings page, and complete the following steps:

1. Click the cog from project details to get to Project Settings.

2. Open "Applets" in side panel.

3. Click + Add New or +.

4. Fill out name, description, and upload file. You can leave categories blank.

5. When you click "Save", the dashboard will be published. On succssful save you will see your dashboard now has an id.

6. You can navigate to it from the site's analytics portal, or directly access the url using this pattern:

{baseUrl}/{projectId}/dashboards/{dashboardId}

Your dashboard should now be listed under cloud.tator.io/dashboards and be accessible at cloud.tator.io/{projectId}/dashboard/{dashboard-id}. Note: The newly created dashboard ID is listed on the settings page edit form for the dashboard.

Update using ui

Any subsequent updates can be made from the Projec Settings page by uploading a new version of the HTML file and clicking Save.

Register using tator-py

Dashboards are registered using the Applet endpoint. To register using tator-py you must first have completed the tator-py installation and have an API Token.

To register using tator-py python client you will need to follow the documentation here: registering an applet using tator-py. To update, you must send the appropriate information and path to your HTML file. You must be using a token for a user account with access to that project you are hoping to register the applet, or you will get an error.

Registering a dashboard with tator-py will look like this:

cd scripts/packages/tator-py/examples/

python3 register_applet.py --host {hostname} --token {token}  --project {projectId} --html-file {pathToFile}  --name "Descriptive Name" --description "Descriptive text."

Update using tator-py

To subsequently update the applet, use the documenation here: updating an applet using tator-py. To update, you must have the ID of the dashboard you are wishing to update, which can be found in project settings, or in the URL path to the dashboard page on tator. You also must using a token for a user account with access to that project.

Updating a dashboard with tator-py will look like this:

cd scripts/packages/tator-py/examples/

python3 update_applet.py --host {hostname} --token {token}  --dashboard-id {dashboardId} --html-file {pathToFile}  --name "Descriptive Name" --description "Descriptive text."

Dashboards for multiple projects

Dashboards are registered to projects separately, even if they are the same HTML file. This is because of the project-specific nature of dashboards — including user access, and data — the nature of dashboards is that they exist one-to-one with a project in terms of registration and maintenance. If you have multiple projects that require the same dashboard you will need to register it to all projects, and update it in each project when/if required.