Share via

All FORM XML Elements Reference

  • Article

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 Designing the Layout of the Work Item Form.

In this topic

  • FORM Example

  • Syntax for FORM Elements

  • Attributes that FORM Elements Specify

  • Elements that Specify Standalone Labels, Hyperlinks, Web Pages, or HTML Content

  • Elements that Filter and Display Link Relationships

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.

<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="&amp;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.

<Column PercentWidth="WidthPerceOfContainingElement" FixedWidth="WidthInPixels">
   <Group> . . . </Group
   <Control> . . . </Control>
   <TabGroup> . . . </TabGroup>
   <Splitter> . . . </Splitter>
</Column >

Recommended

Control

Defines a field, text, hyperlink, or other control element to appear on the work item form.

<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" />

For more information, see Control XML Element Reference.

Required

FORM

Defines the top-level form element.

<FORM>
   <Layout> . . . </Layout>
</FORM>

Required

Group

Provides a visual grouping of elements, similar to the Windows GroupBox.

<Group Label="LabelText" Padding="(left, top, right, bottom)" Margin="(left, top, right, bottom)">
   <Column> . . . </Column>
</Group >

Recommended

Layout

Defines the layout of the work item form.

<Layout Target="ClientName" MinimumSize="(width,height)" Padding="(left, top, right, bottom)" 
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.

Splitter Dock="Left" />

Optional

Tab

Defines the layout of a single tab in a tab group.

<Tab Label="LabelText" Padding="(left, top, right, bottom)" Margin="(left, top, right, bottom)">
   <Group> . . . </Group
   <Control> . . . </Control>
   <TabGroup> . . . </TabGroup>
   <Splitter> . . . </Splitter>
</Tab>

Optional

TabGroup

Defines one or more tabs for the form.

<TabGroup Padding="(left, top, right, bottom)" Margin="(left, top, right, bottom)">
   <Tab> . . . </Tab>
</TabGroup>

Optional

Back to top

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 Designing the Layout of the Work Item Form.

Attribute

Description

Applicable Elements

ControlSpacing

Optional. Specifies the vertical offset of controls. Integer.

Layout

Dock

Optional. Stretches a field control or a splitter to fill the rest of the container. Valid field docking values are as follows: Fill, Top, Bottom, Left, and Right.

  • Fill: Aligns the field so that it fills the container.

  • Top: Aligns the field with the top of the container.

  • Bottom: Aligns the field with the bottom of the container.

  • Left: Aligns the field or splitter with the left side of the container. This value is the only supported orientation for the SPLITTER element.

  • Right: Aligns the field or splitter with the right side of the container.

Control

Splitter

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 (left, top, right, bottom) 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:

  • WinForms: Applies the form to Team Explorer and Team Explorer Everywhere.

  • Web: Applies the form to Team Web Access.

Layout

Type

Required. The type of the control. For more information, see Control XML Element Reference.

Control

Back to top

Elements that Specify Stand-Alone Labels, Hyperlinks, Web Pages, or HTML Content

The WebpageControlOptions element and its child elements have the following syntax structure:

<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 Providing Help Text, Process Guidance, Web Content, and Links to Web Pages 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.

<Content>
   <![CDATA[Contents of HTML]]>
</Content>

For more information, see WebpageControlOptions XML Elements Reference.

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.

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

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

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

Back to top

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:

<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 Defining Link Controls to Restrict Link Relationships and LinksControlOptions Elements.

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.

Back to top

See Also

Concepts

Designing the Layout of the Work Item Form

Designing and Customizing a Work Item Form

Other Resources

Index to XML Element Definitions for Types of Work Items