Custom Widgets

With ftrack comes a set of standard widgets that can be used on dashboards. In addition to these widgets, it is possible for you to build and add your own widgets. This works by creating a web page that uses the ftrack API and shows it using the Web view dashboard widget, Custom widget on Overview, or when launching an action.

The Custom widget and Web view widgets must be enabled from System Settings Advanced Custom widget and 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. To create a dashboard with a custom widget you will need the "Manage custom widget" permission.

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

Resources and examples

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 spark base
Base project which can be used a starting point for building custom widgets using a React-based UI, allowing you to get up and running quickly with developing new widgets. Includes ftrack JavaScript API, Web widget and Spark components.

Libraries

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.

ftrack spark-components
ftrack-spark-components is a collection of reusable React components used to build ftrack integrations and web applications by ftrack and third parties. The components are largely based on React Toolbox.

Basic examples

Creating a custom widget with React
This is a basic example utilizing the JavaScript client of the ftrack API and the iframe widget interface to create a custom widget in ftrack, which shows a list of projects.
Chart Widget
This example shows 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 shows 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.

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 seen below. You can also see this in action in the ftrack spark base project.

/** Return query parameter by *key*. */
function getQueryParameter(key) {
    var query = window.location.search.substring(1);
    var parameters = query.split('&');
    for (var i=0; i<parameters.length; i++)="i++)" {="{">
        var parameter = parameters[i].split('=');
        if (parameter[0] === key) {
            return parameter[1];
        }
    }
    return null;
}

/** Load stylesheet *href*. */
function loadStyleSheet(href){
    var head = document.getElementsByTagName('head')[0];
    var link = document.createElement('link');
    link.rel = 'stylesheet';
    link.type = 'text/css';
    link.href = href;
    head.appendChild(link);
}

// Get theme as set in ftrack from query parameter and inject a stylesheet.
var theme = getQueryParameter('theme') || 'light';
loadStyleSheet('theme-' + theme + '.css');</parameters.length;>

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. This event will only be triggered if the widget is used under a project and user navigates in the left outliner tree view. It 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 be 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.

   
    

    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.