platform-update-home/doc/eclipse_plugin_customization.html
Parent Directory
| 
Revision Log
Revision 1.2 - (view) (download) (as text)
| 1 : | droberts | 1.2 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 : | jeem | 1.1 | <html> |
| 3 : | |||
| 4 : | <head> | ||
| 5 : | <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> | ||
| 6 : | <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> | ||
| 7 : | <meta name="ProgId" content="FrontPage.Editor.Document"> | ||
| 8 : | <title>Eclipse About Dialogs</title> | ||
| 9 : | </head> | ||
| 10 : | |||
| 11 : | <body> | ||
| 12 : | |||
| 13 : | <h1>Eclipse Plug-in Customization</h1> | ||
| 14 : | <p>Last revised 19:00 Wednesday May 22, 2002</p> | ||
| 15 : | <p>This note describes how an Eclipse-based product can customize any of the | ||
| 16 : | plug-ins installed in the product.</p> | ||
| 17 : | <h2>What product developers need to know</h2> | ||
| 18 : | <p>Any plug-in may choose to expose preferences or internal configuration | ||
| 19 : | parameters that are intended to be given product-specific default settings to | ||
| 20 : | better tailor that plug-in for the product's operating environment.</p> | ||
| 21 : | <p>Product-specific customization is controlled from the product's primary | ||
| 22 : | feature through the file named "<code>plugin_customization.ini</code>" | ||
| 23 : | located within the primary feature's plug-in (a <a href="http://java.sun.com/j2se/1.3/docs/api/java/util/Properties.html">java.io.Properties</a> | ||
| 24 : | format file). Only the primary feature gets to do this; other features have no | ||
| 25 : | say. The keys in the <code>plugin_customization.ini</code> file are a | ||
| 26 : | property name qualified by the id of the plug-in; for example, the property | ||
| 27 : | named "<code>defaultPerspectiveId</code>" in the plug-in with id | ||
| 28 : | "<code>org.eclispe.ui</code>" is written "<code>org.eclipse.ui/defaultPerspectiveId</code>". | ||
| 29 : | The specified value overrides the <b> default</b> preference value | ||
| 30 : | specified by a plug-in. For user preferences, the default override determines the setting that | ||
| 31 : | will be used if the user states no preference (or asks to restore | ||
| 32 : | defaults). For internal preferences, the default override determines the setting | ||
| 33 : | that will be used (since the user has no say).</p> | ||
| 34 : | <p>Translatable strings in "<code>plugin_customization.ini</code>" | ||
| 35 : | should be extracted into a companion "<code>plugin_customization.properties</code>" | ||
| 36 : | file. The "<code>plugin_customization.properties</code>" file is | ||
| 37 : | looked for in NL-specific subdirectories within the feature plug-in or fragment | ||
| 38 : | thereof.</p> | ||
| 39 : | <p>No error is reported for a setting that specifies a non-existent plug-in; the | ||
| 40 : | default setting will be overridden in any configuration in which the plug-in is | ||
| 41 : | configured, and ignored in all others. </p> | ||
| 42 : | <p>The plug-in customization mechanism does not cause plug-in activation; | ||
| 43 : | rather, the default setting is applied the first time a plug-in's preference | ||
| 44 : | object is accessed.</p> | ||
| 45 : | <h2>What product developers do not need to know</h2> | ||
| 46 : | <p><b>N.B. The details in this section are not Eclipse platform API, and may | ||
| 47 : | change over time. Do not rely on anything described in this section.</b></p> | ||
| 48 : | <p>Individual plug-ins often define user preference settings with pre-wired | ||
| 49 : | default values.</p> | ||
| 50 : | <p>Plug-ins present their user preferences to the user via the workbench. The | ||
| 51 : | preferences start out at their pre-wired default values. Any settings that the | ||
| 52 : | user changes are saved by the plug-in in its internal preference settings file (located in the | ||
| 53 : | plug-in's state area, at <code><<i>workspace</i>>/.metadata/.plugins/<<i>plug-in | ||
| 54 : | id</i>>/pref_store.ini</code>). The most recent settings are used when the | ||
| 55 : | Eclipse platform is re-launched and the plug-in reactivated.</p> | ||
| 56 : | <p>More generally, a plug-in may also have internal preference settings that are | ||
| 57 : | never exposed to the user. For example, a plug-in might be pre-configured with a | ||
| 58 : | particular URL where the user would be directed for support (or whatever). | ||
| 59 : | Internal preference settings are even simpler than user preference settings | ||
| 60 : | because there is never a need to save values - everything works from pre-wired | ||
| 61 : | defaults.</p> | ||
| 62 : | <p>In 1.0, preference settings are supported by UI API (on AbstractUIPlugIn), | ||
| 63 : | and is therefore something that is limited to UI plug-ins. There is also an | ||
| 64 : | undocumented (and consequently unused) mechanism for overriding these default | ||
| 65 : | settings.</p> | ||
| 66 : | <p>The changes for 2.0 are as follows: make preference settings available to all | ||
| 67 : | plug-ins; provide a simple mechanism that allows a plug-in's preference default | ||
| 68 : | values to be externally configured by a product packager through the primary | ||
| 69 : | feature; and provide a simple mechanism that allows plug-in | ||
| 70 : | preference default values for a packaged product to be externally configured | ||
| 71 : | (e.g., by in house teams creating site-specific product installs).</p> | ||
| 72 : | <ul> | ||
| 73 : | <li>New Core API in Platform Runtime to support preferences. | ||
| 74 : | <ul> | ||
| 75 : | <li>These are based existing JFace preference and preference store | ||
| 76 : | APIs and implementation (based in turn on <code>java.util.Properties</code>.), | ||
| 77 : | API and implementation in <code>AbstractUIPlugIn</code>.</li> | ||
| 78 : | <li>All default preference settings are expected to be supplied by plug-in | ||
| 79 : | itself.</li> | ||
| 80 : | <li>Keys are simple name of preference; e.g., "<code>mypref</code>"</li> | ||
| 81 : | <li>Plug-in code may set initial default preference values to hard-wired | ||
| 82 : | values.</li> | ||
| 83 : | <li>Additional default preference value are retrieved from a known | ||
| 84 : | read-only file (e.g., "<code>preferences.ini</code>") in the | ||
| 85 : | plug-in's root | ||
| 86 : | directory (same format as other property settings). | ||
| 87 : | <ul> | ||
| 88 : | <li>Strings are localized using mechanism like <code>plugin.xml/plugin.properties</code></li> | ||
| 89 : | <li>i.e., translatable strings extracted to "<code>preferences.properties</code>" | ||
| 90 : | file</li> | ||
| 91 : | </ul> | ||
| 92 : | </li> | ||
| 93 : | <li>Default values from file override defaults hard-wired in code. | ||
| 94 : | <ul> | ||
| 95 : | <li>Makes it easy for plug-in writers to configure default preference | ||
| 96 : | values without changing code.</li> | ||
| 97 : | </ul> | ||
| 98 : | </li> | ||
| 99 : | </ul> | ||
| 100 : | </li> | ||
| 101 : | <li>Primary feature supplies preference default overrides. | ||
| 102 : | <ul> | ||
| 103 : | <li> The primary feature is provided by the product | ||
| 104 : | packager.</li> | ||
| 105 : | <li>This mechanism is for the product packager to customize the plug-ins | ||
| 106 : | included in the product.</li> | ||
| 107 : | <li>Keys consist of "/'-separated plug-in id and name of preference; | ||
| 108 : | e.g., "<code>com.example.myplugin/mypref</code>".</li> | ||
| 109 : | <li>A preference default override replaces the default preference value | ||
| 110 : | specified by a plug-in.</li> | ||
| 111 : | <li>For user preferences, the default override determines the setting that | ||
| 112 : | will be used if the user states no preference (or asks to restore | ||
| 113 : | defaults).</li> | ||
| 114 : | <li>For internal preferences, the default override determines the setting | ||
| 115 : | that will be used (since the user has no say).</li> | ||
| 116 : | <li>Primary feature's preference default overrides are stored in a | ||
| 117 : | properties file with feature (same format as other property settings). | ||
| 118 : | <ul> | ||
| 119 : | <li>Root file in plug-in (or fragment) for feature is named "<code>plugin_customization.ini</code>"</li> | ||
| 120 : | <li>Strings are localized using mechanism like <code>plugin.xml/plugin.properties</code></li> | ||
| 121 : | <li>i.e., translatable strings extracted to "<code>plugin_customization.properties</code>" | ||
| 122 : | file</li> | ||
| 123 : | </ul> | ||
| 124 : | </li> | ||
| 125 : | </ul> | ||
| 126 : | </li> | ||
| 127 : | <li>Allow additional preference default overrides to be supplied via the | ||
| 128 : | Eclipse command line. | ||
| 129 : | <ul> | ||
| 130 : | <li>This mechanism is for additional after-market product customization.</li> | ||
| 131 : | <li>Allows in-house teams to provide site-specific customization (e.g., | ||
| 132 : | URL of team repository).</li> | ||
| 133 : | <li>Preference default overrides specified on command line should have | ||
| 134 : | precedence over preference default overrides from primary feature.</li> | ||
| 135 : | <li>Command line option is "-<code>pluginCustomization</code>" | ||
| 136 : | followed by a file name </li> | ||
| 137 : | <li>Keys are same as for product packager; e.g., "<code>com.example.myplugin/mypref</code>".</li> | ||
| 138 : | </ul> | ||
| 139 : | </li> | ||
| 140 : | </ul> | ||
| 141 : | <p>To summarize, the value of a preference named "<code>mypref</code>" from plug-in | ||
| 142 : | "<code>com.example.myplugin</code>" is arrived at as follows:</p> | ||
| 143 : | <ol> | ||
| 144 : | <li>A user stated preference value for "<code>mypref</code>", if any. (Persisted | ||
| 145 : | in a file in the state are plug-in <code>com.example.myplugin</code>.)</li> | ||
| 146 : | <li>A default value: | ||
| 147 : | <ol> | ||
| 148 : | <li>An override value from after-market customization for "<code>com.example.myplugin/mypref</code>", | ||
| 149 : | if any.</li> | ||
| 150 : | <li>An override value from primary feature for "<code>com.example.myplugin/mypref</code>", | ||
| 151 : | if any.</li> | ||
| 152 : | <li>A default value for "<code>mypref</code>" as determined by plug-in | ||
| 153 : | <code>com.example.myplugin</code>, if any. | ||
| 154 : | <ol> | ||
| 155 : | <li>A default value for "<code>mypref</code>" from a read-only file found | ||
| 156 : | in the root directory of the plug-in, if any. </li> | ||
| 157 : | <li>A default value for "<code>mypref</code>" from code in the plug-in, | ||
| 158 : | if any.</li> | ||
| 159 : | </ol> | ||
| 160 : | </li> | ||
| 161 : | <li>The default-default value (i.e., 0 for numbers, false for booleans, | ||
| 162 : | empty string for strings, etc.).</li> | ||
| 163 : | </ol> | ||
| 164 : | </li> | ||
| 165 : | </ol> | ||
| 166 : | |||
| 167 : | </body> | ||
| 168 : | |||
| 169 : | </html> | ||
| 170 : |
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |