In order to make it work, we will rely on a few conventions. In our project, each extension will have its own folder. Name of that folder will be used to produce a package of the same name. In this folder, there must be the manifest file, source files and all the resources. All .debug.js files will be automatically minified. The folder should not contain manually minified files (.min.js files) as those will be overwritten.

First step is to modify TFS build template in order to enable batch script execution. Within this script, source files are minified and extension packages are automatically created.

echo off
 
FOR /R "%SourcesDirectory%" %%G in (.) DO (
 Pushd %%G
 IF EXIST manifest.xml (
 rem minify files
 FOR %%F in ("*.debug.js") DO (
 FOR %%H in (%%~nF) DO ( ajaxminifier "%%F" -out "%%~nH.min.js" -clobber )
 )
 
 rem create zip package
 7za a -tzip "%BinariesDirectory%\%%~nxG.zip" *
 ) 
Popd )

Note, in the script we use 2 external tools:

Ajaxminifier, Microsoft tool available from https://ajaxmin.codeplex.com/

7za, 7zip console available from https://www.7-zip.org/

Both these tools as well as the script have to be deployed on the target build machine where the Build Agent will run the job. For convenience, we deployed all to System32 folder for easy access, but you should be cautious when doing that.

We insert new InvokeProcess action to RunOnAgent and add 2 new arguments BatchFile and BatchFileArguments. That we use to configure properties of InvokeProcess.

Then we create new build definition that includes the configuration for our batch script. Note, the script path is local to the build machine.

Having all that successfully setup, we can now query new build in TFS. It will create the extension package for each control in our solution and put it to the output directory.

Next time, we will look at the implementation details for TFS Web Access progress indicator that you would use to signalize a long(er) running operations in your extensions.

Fiddler is a Web Debugging Proxy which logs all HTTP(S) traffic between your computer and the Internet. Fiddler allows you to inspect traffic, set breakpoints, and "fiddle" with incoming or outgoing data. Fiddler includes a powerful event-based scripting subsystem, and can be extended using any .NET language.

Fiddler is freeware and can debug traffic from virtually any application that supports a proxy, including Internet Explorer, Google Chrome, Apple Safari, Mozilla Firefox, Opera, and many others. You can download Fiddler from https://www.fiddler2.com.

For our purpose, we need to enable Automatic responses and setup 2 AutoResponder rules as seen on the screenshot above.

The URI should be specific to a target TFS that we are using for testing. We use regex here to support scenarios when we indeed do deploy new version of our plugin through the standard process. At that point, part of the URI for the extension changes (number right after the …/_plugins/ part of the URI) and we do not need to update our rule.

First rule responds with HTTP header modification that disables caching of our .js resource. Otherwise, the code would not be requested from the server unless the web browser cache was cleared.

Second rule bypasses the request and supplies our own development copy of the source file from hard drive.

This way, whenever we do any modification to the source our changes will be immediately propagated to the client browser for testing.

Next time, I will show you how to modify Build template to automate extension source file minification and package creation.

Here is the screenshot of what we are trying to achieve today:

First extension that we are going to look at is a progress bar that reflects state of a bug. It will be empty for a new bug, half full for a complete bug and full when the bug gets closed. You could also modify it to reflect your work item’s states more appropriately. For the progressbar, I am using the jQuery UI and the default theme that comes with TFS.

TFS.module("TFS.WA.ProgressBar",
 [
 "TFS.WorkItemTracking.Controls",
 "TFS.WorkItemTracking",
 "TFS.Core"
 ],
 function () {
 var WITOM = TFS.WorkItemTracking,
 WITCONTROLS = TFS.WorkItemTracking.Controls,
 delegate = TFS.Core.delegate,
 moduleBaseUrl = TFS.getModuleBase("TFS.WA.ProgressBar");
 
 // Constructor for ProgressBar
 function ProgressBar(container, options, workItemType) {
 this.baseConstructor.call(this, container, options, workItemType);
 }
 
 // ProgressBar inherits from WorkItemControl
 ProgressBar.inherit(WITCONTROLS.WorkItemControl, {
 _control: null,
 
 // Initialize the control UI without data (in "blank" state).
 _init: function () {
 this._base();
 
 //add css style
 //$("<link />").attr("href", moduleBaseUrl + "style.css")
 //.attr("type", "text/css").attr("rel", "stylesheet").appendTo($("head").first());
 
 this._control = $("<div id='progressbar'></div>").appendTo(this._container);
 },
 
 // Update the control data
 invalidate: function (flushing) { 
 var a = this._workItem.getField('System.State');//same as this._getField() because this control is associated with System.State field
 
 switch(a.getDisplayText())
 {
 case "Active":
 $(this._control).progressbar({ value: 0 });
 break;
 case "Resolved":
 $(this._control).progressbar({ value: 50 });
 break;
 case "Closed":
 $(this._control).progressbar({ value: 100 });
 break;
 }
 },
 
 // Clear the control data
 clear: function () {
 
 }
 
 });
 
 // Register this module as a work item custom control called "ProgressBar"
 WITCONTROLS.registerWorkItemControl("TFS.WA.ProgressBar", ProgressBar);
 
 return {
 ProgressBar: ProgressBar
 };
 });

Before deploying this extension, you will need to update your work item (most likely Bug) definition (please refer to Part 3) to include the control in the WebAccess form layout:

<Control FieldName="System.State" Type="ProgressBar" Label="State:" LabelPosition="Left" />
 

The other sample is much more complex. While the scenario to use this extension is purely artificial, it shows well some more advanced techniques such as work item querying or progress indicator usage. Btw, I will dedicate one separate post entirely to TFS Progress Indicator, so don't worry if you do not fully understand  how it works. The control itself is a combo box that lists all bugs in the project. It remembers what bug is selected for each work item and displays who the bug is assigned to.

TFS.module("TFS.WA.BugList",
 [
 "TFS.WorkItemTracking.Controls",
 "TFS.WorkItemTracking",
 "TFS.Core"
 ],
 function () {
 
 // module content
 
 var WITOM = TFS.WorkItemTracking,
 WITCONTROLS = TFS.WorkItemTracking.Controls,
 delegate = TFS.Core.delegate,
 moduleBaseUrl = TFS.getModuleBase("TFS.WA.BugList");
 
 // Constructor for URIs
 function BugList(container, options, workItemType) {
 this.baseConstructor.call(this, container, options, workItemType);
 }
 
 // BugList inherits from WorkItemControl
 BugList.inherit(WITCONTROLS.WorkItemControl, {
 _control: null,
 _loaded: false,
 
 // Initialize the control UI without data (in "blank" state).
 _init: function () {
 this._base();
 
 //add css style
 $("<link />").attr("href", moduleBaseUrl + "TFS.WA.BugList.styles.css")
 .attr("type", "text/css").attr("rel", "stylesheet").appendTo($("head").first());
 
 this._control = $("<div><select id='BugListList'/><span id='BugListRefreshButton' class='icon icon-refresh-2' /><br /><label class='workitemcontrol-label'>Assigned To:</label><input readonly='readonly' type='text' id='BugListAssignedTo'></div>")
 .appendTo(this._container);
 $(this._control).children("#BugListList").bind("change", delegate(this, this._changed));
 $(this._control).children("#BugListRefreshButton").bind("click", delegate(this, this._updateList));
 },
 
 // Update the control data
 invalidate: function (flushing) {
 if (!this._loaded)
 this._updateList(delegate(this, this._updateListSelection));
 else
 this._updateListSelection();
 },
 
 // Clear the control data
 clear: function () {
 
 },
 
 _updateListSelection: function() {
 var list = $(this._control).children("#BugListList");
 
 $(list).val(this._getField().getValue());
 
 this._updateAssignedTo();
 },
 
 _changed: function () {
 var list = $(this._control).children("#BugListList");
 var val = list.val();
 
 if (this._getField().getValue() == val)
 return; //no need to update the underlying field
 
 //store new value in the underlying field
 this._getField().setValue(val);
 },
 
 _updateAssignedTo: function () {
 var progressId = TFS.globalProgressIndicator.actionStarted("TFS.WA.BugList_updateAssignedTo", true);
 
 var list = $(this._control).children("#BugListList");
 var field = $(this._control).children("#BugListAssignedTo");
 var val = list.val();
 
 //clear 
 $(field).val('');
 
 //call query and fill the field
 var query = "Select [Assigned To] From WorkItems Where [Id] = '" + val + "'";
 this._runQuery(query, function (res) {
 if (res.payload.rows.length == 1) {
 $(field).val(res.payload.rows[0][1]);
 }
 
 TFS.globalProgressIndicator.actionCompleted(progressId);
 });
 
 },
 
 _updateList: function (callback) {
 var progressId = TFS.globalProgressIndicator.actionStarted("TFS.WA.BugList_updateList", true);
 
 var list = $(this._control).children("#BugListList");
 
 //clear options
 $(list).text('');
 
 var that = this;
 
 //call query and fill the list with options
 var query = "Select [State], [Title] From WorkItems Where [Work Item Type] = 'Bug' Order By [State] Asc, [Changed Date] Desc";
 this._runQuery(query, function (res) {
 $.each(res.payload.rows, function (i, v) {
 $(list).append($('<option />').attr('value', v[0]).text(v[2] + " [" + v[1] + "]"));
 });
 
 this._loaded = true;
 
 if ($.isFunction(callback)) callback.call();
 
 TFS.globalProgressIndicator.actionCompleted(progressId);
 });
 },
 
 _runQuery: function (query, callback) {
 this._workItem.store.beginQuery(this._workItem.project, query, callback, null, null);
 }
 
 });
 
 
 // Register this module as a work item custom control called "BugList"
 WITCONTROLS.registerWorkItemControl("TFS.WA.BugList", BugList);
 
 return {
 BugList: BugList
 };
 });

Again, before deploying this extension add following to the work item definition:

1. Add new field to hold the selection:

<FIELD name="SelectedBug" refname="TFS.WA.SelectedBug" type="Integer">
 <HELPTEXT>Bug individually picked from the list of all project bugs</HELPTEXT>
 </FIELD>

       2.   Add the control itself:

<Control FieldName="TFS.WA.SelectedBug" Type="TFS.WA.BugList" Label="Project Bugs:" LabelPosition="Left" />
 

I hope these samples were useful to you and you. In the next post, I will show you how to use Fiddler to speed up your development by surpassing the need to re-deploy the extension every time you make even the slightest modification to the source code.

Extension contains JavaScript source files and a manifest file at least. It can also contain CSS, images or other resources. When deploying the final extension package (which is an ordinary ZIP file with the aforementioned content) it must contain two version of each JavaScript file. The .debug.js version with full source code and comments and .min.js minified file that is reduced in size and does not contain whitespace or comments. A way to automate JS file minification will be shown in a later article.

The manifest file, which is a plain old XML, contains metadata for the extension. This metadata (description, vendor and extension website) is displayed primarily in the Control Panel of the Team Foundation Server. It also contains a list of all modules within that particular extension.

<WebAccess version="11.0">
 <plugin name="description" vendor="Microsoft" moreinfo="url" version="1.0.0" >
 <modules>
 <module namespace="Microsoft.Siemens.BugList“ kind="TFS.WorkItem.CustomControl"/> 
 </modules>
 </plugin>
</WebAccess>

Before you can deploy your extension, you must modify the Work Item definition file. The definition file tells TFS what work item types are available and how should each item be presented. A work item type defines the rules, fields, states, and transitions for an item of work that will be tracked for a team project, such as a bug, requirement, or risk. This definition is shared by both Web Access and Visual Studio (and “other clients” to be more precise). However, there is a way to differentiate what gets displayed where. You can have some layout and controls specific to web access and some to Visual Studio. This actually comes in handy considering the fact that you have to provide 2 different implementations (one .NET, one JavaScript) in order to be able to cater to both.

To retrieve current work item definition file, you use following command:

 witadmin exportwitd /n:Bug /f:c:\bug.xml /collection:https://tfsinstance:8080/tfs/collectionname /p:project

The XML file gets saved to a local disk where you can do any modifications deemed necessary.

You can either:

1. Add proprietary fields to fields collection to store additional data for work each work item

<FIELD name="SelectedBug" 
 refname="TFS.WA.SelectedBug" 
 type="Integer" />
 

2. Add control and associate a field (system or custom) with a control

<Control 
 Name="TFS.WA.Control" 
 FieldName="TFS.WA.SelectedBug" 
 Type="TFS.WA.BugList" 
 Label="Project Bugs:" 
 LabelPosition="Left" />

Control’s optional attribute Name uniquely identifies a control. It is mandatory if more than one control on the form is associated with the same work item field.

FieldName references field in the TFS data store that holds the value for each work item.

Type is our registered extension.

For the full reference, see the MSDN article https://msdn.microsoft.com/en-us/library/ms243932.aspx.

To create different configuration for Web Access and other clients, you split up the layout definition into two groups in a following way:

<FORM>
 <Layout Target="Web">
 <Group>
 …
 </Group>
 </Layout>
 <Layout Target="WinForms">
 <Group>
 …
 </Group>
 </Layout>
</FORM>

Only downside to that is you have to maintain definition for shared controls in both layouts. Also note that control’s name attribute has to be unique across the whole work item definition, not only one layout.

When our work item type definition is ready, we can deploy it back to TFS with the following command:

witadmin importwitd /f:"c:\bug.xml" /collection:https://tfsinstance:8080/tfs/collectioname /p:projectname

Next step is to deploy the packaged extension itself.

We can go to TFS control panel and click the Administration button.

On the Extensions tab, we see all currently deployed extensions, have a chance to enable/disable them or deploy new extensions.

Every time we deploy new version of the extension, it is enough to upload and enable it. It is not necessary to uninstall previous version.

In this post you learned how to modify the work item definition file, create extension package and deploy it to the TFS server. By now, you should be able to start developing Web Access extensions on your own. If you stick with me for couple more posts, you will also see some sample code and learn how to improve your development process.

After reading this article, you should understand how to compose a new Web Access control and what is the minimal code necessary for it.

Below is the source code divided into sections with comments below each of the sections and then we include the full source code at the end of the article again for convenience.

TFS.module("TFS.WA.BugList",
 
 [
 
 "TFS.WorkItemTracking.Controls",
 
 "TFS.WorkItemTracking",
 
 "TFS.Core"
 
 ],
 
 function () {
 

TFS is a global variable belonging to Web Access framework which provides a utility method to define your module. 
The first parameter of the module is a string which specifies a namespace for the module. Please note that this namespace should match the filename you specified for your .js file (the part before flavor).
The second parameter is an array of strings which specifies the dependencies of your module. The list in the above line is a typical list for the custom control development. Web Access module loader makes sure that the dependent modules are first loaded before your module gets executed.
The last parameter is a function which gets executed when the module is loaded and the actual module implementation lives in here. Optionally you can expose anything you want from your module by return an object.

// module content
 var WITOM = TFS.WorkItemTracking,
 WITCONTROLS = TFS.WorkItemTracking.Controls,
 delegate = TFS.Core.delegate,
 moduleBaseUrl = TFS.getModuleBase("TFS.WA.BugList");

For convenience, we define few shortcuts and get the module base URI to use for including CSS files and/or other resources in our module.

// Constructor for URIs
 function BugList(container, options, workItemType) {
 this.baseConstructor.call(this, container, options, workItemType);
 }

Next up is a constructor for our module. The parameters come from XML definition of the work item in TFS. Notice the explicit call to base class constructor.

// BugList inherits from WorkItemControl BugList.inherit(WITCONTROLS.WorkItemControl, {
 _control: null,
 _loaded: false,

We inherit our extension class from WorkItemControl.

// Initialize the control UI without data (in "blank" state).
_init: function () {
 this._base();
 
 //add css style
 $("<link />").attr("href", moduleBaseUrl + "TFS.WA.BugList.styles.css")
 .attr("type", "text/css")
 .attr("rel","stylesheet")
 .appendTo($("head").first());
 
 this._control = $("<div />").appendTo(this._container);
},

Init function represents component initialization, generally consisting of HTML construction. Here we also add CSS link to the DOM. Important thing to remember is that the initialization is shared across multiple items and is not invoked every time a work item is accessed but rather the first time the control is displayed on the UI. The implication of that is that at this point the control is not associated with any work item. Binding mechanism is used for associating controls with specific items (see next slide).

// Update the control data
invalidate: function (flushing) {
 //...
}, 

Invalidate method is called every time the value in the underlying data store has changed (what field is associated with the control is driven by the XML work item type definition). The change occurs when we the value is saved, reverted or refreshed. If flushing is true then the value is being written to the work item field.

// Clear the control data
 clear: function () {},
 });
 // Register this module as a work item custom control called "BugList"
 WITCONTROLS.registerWorkItemControl("TFS.WA.BugList", BugList); 
 return {
 BugList: BugList
 };
 });

Framework calls clear method when the control needs to reset its state to "blank".
At the end we register our extension with the TFS.

bind(workItem)
This method is called when the control is being bound to a new work item. 

unbind(workItem)
This method is called when the control is no longer bound to the specified work item

getControlValue()
This method is called to get the value of the control to write to the corresponding Work Item Tracking field.

cleanup()
This method is called to allow the control to release reference to work item, detach from events, set members to null to free memory which is called after unbind.

_container
This property is a jQuery object (DIV) which contains the control and sub elements are placed. 

_getField()
This method gets the work item form field that corresponds to this control. _getField().getValue() and _getField().setValue(value) are used to read and modify the underlying work item fields. This method returns null if no field is associated with the control in the work item type definition.

Here is the above code again in one part:

TFS.module("TFS.WA.BugList",
[
 "TFS.WorkItemTracking.Controls",
 "TFS.WorkItemTracking",
 "TFS.Core"
],
function () {
 // module content
 var WITOM = TFS.WorkItemTracking,
 WITCONTROLS = TFS.WorkItemTracking.Controls,
 delegate = TFS.Core.delegate,
 moduleBaseUrl = TFS.getModuleBase("TFS.WA.BugList");
 // Constructor for URIs
 function BugList(container, options, workItemType) {
 this.baseConstructor.call(this, container, options, workItemType);
 }
 // BugList inherits from WorkItemControl 
 BugList.inherit(WITCONTROLS.WorkItemControl, {
 _control: null,
 _loaded: false,
 // Initialize the control UI without data (in "blank" state).
 _init: function () {
 this._base();
 
 //add css style
 $("<link />").attr("href", moduleBaseUrl + "TFS.WA.BugList.styles.css")
 .attr("type", "text/css")
 .attr("rel","stylesheet")
 .appendTo($("head").first());
 
 this._control = $("<div />").appendTo(this._container);
 },
 // Update the control data
 invalidate: function (flushing) {
 //...
 },
 // Clear the control data
 clear: function () {},
 //...
 });
 
 // Register this module as a work item custom control called "BugList"
 WITCONTROLS.registerWorkItemControl("TFS.WA.BugList", BugList); 
 return {
 BugList: BugList
};
});
 

In the next article we will take our code and create extension package that can be deployed on the TFS server.

The TFS client library is designed with OOP principles in mind. For JavaScript that means using following techniques:

Data Abstraction

Abstract data types are descriptions and representations of a real-world construct along with associated behaviour. Languages such as C# provide the class keyword to identify abstract data types. In JavaScript functions are used as object descriptors and all functions are actually JavaScript objects. Thus in JavaScript, classes are function definitions.

In TFS, objects consist of constructor definition and methods and properties declared using the prototype keyword.

function MyClass() {
 this.text = "Hello World";
}
var inst = new MyClass();

Inheritance

JavaScript supports inheritance through the use of object prototypes. A prototype is a template of properties that is shared by all instances of the object type. Thus instances of object types “inherit” the values of its prototype property. In JavaScript, all object types have a prototype property that can be both extended and inherited.

TFS contains function inherit that helps properly setup inheritance and construct call chain (base constructor has to be called explicitly with this.baseConstructor.call).

function Parent() { };
 
Parent.prototype.getName= function() {
 return "Parent";
}
 
 
function Child() {
 Parent.call(this);
};
 
Child.prototype = new Parent();
Child.prototype.constructor = Child;
Child.prototype.getName= function() { return "Child"; }
 

Encapsulation

Encapsulation represents the principle of hiding implementation details by restricting access to accessors (getters) and mutators(setters).

For TFS specifically, the following principle applies: All methods and variables are publicly available, but private access is marked with _ (underscore) prefix.

function MyClass()
{
 var _name = "ondrej"; //private member
 this.Age = calcAge(); //public member
 this.getName = function() { //public method
 return m_name;
 }
 
 function calcAge() { //private method
 return 10 + 10;
 }
}
 

Polymorphism

Polymorphism defines disparate behaviours and actions by objects to the same function invocation.

This is used in TFS extension development extensively when, for example overriding default _init method.

//note: we are using objects from previous samples
var p = new Parent();
var c = new Child();
 
 
p.getName(); //returns "Parent"
c.getName(); //returns "Child"

Next time, we will look at the skeleton, or template if you will, of the TFS 2012 Web Access custom control.

To start at the beginning, we will briefly discuss what TFS 2012 Web Access is and what it can do for you. This is by no means a comprehensive description but rather a simple introduction. You can read up more about it here.

After reading this article, you should be able to describe the features and capabilities of Web Access and understand the benefits for your organization.

When using TFS Web Access, you can plan, track and manage work items in Team Foundation Server without a need for a dedicated client application (Visual Studio, Test Professional…).

Information presented to you in Web Access are mainly driven by two things. Permissions, which we will discuss later, and Process Templates, which dictate how work items look, what states they go through etc. In TFS, you have several process templates out-of the box. And of course you have the ability to create your own. In this article I only show the Scrum template.

First activity within your process should be creating product backlog items by using the team's product backlog page.

Next up, you ought to configure your team and team’s capacity and schedule.

Using task board, you can drag items to different columns to conveniently change the status, update hours worked and add new tasks. The Task board is made to look as close as the physical board it represents and I find it very nice that you have the ability to work with the work items (tasks) same way you would had the board been physically available in your office.

In TFS Web Access you also have a full access to work item queries. You can use existing queries you define in Visual Studio as well as create new ad hoc queries.

Then, you have full access to queried items and again, you can edit it or create new from within the Web Access.

This is where we focus the most in this series since this is where our custom controls will be displayed.

From Web Access, you can also access TFS reports on Report Server, same way you would from Visual Studio.

Other nice feature of Web Access is the ability to ask your stakeholders to evaluate the application and provide feedback.

Important part of Web Access is also a Control Panel which is used to administer teams, permissions and extensions. It also provides work areas management and alerts configuration.

Work areas are used to split up large teams into smaller groups that have defined areas of operation. You could have one team focusing on the UI, other on the backend etc. This comes in handy come reporting time when you are given much clearer view on individual teams and the work they have done.

Your users will see certain features in Team Web Access by default. As a member of the Team Foundation Administrators group, you can change this default level of features for some or for all of your users, but you must have the appropriate level of licensing for those users.

• Limited: This level of access restricts the user so that they can only view work items that they create in Team Web Access (also known as Work Item Only View). No other features, such as team pages, are available to users in this group. No client access license (CAL) is required for this level of Team Web Access.
• Standard: This is the default level of access in Team Web Access for your users. Members of this group can view all Team Web Access features except for: sprint planning and backlog views any of the features for requesting feedback from users and managing that feedback. A Team Foundation Server (TFS) CAL is required for all users with this level.
• Full: This level is reserved for users who are licensed to use all features available in Team Web Access, including the sprint planning and backlog management tools and the Request and Manage Feedback tools. To use these features, your user must be licensed for one of the following MSDN subscriptions: Visual Studio Test Professional with MSDN, Visual Studio Premium with MSDN, or Visual Studio Ultimate with MSDN. These MSDN subscriptions each include a TFS CAL for the subscriber.

Hope this overview was helpful to you. Next time, we will start getting into the development with reviewing some principles of Object Oriented Programming (OOP) and the way they are applied in JavaScript and TFS specifically.