Where's the code filling?

Today I was having a problem trying to open a class file I knew the name of but not the project it belonged to (meaning I couldn't just import the package or check it out from CVS). If my workspace hadn't been empty then there wouldn't have been any problem; the Open Type functionality would likely have found the desired class file in the plug-in dependencies. Unfortunately in this case I had just downloaded the nightly build and was using a fresh workspace.

The easiest workaround would have been to create a dummy plug-in project and then try Open Type again. Fortunately, when I mentioned my approach to a co-worker he suggested a more professional solution. His suggestion was to open the plug-ins view, select all the plug-ins in the view, right-click, and select "Add to Java Search." This process created a project in my workspace named External Plug-in Libraries which contained a library of jar files for all the code I might ever want to look at.

In the end, while my co-worker's solution may have been slightly more involved, it definitely seemed like a more proper use of Eclipse functionality and better than my first solution which was just a workaround.

Exploring the Flexibility of Perspectives

As evidenced by over 67 pages of preferences and other configurable options, Eclipse is a very flexible platform; this flexibilty is matched in the user inteface through the use of perspectives. Perspectives define the set and layout of views and shortcuts in the workbench window. While developing a template for the perspectives extension I was able to explore the true power of perspectives. The easiest way to see their flexibility in action is by going through the "Customize Perspective..." pages in the Window menu. The majority of the UI's dynamic content can be modified using the three submenu selection windows on the Shortcuts tab and the numerous options on the Commands tab. An interesting exercise is to turn off all the standard options for a perspective and only add back the ones you intend to use; then save the perspective and use it for a while to see if you begin to use the shortcuts more now that you know where they came from.

When all the options are turned off through the custmization of the perspective, the views that remain are the contributions of the defining perspectives extension. The extension references a class file that is responsible for adding the various views, action sets, and shortcuts. The common method for adding views is to create an IFolderLayout with some position relative to the editor area and use the methods IFolderLayout.addView(String viewId) or IFolderLayout.addPlaceholder(String viewId) (adding a placeholder sets where the view will show up if it is enabled by the user at a later time). The best way of finding view ids is to look through the ui packages for the various platform components and find the id given in the views extension; additionally, the ids are sometimes given as API constants for the various packages. Then, calls to IPageLayout.addActionSet(String actionSetId) will provide the content for the menus and the toolbar and calls to IPageLayout.addNewWizardShortcut(String id) will provide the options shown when the user selects File > New. Again, the required ids can often be found as API constants or by looking at the id given in the respective extension of the various ui packages.Finally, calls to IPageLayout.addShowViewShortcut(String id) will populate the list of rapid navigation views in the Window> Show View submenu and calls to IPageLayout.addPerspectiveShortcut(String id) will generate the list of perspective options for the Window > Open Perspective submenu.

An example of this process can be seen in the class PDEPerspective where the steps are laid out quite logically and are easy to follow. I highly recommend playing with perspectives in order to experience just how much control is provided over the layout and presentation of the user interface.

For more information regarding perspectives, visit the online Help documentation.

Extension Point Templates: External Development

As a continuation from my previous entry regarding the development of templates for extensions points I will now explain how to create the template in a separate plug-in. The main steps are essentially the same; the two required extension points (org.eclipse.pde.ui.newExtensions and org.eclipse.pde.ui.templates) should be added with the appropriate elements, the template class file should be developed, and a templates_3.X folder should be created (where 3.X represents the package schema version) to hold the java and bin files.

The key change in the implementation is that the template class file should subclass OptionTemplateSection rather than PDETemplateSection (since PDETemplateSection is internal to the org.eclipse.pde.ui package). While the majority of the code can remain the same, the method getFormattedPackageName(String id) will need to be updated to so that the supplied package name corresponds to the usual naming standards. This involves replacing the call to super with functionality that will only use java identifier characters and a lower case letter to begin the package name. Furthermore, the abstract methods getInstallURL() and getPluginREsourceBundle() need to be implemented; some sample code is shown below:

protected ResourceBundle getPluginResourceBundle() {
Bundle bundle = Platform.getBundle(UITemplateMessages.Bundle_name);
return Platform.getResourceBundle(bundle);
}

protected URL getInstallURL() {
Bundle bundle = Platform.getBundle(UITemplateMessages.Bundle_name); return bundle.getEntry("/");
}

Note: The use of the variable UITemplateMessages.Bundle_name implies that there is an additional class file named UITemplateMessages that declares externalized strings and points to a file named messages.properties for their definitions.

Beyond making small adjustments to fit the specific extension point and confirming that all file references exist in the plug-in package, there isn’t much more that needs to be done. To test it, simply self host, find your template in the list of Extension Wizards and you’re on your way.

Extension Point Templates: A brief overview

This being my first entry of my first web log, readers must bear with me for any ramblings.

As a new member of the Platform UI team, my first task was to implement new templates for some of the extension points. Since no one on the team had done anything like this, I began to research the templates already in existence (i.e. Action Sets, Editors, Property Pages, etc...). What I discovered was that all the current templates are owned and maintained by the PDE UI team and that a lot of the code they reference is internal. This isn’t a problem if the desire is to create a patch for the PDE UI team, however certain problems arise if one wishes to develop templates in a separate plug-in (as was our intention in the beginning).

To shorten this blog entry I will explain how to develop a new template from an internal standpoint and then in a different entry I will go over the necessary changes to separate the template into an external plug-in. Fittingly, the creation of an extension point template requires the use of two other extension points provided by org.eclipse.pde.ui: newExtensions and templates. org.eclipse.pde.ui.templates is responsible for using contributingId to link to the extension point you’re creating a sample of (e.g. org.eclipse.pde.ui.decorators) and, most importantly, for associating the template with the class file that’s going to do all the work. Then, org.eclipse.pde.ui.newExtensions is responsible for the appearance of the new template in the Extension Wizards tab when adding a New Extension. The settings for newExtension are fairly straightforward; a wizard element defines what name and icon will appear, and links to the newly created template element, then a corresponding description element defines what explanation text will appear.

If you are new to eclipse (as I was) and are looking at templates that have already been created then it is important to note that some of the values (i.e. name and the description) have been externalized to a properties file. When I was first examining the templates already in existence it took me a little while to discover that %newExtension.templates.hello.name referred to a variable within plugin.properties aptly named newExtension.templates.hello.name.

The next step is to develop the class file that will build the template wizard and will perform the generation of the new extension point sample. These tasks are greatly simplified by creating the new file as a subclass of PDETemplateSection. Then the easiest thing to do is to copy the code from another template file and modify it to meet your needs. While most of the methods you copy will be important, a lot of them may be left “as is” or will only require slight modifications to be correct for to your template (i.e. getSectionId). The two methods that will require specific tailoring are createOptions and updateModel. createOptions is responsible for adding the various fields to your wizard page and there are four types of fields that may be invoked; the string option provides space for a user to specify text, the Boolean option creates a checkbox, the choice options creates a combo box when one out of many choices needs to be selected or radio buttons if there are only two choices, and the blank field may be added to provide spacing on the wizard page. The first three options may be given a label and an initial value to be shown on the page. updateModel is then responsible for creating the elements that will appear in the plugin.xml file. Each element is created using an IPluginElement object which is then given the name of the desired element (@see IPluginElement#setName(String name)) and is then assigned attributes for each of the fields that need a value to be set (i.e. id, label, class, etc…). The elements must be created as an instance for the provided parent and then added to the parent (@see IPluginParen#add(IPluginObject child)) once all the attributes have been set. Also worthy of note is the use of externalized strings as defined in PDEUIMessages and whose values are set in pderesources.properties.

The last step is to add any binary files, such as icons, and java files that need to be associated with the extension point. Once the user hits the finish button, AbstractTemplateSection will look in a templates_3.X folder (usually templates_3.0 unless the extension point is only supported in later versions) for a folder with the same name as given in getSectionId and then generate any files and folders found within. Files and folders found in the directory bin are copied into the target project without modification while files found in the directory java are copied into the java source folder by creating the folder structure that corresponds to the package name (variable packageName). The java files are subject to conditional generation and variable replacement (i.e. referring to $pluginId$ will cause a replacement with a variable with the name pluginId as defined in the template class file). This functionality is usually used to set the package name of any required files with a name defined by the user on the template wizard page.

Armed with the templates that have already been created plus the above descriptions, you should now be able to go forth and create your own templates for any one of those wonderful extension points that exist out there. All you need now is committer rights for PDE UI or someone willing to apply your changes in the form of a patch. Failing that, there are indeed ways to perform the creation process from an external plug-in but I’ll save those details for a different entry.