Specifying Work Item Form Controls

Article
12/06/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.

Adding Fields to a Work Item Form
Adding Special Controls to a Work Item Form
Adding Custom Controls to a Work Item Form

Adding Fields to a Work Item Form

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: `<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: 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: `<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: 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. Note: 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.

Adding Special Controls to a Work Item Form

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>`

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>

Adding Custom Controls to a Work Item Form

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.

Change History

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.

Share via