I have been doing a lot with Azure DevOps lately, from building pipelines to dashboard.
As I was building out a dashboard with various widget, I wondered if it was possible to create a custom dashboard widget!
What do you know? You can!
The widget are a combination of HTML, JavaScript and CSS.
So I decided to create a simple sample custom widget that would display two lists, a list of characters from Star Trek, and another list of characters from Star Wars.
This is a very academic sample, just something to get familiar with the widget creation/deployment process.
I started with VS Code to build the custom widget.
I followed the article at https://docs.microsoft.com/en-us/azure/devops/extend/develop/add-dashboard-widget?view=azure-devops, specifically Part 1: Hello World!, to create the bare bones structure.
While the jQuery library is imported by default, I would recommend, where you can, you stick with JavaScript, one less library you need to rely on, and the more I work with JavsScript the more I discover how far it has come with ease of DOM manipulation.
Next, I created two fake APIs using https://www.mocky.io to return my list of characters.
The first API returns a list of Star Trek characters in a JSON format.
[
{
"name":"Jean Luc Picard"
},
{
"name":"Benjamin Sisko"
},
{
"name":"Kathryn Janeway"
}
]
The second API returns a list of Star Wars characters in a JSON format.
[
{
"name":"Luke Skywalker"
},
{
"name":"Anakin Skywalker"
},
{
"name":"Obi-Wan Kenobi"
}
]
Next, add a widget.js file to the scripts directory. This file will contain the JavaScript function to add li elements to the parent ul element.
function createNode(element) {
return document.createElement(element);
}
function append(parent, el) {
return parent.appendChild(el);
}
Update your hello-world.html with the following code:
We will want to make sure that our JavaScript library, widget.js, is pulled in, which is why we add <script src="scripts/widget.js"></script> to the head element.
You are now ready to publish your widget, but first you will need to visit the Visual Studio Marketplace Publishing Portal to creating a publisher profile, don’t worry, your widget will only be available to those organizations you share it with.
Package up your extension as explained at https://docs.microsoft.com/en-us/azure/devops/extend/develop/add-dashboard-widget?view=azure-devops#package-your-extension.
In the vss-extension.json file replace the publisher name fabrikam with the name of your publisher profile.
{
"manifestVersion": 1,
"id": "vsts-extensions-myExtensions",
"version": "1.0.4",
"name": "My First Set of Widgets",
"description": "Samples containing different widgets extending dashboards",
"publisher": "mattruma",
"categories": ["Azure Boards"],
"targets": [
{
"id": "Microsoft.VisualStudio.Services"
}
],
"icons": {
"default": "img/logo.png"
},
"contributions": [
{
"id": "HelloWorldWidget",
"type": "ms.vss-dashboards-web.widget",
"targets": ["ms.vss-dashboards-web.widget-catalog"],
"properties": {
"name": "Hello World Widget",
"description": "My first widget",
"catalogIconUrl": "img/CatalogIcon.png",
"previewImageUrl": "img/preview.png",
"uri": "hello-world.html",
"supportedSizes": [
{
"rowSpan": 2,
"columnSpan": 2
}
],
"supportedScopes": ["project_team"]
}
}
],
"files": [
{
"path": "hello-world.html",
"addressable": true
},
{
"path": "scripts",
"addressable": true
},
{
"path": "sdk/scripts",
"addressable": true
},
{
"path": "img",
"addressable": true
}
]
}
Some things to be aware of:
As you rebuild your widget, you will want to increment the version number in the vss-extension.json file.
To include an additional folder, like in my example, the scripts folder, you will need to include it in the files node of the vss-extension.json.
To allow for different sizes for your widget, add them to the supportedSizes node.
That’s it, pretty straight forward!
Related Links
- https://docs.microsoft.com/en-us/azure/devops/extend/develop/add-dashboard-widget?view=azure-devops
- https://docs.microsoft.com/en-us/azure/devops/extend/develop/manifest?view=azure-devops
- https://docs.microsoft.com/en-us/azure/devops/extend/publish/overview?view=azure-devops
- https://www.mocky.io/
- https://jsfiddle.net/ejno5hax/13/
