RegisterLog In to Jazz.net dW

Work item editor presentations

Summary

This article describes the concept and configuration to further customize the work item editor for new and existing work item types in both the Web UI and Eclipse client, particularly: Editor Presentations, Quick Information Presentations and Query Editor Presentations. For work item customization follow Work Item Customization, and for extensibility follow the wiki at Contributing Attribute Presentations.

The first part of this article covers the structure of Editor Presentations, followed by a how-to for the Eclipse and Web UI clients. The last part describes Query Editor Presentations and Quick Information Presentations.


Overview

Editor presentations define the editor layouts to display work items in the available clients. The layout structure has four basic elements: Tab(s), Header, Section(s) and Presentation(s); as shown in Figure 1. Tabs have a certain layout and contain Sections which are configured to show up in a specific layout slot. A Section then contains Presentations. A Presentation represents a work item attribute, e.g., Priority, or additional information about the current state of the work item, e.g., Team Area, which is not an attribute, but is computed out of other attributes. These elements are described on the following sections.

Some elements can be further customized through some pre-defined parameters as explained in Properties.

Editor Presentation Structure
Editor Presentation Structure

Editor

The topmost element is the Editor, which contains an optional Header and Tab(s). It has an ID which is used to bind from a Work Item Type. For instance, Figure 2 shows how a Story is bound to an Editor.

An Editor Binding in the Eclipse UI
An Editor Binding in the Eclipse UI

Header

This is an optional element within the Editor Presentation to display a header all the time (regardless of the current visible Tab). It is identified by its ID and we can only have one on each Editor Presentation. In terms of behavior it is very similar to a Section, except that it lays Presentations horizontally.

Tabs

A Tab helps to organize the pieces of data to display in an Editor. It has an ID, a title and a layout.

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.

The next section describes the available layouts. These have emerged from the real needs of the Jazz team.

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, however it provides a generic overview for an editor. Notice how the Web UI, as in Figure 3 and Figure 4, shows the slots in slightly different positions tending to put them one below the other but preserving the structure.

Overview Layout in the Eclipse UI
Overview Layout in the Eclipse UI
Overview Layout in the Web UI
Overview Layout in the Web UI

Links Layout

This layout has two rows. The top row has two slots horizontally distributed 60% to 40%. The bottom row has one slot filling the whole space. Vertically the rows are distributed 40% to 60%.

The Links Layout
The Links Layout

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

The Custom Attributes Layout
The Custom Attributes Layout

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 is similar to the Links layout but has an additional slot at the top.

The H Layout
The H Layout

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. Sections are the only elements that contain Presentations and these are displayed one after the other. Note: Headers are considered a Section, but its elements are displayed horizontally.

Overview of the Editor Presentation Structure used for Sections
Overview of the Editor Presentation Structure used for Sections

Presentations

Presentations are used to display an attribute or other additional information related to the work item, i.e., non-attributed-based. 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 which case the default kind for the type of attribute is used.

The clients behave slightly different, while working with an editor. The Web UI provides the ability to customize in a WYSIWYG editor, whereas the Eclipse client is a more hierarchical approach.

The ID of the presentation is optional, but may be necessary for special functionality, e.g., linking from Quick Information.

Non-attribute-based: These Kinds are not based on attributes but represent a certain aspect of the work item, e.g., Team Area, Attachments, Links, Subscribers, History, Approvals, Quick Information.

Attribute-based: These are based on an attribute of the work item. Table 2 summarizes some of the available presentation kinds grouped by purpose.

Overview Attribute Presentations
Purpose Available Kinds
Basic types String, Integer, Boolean, HTML, Text, Wiki. Since 4.0.1: Decimal.
Enumeration types Combo box, radio buttons, String list.
Reference types 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.

Properties

Some elements may be further customized through pre-defined properties. These are entered as key-value pairs as shown in Figure 9, with the exception of attribute-based on the Eclipse client which are embedded in the editor as shown in Figure 10.

Editor Properties
Edit Tab properties in the Eclipse UI
Edit attribute presentation properties in the Eclipse UI
Edit attribute presentation properties in the Eclipse UI

The next section describes the available properties for each of the elements within the Editor Presentations. For Tab properties refer to Table 3, Section properties refer to Table 4 and Presentation properties refer to Table 5.

Tab Properties
Property Description
hideIfEmpty if set to 'true' the presentation will only be visible if its value is different from the null value of the attribute.
Section Properties
Property Description
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 hideIfEmpty property to only show up if any attribute was collected, and no other section declared on the tab.
width can be used together with autocollect to indicate that only attributes with a specific size are displayed. Possible values are small or wide. 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.
Presentation Properties
Property Applies to Since Version Description
readonly if set to 'true' the presentation will be displayed in a readonly look and feel.
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.
hideIfEmpty if set to 'true' the presentation will only be visible if its value is different from the null value of the attribute.
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.
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.
hideIfNoProjectLink 4.0 as value use the ID of the project link. The presentation will only be visible if the work item has links for this project.
timeout E-Signature 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.
allowAnyValue Enumeration 4.0 whether to allow to add new literals.
warningMessage Owned By, Resolved By 4.0 displays a warning if the member does not belong to the Team Area/Project.

How-to: Editor Presentations

The following section describes some of the steps to create an editor presentation using the Web UI and Eclipse clients. On this section we will create an Editor Presentation. This is usually done in a hierarchical way. For instance, we will initially add a Editor Presentation, then a reuse a Header, then create a Tab with a Section and at the end adding Presentations.

Editor Presentations on Web UI

  1. Go to Manage Project > Work Items > Editor Presentations.
    Project Admin UI in the Web Client
    Project Admin UI in the Web Client
  2. To add an Editor Presentation, click Add... right next to the available Editor Presentations and provide an ID.
  3. To add a Header: click Add Header and select an existing one. Remember: we can either add elements or reuse existing ones. For this scenario we will reuse the header in order to provide a consistent look in our Work Items. Note: when we edit a shared element, the editor displays a warning, stating that all instances using that shared element will be affected.
  4. To create a Tab: click Add Tab button. Enter a title and ID, select a layout and click OK. The added tab appears in the editor outlining the available slots according to the selected layout.
  5. To create a Section: click on Add Section. Enter a title and ID, select a slot and click OK. The section is added to the selected slot. You can update its slot by dragging the element into a new slot.
  6. To create a Presentation: click on Add Presentation and select the type attribute-based. Select the attribute and its kind; (optional) a label, description and ID.
  7. Finally, once we have customized our Editor Presentation, we need to bind it to a work item type. Go to Work Items > Types and Attributes and select your Editor Presentation in the drop-down in a Work Item Type.

Editor Presentations on Eclipse client

  1. Go to Project Configuration > Configuration Data > Work Items > Editor Presentations.
    Project Area Editor in the Eclipse UI
    Project Area Editor in the Eclipse UI
  2. To add an Editor Presentation, click Add... right next to the available Editor Presentations and provide an ID.
  3. To add a Header: click Add Header... and select an existing one. The navigation buttons are enabled/disabled depending on the selected element and general Editor rules, for example, Add Header... is disabled when an Editor already contains a Header.

    Remember: we can either add elements or reuse existing ones. For this scenario we will reuse the header in order to provide a consistent look in our Work Items. Note: when we edit a shared element, the editor displays a warning, stating that all instances using that shared element will be affected.
  4. To create a Tab: click Add Tab... button. Enter a title and ID, select a layout and click OK.
  5. To create a Section: select previous Tab and click on Add Section.... Enter a title and ID, select a slot and click OK.
  6. Now we can add Presentations to display Work Item information; select a Section and click on Add Presentation... and select the type attribute-based. Select the attribute and its kind; (optional) a label, description and ID.
  7. Finally, once we have customized our Editor Presentation, we need to bind it to a work item type. Go to Work Items > Types and Attributes and select your Editor Presentation in the drop-down in a Work Item Type.

Query Editor Presentations

This Editor associates work item attributes with Presentations for query parameters. This configuration aspect can only be configured on the Process Configuration Source page as shown in Figure 13. It is an advanced configuration aspect, that only needs to be changed when an attribute should use a different Presentation in the Query Editors.

Query Editor Presentation
Query Editor Presentation

Quick Information Presentations

The Quick Information Editor provides a concise view of information related to a Work Item. For example, Figure 14 displays links to the available Attachments, Subscribers, Mentions.

Quick Information Presentation
Quick Information Presentation

The configuration of the Quick Information Presentation is only available via the Eclipse UI under Process Configuration > Project Configuration > Configuration Data > Work Items > Quick Information Presentations. Which configuration should be used is specified with the 'quickinformationConfiguration' property within the Non-Attribute-based Presentation. 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:

  • Abbreviation Reference: A reference presentation that lists short abbreviations with access to menu and hover.
  • Approvals: A presentation that lists approvals, reviews and verifications.
  • Attachments: A presentation that lists attachments.
  • Collector: A presentation that shows the number of entries.
  • Enumerating Reference: A reference presentation that enumerates references with direct access to menu and hover.
  • Hidden: A presentation to hide entries.
  • Potential Duplicates: A presentation that shows potential duplicates of the current work item (Eclipse client only).
  • Reference: A generic presentation for link types to show references.
  • Subscriber: A presentation that lists users subscribed to the work item.
  • Workitem: A presentation for link types that point to work items.

For more information


About the Authors

The authors are developers in the Tracking and Planning team working on the Work Item component of Rational Team Concert. For additional information about the topic presented in the article add your comments or questions directly in the discussion part, or visit our Jazz.net Forum.

Feedback
Was this information helpful? Yes No 12 people rated this as helpful.