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
<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.
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:
If this attribute is not specified, the current value of the field is used as a parameter |
Parent Elements
Element |
Description |
|---|---|
Required. Defines a field, text, hyperlink, or other control element to appear on the work item form. |
|
Optional Control element. Container element for a label to appear on the work item form. |
|
Optional LabelText element. Container element for the information or label to appear on the work item form. |
|
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&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 |