Library
Work Item Editor Presentations
Summary
The work item editor can be configured to accommodate new work item types or to extend existing types with additional attribues. How this can be done is part of article Work Item Customization. The configuration and concept of the work item editor presentations is described in this article, for extensibility (code contribution) have a look at the wiki at Contributing Attribute Presentations.
Defining editor layouts is limited in RTC 1.0 and RTC 2.0 and subject to change in future versions of RTC. This Article describes what is possible in RTC 1.0 and RTC 2.0.
Overview
The work item editor structure has three basic elements: tabs, sections and presentations. Tabs have a certain layout and contain sections which are configured to show up in a specific layout slot. A section then contains a list of presentations. A presentation represents a work item attribute (like priority) or additional information about the current state of the work item (like Team Area, which is not an attribute, but is computed out of other attributes).
The layout of sections is fixed and for tabs six predefined layouts are available. The layouts have emerged from the real needs of the Jazz team. Sections will always show the configured presentations one after the other.
Some elements may need special parameters - these can be provided by adding properties (<key, value> pairs).
Editors
The topmost element is the editor, which has an ID and contains a list of tabs. The ID is used to bind a work item type to the editor.
Header
Since RTC 2.0, the header of an editor can be configured like a regular section. Its presentations will be laid out horizontally.
Tabs
A tab has an ID, a title and a layout. It contains a list of sections. Tabs can be reused between editors.
The layout of a tab is divided into different parts, called slots. Every section of the tab is configured to show up in a slot. It is possible to configure several sections into one slot, but this is not supported by all layouts. Which layout should be used is configured in the tab, the slot is however configured in the section.
One property can be used with tabs:
- hideIfEmpty: The tab is only shown if it has actually content to display. This property is only supported by the Custom Attributes Layout and only useful in combination with the
autocollectproperty for sections.
Below the available layouts and their slots are illustrated in the Eclipse UI. The Web UI shows the slots in slightly different positions tending to put them one below the other but preserving the structure.
Overview Layout
This layout has four slots. Each slot can have only one section. The layout has originated from the Overview tab of the default editor and is not very flexible, but has some special features that are not yet available in a generic way.
| Eclipse UI | Web UI |
 |  |
Links Layout
This layout has two rows. The top row has two slots with 3/2 ratio. The bottom row has one slot filling the whole space. Vertically the rows have a 2/3 ratio.
Custom Attributes Layout
This layout is one of the more flexible. It can have several sections in each slot. If there are no sections in one slot, the sections in the other slot will extend the full width. The slots are horizontally distributed 30% to 70%.
Approvals Layout and History Layout
These layouts have no slots to configure and can only contain one section which fills the available space. They are not intended to be reused as the same functionality can be achieved with the Custom Attributes layout.
H Layout
This layout is new in RTC 2.0 and similar to the Links layout but has an additional slot at the top.
Sections
A section has an ID, a title and is configured to show up in a layout slot of the containing tab. The available slots depend on the layout of that tab.
A section can be configured with certain properties:
- noHeader: if set to 'true', the section will display no header. If the property is not set, the section has a header.
- autocollect: if set to 'true', the section will collect all work item attributes that are not configured to show up elsewhere and display them with their default presentation. This feature is only available in the Eclipse UI and is used on the 'Custom' tab in the default editor. A tab can then use the
hideIfEmptyproperty to only show up if any attribute was collected (and no other section declared on the tab). - width: can be used together with
autocollectto indicate that only attributes with a specific size are displayed. Possible values aresmallorwide. Every attribute 'knows' whether it is 'small' or 'wide'.
- expanded: if set to 'false', the section will initially be collapsed. If the property is not set, the section will show up expanded.
Presentations
Presentations are used to display an attribute or other additional information related to the work item. A presentation has always a kind which represents the look and capabilities of a presentation (e.g. String kind for editing a string attribute). It is possible to only specify the attribute on a presentation. In that case the default kind for the type of attribute is used.
The ID of the presentation is optional, but may be necessary for special functionality (e.g. linking from quick information).
Presentation kinds exist for the following attribute types:
- For basic types like String, Integer, Boolean, HTML, Text.
- For enumeration types: the default kind shows a combo box; there is an additional kind showing the values of the enumeration as radio buttons.
- Attribute independent kinds: Team Area, Attachments, Links, Subscribers, History, Approvals, Quick Information: these are not based on attributes but represent a certain aspect of the work item.
- Combined presentations: two presentations (Multi-Select List and Checkbox Multi-Select List) use a string to store the value, but the possible values base on an enumeration. The
enumerationproperty is thus mandatory.
- For reference attribute types (since RTC 2.0 available for custom attributes): Contributor, Category, Release, Iteration, Team Area and Team Area list, Project Area and Project Area list, Process Area and Process Area list, Work Item and Work Item list.
Some presentation kinds can be further configured with properties:
- readonly: if set to 'true' the presentation will be displayed in a readonly look and feel.
- hideIfEmpty: if set to 'true' the presentation will only be visible if its value is different from the null value of the attribute.
- quickinformationConfiguration: the value is the ID of the quick information configuration. This property is only applicable to the presentation kind 'Quick Information' (described below).
- enumeration: the value is the type ID of an enumeration. This property is only applicable for the 'Multi-Select List' and 'Checkbox Multi-Select List' presentation kinds, where the attribute is of type string, but the set of possible values is taken from an enumeration.
- hideIfEndpointEmpty: as value use the ID of the link type endpoint. The presentation will only be visible if the work item has links for this endpoint.
- hideIfCreation: if set to 'true' the presentation will not be visible on creation.
- hideIfInState: as value use the comma-separated list of workflow states (ID of the state) where the presentation should not be visible.
- attributeDependency: specify a comma-separated list of attribute identifiers. The presentation will be notified if one of these attributes changes its value. Deprecated since 2.0.0.2, use Attribute Value Provider mechanism and dependencies on attribute layer instead.
- labelVisible: specify whether the label of the presentation is visible. This overwrites the default behavior where the label is visible except when the presentation is the only one in the section.
- timeout: specify the timeout in seconds after which the E-Signature presentation will clear the password. This is only available to the E-Signature presentation. The default is 120.
Quick Information
The Quick Information presentation can be further configured in its own configuration editor. Which configuration should be used is specified with the 'quickinformationConfiguration' property. A quick information kind has a title, a kind, a link target and sometimes an endpoint. The link target is the ID of a presentation. Clicking on a title link in quick information will open the tab containing the specified presentation. An endpoint is necessary for kinds that show links (Workitem, Reference and Enumerating Reference kind). The following kinds are available:
- "Approval": shows approvals, reviews and verifications
- "Attachment": lists the attachments
- "Reference": shows references of the specified endpoint
- "Subscriber": lists the users subscribed by the work item
- "Workitem": lists work items of the specified endpoint
- "Enumerating Reference": shows multiple references as a numbered list (1, 2, 3) for easy access to the context menu
- "Potential Duplicates": shows results of a similarity query regarding the current work item
Yes
No
