TFS 2017 (Hosted XML) | TFS 2015
This topic applies to team project customization for the On-premises XML process model. For the Hosted XML process model, see WebLayout and Control elements. For the Inheritance process model, see Customize a process.
For an overview of process models, see Customize your work tracking experience.
You can control the label name, position, size of text box, and other display controls of plain text, integer, number, date, and tree path work item fields on your work item form. To display these fields, you must specify the correct
Type attribute, from the following options:
DateTimeControl: Used to display formatted date fields that have a field type of
FieldControl: Used to display plain textual or numeric fields and lists of values for fields that have a field type of
HtmlFieldControl: Used to display multiline, rich-text format of fields that have a field data type of
WorkItemClassificationControlUsed to display the hierarchical path fields that have a field type of
For more information about other
Type controls, see the following topics:
- Specify work item form controls
- Provide help text, hyperlinks, or web content
- Define link controls to restrict link relationships
- Add the Attachments control
Update the XML definition for a WIT
If you are new to WIT customization, note the following:
- To customize any aspect of a WIT requires updating the XML definition for the WIT. The WIT XML definition is described in All WITD XML elements reference
- If you are customizing the web form that uses the new work item experience, you'll want to reference the WebLayout and Control elements
- If you are customizing a client form for use with Visual Studio, you'll want to reference the Layout XML element reference
- Follow the sequence of steps outlined in Customize the work item tracking web form.
Control the size and display of data fields
You can control the spacing and size of each data field by using the optional attributes that are described in the following table.
The overall size of each data entry field is determined by several factors: the attributes that are assigned to the field, the size of the container, and the area that is allocated to other fields on the form. Default values are assigned to fields when you do not specify a minimum size. However, attributes that are assigned to other fields in the form can affect the size of fields. The number of columns and the horizontal size that you allocate to the largest field in each column determine the horizontal dimension of a form. The number of fields that you specify in a vertical group and the vertical size that you allocate to each field determine the size of the top of the form and also the size of the bottom of the form.
|Attribute||Description||Pattern value example|
||Specifies the minimum size (Width, Height) for the control. When the container for the control is smaller than this size, horizontal and vertical scrollbars appear.||(100,100)|
||Specifies in pixels the amount of space around the control and between the control and its neighbors (top, bottom, left, right).||(2,0,2,0)|
||Specifies, in pixels, the amount of space around the outside border of the control (top, bottom, left, right).||(2,0,2,0)|
For each form control, you can specify an optional label and the position of the label by using the
LabelPosition attributes. The label can specify a different name than the friendly name that is assigned by the
FIELD element. If you do not specify a label, the friendly name is used. However, note that the friendly name is always used when a team member runs a query to search for work items. The maximum label size is 80 characters.
You must define the same label position to all controls that are defined in the same group.
If you want to add the field in more than one area of the form, such as on the top of the form and on a tab, you can do so by using the
Name attribute. The
Name attribute just identifies the control as distinct from the other control that is added to the form.
Make a field Read-Only
You can mark a field as read-only in one of two ways. In the first method, you add the
READONLY element as a child to the
FIELD element in the
FIELDS section of the type definition. By using the
READONLY element, you can specify whether certain users can modify the field. As shown in the following example, only program managers can modify a Sub-Title field.
<FIELD name="Sub-Title" refname="ACME.ACE.SubTitle" type="String" > <READONLY for="[Global]\Team Foundation Valid Users" not="Program Managers"/> </FIELD>
In the second method, you specify the
ReadOnly attribute for the
CONTROL element. In this method, all users are restricted from modifying the field.
Control FieldName=" ACME.ACE.SubTitle" Type="FieldControl" Label="Sub-Title" LabelPosition="Left" ReadOnly="True" />
Add text and number fields
You use the
FieldControl type to add plain text and number fields to a form. This attribute is also used to add pick lists; fields that are used to display person names, such as the Assigned To or Owner fields; and integer and real numbers. The field control must refer to a field by its reference name. The field label can be plain text or styled as a hyperlink. For more information, see Provide help text, hyperlinks, or web content.
Text, Integer, and Pick List Fields
You can control the format of number fields and the maximum length of characters that can be entered in a text or number field by using the optional attributes that are described in the following table.
||Specifies the characters that you can enter in the field control. Valid values are as follows:
||Specifies the maximum length of characters that you can use for a field control.|
The following code lists the syntax that is used to create the group of fields that appears in the previous illustration.
<TABGROUP> <TAB Label="Planning"> <Group Label="Status" Padding="(0,0,0,3)"> <Column PercentWidth="100"> <Control FieldName="Microsoft.DevDiv.Importance" Type="FieldControl" Label="Importance" LabelPosition="Left" /> <Control FieldName="Microsoft.DevDiv.Commitment" Type="FieldControl" Label="Commitment / Confidence" LabelPosition="Left" /> <Control FieldName="Microsoft.DevDiv.VisionDoc" Type="FieldControl" Label="Vision Doc" LabelPosition="Left" /> <Control FieldName="Microsoft.DeveloperDivision.Features.EstimatedCost" Type="FieldControl" Label="Estimated Cost" LabelPosition="Left" /> <Control FieldName="Microsoft.DevDiv.BusinessUnit" Type="FieldControl" Label="BU (Use Area Path)" LabelPosition="Left" /> <Control FieldName="Microsoft.DevDiv.Website" Type="FieldControl" Label="Website" LabelPosition="Left" /> </Column> </Group> . . . </TAB> </TABGROUP>
Add rich-text formatted text fields
You use the
HTMLFieldControl type to add fields whose data type is
HTML. This control provides support to display formatted text over multiple lines.
<Control Type="HtmlFieldControl" FieldName="Microsoft.VSTS.ReproSteps" Label="Repro Steps" LabelPosition="Top" MinimumSize="(100,500)" />
When you add several
HTMLFieldControl elements on a form that will be stacked vertically, you should specify the
MinimumSize attribute for each field control. In this manner, you can make the text boxes all a similar size. Otherwise, the last HTML control element is sized to fill the form, and the previous elements appear together with smaller text boxes.
Add Date or Calendar fields
You use the
DateTimeControl type to give users a calendar picker to select a date for a
DateTime field. By using this control, you can quickly select a date and time for the field.
**Calendar Field with Format="Short" **
For example, you can specify a preferred start date or a review date that is in the future.
<Control Type="DateTimeControl" FieldName="MyCompany.EnvironmentCR.PreferredStart" Label="Preferred Start Date:" LabelPosition="Left" Format="Short" /> <Control Type="DateTimeControl" FieldName="MyCompany.EnvironmentCR.PreferredStartTime" Label="Preferred Start Time:" LabelPosition="Left" Format="Time" />
You can control the format of the
DateTime field by using the optional attributes that are described in the following table.
||Specifies the format for the date-time field that corresponds to one value of the DateTimePickerFormat enum. Valid values are as follows:
When you specify
||Specifies the custom format that is used for the date-time field that corresponds to the syntax that is defined for the DateTimePicker.CustomFormat property. For example:
CustomFormat = "MMM dd, 'of the year' yyyy"
For more information, see the Microsoft Web site: DateTimePicker.CustomFormat Property.
Add fields for area and iteration paths
You use the
WorkItemClassificationControl type to add fields whose data type is
TreePath. This control provides support to display area path fields and iteration path fields in a hierarchical, nested tree format. The tree shows hierarchical nodes that you can expand and collapse.
<Control Type="WorkItemClassificationControl" FieldName="System.AreaPath" Label="Area"LabelPosition="Left" />
You can use the
WorkItemClassificationControl to display the
System.IterationPath fields. You cannot display any other type of field or custom field by using this control.
For more information, see Customize area or iteration paths.