HierarchicalPreferences

= Hierarchical Preferences =

Eclipse has a preference system that allows each plugin to provide default settings. The builder of a "product" can then add site-specific settings, and finally the user might be able to adjust them. This describes the suggested use for CSS

== Plugin Defaults ==

Each plugin with configurable settings has a file "preferences.ini" that

1. Defines those settings, i.e. their name
2. Documents their meaning, supported values
3. Establishes the default

{{{

Example preferences.ini for plugin org.csstudio.demo

Enable the super feature.

Set to 'on', 'off' or 'automatic' which enables it whenever possible

enable_super=automatic

URL of server where the super feature connects

url=http://localhost/superdata }}}

The Eclipse preference service for a plugin will automatically use this file.

Note that Eclipse offers more ways to establish defaults, which are discouraged for CSS:

1. Defaults hardcoded in calls to the preference service. These are difficult to find in the code.
2. Preference Initializer defined in plugin.xml. This again hides the preference tags and their default values in the code.

Putting the defaults into preferences.ini seems the best way to define and document them.

== Product (Site) Defaults == When bundling plugins into a site-specific product, a file "plugin_customization.ini" in the product plugin is automatically used by Eclipse to override settings.

{{{

Example plugin_customization.ini

Override defaults of plugin org.csstudio.demo:

URL of our super feature server

org.csstudio.demo/url=http://my.site.org/mysuperdata }}}

This way, "your" product has the settings for "your" site built-in.

If you wonder about the names of preference settings supported by each plugin, consult the preferences.ini of the respective plugin.

== Slight Tweaks to the Site Defaults == If a select installation at a site requires a few extra changes, for example a test network installation needs settings that differ from your main campus network, put those into a file with the same format as "plugin_customization.ini", for example "testnet.ini", and run the product with a command-line option

{{{ my_product -pluginCustomization /path/to/testnet.ini }}}

== End User Settings == Finally, the GUI code can offer Preference Pages via which the end user can change the settings. Typically, these end-user settings are saved in the user's workspace, i.e. they persist for the user but don't change the settings of other users or even the site-wide defaults. Details depend on the preference store that the code uses when creating the preference page.