Contributing to the Team Artifacts view in Rational Team Concert 2.0
Summary
This article explains how to contribute to the Team Artifacts view and the Artifacts part of a Project Area or Team Area editor.
Introduction
The Team Artifacts view is an Eclipse view within Jazz that presents a hierarchy of heterogeneous elements that are provided from contributed domains. Domains can also be presented within the Artifacts part of a Project Area or Team Area editor.
What is a Domain?
A domain is an extension mechanism for different components to contribute context specific elements of a given type to a domain navigator such as the Team Artifacts view, Project Area or the Team Area editor.
How To Create a Domain
You will need to add the following required plug-in as a prerequisite: com.ibm.team.process.rcp.ui
Domain implementations must extend the abstract class com.ibm.team.process.rcp.ui.teamnavigator.Domain and override methods as required.
After you have coded your domain, you can contribute it by extending the com.ibm.team.process.rcp.ui.teamArtifactsNavigatorDomain extension point. The schema file for this extension point, teamArtifactsNavigatorDomain.exsd, can be found in the schema folder within the com.ibm.team.process.rcp.ui plug-in provided in a source build.
The id attribute specified for the domain extension needs to either be registered with the server license or be within a namespace that is unlicensed.
- com.ibm.unlicensed.* – Domain will work without being included in the license
- * – Domain will work without being included in the license
- com.ibm.* – Domain needs to be licensed
For example, the declaration of the Plans domain from the com.ibm.team.apt.ide.ui plug-in looks like this:
... <extension point="com.ibm.team.process.rcp.ui.teamArtifactsNavigatorDomain"> <teamArtifactsNovigatorDomain class="com.ibm.team.apt.internal.ide.ui.navigator.PlanningDomain" icon="$nl$/icons/obj16/planning_domain.gif" id="com.ibm.team.process.deliver.requireWorkItem" name="%PlanningDomainName"/> </extension> ...
Within the Team Artifacts view, all calls that concern domain elements are delegated to the corresponding domain. Therefore, a domain represents a factory for the standard JFace notions of content provider, label provider, sorter, and comparer. In addition, there are opportunities to convert model elements for presentation within the UI, contribute to the view context menu, and participate in drag and drop.
Implementing Different Types of Domains
There are two kinds of domains within Jazz: standard domains, which pertain to a specific process area, and top-level domains, which don’t have a process area scope. The type of the domain is determined by the implementation details of specific methods.
Within the Team Artifacts view, standard domains are shown under each project area. They need to return true for Domain#supportsCategory(Category category) when the supplied category is a com.ibm.team.process.rcp.ui.teamnavigator.IProjectAreaCategory. Some example standard domains shown in the Team Artifacts view are the Builds, Streams, and Plans domains.
For domains to be included within the com.ibm.team.process.internal.ide.ui.editors.TeamArtifactsPart of a Project Area or Team Area editor, the domain must return true from Domain#supportsCategory(Category category) when the supplied category is a com.ibm.team.process.rcp.ui.teamnavigator.IProcessAreaEditorCategory. Two domains of this type are Builds and Work Item Categories.
Top-level domains appear outside the context of any Project Area in the Team Artifacts view. Such domains typically present information that is global to the user’s Eclipse workspace, such as the Repository Connections domain, or global to the user across repositories, such as the My Repository Workspaces domain. Implementers are strongly encouraged to use top-level domains sparingly, as many top-level domains would quickly degrade the user experience in the Team Artifacts view. To qualify as a top-level domain, the domain implementation must return false for Domain#supportsCategory(Category).
Content Provider
The domain implementation contributes its elements by providing an org.eclipse.jface.viewers.ITreePathContentProvider.
Label Provider
A label provider is needed to render the domain elements. The label provider must implement org.eclipse.jface.viewers.ITreePathLabelProvider. The label provider can additionally implement a subset of these interfaces: org.eclipse.jface.viewers.IColorProvider, org.eclipse.jface.viewers.IFontProvider, and their sub-types.
Sorter
A domain can provide an org.eclipse.jface.viewers.ViewerSorter for its elements. org.eclipse.jface.viewers.TreePathViewerSorter is also supported.
Comparer
A domain can provide an org.eclipse.jface.viewers.IElementComparer for its elements.
Model Element Conversion
A domain can choose not to expose its model objects but use representation objects within the UI. The convertToModel(Object uiElement) and convertToSelection(Object modelElement) methods are used to convert between these model and UI elements. Object contributions, open actions, and drag-and-drop will always be performed on the converted model elements (those returned from convertToModel(Object uiElement)) if they are available.
Selections in the domain navigator are always of type com.ibm.team.process.internal.rcp.ui.DomainSelection and can be accessed using getWorkbenchPart().getSite().getSelectionProvider().getSelection();. These selections contain the converted model elements. The original selection, with the unconverted elements, can be obtained using DomainSelection.getOriginal().
Contribute to Context Menu
If a selection consists only of elements of one domain (Domain.contains(Object) returns true), this domain gets the opportunity to contribute context menu actions. Upon creation of the context menu the method #contributeContextMenuActions(IMenuManager, IStructuredSelection) is called. An alternative is to use standard JFace object contributions. As mentioned above in the model conversion section, the object contributions will always be triggered based on the converted selection. We encourage domain providers to make use of the New menu that exists within the Team Artifacts view context menu to make object contributions for creation. The id of this menu is defined as com.ibm.team.jface.viewerutilities.ContextMenuHelper#NEW_MENU_ID and contains an initial group defined as com.ibm.team.jface.viewerutilities.ContextMenuHelper#NEW_MENU_GROUP
Participate in Drag and Drop
To enable drag and drop for its elements a domain has to overwrite all these methods:
-
#validateDrop(Object, ISelection, int) -
#getSupportedOperationsForSelection(ISelection) -
#performDrop(Object, ISelection, int)
© Copyright 2008 IBM