Chapter 17. Product Intro Pages

Table of Contents

Welcome Pages
Universal Intro
How to Contribute
Where to Contribute
Issues

Welcome Pages

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.

Universal Intro

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>

How to Contribute

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:

  • Within the same plugin org.csstudio.XXX.
  • In a separate plugin org.csstudio.XXX.intro.

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.

Where to Contribute

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:

overview
This is where each site can publish their site-specific content:
Welcome to CSS for ... users!
CSS is ...
To get started, read the 'first steps'
that introduce the various tools.
You can also read the online help, ...
firststeps
This is where each tool, via a separate org.csstudio.....intro plugin, can contribute some how-to-get-started content.
whatsnew
This is were each site and each tool may add info about most recent changes, so users who've used CSS before can read up on what changed.

Issues

Main Intro Screen

The layout of the Universal Intro main screen is mostly fixed. There isn't much to customize beyond a one-line title and a small icon.

Cheat Sheets

In principle, it would be nice to be able to link to Cheat Sheets from for example the firststeps section with code like this:

<!-- url is one string, broken for readability -->
<link
  url="http://org.eclipse.ui.intro/showStandby?
  partId=org.eclipse.platform.cheatsheet&amp;
  input=org.csstudio.XXXX.some_cheat_sheet"

But that requires the plugin org.eclipse.platform, which in turn adds quite some intro content that is useful for Eclipse programmers but potentially confusing for CSS end-users.