YouTrack InCloud 2017.3 Help

Keymap:

Custom Widget Tutorial

This page shows how to build a custom widget. We decided to cover a very simple case: A sample widget that displays profile information of a predefined GitHub user. This widget does not perform any complex operation, like authentication and authorization in a third-party service, nor does it have complex style elements. Still, we hope that it will give you the taste of how the idea of custom widgets works.

The outline of the developing a custom widget contains the following steps:

Create index.html

Second step is to create an entry point for your widget: index.html file. This is a standard HTML5 file that includes the hub-dashboard-addons library that allows communicating with the dashboard. It also contains CSS styles to display the data retrieved from the GitHub profile. The body element includes the widget script itself (index.js).

Create the script

The third step is to create the script itself. In our case, the script retrieves and displays the user profile of a specified GitHub user.

/* Declare a constant that contains a login of the target github user */constUSER_NAME='jetbrains';/* The following renderUserDetails(user) function creates and inserts the user profile data into the DOM */functionrenderUserDetails(user){constcontainer=document.getElementById('user-details');container.innerHTML=`<imgsrc=${user.avatar_url}class="user-avatar"/><h4>${user.name}aka<ahref="${user.html_url}">${user.login}</a></h4><div><div>Followers:${user.followers}</div><div>Repos:${user.public_repos}</div>`;}/* The following function actually retrieves the data from GitHub using the GitHub API. It uses the Fetch API (https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) */functionloadAndRenderUser(userLogin){returnfetch(`https://api.github.com/users/${userLogin}`).then(response=>{returnresponse.ok?response.json():newError(response);}).then(user=>{renderUserDetails(user);returnuser;}).catch(err=>console.warn(err));}/* The last step is to register the widget in the dashboard and initiate loading the user data. Also, this block defines displayed widget title and adds the refresh button. When you click the refresh button, the script will reload and re-render the user profile data. We use Dashboard API to implement this functionality. */// Register widget:Dashboard.registerWidget(function(dashboardAPI,registerWidgetAPI){// Load GitHub profile dataloadAndRenderUser(USER_NAME)// Set the widget title.then(user=>dashboardAPI.setTitle(`GitHubUser${user.login}`));// Add the refresh button.registerWidgetAPI({onRefresh:()=>loadAndRenderUser(USER_NAME)});});

Test the Widget

To test the widget, we need to load it in the Widgets Playground. First, we run a static server on the local directory with the custom widget files. In our case, we use npm http-server that requires Node.js. Then, as YouTrack InCloud is accessible over HTTPS, by default, we need to make the custom widget accessible over HTTPS. We use ngrok for this tutorial.

To load your widget in the widgets playground:

Install the http-server:

npm i http-server -g

From the custom widget directory, run the http-server with the following command:

http-server . --cors -c-1 -p 9033

The http-server starts and serves the content on the current directory. In the response you see the IP addresses (both internal and external) at which the http-server is accessible. For example:

To make the custom widget accessible over HTTPS, we need to run ngrok service on the port that we used for http-server:

./ngrok http 9033

ngrok starts and in the command line output you will see something like this:

If you modify the code and upload these changes to your web server, use the Reload widget button to refresh the widget content and test the updates.

Upload the Widget

Now that we successfully tested the widget in the playground, we can upload it to the production environment.

First, we create a zip archive with the widget files. You can use any archive application to your liking. Just remember that manifest.json and index.html files must be located on the top-most level of the zip file.

For example, we used command line prompt in Mac OS X to create the archive. Our sample widget contains only three files and all of them are located in the same directory without any subdirectories. Thus the command to create the archive is very simple (run in the custom widget directory):

zip custom-widget.zip *

We created the custom-widget.zip file. Now we just need to upload it to the production environment:

In your production YouTrack InCloud, open the Custom Widgets page.

Click the New widget... button.

The New widget dialog is open in the side bar.

Select the zip file to upload. The information from the manifest.json should be displayed.

Click Upload widget button.

The widget is uploaded to the server and displayed in the list of available custom widgets. It also appears in the Add widget... drop-down menu on the Dashboard:

This it! Now the new custom widget is available to the users of the Dashboard in YouTrack InCloud.