Previous Page
Next Page

18.2. Branding

In addition to providing structure to your collection of plug-ins and fragments, a feature also provides a single location for all your branding information (e.g., About pages, images, etc.). As stated earlier, the branding elements (such as the banner image shown in the Update Manager) aren't located in the feature project itself; most of the branding elements are located in the feature's associated branding plug-in.

There are quite a few different branding files that come into play at this point. Several of them only apply to Eclipse products (a stand-alone program built with the Eclipse platform) while the rest apply to any feature. The files that apply to any type of feature include:

  • about.html

  • about.ini

  • about.properties

  • about.mappings

  • <featureImage> (named in the about.ini file)

    The remaining files, which apply only to products, include:

  • <aboutImage>

  • <windowImages>

  • plugin_customization.ini

  • plugin_customization.properties

  • splash.bmp

18.2.1. The about.html file

Every feature and plug-in should include an about.html file. This is a simple HTML file that is displayed when the user opens the Eclipse About dialog, opens the Plug-in Details dialog, selects a plug-in, and then clicks the More Info button (see Figure 18-14).

Figure 18-14. The About page for the Favorites plug-in.

[View full size image]


Note that to satisfy the RFRS requirements, the about.html must contain the following phrase: "This offering is powered by Eclipse technology and includes Eclipse plug-ins that can be installed and used with other Eclipse (3.1)-based offerings".

18.2.2. The about.ini file

The about.ini file located in the feature's branding plug-in controls most of the feature branding information. It is a standard Java properties file that contains specific keys (see Table 18-1) such as the feature's about text, the name of the image displayed in the Eclipse About dialog (see Figure 18-15), and so on.

Figure 18-15. The About Eclipse dialog.


Table 18-1. about.ini Keys

Key

Description

aboutText

Short multiline description of the feature

featureImage

32x32 pixel image used in the About dialog

tipsAndTricksHref

Link to tips and tricks help page


The first key, aboutText, is a short multiline description of the feature that should give its name, version number, relevant build information, copyright information, and so on. The text will be visible in the About Features dialog (see Figure 18-16), which is accessible by clicking the Feature Details button in the About dialog.

Figure 18-16. The About Eclipse Features dialog.

[View full size image]


To localize (translate) this information, the text can be located in an associated about.properties file with a localization key placed in the about.ini file itself. The about text can also be parameterized with values supplied by the about.mappings file.

This can be useful encoding information that changes based on the product build (such as a build number) or the product install (such as the user's name or license key). For example, the about text might include the phrase "this product is licensed to {0}", where "{0}" represents an argument number that matches a corresponding value, such as "0=Joe User", in the mappings file.

The next key in the about.ini file, featureImage, is used to reference a 32x32 pixel image that will be used to represent the feature in the main About dialog (see Figure 18-15) and the About Features dialog (see Figure 18-16). If multiple features are installed, those features' images will be lined up along the bottom of the About dialog.

If a feature's documentation includes a "tips and tricks" section, you can reference it with the tipsAndTricksHref key. You can access the tips and tricks for any feature that includes them by selecting the Help > Tips and Tricks command.

The about.ini file for the Favorites feature should end up looking like this:

# about.ini
# contains information about a feature
# java.io.Properties file (ISO 8859-1 with "\" escapes)
# "%key" are externalized strings defined in about.properties
# This file does not need to be translated.

# Property "aboutText" contains blurb for About dialog. (translated) aboutText=%blurb

# Property "featureImage" contains path to feature image. (32x32) featureImage=feature.gif

The about.properties file contains any translatable strings from the about.ini file. For the Favorites feature, the file should look like:

# about.properties
# contains externalized strings for about.ini
# java.io.Properties file (ISO 8859-1 with "\" escapes)
# fill-ins are supplied by about.mappings
# This file should be translated.

blurb=Favorites\n\
\n\
Version: 1.0.0\n\
Build id: {0}\n\
\n\
(c) Copyright Quality Eclipse. 2003, 2006. All rights reserved.\n\
Visit http://www.qualityeclipse.com\n\
\n\
This offering is powered by Eclipse technology and includes\n\
Eclipse plug-ins that can be installed and used with other\n\
Eclipse (3.1)-based offerings.

18.2.3. Product branding

The remaining branding files are only applicable to products and are specified by contributing to the org.eclipse.core.runtime.products extension point (see Figure 18-17). As an example, here is the extension definition found in the org.eclipse.platform plug-in:

<extension id="ide" point="org.eclipse.core.runtime.products">
   <product name="%productName"
            application="org.eclipse.ui.ide.workbench"
            description="%productBlurb">
      <property name="windowImages"
                value="eclipse.png,eclipse32.png"/>
      <property name="aboutImage" value="eclipse_lg.png"/>
      <property name="aboutText" value="%productBlurb"/>
      <property name="appName" value="Eclipse"/>
      <property name="preferenceCustomization"
                value="plugin_customization.ini"/>
   </product>
</extension>

Figure 18-17. Product branding properties.

[View full size image]


The windowImages property points to a 16x16 pixel image used as the icon in the upper-left corner of windows and dialogs. For the Eclipse workbench itself, this is the ubiquitous Eclipse icon.

The aboutImage property points to a larger image that is placed next to the about text in the main About dialog. If the image is less than 250x330 pixels in size, the image is shown next to the about text. If the image is larger (up to 500x330 pixels in size), the about text will be suppressed.

As described for the about.ini file earlier, the aboutText property is a short multiline description of the product that should give its name, version number, relevant build information, copyright information, and so on. This text will be displayed in the product About dialog (see Figure 18-15).

The appName property is used to provide a non-translatable name for the application. For Eclipse, this is just the string "Eclipse".

If the product needs to change the default preferences of any other installed plug-ins, it can place those new settings in a file specified by the preferenceCustomization property (e.g., the plugin_customization.ini file). Every line in the file should follow this form:

<plug-in id>/<preference id>=<value>

If any of the values need to be localized, the translated values should be placed in the plugin_customization.properties file, which follows the pattern established in Chapter 16, Internationalization.

The location of the product splash screen is specified by the osgi.splashPath property in the config.ini contained in the product's configuration directory. The splash.bmp file, which Eclipse specifically looks for by name, contains the product splash screen. It should be a 24-bit color bitmap, and its size should be approximately 500x330 pixels. If the text in the splash screen needs to be localized, the splash.bmp file can be located in a fragment.


Previous Page
Next Page