Build a Custom Widget

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.

Widgets are built using HTML, CSS, and JavaScript. These are static web apps that run in a sandboxed 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 an 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.

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 an 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.

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
services	sequence	A list of services that are available to the widget. Specified as a sequence of key and value pairs. The key must be equal to the application name attribute of a registered service. If the key does not match any service, the attribute is ignored. The values correspond to the application versions that are supported for the specified service. Versions numbers follow the format recommended by the Semantic Versioning Specification (SemVer). Only applications whose version matches the specified service are available for the widget.	optional
view	sequence	A list of visual attributes. The only visual attribute that is currently supported is `"fadeOut": true`. This applies shading to the top and bottom of the scrolling content area inside the widget.	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",
            "services": {
            "YouTrack": ">2017.1",
            "Hub": ">3.0"
            },
            "view": {
            "fadeOut": true
            }
            }

Last modified: 7 March 2019

YouTrack Standalone 2017.3 Help

Build a Custom Widget

Widget Package

Widget Manifest