plugin.xml

org.eclipse.ui.perspectives

The platform itself defines one perspective, the Resource perspective. Other platform plug-ins, such as the help system and the Java tooling, define additional perspectives. Your plug-in can define its own perspective by contributing to the org.eclipse.ui.perspectives extension point.

The specification of the perspective in the plugin.xml is straightforward. The following markup is used by the workbench in defining its own resource perspective.

<extension
         point="org.eclipse.ui.perspectives">
      <perspective
            name="%Perspective.resourcePerspective"
            icon="icons/full/cview16/resource_persp.png"
            class="org.eclipse.ui.internal.ResourcePerspective"
            id="org.eclipse.ui.resourcePerspective">
      </perspective>
   </extension>

A plug-in must supply an id and name for the perspective, along with the name of the class that implements the perspective. An icon can also be specified. The perspective class should implement IPerspectiveFactory.

The Hello World manifests

Before we run the new view, let's take a look at the manifest files that were generated for us. First, double-click the plugin.xml file to open the plug-in editor and select the plugin.xml tab.

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.0"?>
<plugin>
	<extension point="org.eclipse.ui.views">
		<category
			name="Hello Category"
			id="com.example.helloworld">
		</category>
		<view
			name="Hello View"
			icon="icons/sample.gif"
			category="com.example.helloworld"
			class="com.example.helloworld.HelloWorldView"
			id="com.example.helloworld.HelloWorldView">
		</view>
	</extension>
</plugin>

The information about the view that we provided when we created the plug-in project was used to generate an entry in the plugin.xml file that defines our view extension. In the extension definition, we define a category for the view, including its name and id. We then define the view itself, including its name and id, and we associate it with the category using the id we defined for our category. We also specify the class that implements our view, HelloWorldView.

As you can see, the plug-in manifest file wraps up all the information about our extension and how to run it into a nice, neat package.

The other manifest file that is generated by the PDE is the OSGi manifest, MANIFEST.MF. This file is created in the META-INF directory of the plug-in project, but is most easily viewed by clicking on the MANIFEST.MF tab of the plug-in editor. The OSGi manifest describes lower-level information about the packaging of the plug-in, using the OSGi bundle terminology. It contains information such as the name of the plug-in (bundle) and the bundles that it requires.

org.eclipse.ui.viewActions

It is common for plug-ins to contribute behavior to views that already exist in the workbench. This is done through the org.eclipse.ui.viewActions extension point. This extension point allows plug-ins to contribute menu items, submenus and tool bar entries to an existing view's local pull-down menu and local tool bar.

You may have noticed an item in the navigator's local tool bar that becomes enabled whenever a readme file is selected. This item also appears in the navigator's local pull-down menu. These actions appear because the readme tool plug-in contributes them using the viewActions extension.

The relevant plugin.xml contribution is below.

<extension
    point = "org.eclipse.ui.viewActions">
      <viewContribution 
         id="org.eclipse.ui.examples.readmetool.vc1" 
         targetID="org.eclipse.ui.views.ResourceNavigator">        
	   <action id="org.eclipse.ui.examples.readmetool.va1" 
              label="%PopupMenu.ResourceNav.label" 
	      menubarPath="additions"
              toolbarPath="additions" 
              icon="icons/obj16/editor.png" 
              tooltip="%PopupMenu.ResourceNav.tooltip" 
   	      helpContextId="org.eclipse.ui.examples.readmetool.view_action_context"
              class="org.eclipse.ui.examples.readmetool.ViewActionDelegate" 
              enablesFor="1"> 
		<selection class="org.eclipse.core.resources.IFile" name="*.readme"/> 
	   </action>
      </viewContribution>
 </extension>

A view contribution with a unique id is specified. The view to which we are adding the action is specified in the targetID. We are contributing to the resource navigator's menu.  We specify the label and the menu bar and tool bar locations for the new action.  (For a complete discussion of menu and toolbar locations, see Menu and toolbar paths).

We also specify the conditions under which the action should be enabled. You can see that this action will be enabled when there is one selection (enablesFor="1") of type IFile (class="org.eclipse.core.resources.IFile"), whose name has ".readme" in the file extension (name="*.readme"). Sure enough, that's exactly what happens when you click around in the resource navigator.  

The information in the plugin.xml is all that's needed to add items to menus and tool bars since plug-in code will only run when the action is actually selected from the menu or toolbar. To provide the action behavior, the implementation class specified in the plugin.xml must implement the IViewActionDelegate interface.

In this example, the readme plug-in supplies ViewActionDelegate to implement the action. If you browse this class you will see that it includes methods for remembering its view, handling selection changes, and invoking its action.  When invoked the action itself simply launches a dialog that announces it was executed.

public void run(org.eclipse.jface.action.IAction action) {
	MessageDialog.openInformation(view.getSite().getShell(),
		MessageUtil.getString("Readme_Editor"),  
		MessageUtil.getString("View_Action_executed")); 
}

Although this action is simple, we can imagine how using selections and more functional dialogs could make this action do something more interesting.

Contributing resource filters

The resource filters extension allows plug-ins to define filters that are useful for filtering out file types in the resource navigator view. This extension is useful when special file types are used to represent internal plug-in information but you do not want the files to be shown in the workbench or manipulated by the user.

The workbench filters out the pattern ".*" to exclude internal files such as .metadata from the resource navigator. Likewise, the JDT plug-in filters out "*.class" files to hide compiled classes.

The markup for the resource filters extension is simple.  The following is from the workbench plugin.xml.

<extension
         point="org.eclipse.ui.ide.resourceFilters">
      <filter
            selected="false"
            pattern=".*">
      </filter>
   </extension>

The filters can be enabled by the user using the resource navigator's local pull-down menu.

In addition to declaring the filter pattern, the plug-in can use the selected attribute to specify whether the filter should be enabled in the resource navigator.  This attribute only determines the initial state of the filter pattern.  The user can control which filter patterns are active.

Adding the preference page

The combination of product properties and default preference values can fully configure the Universal Welcome if no further customization is desired. For products that want to allow users to customize Welcome, a preference page is available. The following code should be added to the product's plugin.xml:

   <extension
         point="org.eclipse.ui.preferencePages">
      <page
            category="org.eclipse.ui.preferencePages.Workbench"
            class="org.eclipse.ui.intro.universal.ExtensionFactory:welcomeCustomization"
            id="com.example.intro.introCustomization"
            name="%introCustomizationPreference.name">
         <keywordReference id="org.eclipse.ui.ide.appearance"/>
      </page>
   </extension>

This code will add the Welcome customization preference page. The page allows users to select the presentation theme. The original choice is provided by the theme preference in the plugin_customization.ini file. In addition, users can choose from the list of available root pages. Checking the root page causes the related tab to appear at the top of the dialog.

When saved, this preference page will prefix the variables with the product id so that it does not interfere with the settings made for other products in the same workbench. Alternatively, selecting the checkbox above will not prefix the variables, making the stored settings visible to all the products.

Completing the plug-in manifest

We started this example by creating our plug-in and document files. Next we created toc files to describe the organization of our content. The remaining piece of work is to pull everything together into a master toc and update our plugin.xml to actually contribute the master toc. 

We start by creating a toc.xml to contribute the three tocs we created initially.  Instead of providing an href for each topic, we use the link attribute to refer to our existing toc files.

<toc label="Online Help Sample" topic="html/book.html">
	<topic label="Concepts">
		<link toc="toc_Concepts.xml" />
	</topic>
	<topic label="Tasks">
		<link toc="toc_Tasks.xml" />
	</topic>
	<topic label="Reference">
		<link toc="toc_Ref.xml" />
	</topic>
</toc>

Then we update the plugin.xml to contribute our master toc:

   <extension point="org.eclipse.help.toc">
      <toc file="toc.xml" primary="true" />
   </extension>

Note the use of the primary attribute.  Setting this attribute to true indicates that the toc should always appear in the navigation, even if it is not referenced by any other toc.  This way, our "master" toc is always guaranteed to show up in the topics list.  It appears at the top level list of books since no other toc references it. 
Note: If more files were associated with this toc but not present in the navigation, but just linked from other topics, then to have those topics available to the search engine we would have to use the extradir attribute in the toc.

Finally, we contribute our individual toc files.

   <extension point="org.eclipse.help.toc">
       <toc file="toc_Concepts.xml" />
       <toc file="toc_Tasks.xml" />
       <toc file="toc_Reference.xml" />
   </extension>

These toc files will not appear in the top level list of books because we did not set the primary attribute.  Toc files that are not designated as primary will only appear in the documentation web if they are referred to from some toc that is a primary toc or is linked in by a primary toc.

That's it. If you copy your plug-in directory to the platform's plugins directory, start the platform, and choose Help->Help Contents, you should see your example appear in the list of books. If you click on the "Online Help Sample", you'll see your toc structure:

Commands

A command is the declaration of a user action by id.  Commands are used to declare semantic actions so that action implementations defined in action sets and editors can associate themselves with a particular semantic command.  The separation of the command from the action implementation allows multiple plug-ins to define actions that implement the same semantic command.  The command is what gets associated with a particular key binding.

The workbench defines many common commands in its plugin.xml file, and plug-ins are encouraged to associate their own actions with these commands where it makes sense.  In this way, semantically similar actions implemented in different plug-ins may share the same key binding.

Defining a command

Commands are defined using the org.eclipse.ui.commands extension point.  The following comes from the workbench markup:

<extension
	point="org.eclipse.ui.commands">
	...
	<command
		name="%command.save.name"
		description="%command.save.description"
		categoryId="org.eclipse.ui.category.file"
		id="org.eclipse.ui.file.save">
	</command>
	...

The command definition specifies a name, description, and id for the action.   It also specifies the id of a category for the command, which is used to group commands in the preferences dialog.  The categories are also defined in the org.eclipse.ui.commands extension point:

      ...
      <category
            name="%category.file.name"
            description="%category.file.description"
            id="org.eclipse.ui.category.file">
      </category>
      ...

Note that there is no implementation specified for a command.  A command only becomes concrete when a plug-in associates its action with the command id.

Associating an action with a command

Actions can be associated with a command in code or in the plugin.xml for action sets.  Your choice depends on where the action is defined.

Actions that are instantiated in code can also be associated with an action definition using IAction protocol.  This is typically done when the action is created.  The SaveAction uses this technique when it initializes itself.

public SaveAction(IWorkbenchWindow window) {
	...
	setText...
	setToolTipText...
	setImageDescriptor...
	setActionDefinitionId("org.eclipse.ui.file.save"); 
}

(Note:  The method name setActionDefinitionID could more appropriately be named setCommandID.  The method name reflects the original implementation of key bindings and uses outdated terminology.)

By invoking setActionDefinitionID, the implementation action (SaveAction) is associated with the command id that was used in the command definition markup. It is good practice to define constants for your action definitions so that they are easily referenced in code.

If you define an action in an action set, then you typically do not need to instantiate an action yourself.  The workbench will do it for you when the user invokes your action from a menu or the keyboard.  In this case, you can associate your action with a command ID in your  XML markup.  The following shows a hypothetical markup for an action set:

<extension point = "org.eclipse.ui.actionSets">
	   <actionSet id="com.example.actions.actionSet"
		   label="Example Actions"
		   visible="true">
		   <action id="com.example.actions.action1"
			   menubarPath="additions"
			   label="Example Save Action"
			   class="org.example.actions.ExampleActionDelegate"
			   definitionID="org.eclipse.ui.file.save">
		   </action>
		   ...
	   </actionSet>
   </extension>

The definitionID attribute is used to declare a command ID for the action.

Using either technique, associating your action with a command ID causes any key bindings that get defined for the command org.eclipse.ui.file.save to invoke your action when appropriate. 

Now let's look at how these key bindings get defined.