A JFace Viewer provides the user with a view of objects using a single content provider, label provider, sorter and filter. The Common Navigator Framework (CNF) extends this idea by allowing a single view to dynamically use multiple and unrelated sets of content providers, label providers, sorters and filters. These can be activated in the view depending on declarative expressions or using API calls. The CNF implemented by the org.eclipse.ui.navigator plugin.
The CNF uses the idea of Navigator Content Extensions (NCE) which can refer to a content provider, label provider, sorter, or drag adaptor (note that filters are configured separately). An NCE has associated expressions that tell it when it is active. NCEs are also presented to the user in the view context menu so that user can turn them on or off in order to show the view in different ways. Examples of NCEs are a resource content extension that controls how resources are presented and Java content extension that shows Java projects. In the IDE's Project Explorer, you can turn off the Java content extension getting a pure resource view of the workspace.
By using the NCEs it's possible to include different model
objects directly in the view. These model objects might be related in a
cascading fashion. For example a resource object (an IFile)
might refer to a Java class object. This Java class object can be
presented directly in the view by defining an NCE. The Java class object
can have children (representing methods, fields, etc) all of which
appear in the view. You can then add another NCE to display model
objects related to the Java (or resource object) that display content
related to a Java Server Page object. This can all be done without the
"lower level" NCEs (resources, Java) being aware of the existence of the
"outer" NCEs (JSP). Further, it's possible for outer NCEs to override by
suppressing processing associated with lower level NCEs according to
their requirements. And even further, it's possible (using the
pipelining mechanism) for even level in this cascaded set of NCEs to
arrange the presentation of the objects according to their
specifications, moving, adding, or suppressing objects as necessary.
The CNF has depends only on org.eclipse.ui and is
therefore suitable for use both within the IDE and in an RCP
application.
The CNF is highly configurable and many of its components can be
used separately (though this is not the typical case). For example, it's
possible use the service that manages content extensions with a viewer
other than the standard CommonViewer.
The CNF documentation has the following sections:
The CNF has the following major parts:
There are currently 3 major navigators in the Eclipse IDE.
org.eclipse.ui.ide
plugin. It shows only the workspace resources and does not support
extensibility to show other content. In a future release, the Navigator
view will be provided by an implementation of the CommonNavigator.
We also provide instructions for migration from the ResourceNavigator to the CNF.
The only navigator intended for general purpose client use if the CNF, which can be used either by adding NCEs visable in the Project Explorer (if developing an IDE plugin), or using a separate instance of the CommonNavigator as a view.
The CNF allows you to include not only resources but any type of object. One typical use case is that of a resource (consider a Java file for example) which has several subordinate objects presented as tree nodes representing aspects of the class like imports, methods, etc. The CommonViewer (portion of the Common Navigator) will include the IResource object representing the Java file, and then as its children an object for each import, method, etc. The mechanism for defining this is a navigator content extension.
Each content extension also provides a means of associating objects with appropriate icons, labels and menu items.
Content extensions are invoked based on an enablement expression which is defined using core expressions in the extension point. Enablement expressions are commonly defined by sensing the class of an object.
A priority may be associated with a content extension which helps to determine the order of invocation of the NCEs. It's possible that more than one content extension may be enabled for a given object and situation. Priorities are defined with words like "high" or "normal". A high priority would be associated with an extension that defines the primary UI for frequently manipulating an object. A low priority would be given to relatively infrequent utility sorts of UI.
Content extensions may be activated and deactivated for a given view part in the UI using the Filters and Customization menu item in the header menu associated with the view part. Common filters are also may also be activated and deactivated the same way.
Filters allow the user to specify which resources or objects to exclude. Like content extensions, filters may be specified centrally and shared.
References to wizards for new/import/export may be defined. These are included in the appropriate popup menu based on the enablement.
Though the CNF provides a mechanism to work with actions, it is recommended that you instead use the Workbench Commands instead of actions.
Action providers provide a means to configure the retargetable actions and programmatically configure the popup menu in a CNF viewer. These are useful for when you must perform a computation to determine which items are added to the menu, or to adjust the retargetable actions to ensure that the user keystrokes are handled properly (like for Cut/Copy/Paste).
A drop assistant may be associated with a content extension to provide handling of additional (non-standard) transfer types or validation in the event of a drop.
The link helper extension point provides a flexible mechanism of determining the appropriate selection in the navigator when an editor is activated. Conversely, it also provides the appropriate editor to be activated when the selection changes.