Adventures with Azure DevOps: Create a Custom Dashboard Widget

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:

  
    
    
    
  

  
    

      

      
Star Trek
      

        
Loading...
      
      
Star Wars
      

        
Loading...
      
    
  

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/