Eclipse provides introduction pages that are accessible via the menu Help, Welcome. They are also displayed to the user when CSS is started for the very first time.

Fundamentally, an RCP product can provide arbitrary introduction page content via the org.eclipse.ui.intro extension point. Refer to the online help for details.

CSS products, however, should use the “Universal Intro” mechanism. Instead of defining the complete introduction page content within your product, it allows other CSS plugins to also contribute intro page content. There is no need to update a custom, product-specific intro when adding or changing plugins.

To enable the Universal Intro, configure the intro extension point as follows for your product, using the correct productId of your product:

<extension point="org.eclipse.ui.intro">
 <introProductBinding
       introId="org.eclipse.ui.intro.universal"
       productId="org.csstudio.....your-product.....product"/>
</extension>

Your product's plugin.xml file should already contain an entry for the org.eclipse.core.runtime.products extension point. You need to add the following elements to configure the main page of the universal intro:

<extension point="org.eclipse.core.runtime.products">
  id="product"
  <product application="...." name="...">
    <property name="aboutImage" value="..."/>
    <!-- Append intro properties: -->
    <property name="introBrandingImageText"
       value="My Version of CSS"/>
    <property name="introBrandingImage"
       value="product:icons/css64.png"/>
    <property name="introTitle"
       value="Welcome to Control System Studio (CSS) for this site!">
    </property>
  </product>
</extension>

You can influence the behavior of the Universal Intro plugin to some extend via preference settings added to your product's plugin_customization.ini file, for example like this:

# Select sections of intro page
org.eclipse.ui.intro.universal/INTRO_ROOT_PAGES=overview,\
     firststeps,whatsnew

# Select scheme
org.eclipse.ui.intro/INTRO_THEME=org.eclipse.ui.intro.universal.slate
# Configure placement of sections
org.eclipse.ui.intro.universal/INTRO_DATA=product:intro_data.xml

The intro_data.xml file mentioned in these settings can look like this:

<?xml version="1.0" encoding="utf-8" ?>
<!-- This file controls the initial placement of
     Welcome (intro) page items.
     File can be generated via the Welcome page preference panel.
     
     Items that are not listed in here will show in a
     default place on their page.
     Items listen in <hidden></hidden> sections will be, well,
     hidden.
  -->
<extensions>
 <page id="overview">
  <group path="page-content/top-left">
   <extension id="org.csstudio.myproduct.product.overview"
              importance="high"/>
  </group>
 </page>
 <page id="whatsnew">
  <group path="page-content/top-left">
    <extension id="org.csstudio.sns.product.whatsnew"
               importance="high"/>
  </group>
 </page>
 <page id="firststeps">
  <group path="page-content/top-left">
    <extension id="org.csstudio.trends.databrowser"
               importance="medium"/>
  </group>
  <group path="page-content/top-right">
    <extension id="org.csstudio.opibuilder" importance="medium"/>
  </group>
 </page>
</extensions>

The following mark-up in your plugin.xml file adds a link to your file doc/overview.xml to the intro pages:

<extension
    point="org.eclipse.ui.intro.configExtension">
 <configExtension
   configId="org.eclipse.ui.intro.universalConfig"
   content="doc/overview.xml">
 </configExtension>
</extension>

The IDE can help with this step: When adding a ..configExtension to your product in the plugin editor, the "Universal Welcome Contribution" is listed as a template. It will generate an example intro file. Consult the Eclipse online help or example files from other CSS plugin for details on the intro file format.

Assuming you have a plugin org.csstudio.XXX and you want to provide intro content, there are two options for the location of that content:

Using the same plugin is the easiest option. All users of the plugin will get the intro content. If site integrators want to disable it, they can do this via a <hidden> section in the org.eclipse.ui.intro.universal/INTRO_DATA. It does, however, add a dependency to the intro plugins to your plugin.

Using a separate plugin for the intoduction makes the inclusion or exclusion of the intro content more straight forward, but adds more plugins, and is additional work. It would allow building products without universal intro or even no intro at all. In the long run, intro content in a separate plugin is probably most flexible. In the short run, it might be OK to add the intro to the existing plugin, then extract it to a separate plugin as the need arises.

Technically, one can contribute to universal intro pages called overview, firststeps, tutorials, samples, whatsnew, migrate, webresources, or even define new pages.

For CSS products it is suggested to concentrate on the following: