You can use the information in this topic as a quick reference to all the elements and main attributes that control the form for a type of work item. You specify these elements in the FORM element container, the third and final major section of the definition of a type of work item. Many elements are nested within others to form groups, sections, or tabs in a work item form. For more information about how to group these elements, see Design the work item form.
In this topic
Elements that specify standalone Labels, Hyperlinks, Web Pages, or HTML content
FORM example
The following example shows the overall structure of the FORM element. You specify the layout of a form by using the Layout element. You can specify different layouts that target different clients. For example, you can specify one layout for Windows clients and a different layout for Team Web Access. A layout typically consists of the top of the form and then a group of tabs. The sequence in which you define the elements within the layout determines the sequence in which the elements appear on the form.
You group elements to appear within columns by using the Group and Column elements. You use a Control element to define each field that you want to appear on the form. You use the Tab element to support different functional areas of field groups.
 Copy Code | |
|---|---|
<FORM>
<Layout>
<Group>
<Column PercentWidth="70">
<Group>
<Column PercentWidth="100">
<Control FieldName="System.Title" Type="FieldControl" Label="Title" LabelPosition="Left" />
<Control FieldName="System.AreaPath" Type="WorkItemClassificationControl" Label="Area Path" LabelPosition="Left" />
<Control FieldName="System.IterationPath" Type="WorkItemClassificationControl" Label="&Iteration Path:" LabelPosition="Left" />
<Group>
<Column PercentWidth="50">
<Control FieldName="Microsoft.VSTS.Common.ProductUnit" Type="FieldControl" Label="PU (Use Area Path)" LabelPosition="Left" />
</Column>
<Column PercentWidth="50">
<Control FieldName="Microsoft.VSTS.Common.Priority" Type="FieldControl" Label="Priority" LabelPosition="Left" />
</Column>
</Group>
</Column>
</Group>
</Column>
<Column PercentWidth="30">
<Group Label="Status">
<Column PercentWidth="100">
<Control FieldName="System.Id" Type="FieldControl" Label="Id" LabelPosition="Left" />
<Control FieldName="System.State" Type="FieldControl" Label="State" LabelPosition="Left" />
<Control FieldName="System.AssignedTo" Type="FieldControl" Label="Assigned To" LabelPosition="Left" />
</Column>
</Group>
</Column>
</Group>
. . .
</Layout>
</FORM> | |
Form elements
You can specify how information and work item fields are grouped and appear in a work item form using the elements that are described in the following table.
 Note |
|---|
For best results, you should nest Control elements in a Group, and you should nest Group elements in a Column, even if the column spans the full width of the form. Also, you should nest every Column section in a Group, even if the group has no visible label or boundary. |
Element | Description | Required? | |||||
|---|---|---|---|---|---|---|---|
Column | Divides a form's regions into columns.
| Recommended | |||||
Control | Defines a field, text, hyperlink, or other control element to appear on the work item form.
For more information, see | ||||||
Required
FORM
Defines the top-level form element.
| Copy Code | |
|---|---|
<FORM> <Layout> . . . </Layout> </FORM> | |
Required
Group
Provides a visual grouping of elements, similar to the Windows GroupBox.
| Copy Code | |
|---|---|
<Group Label="LabelText" Padding="(top, bottom, left, right)" Margin="(top, bottom, left, right)">
<Column> . . . </Column>
</Group > | |
Recommended
Layout
Defines the layout of the work item form.
| Copy Code | |
|---|---|
<Layout Target="ClientName" MinimumSize="(width,height)" Padding="(top, bottom, left, right)" Margin="(left, top, right, bottom)" ControlSpacing="Distance" LabelSpacing="Distance"> <Group> . . . </Group> <Control> . . . </Control> <TabGroup> . . . </TabGroup> <Splitter> . . . </Splitter> </Layout> | |
Required
Splitter
Divides a form into two areas to support the layout of two sibling form elements.
| Copy Code | |
|---|---|
Splitter /> | |
Optional
Tab
Defines the layout of a single tab in a tab group.
| Copy Code | |
|---|---|
<Tab Label="LabelText" Padding="(top, bottom, left, right)" Margin="(top, bottom, left, right)">
<Group> . . . </Group
<Control> . . . </Control>
<TabGroup> . . . </TabGroup>
<Splitter> . . . </Splitter>
</Tab> | |
Optional
TabGroup
Defines one or more tabs for the form.
| Copy Code | |
|---|---|
<TabGroup Padding="( top, bottom, left, right)" Margin="(top, bottom, left, right)"> <Tab> . . . </Tab> </TabGroup> | |
Optional
Attributes that Are Used to Format FORM Elements
You can control the spacing and size of many elements on a work item form by specifying the attributes that the following table describes. For more information, see Design the work item form.
Attribute | Description | Applicable Elements |
|---|---|---|
ControlSpacing | Optional. Specifies the vertical offset of controls. Integer. | Layout |
FixedWidth | Optional. The column width in pixels. PercentWidth and FixedWidth are mutually exclusive. | Column |
Label | Optional. Text to appear for a control or group. If a label is specified, it overrides any label that is associated with the field in the metadata for the control. Required for the Tab element. Text to appear for a tab. LabelText is a text string that contains between 1 and 80 characters. | Control Group Tab |
LabelPosition | Optional. The label position relative to the field data. Possible values are Top, Bottom, Left, and Right. | Control |
LabelSpacing | Optional. Specifies the number of pixels between the label and the edit region of the control. | Layout |
Margin | Optional. String of the form (left, top, right, bottom) that specifies, in pixels, the amount of space around the control and between the control and its neighbors. You can vary the amount of space on each side. Pattern value: ^\(\d+\,\d+\,\d+\,\d+\)$ Pattern value example: (2,0,2,0) | Control Group Layout Tab TabGroup |
MinimumSize | Optional. String of the form (width, height). This value specifies the minimum size for the form itself. When the container control smaller than this size, horizontal and vertical scrollbars appear. | Control Layout |
Name | Optional. Name for the control. If unspecified, the name is the same as the FieldName. | Control |
Padding | Optional. String of the form (top, bottom, left, right) that specifies, in pixels, the amount of room around the outside border of the control and around the inside border. You can vary the amount of space on each side. | Control Group Layout Tab TabGroup |
PercentWidth | Optional. The column width as a percentage of the containing element's width. PercentWidth and FixedWidth are mutually exclusive. | Column |
ReadOnly | Optional. You can display a read-only field in a control. Different controls respond to this attribute in slightly different ways. | Control |
Target | Optional. String that specifies to which client this layout applies. Visual Studio displays this work item type in this layout if the Target attribute is omitted or set to Windows Forms. External clients can specify additional layouts by using custom Target attributes that Visual Studio ignores. The following values are valid:
| Layout |
Type | Required. The type of the control. For more information, see |
Control
Elements that specify stand-alone Labels, Hyperlinks, Web Pages, or HTML Content
The WebpageControlOptions element and its child elements have the following syntax structure:
| Copy Code | |
|---|---|
<WebpageControlOptions AllowScript="true | false" ReloadOnParamChange="true | false" > <Link UrlRoot="UrlRoot" UrlPath ="UrlPathWithParameters"> <Param index="IndexValue" value="ParamValue" type ="Original | Current"/> </Link> <Content> <![CDATA[Contents of HTML]]> </Content> </WebpageControlOptions> | |
You use the elements that are described in the following table to define plain text or hyperlinked labels, add hyperlinks to a field, or display Web page content in a work item form. For more information, see Provide help text, hyperlinks, or web content on a work item form.
Element | Required? | Description | ||||
|---|---|---|---|---|---|---|
Content | Optional WebpageControlOptions element. | Specifies the CDATA HTML-based content to appear in a work item form.
For more information, see | ||||
LabelText
Optional Control element when type="LabelControl".
Defines either a plain or hyperlinked label.
For more information, see LabelText and Text XML Elements Reference.
Link
Optional Control element when type="FieldControl".
Optional Text element.
Optional WebpageControl element.
Optional WebpageControlOptions element.
Defines the hyperlink for a field, label, or Web browser content to appear in a work item form.
| Copy Code | |
|---|---|
<Link URLRoot="URLRoot" URLPath ="URLPathWithParameters">
<Param />
</Link> | |
For more information, see Link and Param XML Elements Reference.
Param
Optional Link element.
Specifies a value to determine the URL of the hyperlink when URLPath is specified for the Link element.
| Copy Code | |
|---|---|
<Param index="IndexValue " value="ParamValue " type ="Original | Current"/> | |
For more information, see Link and Param XML Elements Reference.
Text
Optional LabelText element.
Container element for the information or label to appear on the work item form.
| Copy Code | |
|---|---|
<Text>
<Link >
<Param />
</Link>
LabelText
</Text> | |
For more information, see LabelText and Text XML Elements Reference.
WebpageControlOptions
Optional Control element when type="WebpageControl"
Container element that specifies the options for the Web page control.
For more information, see WebpageControlOptions XML Elements Reference.
Elements that filter and display link relationships
You use the LinksControlOptions element to define the options for controlling what links can be added to a work item and the default columns that you want to appear for the list of links in a work item. When you add link control to a work item form, you can specify filters that restrict the types of links that users can create and the types of work items between which users can create links. The LinksControlOptions element and its child elements have the following structure:
| Copy Code | |
|---|---|
<LinksControlOptions>
<WorkItemLinkFilters FilterType="include | exclude | includeAll | excludeAll">
<Filter LinkType="linkTypeRefName" FilterOn="reverseName | forwardName" />
</WorkItemLinkFilters>
<ExternalLinkFilters FilterType ="include | exclude | includeAll | excludeAll">
<Filter LinkType="externalLinkName"/>
</ExternalLinkFilters>
<WorkItemTypeFilters Scope=" project | all" FilterType=" include | exclude | includeAll" />
<Filter WorkItemType="workItemTypeReferenceName"/>
</WorkItemTypeFilters>
<LinkColumns>
<LinkColumn RefName="referenceName" | LinkAttribute="linkAttributeName"/>
</LinkColumns>
</LinksControlOptions> | |
Specifically, you use the elements that are summarized in the following table. For more information about how to use these elements, see Define link controls to restrict link relationships and
Element | Required? | Description |
|---|---|---|
LinksControlOptions | Optional Control element when type="LinksControl" | Provides a container for elements that define the options for controlling what links can be added to a work item and the default columns that you want to appear for the list of links in a work item. |
WorkItemLinkFilters | Optional LinksControlOptions element | Provides a container for one or more Filter elements that specify the link filter criteria to use for link types that are defined for the team project collection. |
ExternalLinkFilters | Optional LinksControlOptions element | Provides a container for one or more Filter elements that specify the filter criteria to use for link types that are defined in other team projects. |
WorkItemTypeFilters | Optional LinksControlOptions element | Provides a container for one or more Filter elements that specify the filter criteria to apply to work item types. |
Filter (link types) | Required WorkItemLinkFilters element when the FilterType attribute is exclude or include. Required ExternalLinkFilters element when the FilterType attribute is exclude or include. | Specifies the types of links to include or exclude from the set of links that can be created for the work item. |
Filter (work item types) | Optional WorkItemTypeFilters element when the FilterType attribute is exclude or include. | Specifies the types of work items to include or exclude from the set of work item types between which users can link. |
LinkColumns | Optional LinksControlOptions element | Provides a container for one or more LinkColumn tags. |
LinkColumn | Required LinkColumns element | Specifies the work item fields and link type attributes to appear on the work item form for the list of links. |
See Also
Concepts
Other Resources
