Design the Layout of the Work Item Form

When you design a work item form, you want to position fields on the form so that they support the data entry and workflow processes that will be followed by team members. If you are adding just a few fields to an existing form, you must determine where you want to add them on the form. If you are adding several fields to support a new collection of data to track, you may want to add a new tab just for these fields. To minimize the need to scroll a form, you can group fields into several columns in the top of the form or in a tab.

If you are adding a new work item type, you may want to copy an existing type and modify it to display the fields and workflow process that support the new type.

When you design the layout, consider the following tips to get the best results:

• Place fields at the top of the form that team members must reference or update frequently.

• Place fields on a tab that only a few team members must reference or update infrequently. For example, controls that link work items or attach files are typically positioned on separate tabs.

• Group fields into columns to maximize the display of data fields. You can use columns in the top of the form or on a tab. You can also display tabs in a multicolumn format.

• Use one or more link controls on separate tabs or on the same tab to restrict the types of links that can be created between work item types fields.

For information about how to export, import, and verify work item form changes, see Change the Work Item Form Layout.

In this topic

• Segmenting the Form into Areas

• Working with Tabs

• Grouping Fields

• Sizing Columns

• Using a Splitter to Support Variable Column Sizing

• Controlling the Size of the Form and Form Elements

• Specifying Different Layouts for Different Targets

Segmenting the Form into Areas

You use layout elements to segment your work item form into different areas, grouping related fields and allocating space on the form according to the data entry requirements. The following table describes the elements that are used to segment the form into different areas.

The following illustration shows a form whose upper area displays eight fields that are arranged roughly into two columns. The lower portion displays two sets of three tabs that are arranged in a two-column layout.

Custom Form with Three Tabs in a Two Column Layout

Top of the Form

The following code defines the top of the form. You can introduce columns as needed. As shown in this example, the first column, which is sized at 70 percent of the width of the form, contains two groups of fields. The second group of fields, which contains the PU (Use Area Path) and Priority fields, is defined in a two-column layout. The second column spans the remaining 30-percent width of the form. As the form is resized, the areas that are allocated to the columns vary proportionally.

<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>
        <Group Label="">
          <Column PercentWidth="60">
. . .
</Layout>
</FORM>

Back to top

Working with Tabs

You use tabs to cluster a group of fields or to support one or more special controls, such as the controls that link work items, link work item history, or attach files. Several definitions of work item types for the Microsoft Solutions Framework (MSF) process templates use several tabs to control the types of links that can be created, based on the link type. For more information, see Work Items and Workflow (Agile) or Work Items and Workflow (CMMI).

For more information about how to use special controls, see the following topics:

• Provide Help Text, Process Guidance, Web Content, and Links to Web Pages on a Work Item Form

• Add the Attachments Control

• Define Link Controls to Restrict Link Relationships

By using the attributes that are described in the following table, you can label the tab and specify padding and margins that control the number of pixels inside and outside the border of the tab control.

Six Tabs Arranged in a Side by Side by Layout

The following code lists the syntax that is used to create the layout that is shown in the previous illustration.

<FORM>
      <Layout>
        . . . 
            <TabGroup>
              <Tab Label="Planning">
                <Group Label="Status" Padding="(0,0,0,3)">
                  <Column PercentWidth="50">
                    <Control FieldName="Microsoft.DevDiv.Importance" Type="FieldControl" Label="Importance" LabelPosition="Left" />
                    <Control FieldName="Microsoft.DevDiv.Commitment" Type="FieldControl" Label="Commitment / Confidence" LabelPosition="Left" />
                    . . .
                  </Column>
                  <Column PercentWidth="50" />
                </Group>
                <Group>
                  <Column PercentWidth="100">
                    <Control FieldName="Microsoft.DevDiv.Story" Type="HtmlFieldControl" Label="Story Board" LabelPosition="Top" />
                  </Column>
                </Group>
                <Group>
                  <Column PercentWidth="100">
                    <Control FieldName="System.Description" Type="HtmlFieldControl" Label="Value Proposition Description" LabelPosition="Top" />
                  </Column>
                </Group>
              </Tab>
              <Tab Label="Marketing">
                <Group>
                  <Column PercentWidth="100">
                    <Control FieldName="Microsoft.DevDiv.MarketingOwner" Type="FieldControl" Label="Marketing Owner" LabelPosition="Top" />
                    <Control FieldName="Microsoft.DevDiv.MarketingDescription" Type="HtmlFieldControl" Label="Marketing Description" LabelPosition="Top" />
                  </Column>
                </Group>
              </Tab>
              <Tab Label="Relationships">
                <Control Type="LinksControl" Label="Pillars" LabelPosition="Top" Name="Pillars">
                  . . . 
                </Control>
                <Control Type="LinksControl" Label="Experiences - Feature Groups" LabelPosition="Top" Name="Experiences">
                  . . . 
                </Control>
                <Control Type="LinksControl" Label="Flags / Associations" LabelPosition="Top" Name="Flags">
                  . . . 
                </Control>
              </Tab>
            </TabGroup>
          </Column>
          <Column PercentWidth="40">
            <TabGroup>
              <Tab Label="History">
                <Control FieldName="System.History" Type="WorkItemLogControl" Label="Detailed Description and History" LabelPosition="Top" Dock="Fill" />
              </Tab>
              <Tab Label="Links">
                <Control Type="LinksControl" LabelPosition="Top" >
                  . . . 
                </Control>
              </Tab>
              <Tab Label="File Attachments">
                <Control Type="AttachmentsControl" LabelPosition="Top" />
              </Tab>
            </TabGroup>
          </Column>
        </Group>
      </Layout>
</FORM>

Back to top

Grouping Fields

You use the Group element to visually group elements, similar to the Windows GroupBox. By using the attributes that are described in the following table, you can label each group and specify padding and margins that control the number of pixels inside and outside the border of the group area. The Group element should always be followed by a Column element, even if the group has only one column.

You should use the Group element as a container for fields in a column and as a container for columns in a segmented area on the form. You can specify the Column element only as a child element in a Group element.

You can control the spacing and size of the overall form layout by specifying the attributes that are described in the following table.

Group of Fields Arranged on a Tab

The following code lists the syntax that is used to create the group of fields that is shown in the previous illustration. For more information about how to specify the fields by using the Control element, see Control the Display of Work Item Fields.

<TabGroup>
<Tab Label="Planning">
<Group Label="Status" Padding="(0,0,0,3)">
   <Column PercentWidth="5100">
      <Control FieldName="Microsoft.DevDiv.Importance" Type="FieldControl" Label="Importance" LabelPosition="Left" />
      <Control FieldName="Microsoft.DevDiv.Commitment" Type="FieldControl" Label="Commitment / Confidence" LabelPosition="Left" />
      <Control FieldName="Microsoft.DevDiv.VisionDoc" Type="FieldControl" Label="Vision Doc" LabelPosition="Left" />
      <Control FieldName="Microsoft.DeveloperDivision.Features.EstimatedCost" Type="FieldControl" Label="Estimated Cost" LabelPosition="Left" />
      <Control FieldName="Microsoft.DevDiv.BusinessUnit" Type="FieldControl" Label="BU (Use Area Path)" LabelPosition="Left" />
      <Control FieldName="Microsoft.DevDiv.Website" Type="FieldControl" Label="Website" LabelPosition="Left" />
   </Column>
</Group>
   . . .
</Tab>
</TabGroup>

Back to top

Working with Columns

You can design an area in a form that has two or more columns. You can specify the column width as fixed or as a percentage of the width of the containing element by using the FixedWidth or PercentWidth attributes, respectively. These two Column attributes are mutually exclusive. To allow a user to resize the column, you can specify a Splitter control, as Using a Splitter to Support Variable Column Sizing describes.

Three-Column Layout

The following code produced the previous three-column layout of fields. When you organize groups of fields into columns, use the Group element to contain each column of fields. Optionally, you can label the groups of fields.

<FORM>
   <Layout>
      <Group>
          <Column PercentWidth="36">
            <Group>
            <Control FieldName="System.Title" Type="FieldControl" Label="Title" LabelPosition="Left" />
            <Control FieldName="System.AreaPath" Type="WorkItemClassificationControl" Label="Area" LabelPosition="Left" />
            <Control FieldName="Microsoft.VSTS.Common.ProductUnit" Type="FieldControl" Label="Product Unit" LabelPosition="Left" />
            <Control FieldName="Microsoft.DevDiv.BusinessUnit" Type="FieldControl" Label="Business Unit" LabelPosition="Left" />
            </Group>
          </Column>
          <Column PercentWidth="33">
            <Group>
            <Control FieldName="Microsoft.DevDiv.SubTitle" Type="FieldControl" Label="Sub Title" LabelPosition="Left" />
            <Control FieldName="System.IterationPath" Type="WorkItemClassificationControl" Label="Iteration" LabelPosition="Left" />
            <Control FieldName="Microsoft.DevDiv.Other" Type="FieldControl" Label="Other" LabelPosition="Left" />
            </Group>
          </Column>
          <Column PercentWidth="31">
            <Group>
            <Control FieldName="Microsoft.DevDiv.Type" Type="FieldControl" Label="Type" LabelPosition="Left" />
            <Control FieldName="System.AssignedTo" Type="FieldControl" Label="Assigned To" LabelPosition="Left" />
            <Control FieldName="System.State" Type="FieldControl" Label="State" LabelPosition="Left" />
            </Group>
          </Column>
      </Group>
. . .
   </Layout>
</FORM>

Using a Splitter to Support Variable Column Sizing

You use the Splitter element when you want to allow the viewer of the form to dynamically resize the columns. The splitter appears as a dotted line on the form, as shown in the following illustration. You cannot specify any child elements in the Splitter element.

2-Column Layout with Splitter

A Group element that contains Splitter and Column elements must specify exactly three Column elements in the following sequence:

1. a Column to the left of the splitter

2. a Column that contains only the Splitter element

3. a Column to the right of the splitter

See the following example for more information.

<Group>
   <Column PercentWidth="50">
      <Group Label="First Group Left ">
         <Column PercentWidth="50">
            <Control FieldName="Microsoft.VSTS.Common.Priority" Type="FieldControl" Name="Pri2" Label="Priority:" />
            <Control FieldName="Microsoft.VSTS.Common.Rank" Type="FieldControl" Label="Stack Rank:" />
            <Control FieldName="Microsoft.VSTS.Scheduling.BaselineWork" Type="FieldControl" Label="Original Estimate:" />
            <Control FieldName="Microsoft.VSTS.Scheduling.RemainingWork" Type="FieldControl" Label="Remaining:" />
   </Column>
   <Column>
      <Splitter>
   </Column>
   <Column PercentWidth="50">
      <Group Label="Second Group Right">
            <Control Type="DateTimeControl" FieldName="ABC_Company.Project.Manual.ChangeDate" Label="Change Date" Format="Short" LabelPosition="Right" />
            <Control Type="DateTimeControl" FieldName="ABC_Company.Project.Manual.EstimateStartDate" Label="Estimated Start Date" Format="Short" LabelPosition="Right" />
            <Control Type="DateTimeControl" FieldName="ABC_Company.Project.Manual.ActualStartDate" Label="Actual Start Date" Format="Short" LabelPosition="Right" />
            <Control Type="DateTimeControl" FieldName="ABC_Company.Project.Manual.FinishDate" Label="Finish Date" Format="Short" LabelPosition="Right" />
      </Group>
   </Column>
</Group>

Back to top

Controlling the Size of the Form and Form Elements

You can specify the minimum horizontal and vertical size of each form layout by using the MinimumSize attribute for the layout. However, the form is resized according to the combined dimensions when the combined horizontal and vertical sizes of the field controls and layouts that are defined for each form are larger than the specified minimum dimensions. In addition, the vertical size of all tabs conforms to the dimension that is required to size the tab with the maximum vertical layout. The last field control on each tab may be resized accordingly to fill in the vertical dimension.

Scrollbars appear when the container that is displaying the form layout is smaller than the minimum horizontal or vertical size of the form. If this occurs, double-scroll problem might occur. With double-scroll, users may have to scroll both the form itself and the field control to find the information that they want. To avoid the double-scroll problem, you may want to place field controls that are subject to scrolling, such as HTML and History fields, on their own tab.

Back to top

Controlling the Size of the Layout

You can control the spacing and size of the overall form layout by specifying the attributes that are described in the following table.

Back to top

Controlling the Size of Form Elements

You use the Control element MinimumSize attribute to specify the minimum width and height that each form element should occupy. If you do not have sufficient vertical space, a scrollbar appears to keep its minimum size. Without this attribute, the controls are drawn by using their default sizes, unless controls in other tabs take more space that increases the size of the tab. You can use other attributes, such as Dock, Margin, and Padding, to align or stretch the control and define the size of the border around the control. For more information, see the following topics:

• Control the Display of Work Item Fields

• Provide Help Text, Process Guidance, Web Content, and Links to Web Pages on a Work Item Form

• Add the Attachments Control

• Define Link Controls to Restrict Link Relationships

Back to top

Specifying Different Layouts for Different Targets

You can specify different layouts for different targets by using the Layout element Target attribute. To target Visual Studio or Team Explorer Everywhere, you specify WinForms, and to target Team Web Access, you specify Web.

<FORM>
   <Layout Target="WinForms" >
      . . . 
   </Layout>
   <Layout Target="Web" >
      . . . 
   </Layout >
</FORM>

Back to top

See Also

Tasks

Change the Work Item Form Layout

Concepts

Design and Customize a Work Item Form

Control the Display of Work Item Fields

Add the Attachments Control

Define Link Controls to Restrict Link Relationships

Other Resources

Provide Help Text, Process Guidance, Web Content, and Links to Web Pages on a Work Item Form