All FORM XML Elements Reference

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

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

<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="(top, bottom, left, right)" 
Margin="(top, bottom, left, right)" ReadOnly="True | False" MinimumSize="(Width,Height)" 
Name="InstanceName" />

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

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

<Layout Target="ClientName" MinimumSize="(width,height)" Padding="(top, bottom, left, right)" 
Margin="(top, bottom, left, right)" ControlSpacing="Distance" LabelSpacing="Distance">
   <Group> . . . </Group>
   <Control> . . . </Control>
   <TabGroup> . . . </TabGroup>
   <Splitter> . . . </Splitter>
</Layout>

Splitter Dock="Left" />

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

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

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

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 Provide Help Text, Process Guidance, Web Content, and Links to Web Pages on a Work Item Form.

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

<Link URLRoot="URLRoot" URLPath ="URLPathWithParameters">
   <Param />
</Link>

<Param index="IndexValue " value="ParamValue " type ="Original | Current"/>

<Text>
   <Link >
      <Param />
   </Link>
   LabelText
</Text>

Back to top

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

Back to top

See Also

Concepts

Design the Layout of the Work Item Form

Design and Customize a Work Item Form

Other Resources

Index to XML Element Definitions for Work Item Types