# Common Navigator Framework

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:

- Configuration Overview - A high level discussion of the configuration.
- Operational Topics - A detailed discussion of various topics in the operation of the CNF
- Step-by-step Instructions - Provides configuration instructions for various scenarios.
- Troubleshooting - Some suggestions for troubleshooting.

## Major Components of the Common Navigator Framework

The CNF has the following major parts:

1. View Part - CommonNavigator .
2. Viewer -CommonViewer the implementation of a viewer that is contained in the above view part. You can also use the CNF with your own viewer that can be displayed anywhere.
3. Navigator Content Extensions - org.eclipse.ui.navigator.navigatorContent This extension point is where you configure the collections of content you want to make visible.
4. Navigator Viewer - org.eclipse.ui.navigator.navigatorContent This extension point is used to declare the relationship between the NCEs and a particular viewer. Regular expressions may be used here to allow a viewer to dynamically detect NCEs that it does not know about beforehand. visible.
5. Resource Support - Resources are one of the main types of objects managed by the CNF. To support this the org.eclipse.ui.navigator.resources plug-in provides all of the necessary definitions. The Project Explorer is configured using these definitions.

## Navigators - Where the CNF Fits

There are currently 3 major navigators in the Eclipse IDE.

1. Project Explorer - This is an instance of the CommonNavigator that is provided by the org.eclipse.ui.navigator.resources plugin. It provides a view of the workspace and has a large number of NCEs contributed for resources, Java, C, Web Tools, Data Tools, PHP, etc.
2. Package Explorer - Provided by the Java Development Tools (JDT) UI project, this provides a view of Java classes for the workspace. Generally speaking, the presentation of the Package Explorer and Project Explorer for Java objects is substantially similar. The JDT is not used for projects beyond Java.
3. Navigator - This view is an implementation of the now deprecated (as of 3.5) org.eclipse.ui.views.navigator ResourceNavigator class provided in the `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.

## Navigator Content Extensions (NCE)

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.

## Common Filters

Filters allow the user to specify which resources or objects to exclude. Like content extensions, filters may be specified centrally and shared.

## Common Wizards

References to wizards for new/import/export may be defined. These are included in the appropriate popup menu based on the enablement.

## Action Providers

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

## Drag and Drop Support

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.

## Link With Editor Support

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.