### 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.gif
    				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.gif
    		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.

- about.ini specifies the about text and images for features, windows, and the about dialog itself. It also specifies the welcome page. See Customization using about.ini for a complete description of the format of this file.
- about.properties should be used to hold translated strings from the about.ini file (using "%var" as the value in about.ini paired with an entry for the key "var" in about.properties. This file is a java.io.Properties format file.
- about.mappings can be used to fill in values for fill-in fields in the about text. This is useful when the about text contains information specific to a particular install, such as license key, install date, or licensed user. For example, the about text could be defined as "AcmeWeb is licensed to {0}". The about.mappings file could be generated at install time based on input from the user. The final form should contain a mapping for the field, such as "0=Joe Q. Webuser". The about.mappings file is a java.io.Properties format file.

### 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.gif

### 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.