Customizing a primary feature

Product customization works differently when using the primary feature mechanism. The branding information for the feature is located in a plug-in identified by the primary feature (or the plug-in of the same name as the primary feature if none is specified). The files that designate and define branding information for our hypothetical acmeweb application are highlighted in the sample directory structure below:

acmeweb/
	acmeweb.exe	(product executable - invokes eclipse.exe and specifies the primary feature)
	eclipse/
		.eclipseproduct
		eclipse.exe
		startup.jar
		install.ini
		.config/
		platform.cfg
		jre/
		features/
			com.example.acme.acmefeature_1.0.0/    (primary feature)
				feature.xml
		plugins/
			com.example.acme.acmefeature_1.0.0/    (plug-in for primary feature.  Contains branding info.)
				plugin.xml
				about.ini
				about.html
				about.mappings
				about.properties
				acme.png
				plugin_customization.ini
				splash.jpg
				welcome.xml
			com.example.acme.acmewebsupport_1.0.0/
			...
		links/
			...

The plug-in associated with a primary feature is where the branding information for a product is specified.  There are many customizable aspects of a product.  Product-level customizations are defined using the about.ini file and other files described therein.  Products can also control the default preference values of other plug-ins.  This is done using the plugin_customization.ini file.

Referring once again to our sample product's primary feature plug-in, let's look closer at how the product is customized.

com.example.acme.acmefeature_1.0.0/
		plugin.xml
		about.ini
		about.html
		about.mappings
		about.properties
		acme.png
		plugin_customization.ini
		plugin_customization.properties
		splash.bmp
		welcome.xml

We'll review the same customizations that we reviewed for the products extension point, focusing on how the specification differs using the primary feature mechanism.

About dialogs

As discussed with the product-level customization, all features and plug-ins should contribute an about.html file that provides information about that particular plug-in.

The primary feature also supplies the information and graphics for the overall product.  Additional files are used to specify this information.

Window images

A 16x16 pixel color image can be used to brand windows created by the product.  It will appear in the upper left hand corner of product windows.  It is specified in the windowImage attribute in the about.ini file.  The path should be specified as a plug-in relative path.  A proper entry for the directory structure shown above would be as follows:

windowImage=acme.png

Welcome page

Plug-ins using the Eclipse 2.1 Welcome mechanisms should specify the welcome page file in the welcomePage attribute in the about.ini file. The path should be specified as a plug-in relative path.  A proper entry for the directory structure shown above would be as follows:

welcomePage=welcome.xml

You can also specify an national language lookup for the file.  (See Locale specific files for more detail.)

welcomePage=$nl$/welcome.xml

Splash screens

The product splash screen is supplied in a splash.bmp file located in the primary feature plug-in directory.  The image should be supplied in 24-bit color BMP format (RGB format) and should be approximately 500x330 pixels in size.  If splash screens need to be customized for different locales, they can be placed in a fragment of the primary feature's plug-in.

Preferences defaults

The plugin_customization.ini file is used to set the default preference values for preferences defined by other plug-ins.  This file is a java.io.Properties format file. Typically this file is used to set the values for preferences that are published as part of a plug-in's public API.  That is, you are taking a risk if you refer to preferences that are used by plug-ins but not defined formally in the API.  

One common customization is to set the default perspective for the workbench.  This preference is defined in the org.eclipse.ui plug-in.   The following example assumes that the product should be launched with the resource perspective as the default perspective.

org.eclipse.ui/defaultPerspectiveId=org.eclipse.ui.resourcePerspective

If you discover you need to change the default value for one of another plug-in's preferences, consult the API documentation for that plug-in to see if the preference is considered public.

The plugin_customization.properties file contains translated strings for the plugin_customization.ini file.