Link and Param XML Elements Reference

You can add a hyperlink to a field or a standalone label on a work item form by using the Link element. You use the Link element in the following instances to:

• Add a hyperlink to a field label

• Add a hyperlink to a standalone label or portions of informational text

• Specify the URL for content to be displayed within a work item form

To add elements to a form, you modify the definition for a work item type. See Modify or add a custom work item type (WIT).

The Link element is either a child element of the Control element, or a child element of the WebpageControlTarget or WebpageControlOptions elements. For more information about these elements, see Control XML element reference and WebpageControlOptions XML Elements Reference.

Schema Hierarchy

WITD

   WORKITEMTYPE

       FORM

           Layout

               Group

               Column

               Tab

                     Control

<Link URLRoot="URLRoot" URLPath ="URLPathWithParameters">
   <Param Index="IndexValue " Value="ParamValue " Type ="Original | Current"/>
</Link>

Attributes and Elements

The following sections describe attributes, child elements, and parent elements.

Child Elements and Attributes

Element	Attribute	Description
Link		Optional Control element when type="FieldControl". Optional LabelText element. Optional Text element. Optional WebpageControlOptions element. Container element for defining a hyperlink or URL. The element type is complex type: HyperLinkType.
	UrlRoot	Required Link attribute. Specifies the protocol and the server name of the URL to which the label links. Supported protocols are HTTP, HTTPS and MAILTO. You can either hardcode the specified server name , or you can use one of the following macros and optionally append additional address information to a macro: Note Each macro links to the URL that is defined and enabled for the team project of the work item form for which the Link element is defined. If any of the resources are not provisioned or enabled for the team project, a "page not found" error will appear. @PortalPage: The URL of the SharePoint site for the current team project (for example, https://serverName/sites/collectionName/TeamProjectName). @ProcessGuidance: The URL of the SharePoint site for the process guidance for a team project. @ReportManagerUrl: The URL of the server that hosts Report Manager for the current team project. This provides a link to the folder view for the reports (for example, https://serverName/Reports/Pages/Folder.aspx?ItemPath=/collectionName/teamProjectName). @ReportServiceSiteUrl: The URL of the server that hosts SQL Server Reporting Services for the current team project plus the base path for the team project (for example, https://serverName/Reports/Pages/reportservice.asmx?ItemPath=/collectionName/teamProjectName). To determine the hardcoded value for the first two macros, you can open the project portal settings for a team project. For more information, see Configure or redirect process guidance. The attribute type is simple type: NonBlankString.
	UrlPath	Optional Link attribute. Specifies a URL path for the hyperlink. You use this attribute to specify variable parameters that are determined at run time. The attribute type is simple type: NonBlankString.
Param		Optional Link element. Required when UrlPath is specified. Specifies a value to be used to determine the URL of the hyperlink when UrlPath is specified. The element type is complex type: HyperLinkParamType.
	Index	Required Param attribute. Specifies the index of the parameter where the value must be formatted into the URL string. It is not required to order the Index values sequentially; however, they must match the number of the index in the URLPath string. The attribute type is PositiveInteger. The first index number should be 0.
	Value	Required Param attribute. Specifies the number associated with the value for a URL path for the hyperlink. Specifies a value that must be formatted into the URLPath string. Values must be valid reference names of fields used in the work item type definition. The @Me variable is supported. It is replaced with the name of the current team member that is viewing the work item form. Value entries are not case sensitive The attribute type is xs:string.
	Type	Optional Param attribute. Specifies that the original value of the field must be used for the parameter. The attribute type is simple type:HyperLinkParamValueKind. Valid values are as follows: Original: Specifies to use the original parameter value to determine the URL path. Current: Specifies to use the current parameter value to determine the URL path. If this attribute is not specified, the current value of the field is used as a parameter

Parent Elements

Element	Description
Control	Required. Defines a field, text, hyperlink, or other control element to appear on the work item form.
LabelText	Optional Control element. Container element for a label to appear on the work item form.
Text	Optional LabelText element. Container element for the information or label to appear on the work item form.
WebpageControlOptions	Optional Control element. Container element that specifies the options for the Web page control. For more information, see Displaying Web Content within a Work Item Form.

Remarks

The default behavior of the Link element is to open the hyperlink in the work item form or Web page. If the hyperlink is authored to open in a new window (target="_blank"), then an external browser is opened.

You can combine plain and hyperlinked text by adding multiple Text elements in a LabelText element.

The LabelText element is only recognized by clients that are running the latest version of Team Explorer. Therefore, you must specify the Label attribute in a Control element when you specify a child Link element. For clients that are running the latest version of Team Explorer, the text provided by the a LabelText element appears in the work item form. For clients that are running previous versions of Team Explorer, the text specified by the Control element Label attribute appears in the work item form.

Example: Specifying a Hyperlink with Parameters

Description

The following example shows how you can define a hyperlink that links to the process guidance for the Iteration topic:

https://serverName/sites/collectionName/projectName/render.aspx?wit=bug&topic=Iteration

The name of the project is derived from the value assigned to the System.Project field.

Code

<Link UrlRoot="https://serverName" UrlPath="sites/{0}/render.aspx?wit=bug&amp;topic=Iteration">
   <Param Index="0" Value="System.Project" />
</Link>

Example: Adding a Hyperlink to a Standalone Label

Description

The following example shows how you can assign a hyperlink to the text "work item guidance" on a work item form.

Code

<Control type="LabelControl">
   <LabelText> 
      <Text>
         <Link UrlRoot="https://www.msn.com" />
      work item guidance
      </Text>
   </LabelText> 
</Control>

Example: Adding a Hyperlink to a Field

Description

The following example shows how you can add a hyperlink to the label for a field on a work item form.

Code

<Control Type="FieldControl" FieldName="System.Title" LabelPosition="Left" Label="This text comes from the Label attribute:">
   <LabelText>
      <Text>
         <Link UrlRoot="http://www.live.com/" />
         This text comes from the inner Label Text
      </Text>
   </LabelText>
</Control>

Schema Definitions

• HyperLinkType

• NonBlankString

• HyperLinkParamType

• HyperLinkParamValueKind

Complex Type: HyperLinkType

<xs:complexType name="HyperLinkType" >
   <xs:sequence>
      <xs:element name="Param" type="HyperLinkParamType" minOccurs="0" maxOccurs="unbounded"/>
   </xs:sequence>
   <xs:attribute name="UrlRoot"  type="NonBlankString" use="required" />
   <xs:attribute name="UrlPath"  type="NonBlankString" use="optional" />
</xs:complexType>

HyperLinkParamType

<xs:complexType name="HyperLinkParamType" >
   <xs:attribute name="Index"     type="PositiveInteger" use="required" />
   <xs:attribute name="Value"     type="xs:string" use="required" />
   <xs:attribute name="Type" type="HyperLinkParamValueKind" use="optional" />
</xs:complexType>

NonBlankString

<xs:simpleType name="NonBlankString">
   <xs:restriction  base="xs:string">
   <xs:pattern value=".*\S+.*"/>
   </xs:restriction>
</xs:simpleType>

HyperLinkParamValueKind

<xs:simpleType name="HyperLinkParamValueKind">
   <xs:restriction base="xs:string">
   <xs:enumeration value="Original"/>
   <xs:enumeration value="Current"/>
   </xs:restriction>
</xs:simpleType>   

Element Information

Namespace	https://schemas.microsoft.com/VisualStudio/2008/workitemtracking/typedef
Schema Name	Work Item Type Definition
Validation File	WorkItemTypeDefinition.xsd
Element Type	HyperLinkType, HyperLinkParamType
Can Be Empty	Not applicable

See Also

Concepts

Specify work item form controls

Design the work item form