Share via


Control XML Element Reference

You use the Control element to define a work item field, text, hyperlink, or other control element to display in a work item form. For examples of how to use this element, see Specifying Work Item Form Controls. For more information, see Designing and Customizing a Work Item Form.

Schema Hierarchy

WITD

   WORKITEMTYPE

       FORM

           Layout

               Group

               Column

               Tab

<xs:element name="Control" type="ControlType" minOccurs="0"/>

<Control FieldName="FieldName" Type="AttachmentsControl | DateTimeControl | FieldControl | 
HtmlFieldControl | LabelControl | LinksControl | WebpageControl | WorkItemClassificationControl | 
WorkItemLogControl" Label="LabelText" LabelPosition="Top | Bottom | Left | Right" 
Dock="Fill | Top | Bottom | Left | Right" Padding="(left, top, right, bottom)" 
Margin="(left, top, right, bottom)" ReadOnly="True | False" MinimumSize="(width,height)" 
Name="InstanceName" >
<LabelText> . . . </LabelText>
<Link> . . . </Link>
<LinksControlOptions> . . . </LinksControlOptions>
<WebpageControlOptions> . . . </WebpageControlOptions>
</Control>

Attributes and Elements

The following sections describe attributes, child elements, and parent elements.

Attributes

Attribute

Description

FieldName

Optional ControlType attribute.

Specifies the work item field with which the control is associated. The attribute type is typelib:ReferenceFieldName. Minimum length: 1; maximum length: 70.

Pattern value: ^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z0-9_]+)+$

Pattern value example: Company.Division.IssueType

Type

Required ControlType attribute.

Specifies the data type of the control. The attribute type is ValidControlsType Simple Type. Specify a string from one of the following built-in types:

  • AttachmentControl: Use to display work item attachments. This control does not have an associated field or field type.

  • DateTimeControl: Use to display formatted date fields with a field type of DateTime.

  • FieldControl: Use to display plain textual or numeric fields and lists of values for fields with a field type of String, Identity, Integer, Double, and PlainText.

  • HtmlFieldControl: Use to display multi-line, rich-text format of fields with a field type of HTML.

  • LabelControl: Use to display text that is not associated with a field. The text can be plain or hyperlinked.

  • LinksControl: Use to display work item links. This control does not have an associated field or field type.

  • WebpageControl: Use to display HTML-based content defined by a URI or embedded within a CDATA tag. This control does not have an associated field or field type.

  • WorkItemClassificationControl Use to display the hierarchical path fields with a field type of TreePath.

    NoteNote
    The System.AreaPath and System.IterationPath fields are the only fields that use this data type. You cannot define a custom field using this data type.
  • WorkItemLogControl: Use to display work item history information and fields with a field type of History.

    NoteNote
    The System.History field is the only field that uses this data type. You cannot define a custom field using this data type.

For more information, see Specifying Work Item Form Controls.

NoteNote
You can use a custom control by setting the Type attribute to a custom value. Any control whose Type value does not match the name of a built-in type is considered a custom control. For more information, see the Microsoft Web site: Work Item Tracking Custom Controls.

Label

Optional ControlType attribute.

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

LabelPosition

Optional ControlType attribute.

Specifies the position of the label relative to the control data. Specify a string from one of the following values:

  • Top: Places the label above the control data.

  • Bottom: Places the label below the control data.

  • Left: Places the label to the left of the control data.

  • Right: Places the label to the right of the control data.

Dock

Optional ControlType attribute.

Aligns the field together with the specified side of the container, or stretches the field to fill the container. The attribute type is DockType. Specify a string from one of the following values:

  • Fill: Aligns the field so that it fills the container. This value is not a supported orientation for the Splitter Element.

  • Top: Aligns the field together with the top of the container. This value is not a supported orientation for the Splitter Element.

  • Bottom: Aligns the field together with the bottom of the container. This value is not a supported orientation for the Splitter Element.

  • Left: Aligns the field together with the left side of the container.

  • Right: Aligns the field together with the right side of the container. This value is not a supported orientation for the Splitter Element.

Padding

Optional ControlType attribute.

Specifies the amount of space in pixels around the inside border of the control which corresponds to the top, bottom, left, and right spaces. The attribute type is SizeType.

Pattern value: ^\(\d+\,\d+\,\d+\,\d+\)$

Pattern value example: (2,0,2,0)

Margin

Optional ControlType attribute.

Specifies the amount of space in pixels around the outside border of the control which corresponds to the top, bottom, left, and right spaces. The attribute type is SizeType.

Pattern value: ^\(\d+\,\d+\,\d+\,\d+\)$

Pattern value example: (2,0,2,0)

ReadOnly

Optional ControlType attribute.

Specifies that the field is read-only. The attribute type is ReadOnlyType. Specify a string from one of the following values:

  • True: Specifies that the control data is read-only.

  • False: Specifies that the control data is not read-only.

MinimumSize

Optional ControlType attribute.

Specifies the minimum size in pixels that the control should occupy in the form. The syntax is specified in (width,height). The attribute type is SizeType.

Pattern value: ^\(\d+\,\d+\)$

Pattern value example: (100,100)

NoteNote
If you do not have sufficient vertical space, then a scrollbar appears to keep its minimum size. Without this attribute, the controls are drawn with their default sizes, unless controls in other tabs take more space. The overall size of any one form control depends on the size of the largest form area or tab.

Name

Optional ControlType attribute.

Identifies a control uniquely. The Name is important if more than one control on the form is associated with the same work item field. The attribute type is xs:string.

NoteNote
You use the Name attribute when you want to have the same field displayed in more than one location on the form. You specify a unique value for the Name attribute for both control entries so that the system identifies each control uniquely. It is useful to show the same control in various locations based on the context of tabs.

NumberFormat

Optional ControlType attribute that is valid only when it is used with FieldControl.

Specifies the characters that you can enter in the field control. Valid values that you can use are as follows:

  • WholeNumbers: Specifies that whole numbers are allowed.

  • SignedWholeNumbers: Specifies that signed whole numbers are allowed.

  • DecimalNumbers: Specifies that decimal numbers are allowed.

  • SignedDecimalNumbers: Specifies that signed decimal numbers are allowed.

MaxLength

Optional ControlType attribute that is valid only when it is used with FieldControl.

Specifies the maximum length of allowed characters for a field control. The attribute type is xs:integer.

Format

Optional ControlType attribute that is valid only when it is used with DateTimeControl.

Specifies the format for the date-time field corresponding to one of the values of the DateTimePickerFormat enum. Valid values that you can use are as follows:

  • Custom: Displays the date/time value in a custom format. The Custom format can be set by specifying 'Custom' as the value for the Format attribute, and setting another attribute named CustomFormat with a custom format string. For example:

    Format="Custom"

    CustomFormat = "MMM dd, 'of the year' yyyy "

    For more information, see the Microsoft Web site: DateTimePicker.CustomFormat Property.

  • Long: Displays the date/time value in the long date format set by the user's operating system.

  • Short: Displays the date/time value in the short date format set by the user's operating system.

  • Time: Displays the date/time value in the time format set by the user's operating system.

For more information, see the Microsoft Web site: DateTimePickerFormat Enumeration.

CustomFormat

Optional ControlType attribute that is valid only when it is used with DateTimeControl and the Format attribute.

Specifies the custom format for the date-time field corresponding to the syntax defined for the DateTimePicker.CustomFormat property. For more information, see the Microsoft Web site: DateTimePicker.CustomFormat Property.

Child Elements

Element

Description

LabelText

Optional element. You can specify this element when ControlType is specified as FieldControl or LabelControl.

Container element for specifying the text, hyperlink, and position of a field or label whose text is partly associated with a hyperlink.

For more information, see LabelText and Text XML Elements Reference and Providing Help Text, Process Guidance, Web Content, and Links to Web Pages on a Work Item Form.

Link

Optional element. You can specify this element when ControlType is specified as FieldControl or LabelControl.

Defines the hyperlink for a field or label.

For more information, see Link and Param XML Elements Reference and Providing Help Text, Process Guidance, Web Content, and Links to Web Pages on a Work Item Form.

LinksControlOptions

Optional element. You can specify this element when ControlType is specified as LinksControl.

Defines the link filters and layout of column fields to display the list of links.

For more information, see Defining Link Controls to Restrict Link Relationships.

WebpageControlOptions

Optional element. You can specify this element when ControlType is WebpageControl.

Specifies the controls that govern loading the Web page target in the work item form.

For more information, see WebpageControlOptions XML Elements Reference and Providing Help Text, Process Guidance, Web Content, and Links to Web Pages on a Work Item Form.

anyAttribute

Optional element.

Optional. ControlType is extensible through use of the anyAttribute element. ProcessContents: skip.

Parent Elements

Element

Description

Layout

Required. Defines how to display the elements on the work item form.

Column Element

Required. Defines columns for the form.

Tab Element

Required. Defines a tab for the form.

Remarks

Control is an optional child element of Layout, Column, and Tab.

Layout and Column indicators:

minOccurs = "0"

maxOccurs = "1"

Tab indicators:

minOccurs = "0"

maxOccurs = "unbounded"

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

For an example of each control type, see Specifying Work Item Form Controls.

Example

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

Element Information

Namespace

https://schemas.microsoft.com/VisualStudio/2008/workitemtracking/typedef

Schema Name

Work Item Type Definition

Validation File

WorkItemTypeDefinition.xsd

Element Type

ControlType Complex Type

Can Be Empty

Not applicable

See Also

Concepts

Designing and Customizing a Work Item Form

All FORM XML Elements Reference

Specifying Work Item Form Controls

Change History

Date

History

Reason

January 2011

Added child elements to the syntax, removed or replaced links to topics that have been removed.

Information enhancement.