Hidden Clause

(The next few posts are a cheat. I have been slowly amassing these blogs for the last few weeks/months.)

So you want to write an Eclipse plug-in and don’t know where to start? Join the crowd. I wrote a great book on Eclipse (well, at least I liked it) and still find myself at a loss when it comes to implementing a standard feature set of functionality within a plug-in (sample chapters here).

I am going to document (read: heavily edit) what I did to implement a plug-in I am building to relearn all the things I wrote about in my book, but never really got a chance to use in this ever changing economy.

This blog will act as my requirements document as well as my FAQ. This way, when I forget how I did something I can just come here.

Where to Start?

Let’s say I have a software tool that is in desperate need of an IDE to help automate a number of silly tasks. That means a few things:

• I want to aggregate the tasks
• I want to aggregate any files involved in configuring the tool
• I want to aggregate any source code involved in extending the tool

In addition, I want to use Mylyn to help me keep track of my tasks.

The list of things that can be done in Eclipse can be rather daunting. At a high-level this plug-in needs to accomplish a stardard list of things:

• Create a project
• Create some custom format XML files
• Manage files within the project
• Edit some XML files using a form-based approach rather than just editing the XML directly
• Deploy files to a target directory

When it comes to adding functionality the best place to start is with use cases. Here are the ones I used:

• Create a custom project
• Edit a custom XML file
• Deploy the files
• Monitor how the deployed files have affected

The actor for all of the use cases will be a developer.

Create a custom project

The steps to create the custom project will be:

1. Open the New Wizard dialog.
2. Open the Custom Project folder
3. Select the Custom Project item
4. Press Next
5. Enter the name of the project and a location in which to put it
6. Press Finish
7. A custom perspective will open

The custom perspective that will only display projects of my type. The project will contain custom categories where files will be displayed. The physical location of the files and the displayed location of the files in the navigator will be different. For example, the files may be located in:

root/
  folder1/
    filetype1-1.xml
  folder2/
  folder3/
    filetype2-1.xml
    filetype3-1.xml

The custom navigator will display the files in an almost flat structure:
My Project
  Category 1
    fileType1-1.xml
  Category 2
    fileType2-1.xml
  Category 3
    fileType3-1.xml

If the user wants to see the actual folder structure they can look at the project in the Navigator view.

The custom perspective will display:

• A custom navigator
• The Navigator view
• The Outline view
• A log file view
• Some yet-to-be-announced views
• Editors as appropriate

The custom navigator will display individual images next to the workspace, project, categories and various file types that are displayed.

The custom navigator will allow the standard Eclipse behaviors from a popup:

• Cut/copy/paste
• Rename
• Refresh
• Workspaces
• New
• Project
• Other

Edit a Custom XML file

There are a few XML files that need to be edited in a consistent and reliable way. The user will interact with a custom editor that will let them modify the XML file through a form or as XML text. The editor will have multiple form pages and one text page for direct XML editing.

Deploy the files

Once the files are in place, copy the files to the proper locations in the target software.

Right-click on the workspace or project will deploy the entire project.
Right-click on a particular category will deploy only the contents of that category
Right-click on a particular file will deploy just that file

In Addition

The above is all well and good, but the plug-in should also adhere to best practices whenever possible and that includes testing, putting strings in separate property files and flagging other strings as ignorable, caching images and disposing them.

What about testing? Testing is certainly interesting in the development of an Eclipse plug-in. The Eclipse Plug-ins book explains how to test a plug-ins, but there are a few things to bear in mind when testing anything:

• Don’t test the platform
• Test new functionality
• Test before fixing a bug

I don’t enjoy having to change the API of a class to support testing, but sometimes there aren’t a lot of ways to test an API without retrofitting Eclipse to support dependency injection.

Therefore I will not be writing tests when creating Wizards or perspectives, but I will be writing tests on the behavior that the various GUI components will execute when they are told to do something. For example, the GUI flow for the use case Create A Custom Project will consist of:

• Opening the New Wizard dialog
• Displaying one or more Wizard pages
• Clicking Finish causes the custom perspective to open
• Clicking Cancel leaves everything the way it was

The flow, as a first phase of implementation, can work with little or no code. Whatever code needs to be written will just be glue code. Once those pieces come together then behavior can be written:

• Create a custom project
• Display the custom project in a custom navigator

Bear in mind that the Eclipse Plug-in Wizard has a number of templates that you can select from to create most of what you need to implement the first phase of a plug-in. The problem is that some of the things I needed were not there so I thought it better to assemble it piece by piece and blog about it.

Sorry for all the talking and not implementing anything. And BTW, I might never finish. Hope that is not a problem.