Export (0) Print
Expand All

Specifying Work Item Form Controls

Updated: June 2010

You can use this topic as a quick reference to the CONTROL element, its child elements, and attributes. For information about how to use this element to display fields on a work item form in Team Foundation, see Controlling the Display of Work Item Fields.

For each field or form control that you want to display on a work item form, you add a CONTROL element. This element provides nine values for the Type attribute, which you can use to add fields or special controls to add links and attachments. In addition, you can create a custom control and add it to a work item form.

Use the optional Label attribute to specify the text that appears next to the control. Use the related LabelPosition attribute to specify where the label appears in relation to the control.

When you customize a work item form, you typically add to the form a subset of the fields that are already defined for that type of work item type. The definition of each field controls many aspects of which data appears by default or which data you can specify in the form.

Each field is associated with a data type. Also, Team Foundation tracks many fields, and you should not change them. For example, Team Foundation tracks the Created Date and Created By fields. You can create search criteria that use these fields. However, you cannot change their values from a work item form. For more information, see Using System Fields.

You can use the information in the following table to determine which field type is supported by which Type attribute of the CONTROL element. You use the Label attribute to specify the text that appears next to the control, and you use the related LabelPosition attribute to specify where the label appears in relation to the control.

Field type

Type attribute options

Usage

DateTime

FieldControl

DateTimeControl

Use FieldControl to provide a text field for the input or display of a field that has the DateTime data type.

<Control FieldName=" MyCompany.Group1.StartDate " Type="FieldControl" Label="Start Date" LabelPosition="Left" />

Use DateTimeControl to provide a calendar picker to specify a date for a field, as the following illustration shows:

Calendar picker
<Control Type="DateTimeControl" FieldName="MyCompany.Group.ScheduleStart" Label="Scheduling Start Date:" LabelPosition="Left" Dock="Fill" Format="Short" />

Double

FieldControl

Use FieldControl to provide a text field for the input or display of a field that has the Double data type.

<Control FieldName="ABC_Company.Statistics.Analysis" Type="FieldControl" Label="Analysis %" LabelPosition="Left" />

History

WorkItemLogControl

Use WorkItemLogControl to provide a control field for History fields that track discussion threads and other historical information, as the following illustration shows:

History tab and field on work item form

You can use this control only to support the display of the history field of a work item, the System.History work item field. If you use this control, you can expand and collapse details about historical revisions to a work item. You can also format text that you add to the history field.

<Control Type="WorkItemLogControl" FieldName="System.History" Label="Detailed Description
and History" LabelPosition="Top" Dock="Fill" />

HTML

HTMLControl

Use HTMLControl to provide a control field that enables HTML fields to capture rich-text formatting, as the following illustration shows:

HTML field shown on work item form
<Control Type="HtmlFieldControl" FieldName="Microsoft.VSTS.Notes" Label="Notes" Dock="Fill" />

You can set the size of the control by specifying the MinimumSize attribute. A scroll bar appears when the content of the field exceeds the size of the control box. Additional controls on the form or other tabs may also affect the size of the control. For more information, see Designing the Layout of the Work Item Form.

Integer

FieldControl

Use FieldControl to provide a control field for a field that has the Integer data type.

<Control FieldName="System.Id" Type="FieldControl" Label="Id" LabelPosition="Left" />

PlainText

FieldControl

Use FieldControl to provide a control field for a PlainText field, such as a text box that contains descriptions that may contain more than 255 characters.

<Control FieldName="Microsoft.VSTS.DocName" Type="FieldControl" Label="Vision Doc Location" LabelPosition="Left" />

String

FieldControl

Use FieldControl to provide a control field for a String field. String fields are limited to 255 characters.

<Control FieldName="System.Title" Type="FieldControl" Label="Title" LabelPosition="Left" />

TreePath

WorkItemClassificationControl

Use WorkItemClassificationControl to provide a control field for a TreePath field.

<Control FieldName="System.AreaPath" Type="WorkItemClassificationControl" Label="Area Path" LabelPosition="Left" />

Optional Control Element Field Attributes for All Control Types

The following optional attributes can be specified only for those control types that are listed.

Attribute

Description

Field

Specifies the control that is associated with the work item field.

Label

Specifies the visible text on the form that identifies the control. Specify a string that contains no more than 80 characters.

LabelPosition

Specifies the position of the label in relation to the control data. Specify a string from one of the following values: Top, Bottom, Left, or Right.

Caution noteCaution:
You must specify the same LabelPosition for all fields that are defined in the same GROUP element container.

Dock

Specifies the alignment of the label with the side of the container that you specify, or stretches the field to fill the container. Specify a string from one of the following values: Fill, Top, Bottom, Left, or Right.

Padding

Specifies the amount of space, in pixels, around the inside border of the control. Specify four values that correspond to the top, bottom, left, and right as in the following example: (2,0,2,0).

Margin

Specifies the amount of space, in pixels, around the outside border of the control. Specify four values that correspond to the top, bottom, left, and right as in the following example: (2,0,2,0).

ReadOnly

Specifies that the field is read-only. Specify True or False.

MinimumSize

Specifies the minimum amount of space, in pixels, that the control should occupy in the form. Specify two values that correspond to the width and height as in the following example: (100,100).

Name

Uniquely identifies a control. The Name attribute is required only if more than one control on the form is associated with the same work item field.

NoteNote:
You use the Name attribute to display the same field in more than one area on the form. You specify a unique value for the Name attribute for both control entries so that Team Foundation identifies each control uniquely. It is useful to show the same control in various locations based on the context of tabs.

Optional Control Element Field Attributes for Specific Control Types

You can specify the following optional attributes for only those control types that are listed.

Attribute

Control types

Description

NumberFormat

FieldControl

Specifies the characters that you can type in the field control. Specify one of the following values: WholeNumbers, SignedWholeNumbers, DecimalNumbers, or SignedDecimalNumbers.

MaxLength

FieldControl

Specifies the maximum number of characters that you can specify in a field control.

Format

DateTimeControl

Specifies the format for the date-time field that corresponds to one value of the DateTimePickerFormat enum. Specify one of the following values: Custom, Long, Short, or Time.

CustomFormat

DateTimeControl

Specifies the format for the date-time field when Format=”Custom”. The syntax for the format corresponds to the syntax of the DateTimePicker.CustomFormat property.

The following table describes the Type attributes for the CONTROL element, which you can use to manage file attachments or create links.

Type attribute options

Usage

AttachmentsControl

Use this control to enable users to display and manage the file attachments of a work item. If you use this control, users can open, add, and remove file attachments from work items. This control is usually contained in its own tab group, as in the following example:

<TAB Label="Attachments">
   <CONTROL Type="AttachmentsControl" LabelPosition="Top" Dock=”Fill” />
</TAB>

LinksControl

Use this control to enable users to display and manage links from this work item to other work items. If you use this control, users can open, edit, add, and remove links. This control is usually contained in its own tab group, as in the following example:

<TAB Label="All Links">
   <CONTROL Type="LinksControl" LabelPosition="Top" Dock=”Fill” />
</TAB>

In addition to the built-in controls, you can add a custom control to a work item form.

For example, you could add a custom control to capture a screenshot from the Clipboard. As an alternative, you could provide a control to capture multiple values by adding a check box for values that appear in a list or a menu.

To implement a custom control, you must specify the name of the control for the Type attribute. For more information, see the following page on the Microsoft Web site: Work Item Tracking Custom Controls.

Date

History

Reason

June 2010

Added more information about the attributes that the CONTROL element supports.

Customer feedback.

July 2010

Added several illustrations and a link to more information about how to use the controls.

Customer feedback.

Community Additions

ADD
Show:
© 2014 Microsoft