All FORM XML elements reference (TFS 2015)

Artículo
03/02/2017

Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018 - TFS 2013

Important

This topic applies to 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 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.

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 the web portal. 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="&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="WidthPercentOfContainingElement" 
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"
Padding="(top, bottom, left, right)" Margin="( top, bottom, 
left, right)"  
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="(top, bottom, left, right)" 
Margin="(top, bottom, left, right)">     
<Column> . . . </Column>  
</Group >

Recommended

Layout

Defines the layout of the work item form.

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

<Splitter />

Optional

Tab

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

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

<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: `WinForms`: Applies the form to Team Explorer and Team Explorer Everywhere. `Web`: Applies the form to the web portal.	`Layout`
`Type`	Required. The type of the control. For more information, see Control.	`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:

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

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.
`LabelText`	Optional `Control` element when `type="LabelControl"`.	Defines either a plain or hyperlinked label. For more information, see LabelText and Text.
`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.
`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.
`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.
`WebpageControlOptions`	Optional `Control` element when `type="WebpageControl"`	Container element that specifies the options for the Web page control. For more information, see WebpageControlOptions.

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:

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

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

Compartir a través de

All FORM XML elements reference (TFS 2015)

FORM example

Form elements

Attributes that are used to format FORM elements

Elements that specify stand-alone Labels, Hyperlinks, Web Pages, or HTML Content

Elements that filter and display link relationships

Recursos adicionales

Compartir a través de

All FORM XML elements reference (TFS 2015)

FORM example

Form elements

Attributes that are used to format FORM elements

Elements that specify stand-alone Labels, Hyperlinks, Web Pages, or HTML Content

Elements that filter and display link relationships

Related articles

Recursos adicionales