An infocenter product plugin cookbook
Wiki page: Submitted by bob_beims on Wed, 2010-04-14 19:10. Last updated on Wed, 2010-04-14 19:17.
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
- 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:
- 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)
- select File > New > Project and select Plug-in Project
- uncheck the "Create Java Project" check box
- give the project a name (this name will be used as the initial plugin ID, but can be changed later)
- click Next
- edit the Properties "Name" field to provide a meaningful, human readable, name to the plugin
- enter "My Company, Inc." in the "Provider" field
- click Next
- select the "Plug-in with sample help content" template
- 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:
- select the "Extensions" tab
- click "Add"
- uncheck "Show only extension points from the required plugins"
- type "runtime.products" in the "Extension Point filter" box
- double-click on the "org.eclipse.core.runtime.products"
- click "No" in the "New plugin dependency" dialog that will pop up
- 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
- right-click on the plugin extension you just created
- select "New > product"
- delete the text that was automatically generated for "application" and replace it with org.eclipse.help.base.helpApplication
- right-click on the product node you just named
- select "New > property"
- delete the text that was automatically generated for "name" and "value" and replace them with
- name = preferenceCustomization
- value = plugin_customization.ini
- save the project
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
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
- switch to the "Overview" tab
- make sure the "Version" string is set appropriately (note that a ".qualifier" suffix will be replaced with a date/time stamp at build time)
- switch to the "Build" tab
- make sure all appropriate assets are checked in the "Binary Build" window (you won't be doing a source build)
- right-click on the top-level plugin folder in the Package Explorer
- select "Export..."
- select "Plug-in Development > Deployable plug-ins and fragments"
- click Next
- check the box next to your plugin
- use the Browse button to specify where the plugin should be saved
- click the Options tab
- make sure the "Package plug-ins as individual JAR archives" is selected, and "Export source" is not selected
- click Finish
Installing the customization plugin
- 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