Widget Development Guide

Custom widgets are miniature application views that can you can embed in a YouTrack dashboard. You can build a widget that lets you view and interact with any application that is part of your software ecosystem, including custom views for YouTrack data and information that is stored in your built-in Hub service.

This page includes a basic overview of the widget package and manifest file. For a step-by-step introduction to custom widgets, read the Custom Widget Tutorial.

The fastest way to build a custom widget is to use our Yeoman generator. When you run the generator:

Yeoman builds the basic project structure and installs all of the required dependencies.
The index.html file that is required for the widget package is created in the src directory.
The prompts in the command line let you specify values for the name, description, and author attributes in the manifest.json file.
The code for a sample widget is saved to the app subdirectory.

To build a custom widget with the generator, access the widget generator in GitHub and follow the instructions in the README file. To get started, use the following commands:

npm install -g yo @jetbrains/generator-ring-ui

Then switch to the root directory of your widget (create one if necessary) and run:

yo @jetbrains/ring-ui:hub-widget

The generator prompts you to enter the widget name (defaults to the name of the current directory), widget description, and author. Yeoman creates your project files and installs all the dependencies for you.

At this point, you should have all of the tools that you need to get started. As you build your widget, use the information on this page for reference.

Widgets are built using HTML, CSS, and JavaScript. These are static web apps that run in a sandboxed inline frame (iFrame).

The widget must have entry file that is named index.html.
Your widget package can contain related source files.

There are a few resources that you can use to build your widgets.

Resource	Description
dashboard.css	This .css file contains the default text styles and layout definitions that are used for widgets in YouTrack. You can use this as the default stylesheet for your dashboard widgets or modify these style to change your widget layout.
dashboard script	This script contains code that communicates with a dashboard through messages. It creates a `Dashboard` object in the global scope, where you can call the single method `registerWidget`. To use this script, choose one of the following implementations: Add a reference to it in the header of your `index.html` file. Wrap the reference inside a <script> tag. For example: <script src="https://unpkg.com/hub-dashboard-addons@latest"></script> Use the npm package manager to install the script with the `npm install hub-dashboard-addons` command. You can then add references to the script in your application any way you want.
Ring UI	JetBrains has published an open-source library of web components that are used for our web-based products. The library contains over 50 React controls, ranging from simple links and buttons to sophisticated controls like a date picker and an interactive hierarchical data list. This library is used extensively inside YouTrack, Hub, Upsource, TeamCity and other products. For a complete list of components and setup instructions, access the Ring UI library online.

Resource

Description

dashboard.css

This .css file contains the default text styles and layout definitions that are used for widgets in YouTrack. You can use this as the default stylesheet for your dashboard widgets or modify these style to change your widget layout.

dashboard script

This script contains code that communicates with a dashboard through messages. It creates a Dashboard object in the global scope, where you can call the single method registerWidget.

To use this script, choose one of the following implementations:

Add a reference to it in the header of your index.html file. Wrap the reference inside a <script> tag. For example:
<script src="https://unpkg.com/hub-dashboard-addons@latest"></script>
Use the npm package manager to install the script with the npm install hub-dashboard-addons command. You can then add references to the script in your application any way you want.

Ring UI

JetBrains has published an open-source library of web components that are used for our web-based products. The library contains over 50 React controls, ranging from simple links and buttons to sophisticated controls like a date picker and an interactive hierarchical data list. This library is used extensively inside YouTrack, Hub, Upsource, TeamCity and other products.

For a complete list of components and setup instructions, access the Ring UI library online.

When you have assembled all of the content and source files for your widget, add a manifest to the top-most directory and create a ZIP archive. You can then import the ZIP archive into YouTrack and enable the widget for use on your dashboards.

Each widget should contain a manifest.json file. This file defines the attributes for your custom widget.

For YouTrack to read and display the attributes in the widget manifest:

The file must be named manifest.json.
The file must be stored in the top-most directory of the ZIP archive.

The following attributes are defined in the widget manifest:

Attribute

Type

Description

Condition

key

string

The internal ID that is used to identify the widget in YouTrack. This ID must be unique per server.

required

version

string

The version number of the widget app.

required

name

string

The name of the custom widget. This identifies the widget in the Custom Widgets list and is shown in the Add widget drop-down menu.

required

description

string

The description that is displayed on the Custom Widgets list.

required

author

string

The name and email address of the developer who created the widget. Specified in the same format that is used in an NPM package. For more information, refer to the npm package description.

required

homeUrl

URL

The web address of the widget homepage or code repository. Shown in the Details sidebar in the widget list.

optional

applicationName

string

The name of the application that the widget is designed to display content from. For example, YouTrack.

optional

iconUrl

URL

The address of the image that is used as the widget icon. The location is relative to the widget root folder, without a leading slash. If empty, the icon of the application referenced in the applicationName is shown in the widget header.

optional

dependencies

sequence

A list of services to which the widget sends HTTP requests. Specified as a sequence of key and value pairs. For the widget to work as expected, these services must be connected to your YouTrack installation. For more information, see Dependencies.

The key must be equal to the application name attribute of a registered service. If the key does not match any service in YouTrack, the attribute is ignored.
The values correspond to the application versions that are supported for the specified service. Only applications whose version matches the specified service are available for the widget.

Versions numbers follow the format recommended by the Semantic Versioning Specification (SemVer). For more information, refer to the semantic versioner for npm.

optional

products

sequence

A list of products and compatible versions where the widget can be installed. Specified as a sequence of key and value pairs, similar to the list of dependencies. For more information, see Products.

The key must be equal to the application name attribute of a registered service. If the key does not match any registered services, the attribute is ignored.
The values correspond to the application versions that the widget is compatible with. Installation is only supported by applications whose version matches the specified service.

required

view

sequence

A list of visual attributes. The following attributes are supported:

Attribute	Type	Description
fadeOut	Boolean	Determines the visual presentation of the scrolling content area. When `true`, applies shading to the top and bottom of the scrolling content area inside the widget.
defaultWidth	integer	Sets the default width of the widget when a user adds it to a dashboard. When empty, the value is set to `2`.
defaultHeight	integer	Sets the default width of the widget when a user adds it to a dashboard. When empty, the value is set to `2`.

The values that can be specified for the defaultWidth and defaultHeight attributes correspond with the columns and rows for the grid on the dashboard. The grid for the Dashboard page has eight columns and an infinite number of rows. When you set these attributes in the widget manifest, you determine the width and height that is most appropriate for displaying the content in your widget.

optional

capabilities

sequence

A list of capabilities that the widget supports in the web browser. These attributes inform users who install the widget of functionality that manipulates browser behavior. The following attributes are supported:

Attribute	Type	Description
popups	Boolean	When `true`, the widget is capable of displaying alerts and opening links in new browser tabs or windows. Specify this attribute when your widget uses the `target="_blank"` attribute for one or more links, uses the `window.open()` method, or uses the `alert()` method.
topNavigation	Boolean	When `true`, the widget is capable of opening a link as the top document in the browser window, navigating away from the current page. Specify this attribute when your widget uses the `target="_parent"` or `target="_top"` attribute for one or more links.

optional

The following example shows how each of these attributes are defined in the JSON file. To build your own manifest, copy this example, paste it into your editor, and replace the sample attributes with your own.

{
    "key": "some-widget",
    "version": "1.0",
    "name": "Display name",
    "description": "A widget to do something",
    "author": "Dee Veloper <dee.veloper@gmail.com>",
    "homeUrl": "https://github.com/huston007/some-widget",
    "applicationName": "YouTrack",
    "iconUrl": "static/icon.svg",
    "dependencies": {
        "YouTrack": ">2017.1",
        "Hub": ">3.0"
    },
    "products": {
        "Hub": ">=2018.1",
        "Upsource": ">=2018.1",
        "YouTrack": ">=2018.1"
    },
    "view": {
        "fadeOut": true,
        "defaultWidth": 3,
        "defaultHeight": 2
    },
    "capabilities": {
        "popups": true,
        "topNavigation": true
    }
}

There are two sections in the widget manifest that define whether the widget is compatible with an installation and the services that are connected to it. Use the information provided here to set the values in your manifest accordingly.

The dependencies section contains a list of services to which the widget sends HTTP requests. If these services are not connected to the YouTrack installation, the widget does not have any data to display.

In some cases, your HTTP requests require a specific API version for the connected service. To function properly, your widget needs to specify the minimum version number that supports the request.

The products section lists the products into which the widget can be installed. Here, the versioning depends on the version of the dashboard API that is supported by the product itself.

Extensions to the dashboard API are officially supported in new minor versions of Hub. New minor versions of YouTrack and Upsource incorporate these changes as well.

For example, if a widget uses a method that was added after the release of Hub 2018.1, the widget can be installed in Hub versions 2018.2 and later. The references to YouTrack and Upsource in the products section should also require 2081.2 as the minimum version for installation.

To protect your installation against malicious archive packages, Hub blocks uploads that are too large or contain too many files. These limitations apply to all uploads, including custom widgets that have been downloaded from the JetBrains Plugins Repository. Each widget package is subject to the following limitations:

The ZIP archive itself cannot be larger than 10 MB.
Single uncompressed files inside the archive cannot be larger than 30 MB.
The ZIP archive cannot contain more than 1000 files.

Last modified: 1 July 2020

YouTrack Standalone 2020.2 Help

Widget Development Guide

Quick Start

Widget Package

Widget Manifest

Widget Compatibility

Dependencies

Products

Size Limitations