<p>A 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 <b><a

	href="../reference/api/org/eclipse/ui/navigator/package-summary.html">

org.eclipse.ui.navigator</a></b> plugin.</p>

<p>The CNF uses the idea of <i>Navigator Content Extensions</i>

(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.</p>

<p>By using the NCEs it's possible to include different <i>model objects</i> directly 

in the view.  These model objects might be related in a cascading fashion.  For example

a resource object (an <code>IFile</code>) 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.

</p>

<p>???The CNF has depends only on <code>org.eclipse.ui</code> 

and is suitable for use both within the IDE and in an RCP application.</p>

<p>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

<code>CommonViewer</code>.  </p>

<h2>Major Components of the Common Navigator Framework</h2>

<p>The CNF has the following major parts:</p>

<ol>

	<li><b>View Part</b> - <b><a

		href="../reference/api/org/eclipse/ui/navigator/CommonNavigator.html">CommonNavigator

	</a></b>.</li>

	<li><b>Viewer</b> -<b><a

		href="../reference/api/org/eclipse/ui/navigator/CommonViewer.html">CommonViewer

	</a></b> the implementation of a viewer that is contained in the above view

	part.</li>

	<li><b>Navigator Content Service</b> - <b><a

		href="../reference/api/org/eclipse/ui/navigator/INavigatorContentService.html">INavigatorContentService

	</a></b> a service that manages content extensions and allows them to be

	discovered based on objects associated with a viewer. Most users do not

	interact directly with the Content Service, but it is possible to use

	it independently from the common navigator view part.</li>

</ol>

<h2>Navigators - Where the CNF Fits</h2>

<p>There are currently 3 major navigators in the Eclipse IDE.</p>

<ol>

<li><b>Project Explorer</b> - This is an instance of the CommonNavigator that is provided by the  <b><a

	href="../reference/api/org/eclipse/ui/navigator/resources/package-summary.html">

org.eclipse.ui.navigator.resources</a></b> 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.</li>

<li>

<b>Package Explorer</b> - 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.

</li>

<li><b>Navigator</b> - This view is an implementation of the now deprecated (as of 3.5) 

ResourceNavigator class

provided in the <code>org.eclipse.ui.ide</code> 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.

</li>

</ol>

<p>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.</p>

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<HTML>

<HEAD>

<meta name="copyright"

	content="Copyright (c) Oakland Software and others 2008. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page.">

<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">

<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1"

	TYPE="text/css">

<TITLE>Using the Common Navigator in an RCP Application</TITLE>

<link rel="stylesheet" type="text/css" HREF="../book.css">

</HEAD>

<BODY BGCOLOR="#ffffff">

<h1>Using the Common Navigator in an RCP Application</h1>

<p>

To add the Common Navigator to an RCP application and have it manipulate the

workspace resources, first follow the <a href="cnf_steps_resources.htm">steps</a>

and then follow these.  If you don't want to have the CN to use resources, omit

the resources steps.

</p>

<ol>

<li>

Add the following as dependent plug-ins:

<ol type="a">

<li>org.eclipse.ui.navigator</li>

</ol>

</li>

<li>Add a View extension (org.eclipse.ui.views) which uses the class org.eclipse.ui.navigator.CommonNavigator.

<pre>

   <extension

         point="org.eclipse.ui.views">

      <view

            name="View"

            class="org.eclipse.ui.navigator.CommonNavigator"

            id="example.view">

      </view>

   </extension>

</pre>

</li>

<li>Update your perspective factory (IPerspectiveFactory) code to show the new View (this is necessary when adding any View):

<pre>

	public void createInitialLayout(IPageLayout layout) {

		String editorArea = layout.getEditorArea();

		layout.setEditorAreaVisible(false);

		layout.setFixed(true);

		layout.addStandaloneView("example.view",  true /* show title */, IPageLayout.LEFT, 1.0f, editorArea);

	}

</pre>

<p>

Note that for the moment you need to specify "true" to show title, otherwise the viewer will not render correctly

(<a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=235171">bug 235171</a>).</p>

</li>

<li>

Add a org.eclipse.ui.navigator.viewer extension that has:

<ul>

<li>viewerContentBinding, point this to your View Id above (example.view)

<ul>

<li>includes of:

<ul>

<li>com.yourcompany.yourapp.yournav.*</li>

</ul>

</li>

</ul>

</li>

</ul>

<pre>

   <extension

         point="org.eclipse.ui.navigator.viewer">

       <viewerContentBinding 

            viewerId="example.view">

          <includes>

       	     <contentExtension pattern="com.yourcompany.yourapp.yournav.*" />		       	      

          </includes>

       </viewerContentBinding>

   </extension>

</pre>

</li>

<li>Add navigator content extensions as required:

</li>

<li>If you need resources, add the following to your WorkbenchAdvisor

<ol type="a">

<li>To get the resource workspace as input, override this method:

<pre>

	public IAdaptable getDefaultPageInput() {

		IWorkspace workspace = ResourcesPlugin.getWorkspace();

		return workspace.getRoot();

	}

</pre>

</li>

<li>If you need resources, you need to have the workbench adapters correctly hooked up, so

add this code to the initialize() method:

<pre>

	public void initialize(IWorkbenchConfigurer configurer) {

		IDE.registerAdapters();

	}

</pre>

</li>

</ol>

</li>

</ol>

</BODY>

</HTML>

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<HTML>

<HEAD>

<meta name="copyright"

	content="Copyright (c) Oakland Software and others 2009. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page.">

<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">

<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1"

	TYPE="text/css">

<TITLE>Configuring the Common Navigator</TITLE>

</HEAD>

<BODY BGCOLOR="#ffffff">

<h1>Procedures for Using the CNF</h1>

<p>The sections below define the set of steps for using the CNF 

in various scenarios.

Some of the sets of below have a plugin in the UI examples

that shows the end result.

</p>

<p>

<ul>

<li><a href="cnf_steps_resources.htm">Using only Resources</a>

 (<code>org.eclipse.ui.examples.navigators.resources</code>)</li>

<li><a href="cnf_steps_rcp.htm">Using with an RCP Application</a></li>

<li><a href="cnf_steps_rn_migration.htm">Migrating from the ResourceNavigator</a></li>

<li><a href="cnf_steps_resources.htm">Using Resources Combined with Model Objects</a>

 (<code>org.eclipse.ui.examples.navigators.properties</code>)</li>

</ul>

</p>

</BODY>

</HTML>

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<HTML>

<HEAD>

<meta name="copyright"

	content="Copyright (c) Oakland Software and others 2008, 2009. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page.">

<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">

<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1"

	TYPE="text/css">

<TITLE>Using the Common Navigator with Resources</TITLE>

<link rel="stylesheet" type="text/css" HREF="../book.css">

</HEAD>

<BODY BGCOLOR="#ffffff">

<h1>Using the Common Navigator with Resources</h1>

<p>

To create a Common Navigator view that manipulates workspace resources

(in the IDE) use the steps below.  These steps can also be applied to an RCP application, but 

you will also need to do the some additional <a href="cnf_steps_rcp.htm">work</a>.  You don't need to

use any code at all to do this.

</p>

<p>The example plugin <code>org.eclipse.ui.examples.navigators.resources</code> shows this.

</p>

<ol>

<li>

Add the following as dependent plug-ins:

<ol type="a">

<li>org.eclipse.ui.navigator</li>

<li>org.eclipse.ui.navigator.resources</li>

</ol>

</li>

<li>Add a View extension (org.eclipse.ui.views) which uses the class org.eclipse.ui.navigator.CommonNavigator.

<pre>

   <extension

         point="org.eclipse.ui.views">

      <view

            name="View"

            class="org.eclipse.ui.navigator.CommonNavigator"

            id="example.view">

      </view>

   </extension>

</pre>

</li>

<li>

Add a org.eclipse.ui.navigator.viewer extension that has:

<ul>

<li>viewerActionBinding, point this to your View Id above (example.view)

<ul>

<li>includes of org.eclipse.ui.navigator.resources</li>

</ul>

</li>

<li>viewerContentBinding, point this to your View Id above (example.view)

<ul>

<li>includes of:

<ul>

<li>org.eclipse.ui.navigator.resources</li>

<li>org.eclipse.ui.navigator.resourceContent</li>

<li>org.eclipse.ui.navigator.resources.*</li>

</ul>

</li>

</ul>

</li>

</ul>

<pre>

   <extension

         point="org.eclipse.ui.navigator.viewer">

       <viewerActionBinding

            viewerId="example.view">

         <includes>

             <actionExtension pattern="org.eclipse.ui.navigator.resources.*" />

         </includes>

       </viewerActionBinding>

       <viewerContentBinding 

            viewerId="example.view">

          <includes>

       	     <contentExtension pattern="org.eclipse.ui.navigator.resourceContent" />		       	      

	     <contentExtension pattern="org.eclipse.ui.navigator.resources.filters.*"/>

          </includes>

       </viewerContentBinding>

   </extension>

</pre>

</li>

</ol>

</li>

</ol>

</BODY>

</HTML>

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<HTML>

<HEAD>

<meta name="copyright"

	content="Copyright (c) Oakland Software and others 2008. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page.">

<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">

<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1"

	TYPE="text/css">

<TITLE>Migrating from the ResourceNavigator</TITLE>

<link rel="stylesheet" type="text/css" HREF="../book.css">

</HEAD>

<BODY BGCOLOR="#ffffff">

<h1>Migrating from the ResourceNavigator</h1>

<p>

First follow the steps to add the Common Navigator for <a href="cnf_steps_resources.htm">resources</a>.

If your application is an RCP application, also do the <a href="cnf_steps_resources.htm">RCP steps</a>.

</p>

<p>The following steps discuss the migration component for each part of the ResourceNavigator</p>

<ol>

<li>

<code>org.eclipse.ui.ide.resourceFilters</code>

<p>

Add the corresponding 

<b><a href="../reference/extension-points/org_eclipse_ui_navigator_navigatorContent.html">org.eclipse.ui.navigator.navigatorContent/commonFilter</a></b>

extensions.

</p>

</li>

<li>

<code>FrameList</code> support <code>get/setFrameList()</code>

<p>

The FrameList support is used for the Go Into functionality.  Support for this 

is included in the ProjectExplorer subclass of CommonNavigator.  You should subclass ProjectExplorer

instead of CommonNavigator. 

</p>

</li>

<li>

<code>ResourcePatternFilter</code> support <code>get/setPatternFilter()</code>

<p>

Configure the ResourcePatternFilter using the 

<b><a href="../reference/extension-points/org_eclipse_ui_navigator_navigatorContent.html">org.eclipse.ui.navigator.navigatorContent/commonFilter</a></b>

extension.  Then you can access the instance of the filter using the following code (where <code>yourViewer</code> is the instance

of the CommonViewer and <code>yourFilterId</code> is the string of the Id of your common filter configured above:

<pre>

INavigatorContentService contentService = yourViewer.getNavigatorContentService();

INavigatorFilterService filterService = contentService.getFilterService();

ICommonFilterDescriptor[] fds = filterService.getVisibleFilterDescriptors();

for (int i = i; i < fds.length; i++) {

	if (fds[i].getId().equals(yourFilterId))

		return filterService.getViewerFilter(filterDescriptor);

}

</pre>

</p>

<p>

Note:

(??? possibly don't deprecate ResourcePatternFilter, or move this into 

org.eclipse.ui.navigator.resources as it is; this class does not depend on ResourceNavigator.)

</p>

</li>

<li>

<code>IWorkingSet</code> support <code>get/setWorkingSet()</code>

<p>

??? figure out the corresponding ProjectExplorer way to do this.

</p>

</li>

<li>

<code>ResourceSorter</code> support <code>get/setResourceSorter()</code>

<p>

??? Similar to the filter service.

</p>

</li>

<li>

<code>ResourceComparator</code> support <code>get/setResourceComparator()</code>

<p>

??? Have to use ResourceSorter instead for now as the CN does not directly support

ResourceComparators

</p>

</li>

</ol>

</BODY>

</HTML>