Widget Development Guide

Quick Start

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.

Widget Package

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.

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.

Widget Manifest

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:

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
    }
}

Widget Compatibility

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.

Size Limitations

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.