Designing the Layout of the Work Item Form

Artykuł
12/06/2010

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 How to: 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.

Element	Description
FORM	Contains the LAYOUT elements that specify the display of fields and controls for the work item type.
LAYOUT	Contains all elements that specify the display of fields and controls for a specific target. You can specify different layouts for different targets, such as a Windows form or a Web form. Child elements that you can specify in a LAYOUT element include CONTROL, GROUP, TABGROUP, and SPLITTER elements.
GROUP	Clusters child elements on the form. A group is visually separated by a border and an optional label. Groups that are defined in an adjacent position in the XML stack are split vertically in the displayed form. You can specify the COLUMN element as a child of a GROUP element.
COLUMN	Keeps all child elements in a vertical column or splits a form vertically. Columns must appear in a GROUP. GROUP elements in COLUMN elements can be used to create nested areas. By default, columns split a GROUP evenly. You can specify an optional percentage width attribute to allocate more space to one or more columns. Child elements that you can specify in a COLUMN element include CONTROL, GROUP, TABGROUP, and SPLITTER elements.
SPLITTER	Allows a team member to resize the width that is allocated to two columns in a form.
TAB	Adds different pages or tabs to a form to support the display of additional fields and controls. Child elements that you can specify in a TAB element include CONTROL, GROUP, TABGROUP, and SPLITTER elements.
TABGROUP	Contains a group of TAB elements. In general, you add tabs to a single tab group. However, you could stack two or more tab groups vertically in a form.

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

Custom work item form

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>

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.

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.

Attribute	Description
Label	Required. Text that specifies the name of the tab page.
Margin	Optional. Specifies, in pixels, the amount of space around the tab.
Padding	Optional. Specifies, in pixels, the amount of space around the outside and inside border of the tab.

Six Tabs Arranged in a Side by Side by Layout

Custom form showing two groups of 6 tabs

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>

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.

Attribute	Description
Label	Optional. Text that specifies the name of the group.
Margin	Optional. Specifies, in pixels, the amount of space around the group and between the control and its neighbors. You can vary the amount of space on each side.
Padding	Optional. Specifies, in pixels, the amount of space around the outside border of the group. You can vary the amount of space on each side.

Group of Fields Arranged on a Tab

Group of several fields

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 Specifying Work Item Form Controls.

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

Working with Columns

You can design an area in a form that has two or more columns. You can allocate various percentages of the form width to each column to handle fields that require more width to display their data. To let the user resize the column, you can specify a SPLITTER control, as described in Using a Splitter to Support Variable Column Sizing.

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.

3 Column Layout

3-Column Display

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

2 Column Layout with Splitter

A GROUP element that contains SPLITTER and COLUMN elements must specify exactly three COLUMN elements in the following sequence:

a COLUMN to the left of the splitter
Aa COLUMN that contains only the SPLITTER element
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>

Controlling the Size of the Form and Form Elements

The number of columns and the horizontal size that are allocated to the largest field in each column determine the horizontal dimension of a form. The number of fields that is specified in a vertical group and the vertical size that is allocated to each field determine the size of the top of the form and also the size of the bottom of the form.

By positioning each HTML text box on a separate tab, especially if these boxes may contain lots of text, you can avoid the double-scroll problem. This problem occurs when the viewer of the form has to scroll the form itself to find a text box and then scroll in the box to find the text of interest.

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.

Attribute	Description	Pattern value example
MinimumSize	Optional. String of the form (width, height). This value specifies the minimum size for the form itself. When the container control is smaller than this size, horizontal and vertical scrollbars appear.	(100,100)
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.	(2,0,2,0)
Padding	Optional. String of the form (left, top, right, bottom) that specifies, in pixels, the amount of space around the outside border of the control and around the inside border. You can vary the amount of space on each side.	(2,0,2,0)
ControlSpacing	Optional. Specifies the vertical offset of controls. Integer.	N/A

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.

Specifying Different Layouts for Different Targets

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

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

Change History

Date	History	Reason
July 2010	Added illustrations and more code samples.	Customer feedback.

Udostępnij za pośrednictwem