WebLayout and Control elements

Last Update: 3/6/2017

Team Services (Hosted XML) | TFS 2017

IMPORTANT

This topic applies to team project customization for Hosted XML and On-premises XML (TFS 2017 and later versions) process models. For TFS 2015, see Layout XML element reference.

For the Inheritance process model, see Customize a process. For an overview of process models, see Customize your work tracking experience.

You use the WebLayout element to define the layout and controls that appear on work item forms displayed through the web portal. It supports the new work item experience. It is in addition to the Layout element which defines the form elements that appear when viewed through Visual Studio and other non-web clients.

The WebLayout element is a required child element of the FORM element.

NOTE

When the new form roll out is enabled, the XML definitions for all work item types (WITs) in the collection are updated to include a WebLayout section within the FORM section.

The new form makes available several new features as described in New work item experience. Your account or project collection administrator manages the switch to the new form.

Summary of new and deprecated elements and attributes

The WebLayout and updated Control elements introduce several new elements and deprecate several elements and attributes. Overall, it's a much simpler syntax structure than its predecessor.

New elements

    • ControlContribution
    • GroupContribution
    • Input
    • Inputs
    • Page
    • PageContribution
    • Section
    • SystemControls
    • WebLayout

Maintained elements

    • FORM
    • Layout
    • Group
    • Control

Deprecated elements

    • Column
    • Splitter
    • Tab
    • TabGroup

Deprecated attributes

    • ControlSpacing
    • FixedWidth
    • LabelPosition
    • LabelSpacing
    • Margin
    • MinimumSize
    • Padding
    • PercentWidth

In the new web form layout, the system manages the header elements shown below. These include the display of the work item ID, Title, State, Assigned To, Area and Iteration fields, tags, as well as the pages to display History page icon History, Links page icon Links, and Attachments page icon Attachments.

Header element within web form

When you export a WIT definition, you'll see a SystemControls section at the beginning of the WebLayout section, similar to the following:

<WebLayout>
    <SystemControls>
      <Control Type="FieldControl" FieldName="System.Title" EmptyText="Enter title" />
      <Control Label="Assi&amp;gned To" Type="FieldControl" FieldName="System.AssignedTo" />
      <Control Label="Stat&amp;e" Type="FieldControl" FieldName="System.State" />
      <Control Label="Reason" Type="FieldControl" FieldName="System.Reason" />
      <Control Label="&amp;Area" Type="WorkItemClassificationControl" FieldName="System.AreaPath" />
      <Control Label="Ite&amp;ration" Type="WorkItemClassificationControl" FieldName="System.IterationPath" />
      <Control Label="History" Type="WorkItemLogControl" FieldName="System.History" />
      <Control Label="Links" Type="LinksControl" Name="Links" />
      <Control Label="Attachments" Type="AttachmentsControl" Name="Attachments" />
    </SystemControls>
...

You can modify select elements within the SystemControls section, such as changing the EmptyText attribute value for the System.Title field. In general, we recommend you don't customize this section much more than that.

The other layout elements that you can customize are those associated with a page, such as the Details page, or other custom pages that you add.

TIP

The Page element is similar to the deprecated Tab element. However, a Page element can't be grouped or nested. One page defines one tab within the web form.

This topic provides you with a quick reference to the WebLayout element and it's child elements. Use this as a guide to further customize a WIT definition that's been transformed and contains the new WebLayout section.

To customize the windows client layout, the Layout XML element.

WebLayout example

The following example shows the overall structure of the WebLayout section within the FORM section. The WebLayout specifies a Control element for each field you want to have appear on the form.

You group elements to appear within a Page by using the Section and Group elements. You use a Control element to define each field or control that you want to appear on the form.

The following example specifies the syntax for the Details page shown previously in this topic.

<FORM>
. . .
  <WebLayout>
       <SystemControls>
          <Control Type="FieldControl" FieldName="System.Title" EmptyText="Enter title" />
          <Control Label="Assi&amp;gned To" Type="FieldControl" FieldName="System.AssignedTo" />
          <Control Label="Stat&amp;e" Type="FieldControl" FieldName="System.State" />
          <Control Label="Reason" Type="FieldControl" FieldName="System.Reason" />
          <Control Label="&amp;Area" Type="WorkItemClassificationControl" FieldName="System.AreaPath" />
          <Control Label="Ite&amp;ration" Type="WorkItemClassificationControl" FieldName="System.IterationPath" />
          <Control Label="History" Type="WorkItemLogControl" FieldName="System.History" />
          <Control Label="Links" Type="LinksControl" Name="Links" />
          <Control Label="Attachments" Type="AttachmentsControl" Name="Attachments" />
        </SystemControls>
    <Page Label="Details" LayoutMode="FirstColumnWide">
        <Section>
          <Group Label="Description">
             <Control Label="Description" Type="HtmlFieldControl" FieldName="System.Description" />
          </Group>
        </Section>
        <Section>
      <Group Label="Planning">
          <Control Label="Story Points" Type="FieldControl" FieldName="Microsoft.VSTS.Scheduling.StoryPoints" />
          <Control Label="Priority" Type="FieldControl" FieldName="Microsoft.VSTS.Common.Priority" />
        </Group>
        <Group Label="Classification">
          <Control Label="Value area" Type="FieldControl" FieldName="Microsoft.VSTS.Common.ValueArea" />
        </Group>
      </Section>
      <Section>
        <Group Label="Development">
          <Control Type="LinksControl" Name="Development">
            <LinksControlOptions ViewMode="Dynamic" ZeroDataExperience="Development" ShowCallToAction="true">
              <ListViewOptions GroupLinks="false">
              </ListViewOptions>
              <LinkFilters>
                <ExternalLinkFilter Type="Build" />
                <ExternalLinkFilter Type="Pull Request" />
                <ExternalLinkFilter Type="Branch" />
                <ExternalLinkFilter Type="Fixed in Commit" />
                <ExternalLinkFilter Type="Fixed in Changeset" />
                <ExternalLinkFilter Type="Source Code File" />
              </LinkFilters>
            </LinksControlOptions>
          </Control>
        </Group>
       <Group Label="Related Work">
          <Control Type="LinksControl" Name="Related Work">
            <LinksControlOptions>
              <LinkFilters>
                <WorkItemLinkFilter Type="System.LinkTypes.Hierarchy-Reverse" />
                <WorkItemLinkFilter Type="System.LinkTypes.Hierarchy-Forward" />
                <WorkItemLinkFilter Type="System.LinkTypes.Related" />
              </LinkFilters>
              <Columns>
                <Column Name="System.State" />
                <Column Name="System.ChangedDate" />
                <Column Name="System.Links.Comment" />
              </Columns>
            </LinksControlOptions>
          </Control>
        </Group>
      </Section>
    </Page>
  </WebLayout>
</FORM>

Customize the web layout

To modify the web layout, use the information provided in this topic to modify the XML definition file for a specific work item type. To import and export your changes, see Customize the work item tracking web form.

WebLayout element syntax

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 WebLayout, you no longer add controls for attachments, links, and history. The system automatically addes these controls (AttachmentControl, LinksControl, WorkItemClassificationControl and WorkItemLogControl) are automatically added to the web form of each WIT.

Nest elements

You nest the following elements:

  • Page elements within a single WebLayout element
  • Section elements within a Page element, limit the number of Section elements to four within a Page
  • Group elements within a Section element
  • Control elements within a Group element.
TIP

The schema definition for work item tracking defines all FORM child elements as camel case and all other elements as all capitalized. If you encounter errors when validating your type definition files, check the case structure of your elements. Also, the case structure of opening and closing tags must match according to the rules for XML syntax. For more information, see Control XML element reference.

Element

Description

Control

Optional child element for a Group within WebLayout. Defines a field, text, hyperlink, or other control element to appear on the work item form.


<Control FieldName="FieldName" Type="DateTimeControl | ExtensionsControl | FieldControl | HtmlFieldControl | LabelControl | WebpageControl" Label="LabelText" EmptyText="TextString" ReadOnly="True | False" Name="InstanceName" />

See Control element attributes and control type for information about each attribute.

ControlContribution

Optional child element of Group within WebLayout used to secify a field-level work item extension to appear on the form.


<ControlContribution Id="ContributionId" Label="Name"  >
   <Inputs>
      <Input Id="FieldName" Value="Value" />
   </Inputs>
</ControlContribution>

The ContributionId you specify must be installed on the account or team project collection. The WIT definition files that you export contain a list of installed contributions.

Extension

Required child element for Extensions. Use to specify an extension ID of a work item control extension to display in the work item form. You must specify each extension that is used in the layout for a ControlContribution, GroupContribution, or PageContribution element.


<Extension Id="ExtensionId" />

The ExtensionId you specify must be installed on the account or team project collection. The WIT definition files that you export contain a list of installed extensions.

Extensions

Optional container child element of WebLayout used to support specifying one or more Extension elements. If extensions are used in the form, specify them prior to a Page element.


<WebLayout >
   <Extensions >
       <Extension Id="ExtensionId" />
      . . . 
   </Extensions >
. . .
</WebLayout >

FORM

Required child element of WITD used to specify the layout and controls to appear on the work item form. Parent element for both the Layout (client form layout) and WebLayout (web form layout) elements.

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

Group

Required child element of Section. Provides a visual grouping of elements within a section which you can label.

<Group Label="LabelText" 
   <Control> . . . </Control>
</Group >

GroupContribution

Optional child element of Section within WebLayout used to specify a group-level work item extension to appear on the form. The extension will appear as a group within the form.


<GroupContribution Id="ContributionId" Label="Name" />

The ContributionId you specify must be installed on the account or team project collection. The WIT definition files that you export contain a list of installed contributions.

Input

Required child element for Inputs that specifies input data for an extension.


<Input Id="FieldName" Value="Value" />

Inputs

Optional container child element for ControlContribution used to support specification of input data for an extension.


   <Inputs>
      <Input Id="FieldName" Value="Value" />
   </Inputs>

Page

Required child element of WebLayout. Defines the layout of a page within the web form.

Specify the name of the page and the layout to use.

<Page Label="PageName" LayoutMode="FirstColumnWide | EqualColumns ">  
   <Section>  
       <Group> . . . 
           <Control> . . . </Control>
           <Control> . . . </Control>
       </Group>
   </Section>
</Page>

PageContribution

Optional child element of WebLayout used to specify a page-level work item extension to appear on the form. The extension will appear as a page within the form.


<PageContribution Id="ContributionId" Label="Name"  />

The ContributionId you specify must be installed on the account or team project collection. The WIT definition files that you export contain a list of installed contributions.

Section

Required child element of Page. Defines the layout of a section within a page of the web form. Sections form groups that support variable resizing. A limit of four sections can be defined within a Page.

<Page>  
   <Section>  
       <Group> . . . 
           <Control> . . . </Control>
           <Control> . . . </Control>
       </Group>
   </Section>
</Page>
SystemControls

Optional child element for WebLayout. Allows you to define the labels and empty text values for controls present in the header of the new work item form (built-in controls). This also includes, the labels for the History, Links, and Attachments tabs.

<SystemControls>  
    <Control Type="FieldControl" FieldName="System.Title" EmptyText="Enter title" /> 
    <Control Label="Assi&gned To" Type="FieldControl" FieldName="System.AssignedTo" />
    <Control Label="Stat&e" Type="FieldControl" FieldName="System.State" />
    <Control Label="Reason" Type="FieldControl" FieldName="System.Reason" />
    <Control Label="&Area" Type="WorkItemClassificationControl" FieldName="System.AreaPath" />
    <Control Label="Ite&ration" Type="WorkItemClassificationControl" FieldName="System.IterationPath" />
    <Control Label="History" Type="WorkItemLogControl" FieldName="System.History" />
    <Control Label="Links" Type="LinksControl" Name="Links" />
    <Control Label="Attachments" Type="AttachmentsControl" Name="Attachments" />
</SystemControls>

WebLayout

Required child element of FORM. Defines the layout of the work item form displayed in the web portal. Includes one or more Page elements.

<WebLayout> 
   <Page>  
       <Section>  
           <Group> . . . 
               <Control> . . . </Control>
               <Control> . . . </Control>
           </Group>
       </Section>
   </Page>
. . .
</WebLayout>

Control element syntax

You use the Control element to define a work item field, text, hyperlink, or other form type to display in a work item form. The Control element you specify within the WebLayout section should conform to the following syntax:


<Control FieldName="FieldName" Type="DateTimeControl |  FieldControl | HtmlFieldControl | LabelControl | WebpageControl" Label="LabelText" LabelPosition="Top | Bottom | Left | Right" EmptyText="TextString" ReadOnly="True | False" Name="InstanceName" />

Control element attribute syntax

Attribute Description

FieldName

Optional. Specifies the work item field with which the control is associated. Specify the reference name of the field which should be between 1 an 70 characters.

Type

Required. Specifies the data type of the control. Specify a string from one of these built-in types:

  • DateTimeControl: Use to display formatted date fields with a field type of DateTime.

  • FieldControl: Use to display Boolean, plain text, numeric fields, person-name fields, and pick lists. Supports fields with a data type of Boolean, Double, Identity, Integer,PlainTextm and String.

    Feature availability: The Boolean data type field is only supported for Team Services and TFS 2017 and later versions.
  • HtmlFieldControl: Use to display multi-line, rich-text format of fields with a field type of HTML.

  • LabelControl: Use to display text that is not associated with a field. The text can be plain or hyperlinked. You can specify additional controls using the LabelText, Link and Text elements.

  • WebpageControl: Use to display HTML-based content defined by a URI or embedded within a CDATA tag. This control does not have an associated field or field type. You specify the content and links to display using the WebpageControlOptions element.

EmptyText

Optional. Specifies a text string between 1 and 255 characters in length that appears when a field is empty.

Label

Optional. Specifies the visible text on the form that identifies the control. Specify a string of no more than 80 characters. If unspecified, the friendly name of the FieldName is used.

ReadOnly

Optional. Specifies that the field is read-only:

  • True: Control field is read-only.

  • False: Control field isn't read-only.

Name

Optional. Identifies a control uniquely. The Name is important if more than one control on the form is associated with the same work item field.

Note: You use the Name attribute when you want to have the same field displayed on more than one Page on the form. You specify a unique value for the Name attribute for both control entries so that the system identifies each control uniquely.

Control element Type attribute syntax

Type Description
DateTimeControl Use to display formatted date fields with a data type of DateTime.

Use FieldControl to provide a text field for the input or display of a DateTime data type field.

<Control FieldName=" MyCompany.Group1.StartDate " Type="FieldControl" Label="Start Date" LabelPosition="Left" />

Use DateTimeControl to provide a calendar picker to select a date for a field, as shown in the following illustration.

Date-Time control, Calendar field
<Control Type="DateTimeControl" FieldName="FabrikamFiber.Schedule.SubmittedDate" Label="Submitted Date:" LabelPosition="Left"  Format="Short" />
FieldControl Use to display fields with a data type of Boolean, String, Identity, Integer, Double, and PlainText.
For example:

<Control Type="FieldControl" FieldName="FabrikamFiber.Milestone" Label="Milestone" Name="Milestone" LabelPosition="Left" />
>[!NOTE]
>Feature availability: The Boolean data type field is only supported for Team Services and TFS 2017 and later versions.

A Boolean field displays as a checkbox within the web work item form.

Boolean field display in web work item form

Within a client work item form, such as Visual Studio or Eclipse, a value of True or False will display.


HTMLFieldControl Use to display multi-line, rich-text formatted control. Specify this control type for fields of Type=HTML.
HTML field shown on work item form
For example:
<Control Type="HtmlFieldControl" FieldName="FabrikamFiber.ReleaseNotes" Label="Release Notes" Dock="Fill" />
LabelControl Use to display text that is not associated with a field. The text can be plain or hyperlinked. You can specify additional controls using the LabelText, Link and Text elements. See LabelText and Text XML elements reference and Link and Param XML elements reference.
WebpageControlOptions

Use to display HTML-based content defined by a URI or embedded within a CDATA tag. This control does not have an associated field or field type. You specify the content and links to display using the WebpageControlOptions element.

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 Content, LabelText, and Linkelements to define plain text or hyperlinked labels, add hyperlinks to a field, or display Web page content in a work item form. See Provide help text, hyperlinks, or web content on a work item form for details about the syntax.

If you're just getting started with the new form, see these additional topics to manage the roll out or customize it:

To learn more about process models and what's supported with each, see Customize your work tracking experience.

Marketplace extensions

Visit the Visual Studio Team Services Marketplace and search on "custom controls" to find extensions you can start using.

Form extensions

The ControlContribution, GroupContribution, and PageContribution elements reference the Id of contributions from the extensions that have been installed for a project collection or account. You install an extension from Visual Studio Marketplace. To create an extension, see Create your first extension.

Once the extensions have been installed, you add the Contribution element to the XML definition for a work item type. You export these files either by exporting a process or exporting a WIT definition file.

When you export the XML definition, it will contain a comment section that lists the installed extensions, their IDs, and any required inputs. For example:


<!--**********************Work Item Extensions**********************

Extension:
    Name: color-control-dev
    Id: mariamclaughlin.color-control-dev

    Control contribution:
        Id: mariamclaughlin.color-control-dev.color-control-contribution
        Description: 
        Inputs:
            Id: FieldName
            Description: The field associated with the control.
            Type: Field
            IsRequired: true

            Id: Labels
            Description: The list of values to select from.
            Type: String
            IsRequired: false

            Id: Colors
            Description: The field associated with the control.
            Type: String
            IsRequired: false

Extension:
    Name: vsts-workitem-recentlyviewed
    Id: mmanela.vsts-workitem-recentlyviewed

    Group contribution:
        Id: mmanela.vsts-workitem-recentlyviewed.recently-viewed-form-group
        Description: Recently viewed work item form group

Extension:
    Name: vsts-extensions-multi-values-control
    Id: ms-devlabs.vsts-extensions-multi-values-control

    Control contribution:
        Id: ms-devlabs.vsts-extensions-multi-values-control.multi-values-form-control
        Description: Multi Values Selection Control.
        Inputs:
            Id: FieldName
            Description: The field associated with the control.
            Type: Field
            IsRequired: true

            Id: Values
            Description: The list of values to select from.
            Type: String
            IsRequired: false

Extension:
    Name: vsts-extension-workitem-activities
    Id: ms-devlabs.vsts-extension-workitem-activities

Extension:
    Name: vsts-uservoice-ui
    Id: ms-devlabs.vsts-uservoice-ui

    Group contribution:
        Id: ms-devlabs.vsts-uservoice-ui.vsts-uservoice-ui-wi-group
        Description: Shows User Voice details on the work item form
--> 

Given the above example, you can add the following code snippet to your work item type definition to turn on the user voice group vsts-uservoice-ui extension by specifying the extension Id:

<WebLayout>
... 
 <Extensions>
     <Extension Id="ms-devlabs.vsts-uservoice-ui" /> 
 </Extensions>

...
</WebLayout> 

Upon import of the updated WIT definition, the group extension will automatically appear on your work item form.

The next time you export your WIT definition, you'll see that a GroupContribution element has been added. You can move this element within the WebLayout section just as you would any other control.