EclipseHelp Standalone Infocenter Customization

This page contains how-to information about creating a plugin to customize a standalone infocenter without modifying the base files of the Eclipse installation.

 

• Creating a product plugin to contain all customizations
  • Create a plugin project:
  • Add look-n-feel customizations to the plugin:
  • plugin_customization.ini
  • other customization plugin content
• Export the plugin
• Installing the customization plugin
• Invoking the customization plugin

Background / related information

• help.eclipse.org :: Infocenter customization
• help.eclipse.org :: Help system customization
• dita.xml.org :: Setting up an Infocenter for publishing DITA content
• dita-users :: Producing standalone Eclipse Help

Creating a product plugin to contain all customizations

Create a plugin project:

1. launch the Eclipse IDE (it is suggested that you use the same or later version of the IDE as the version you're using for the infocenter runtime)
2. select File > New > Project and select Plug-in Project
3. uncheck the "Create Java Project" check box
4. give the project a name (this name will be used as the initial plugin ID, but can be changed later)
5. click Next
6. edit the Properties "Name" field to provide a meaningful, human readable, name to the plugin
7. enter "My Company, Inc." in the "Provider" field
8. click Next
9. select the "Plug-in with sample help content" template
10. click Finish

You've now created a basic plugin package with a single extension point (a ToC) and some example content; this extension point and content will probably be deleted later (unless you're planning on providing a custom ToC and perhaps a splash page with this plugin).

Add look-n-feel customizations to the plugin:

1. select the "Extensions" tab
2. click "Add"
3. uncheck "Show only extension points from the required plugins"
4. type "runtime.products" in the "Extension Point filter" box
5. double-click on the "org.eclipse.core.runtime.products"
6. click "No" in the "New plugin dependency" dialog that will pop up
7. enter an ID and Name for this extension
   • the extension ID will be appended to the plugin ID as the fully-qualified product identifier in the command line used to start the infocenter
   • the extension Name is the string that will be displayed in the title of browser windows for the infocenter
8. right-click on the plugin extension you just created
9. select "New > product"
10. delete the text that was automatically generated for "application" and replace it with org.eclipse.help.base.helpApplication
11. right-click on the product node you just named
12. select "New > property"
13. delete the text that was automatically generated for "name" and "value" and replace them with
    • name = preferenceCustomization
    • value = plugin_customization.ini
14. save the project

You've now set up a product plugin that tells Eclipse to find the plugin_customization.ini file for the helpApplication within this plugin ... so now you need to create the plugin_customization.ini file itself.

 

plugin_customization.ini

The plugin_customization.ini file is a text file that defines preference overrides for the default Eclipse installation. Entries in the text file are key/value pairs, where keys are qualified by the id of the plugin where the default value is found. For example, the default value for the banner property is org.eclipse.help.webapp/advanced/banner.html and thus that default may be overridden to specify the banner.html file inside your customization plugin via the key/value  

• org.eclipse.help.base/banner = /<your plugin id here>/banner.html

Another example:

• org.eclipse.help.base/windowTitlePrefix = false will turn off the "Help - " prefix normally displayed in the title of browser windows

Refer to Infocenter customization for a list of property defaults that you might want to override.

 

A good starting point might be to copy the plugin_customization.ini file from the org.eclipse.platform_<version.qualifier> plugin of your Eclipse IDE, remove those key/value pairs you're not going to override, and modify the others.

 

other customization plugin content

Other items that you might include in your plugin are:

• a banner.html file
• graphic files referenced by banner.html or other UI elements you're overriding
• CSS files referenced by banner.html or the org.eclipse.help.base/topic_css or org.eclipse.help.base/nav_css properties
• a helpData.xml file to show/hide and order the ToC entries

Export the plugin

1. switch to the "Overview" tab
2. make sure the "Version" string is set appropriately (note that a ".qualifier" suffix will be replaced with a date/time stamp at build time)
3. switch to the "Build" tab
4. make sure all appropriate assets are checked in the "Binary Build" window (you won't be doing a source build)
5. right-click on the top-level plugin folder in the Package Explorer
6. select "Export..."
7. select "Plug-in Development > Deployable plug-ins and fragments"
8. click Next
9. check the box next to your plugin
10. use the Browse button to specify where the plugin should be saved
11. click the Options tab
12. make sure the "Package plug-ins as individual JAR archives" is selected, and "Export source" is not selected
13. click Finish

Installing the customization plugin

1. drop the .jar into the <eclipse home>/plugins or <eclipse home>/dropins directory

Invoking the customization plugin

When starting your infocenter, add -product <your plugin ID>.<your product extension ID> to the command line. For example, since the example plugin attached below has a plugin ID of net.myco.info and a product extension ID of ic-cust the command line option to invoke it is  

-product net.myco.info.ic-cust