Branding Eclipse Products

Last year we worked on a new Eclipse-based IDE, in particular creating product branding from scratch. Despite visual editors and several existing online tutorials, that still proved confusing, so I've decided to documented what we've learned.

In this post, we'll review branding of a simple product. It has:

• One functional plugin, and one functional feature including that one plugin
• One product plugin and one product feature including the product plugin and functional feature
• Product configuration

To make things simpler:

• I use artwork we used in our products.
• There's no localization of strings
• The welcome/intro screen is almost neglected, since we use custom HTML for that, and it might be best approach for any new product.

Of course, I assume you know what is plugin and what is feature.

Functional features

Functional feature, along with contained plugins, implements some useful behavior that you can potentially install into any Eclipse-based product. For example, EGit feature is equally useful for Java and C++ IDE. For proprietary products, it is often tempting to just mix everything together, but creating separate features is often beneficial. The first example is of exactly such standalone feature, see sources. 

The important files in the plugin are META-INF/MANIFEST.MF, about.ini and about.html. For the feature, feature.xml and about.html are important. In particular, feature.xml relays most of the branding to a 'branding plugin', which, in our case, is the lonely functional plugin. 

Starting with that source, you can import it into your PDE, click on feature.xml, export feature into a directory, install it into a second Eclipse installation, and then "Help->About" dialog will look like this:

In the row of icons that represent feature providers, there is our "crystal ball" logo. The icon is defined by the branding plugin, via featureImage attribute in about.ini. Should you have multiple feature with the same icon (pixel-wise), they will be merged in this dialog. Clicking "Installation Details" gives us in-depth information:

This dialog shows root P2 installable units in the Eclipse instance. The 'name' column is taken from 'label' attribute of feature.xml, and the description below comes from the 'description' element in feature.xml.  The same description is shown when installing the feature. We can also use the "Properties" button to see more details from feature.xml, like copyright and license:

The above is fairly reasonable. The features tab, however, brings some surprises:

The "Feature Name" column is coming from branding plugin, the Bundle-Name attribute of MANIFEST.MF. The description below is composed from 'label' attribute in feature.xml and 'aboutText'  attribute in plugin's about.ini. The icon is also coming from about.ini - and if you specify icon attribute in feature.xml, it is ignored. Finally, the "License" button opens about.html file in the feature directory - which is generally different from license attribute in feature.xml. Clicking the "Plug-in Details" button shows branding information for plugins, which is rather simple:

The "Provider" and "Plug-in Name" fields correspond to Bundle-Vendor and Bundle-Name in MANIFEST.MF. The "Legal Info" button opens about.html in plugin's root directory. As an aside, I'm not sure why it's called "License" for features and "Legal Info" for plugins and "License Agreement" for installable units.

Products

Products put together a set of functional features that make sense for a particular audience, and add particular overall branding. Physically, product consists of a product feature and product plugin, organized the same way as functional feature and plugin. The example source for that is here, which you can again import into PDE, export into P2 repository, and install into separate Eclipse instance, and then run it with the "-product com.codesourcery.seed.product.product" command-line option.

The key element of product branding is this extension in plugin.xml:

<product name="Example Eclipse Product" application="org.eclipse.ui.ide.workbench">
    <property name="appName" value="Example Eclipse Product"/>
    <property name="windowImages"  value="images/csl16.png,images/csl32.png,images/csl48.png"/>
    <property name="aboutImage" value="images/IDE_about.png"/>
    <property name="aboutText" value="About text for the example product."/>
    ...
</product>

The first two properties define outside appearance of the product - it's name, shown in the window title, and its icon, shown in taskbar, or launcher, or window switcher, depending on your OS. The other two attributes affect the about dialog box, making it look like below:

Now it actually looks like a custom product! The installation details in this case are almost the same, except that it has two features, one depending on the other:

There are several other properties in product definition that are related to welcome screen, but as I've said, we replace it completely, so I'm not going to describe it. The example source code has some definitions if you're interested.

Launcher and Product Build

The product feature we've built can be exported from PDE (or built with Maven, if you wish), and installed into Eclipse, but we usually want to build a complete product that can be immediately run. We need product configuration (.product file) for that, and it's covered in detail elsewhere. As far as branding goes, we only need two details:

• Showing custom splash screen on startup
• Starting our product

The product configuration specifies them in fairly direct way - the product is specified as attributes of the top-level 'product' element, and the splash screen becomes a command-line attribute to the launcher. In the exported product directory, two files control this behaviour. First, the eclipse.ini files in the root directory contains '-showsplash com.codesourcery.seed.product' for the splash screen. Second, the 'configuration/config.ini' specifies the product to run. That almost completes our product branding. 

Almost, because while product extension point can specify window icon and similar properties, the .product file also can specify those. When you do product export in PDE, the properties from .product files are copied into product extension point, so unless you duplicate them, you get product with no window icons. This problem is accounted for in the final version. We don't have this problem in practice, since we built the final product from the command line, and so splash screen and product id is the only branding we need in the '.product' file.

Do it yourself

I have put together a seed Eclipse product over at GitHub, and you are free to use it if you are creating a new product. I would suggest these tips:

• Use high-resolution artwork, preferably created from vector originals, and keep those originals.
• Having license in every about.html and every feature.xml is awkward. Either automate it, or refer to documentation for license terms.
• Use the same label for each functional feature and its branding plugin
• If you can get HTML support working on your target systems, use custom HTML instead of default welcome screen.

Hope this help!

Acknowledgements

Dmitry Kozlov has worked with me on this, while Sourcery Services allowed me to take time to summarize our experience.