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 andWebpack 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.ready

Should be sent from the widget when the widget has loaded and is ready to receive topics from the application. Once the application receive this topic it will respond by sending the ftrack.widget.load topic. The ready topic

{
    topic: 'ftrack.widget.ready'
}

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.widget.update

Sent when the ftrack UI navigates to an entity and has the following structure:

{
    topic: 'ftrack.widget.update',
    data: {
        entity: {
            id: 'eb16970c-5fc6-11e2-bb9a-f23c91df25eb',
            type: 'TypedContext'
        }
    }
}

ftrack.application.open-sidebar

Can be sent from the widget to open the sidebar for an entity in the ftrack UI and should look like:

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

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.



    Example
            // 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'
                },
                '*'
            );
        });
   


    Open sidebar
    Navigate

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.

Did this answer your question?