Contributing to universal intro
In order to hook into to the universal intro, developers should have a
product-based eclipse application. This requires the use of the
org.eclipse.runtime.products
extension point (the assumption is
that the product has already been defined):
<extension
id="foo"
point="org.eclipse.core.runtime.products">
<product
application="org.eclipse.ui.ide.workbench"
description="Product Foo to use for testing the universal intro"
name="Product Foo">
</product>
</extension>
For this example, assume that the extension is defined in the plugin.xml
file in the
com.example.intro
plug-in. A
long-standing feature of the eclipse intro support is the ability to hook
products and intros using the product-intro binding:
<extension
point="org.eclipse.ui.intro">
<introProductBinding
introId="org.eclipse.ui.intro.universal"
productId="com.example.intro.foo"/>
</extension>
The extension above binds the universal intro implementation
(org.eclipse.ui.intro.universal) and our product id.
Universal intro customization is split between product branding properties and
preferences. Product branding properties are set by the product and cannot be
modified. They include product title, branding image and branding image text:
<product
application="org.eclipse.ui.ide.workbench"
description="Product Foo to use for testing the universal intro"
name="Product Foo">
<property
name="introTitle"
value="Welcome to Product Bar"/>
<property
name="introBrandingImage"
value="product:eclipse.png"/>
<property
name="introBrandingImageText"
value="XYZ Company"/>
</product>
Product properties whose values represent a file name relative to the product
bundle must be qualified with the 'product:' prefix. The following properties are
supported:
-
introTitle - the value of the property will be used at the top of
the root page (assuming that the current presentation theme elected to show
the root page title)
-
introBrandingImage - the value of the property represents the
file name of the image to be used as the root page brand mark. The image
should ideally be PNG with alpha blending but other formats are also valid.
Image file names relative to the product bundle must have a 'product:'
prefix.
-
introBrandingImageText - an alternative text to be used for the
branding image.
-
introDescription-<pageId> - an option description text that
appears below the title on each of the sections, where pageId is one of the
values listed further below (e.g. introDescription-overview,
introDescription-samples etc.). This value should be translated in
plugin.properties file.
Second half of universal intro variables are accessible as preferences. The
split is due to the fact that these variables can be configured by users and are
exposed in the new Welcome preference page. The initial values for these preferences
should be placed in the 'plugin_customization.ini' file that is referenced from
the product extension. These preferences are:
-
org.eclipse.ui.intro.universal/INTRO_ROOT_PAGES - a comma-separated list of
root page identifiers that should be visible in the home page. Valid values
are:
-
overview
-
firststeps
-
tutorials
-
samples
-
whatsnew
-
migrate
-
webresources
-
org.eclipse.ui.intro.universal/INTRO_DATA - a file name pointing at
the XML file with the page layout settings (see more about this below). The
file name relative to the product bundle must have 'product:' prefix.
-
org.eclipse.ui.intro/INTRO_THEME - a unique identifier of the
presentation theme to be used for this
product. Note that this preference comes from 'org.eclipse.ui.intro
plug-in' because active theme selection is performed at the framework
level.
-
org.eclipse.ui.intro/INTRO_START_PAGE - the id of the page which will
be shown when Eclipse starts the first time.
-
org.eclipse.ui.intro/INTRO_HOME_PAGE - the id of the page which will
be shown when the home button is pressed.
-
org.eclipse.ui.intro/INTRO_STANDBY_PAGE - the id of the page which will
be shown when welcome is displayed in a non-maximized form.
-
When using universal intro valid values for the three page related
properties are are root, overview, firststeps, tutorials, samples, whatsnew, migrate or webresources
or the name of a page contributed using a config extension.
