Building templates with the Eclipse Plug-in Development Environment (Part 1)


1.Eclipse Plugin Development Enviroment 

This article introduces the creation of templates in Eclipse so you can enhance the experience of your clients. We will develop a simple template as an example of the flexibility PDE's templating system provides

Today will focus on the templating functionality offered in PDE. If you remember the day you tried to create your first plug-in in Eclipse, you were making your way through the New Plug-in Project wizard.

Figure 1

Figure 2

in Figure 2 you can find template wizard to select different templates for your plugin project actually this is really helpful for any user to understand and explore the project that they trying to working on.

PDE have of two main parts UI and Build. The UI component is responsible for all the wizards and editors you see while developing plug-ins. It also contains the templating infrastructure . The Build component is responsible for the building and packaging of plug-ins.

2.Creating templates 

first create a new plug-in project (File > New > Project > Plug-in Project). Take advantage of templates. Make sure your project has a dependency on org.eclipse.pde.ui. so that you need to check the tick that asks "this plugin will make contribution to the ui". Once this is done, we can go to the Extensions tab of the plug-in editor and begin creating our template.

3.PDE templates 

All the templates in the Plug-in Project wizard are owned by PDE and the source for these templates is freely available on Eclipse's git repository.

The most important extension point we'll use to create templates is org.eclipse.pde.ui.pluginContent. This provides the ability to contribute wizards that create additional content for PDE plug-in projects. After the plug-in manifest and key files have been created, these wizards can be used to add more files and extensions to the initial structure. Our implementation of this wizard is going to add content based on a parametrized template customized based on the user choices in a wizard. Now let's get started with this extension point.

Figure 3

 define a new wizard with ID (org.X2CODE.example.wizard.wizard1),
name (Simple View Wizard), icon and class definition (see the code below). The important method of the class definition is createTemplateSections(), which is responsible for returning template sections that drive the creation of content. The next section will discuss how to create our template file(s) and afterward, what exactly resides in a template section.

4.Sample Template wizard

package org.X2CODE.example.wizard; 

import org.eclipse.pde.ui.IFieldData; 
import org.eclipse.pde.ui.templates.ITemplateSection; 
import org.eclipse.pde.ui.templates.NewPluginTemplateWizard; 

public class SimpleViewTemplateWizard extends NewPluginTemplateWizard {   protected IFieldData fData;       
public void init(IFieldData data) {        
super.init(data);        
fData = data;        
setWindowTitle("Simple View Wizard");              

public ITemplateSection[] createTemplateSections() {        
return new ITemplateSection[] {new SimpleViewTemplateSection()};    

5.Template Project Structure

Figure 4

6.Conditional logic in templates

As you see in our template, it is possible to have simple conditional logic in our templates. The templating system supports simple and nested if statements. This can be helpful if you desire to make your templates flexible based on user input. 

The next is to create a template we can use to generate code. To do this, we have to set up our project properly. The child of this templates folder is viewtemplate and signifies the grouping of files, known as a section, you want associated with your template. You can name this folder anything you want. Under the section folder, we have two folders: bin and java. These contain content that will be copied when the template is created. The content in the java folder is important because this is the class that represents our view. It's named $template$.java because the templating system will automatically swap out the variable $template$ for the user-desired name. Inside this class file, we also have variable substitutions we want our users to customize. The names of these variable substitutions are flexible and will be discussed in the next section, which focuses on template sections.

if you look at the template folder name it is some what important because The name of this folder is significant as it dictates to PDE what versions of Eclipse this template is applicable for. If you wanted your template to run on V3.1 and greater, you would name your folder templates_3.1.

7.Template sections 


Template sections are the Java classes that contain the UI and control logic that drive the input to your template. Template sections must implement the ITemplateSection interface. For your convenience, PDE has an abstract class, OptionTemplateSection, that can save you a lot of time. There are quite a few things you can do with template sections (I'll leave it to you as an exercise to explore the included code sample), we're going to focus on the most important ones. The first step is to make sure we're adding wizard pages via the addPages(...) method. In this simple case, we only have one page to add, on the first page.

7.1 $Template$.java

package $packageName$; 

import org.eclipse.swt.SWT; 
import org.eclipse.swt.widgets.Composite; 
import org.eclipse.swt.widgets.Label; 
import org.eclipse.ui.part.ViewPart; 

public class $className$ extends ViewPart {  
public void createPartControl(Composite parent) {      
Label label = new Label(parent, SWT.CENTER);      
%if importantMessage      
   String message = new String(" $message$!!!");                 %else      
   String message = new String(" $message$"); 
%endif      
label.setText(message);   
        }      
public void setFocus() {
        }   
}


7.2 sampleTemplateSection.java

...
public void addPages(Wizard wizard) {  
WizardPage page = createPage(0, IHelpContextIds.TEMPLATE_INTRO); page.setTitle("Simple View Template");   
page.setDescription("Creates a simple view");   
wizard.addPage(page);   markPagesAdded(); 

...

The next step is to provide clients with a UI so they can take advantage of the template. This is done by declaring variables used by the template and also by adding options via the addOption(...) method. In our class, we have a convenience method createOptions(), which gets called in the constructor to create the options.



... 
private static final String KEY_CLASS_NAME = "className"; 
private static final String KEY_VIEW_NAME = "viewName"; 
private static final String KEY_MESSAGE_NAME = "message"; 
private static final String KEY_IMP_MESSAGE_NAME = "importantMessage";
 ... 
private void createOptions() {   

addOption(KEY_CLASS_NAME, "Class Name ", "SimpleView", 0);   addOption(KEY_VIEW_NAME, "View Name", "SimpleView", 0);   addOption(KEY_MESSAGE_NAME, "Message", "Hello World", 0);   addOption(KEY_IMP_MESSAGE_NAME, "Important?", false, 0); 

..

The templating system provides several methods to help you add options; you can see the implementation of these methods in the BaseOptionTemplateSection class. However, if you require more flexibility than what the templating system offers, I will point you to the registerOption(...) method. It is possible to create your own set of options, for example, if you wanted a combo choice option, you would instantiate a ComboChoiceOption and invoke the registerOption(...) method.

The final step is to write the code that creates and populates the extension point(s) you're interested in. In our simple example, we are only concerned with the org.eclipse.ui.views extension point. In the PDE templating system, the updateModel(...) method is called when the template is being created, and it is expected of you as the template creator to create your extensions -- and other things -- here. As a side note, it is also possible to create multiple extension points even though the code listing below shows just the creation of one

...          
protected void updateModel(IProgressMonitor monitor) throws CoreException {      
IPluginBase plugin = model.getPluginBase();     
IPluginModelFactory factory = model.getPluginFactory();                    // org.eclipse.core.runtime.applications      
IPluginExtension extension = \      createExtension("org.eclipse.ui.views", true);            
IPluginElement element = factory.createElement(extension);      element.setName("view");      
element.setAttribute("id", getStringOption(KEY_CLASS_NAME));      element.setAttribute("name", getStringOption(KEY_VIEW_NAME));      element.setAttribute("icon", "icons/sample.gif");            
String fullClassName = getStringOption(KEY_PACKAGE_NAME)\         +"."+getStringOption(KEY_CLASS_NAME);            element.setAttribute("class", fullClassName);      extension.add(element);            plugin.add(extension);   }          
...

org.eclipse.pde.ui.templates The org.eclipse.pde.ui.templates extension point is important to note before we conclude. This extension point provides the gateway to the custom plug-in wizard. If you have a specific extension point that you're templating, I recommend you extend this as it allows clients to use your template along with others. In the case of the example used here, we can simply reuse the OptionTemplateSection implementation (SimpleViewTemplateSection). I just want to stress that if you created a custom extension point, it would help your users if you provided a template for them. Remember when you were first learning Eclipse and had to create a view? The view template was highly valuable in understanding how things work. Extend the same courtesy to your users.



1 comment : Leave Your Comments

  1. When you copy a post, always link back to the original one.
    http://aniszczyk.org/wp-content/uploads/2009/10/Building-templates-with-the-Eclipse-Plug-in-Development-Environment.pdf

    ReplyDelete