Getting started with widgets
At the Connect Event in 2015, the new Dashboard functionality of Visual Studio Team Services was released. The standard Overview hub is converted into a Dashboard and you can add, remove and arrange widgets on it to display the information you need.
If you look at the figure below, you see the standard Dashboard that is part of your Team Projects. If you place the dashboard in Edit mode you can remove individual widgets and open the configuration page for configurable widgets.
By using the new extension model of Visual Studio Team Services you can easily add your own widgets and deploy them to Visual Studio Team Services. This blog post series shows you how to create and deploy two varieties of a Countdown widget from start to finish as shown in the picture below. The widget has a tile and a configuration page and communicates with VS Team Services through the REST API. This series is authored by Wouter de Kort and Mathias Olausson. Check out the Countdown widget on the marketplace.
Creating a basic extension
To get started with developing extension for VS Team Services, you can use the Visual Studio Template that is available on the Visual Studio Gallery. This template creates all the required files to develop an extension and configures some tasks that help you in compiling and publishing your widget.
After creating a new extension based on this template you get the files shown below. There are a couple of important files that you need to modify to deploy a basic widget.
First, you need to modify the vss-extension.json file. This is a json file with info about your widget like version number and description. You can read all about extension manifests here. You then configure the contribution points that your extension targets. In this case, you want to create a widget so you create a contribution of type ms.vss-dashboards-web.widget that targets the ms.vss-dashboards-web.widget-catalog. Your contribution point also has a couple of properties where URI is the most important one. The URI points to one of the HTML files in your project that VS Team Services will use as the tile of your widget. To make sure that this HTML file gets deployed, you add a files array to your configuration file where you list the files that you want to deploy to VS Team Services as a part of your extension.
{
"manifestVersion": 1,
"id": "vsts-extensions-HelloWorld",
"version": "0.1.0",
"name": "Hello from the Widget World",
"description": "Hello from the Widget World.",
"publisher": "WouterDeKort",
"targets": [
{
"id": "Microsoft.VisualStudio.Services"
}],
"contributions": [
{
"id": "HelloWorldWidget",
"type": "ms.vss-dashboards-web.widget",
"targets": [
"ms.vss-dashboards-web.widget-catalog"
],
"properties": {
"name": "HelloWorld Widget",
"description": "Hello from the Widget World",
"previewImageUrl": "img/preview.png",
"uri": "main.html",
"supportedSizes": [
{
"rowSpan": 1,
"columnSpan": 1
}],
"supportedScopes": [ "project_team" ]
}
},
"files": [
{
"path": "main.html",
"addressable": true
},
{
"path": "img",
"addressable": true
},
{
"path": "scripts",
"addressable": true
}]
}
Another file you need to modify is the settings.vset.json file. In this file you specify the publish credentials required for publishing your extension to Team Services. You need to add both a publisher and a Personal Access token. You can create a publisher by navigating to the Visual Studio Marketplace Publishing Portal and creating a new publisher. Make sure to copy the publisher ID and put that in your settings file. To create a Personal Access token follow the steps at Acquire a Personal Access Token. Copy your token and put in in the settings.vset.json file.
The next step is modifying the HTML page to display the content of your widget. The following HTML is a basic skeleton that displays the text Hello from the Widget World and loads the correct SDK scripts so that VS Team Services can load your extension.
<!DOCTYPE html>
<html>
<head>
<link href="css/app.css" rel="stylesheet" />
</head>
<body>
<div class="title"></div>
<script src="scripts/lib/VSS.SDK.js"></script>
<script type="text/javascript">
VSS.init({
explicitNotifyLoaded: true
});
VSS.require("TFS/Dashboards/WidgetHelpers", function (WidgetHelpers) {
VSS.register("HelloWorldWidget", function () {
return {
load: function (widgetSettings) {
var $title = $('h1.title');
$title.text('Hello From The Widget World');
return WidgetHelpers.WidgetStatusHelper.Success();
}
}
});
VSS.notifyLoadSucceeded();
});
</script>
</body>
You can now publish your extension to your account by running the Publish task in the Grunt file. Don't worry if you don't know how all this works, we will explore it in more detail in the end of this post.
Check out the Widgets SDK for more information.
Check out the Countdown widget on the marketplace.
Coming up…
About the team
 Wouter de Kort |
Wouter de Kort works as the Principal Expert DevOps at Ordina where he runs a team of DevOps Consultants. He helps organizations to stay on the cutting edge of software development on the Microsoft stack. Wouter focuses on Application Lifecycle Management and software architecture. He loves solving complex problems and helping other developers to grow. Wouter authored a couple of books, is a Microsoft Certified Trainer and an ALM Ranger. You can find him on Twitter @wouterdekort and on his blog or at the various conferences where Wouter speaks. |
| Mathias Olausson works as the CTO at Solidify, specializing in DevOps and application lifecycle management practices. With over 15 years of experience as a software consultant and trainer, he has worked on numerous projects and in many organizations. Mathias has been a Microsoft Visual Studio ALM MVP for eight years and is active as a Microsoft ALM Ranger. Mathias is a frequent speaker on Visual Studio and Team Foundation Server at conferences and industry events, and he blogs at https://blogs.msmvps.com/molausson. |