Widgets¶

A bunch of standard widgets are available in ftrack that can be used on dashboards. If you are a developer and want to build and add your own widgets you can do that by building a web page that uses the ftrack API and show it using the Web view dashboard widget or when launching an action.

The Web view widget can be configured to allow for two way communication between the ftrack UI and the iframe using the postMessage API. For actions, two way communication is always enabled.

Communication with the ftrack web UI can be done using a set of predefined topics. The entity details such as id and and type use the same naming as in the ftrack API.

Note

Custom objects such as Task, Shot etc. are currently referred to by their inherited type name TypedContext.

Note

When serving the widget, you will need to use the same protocol, typically https://, as ftrack is hosted on or the widget will be blocked due to mixed content restrictions in browsers.

Example widgets & resources¶

We have created a few example widgets that you can use as an inspiration for your implementation. A minimal example is also included at the bottom of this page.

ftrack JavaScript API: The JavaScript API client allows developers to write JavaScript scripts, running in a web browser, that talk directly with an ftrack server.
ftrack web widget: This small library encapsulates some logic which can be used to build custom dashboard widgets for ftrack. The library exposes an UMD module, accessible as ftrackWidget on the global (window) object.
Basic Widget Example: This is a basic example which shows the use of the JavaScript client for the ftrack API and the iframe widget interface, to create a custom widget in ftrack which shows a grid of versions published on the selected entity. The example is built using vanilla JavaScript to make no assumptions of framework or libraries used.
Chart Widget: This example showing how to use the c3js library for building chart widgets in ftrack. The example shows a line chart with number of created versions during the last 30 days.
Review Sessions Widget: This example showing how to use the templating engine library, Handlebars, for widgets in ftrack. The example shows review sessions for a project.
React Example Widget: This example shows how the JavaScript API can be used in conjunction with ES2015, React and Webpack to build a widget showing notes.
ftrack spark base: Base project which can be used a starting point for building custom widgets using a React-based UI with components that are ready to be used.

Tip

If you create a dashboard with a single Web view widget it will automatically stretch to the available vertical space.

User theme¶

In the ftrack web interface, we support both a light and a dark theme which the users can choose from. To give the user a seamless experience, your custom widget may also support these interfaces.

When the widget is loaded a query parameter with the key theme and the value of either light or dark will be injected into the URL. You can use this value to serve the user one of two stylesheets. A JavaScript snippet of how you can achieve this is available for download here. You can also see this in action in the ftrack spark base project.

Supported topics¶

The following topics are supported:

ftrack.widget.load¶

Sent when the iframe loads and contains information about the current entity and credentials for the current user that can be used with the ftrack API. It has the following structure:

{
    topic: 'ftrack.widget.load',
    data: {
        entity: {
            id: 'eb16970c-5fc6-11e2-bb9a-f23c91df25eb',
            type: 'TypedContext'
        },
        credentials: {
            serverUrl: 'https://some-server.ftrackapp.com',
            apiUser: 'username',
            apiKey: '577ffa44-e702-47f3-b831-4c1115ebf48e'
        },
        theme: 'dark'
    }
}

The data will always contain credentials, but may contain entity for a single entity such as when used on a dashboard and selection when used as an action user interface widget.

ftrack.application.open-actions¶

Can be sent from the widget to open a window display available for the specified selection. The message should be formatted like the following:

{
    topic: 'ftrack.application.open-actions',
    data: {
        selection: [{
            id: 'eb16970c-5fc6-11e2-bb9a-f23c91df25eb',
            type: 'TypedContext'
        }]
    }
}

ftrack.application.navigate¶

Can be sent from the widget to navigate to another entity in the ftrack UI and should look like:

{
    topic: 'ftrack.application.navigate',
    data: {
        id: 'eb16970c-5fc6-11e2-bb9a-f23c91df25eb',
        type: 'TypedContext',
        module: 'project'
    }
}

The module can be omitted to keep the currently active module active. Otherwise it should specified as one of the following:

overview

project

planning

report

my_tasks

system_settings

account_settings

Example¶

This is a simple example of a web page that could be used as a Web view widget.

<html>
<head>
    <title>Example</title>
    <script type="text/javascript">

        // Open sidebar for a hardcoded entity.
        window.openSidebar = function () {
            window.parent.postMessage(
                {
                    'topic': 'ftrack.application.open-sidebar',
                    'data': {
                        'id': 'ae67656a-b3ce-11e1-8ed3-f23c91df25eb',
                        'type': 'TypedContext'
                    }
                },
                window.credentials.serverUrl
            );
        }

        // Navigate to a hardcoded entity.
        window.navigate = function () {
            window.parent.postMessage(
                {
                    'topic': 'ftrack.application.navigate',
                    'data': {
                        'id': 'ae67656a-b3ce-11e1-8ed3-f23c91df25eb',
                        'type': 'TypedContext'
                    }
                },
                window.credentials.serverUrl
            );
        }

        // Listen to messages.
        window.addEventListener('message', function (event) {
            var content = event.data;
            console.debug('Got ' + content.topic + ' event.', content);

            if (content.topic === 'ftrack.widget.load') {
                //Store credentials for later.
                window.credentials = content.data.credentials;

            } else if (content.topic === 'ftrack.widget.update') {
                // Load new data.
            }
        }, false);

        // Inform application that we are ready to receive messages.
        window.addEventListener('DOMContentLoaded', function () {
            window.parent.postMessage(
                {
                    topic: 'ftrack.widget.ready'
                },
                '*'
            );
        });
    </script>
</head>
<body>
    <a href="#" onclick="openSidebar();">Open sidebar</a>
    <a href="#" onclick="navigate();">Navigate</a>
</body>
</html>

Security¶

Since the current users API credentials are passed to the widget, the URLs that can be used to show custom widgets can be restricted from Advanced settings.

Widgets¶

Example widgets & resources¶

User theme¶

Supported topics¶

ftrack.widget.ready¶

ftrack.widget.load¶

ftrack.widget.update¶

ftrack.application.open-sidebar¶

ftrack.application.open-actions¶

ftrack.application.navigate¶

ftrack.application.close-widget¶

Example¶

Security¶