Intro support

Intro support is a set of extension points and workbench parts that allow plug-ins to define specialized pages that introduce a platform product to new users. The intro information is typically shown the first time a product is started. Intro support is typically configured at the product level, although individual plug-ins can contribute intro information to known product intro configurations.

From a workbench point of view, the root of the intro support is in the intro part. This part is specified in an extension definition. When the workbench initializes, it creates an intro site that reserves space for the intro page. The intro part implementation for the site is determined using product configuration information. Once an intro part is shown, it can move between two modes:

in full mode, the intro part takes over the main workbench area.
in standby mode, the intro part moves to the side, allowing the current perspective to remain visible.

Once an intro part is established, it must be configured with intro information. This is done using an intro config which is also contributed using an extension. Individual plug-ins can add to the basic product intro config using their own extensions.

We'll look at the platform SDK intro page as an example in order to better understand these concepts.

Defining an intro part

The IIntroPart interface and the org.eclipse.ui.intro extension point make up the generic mechanism that can be used to create your own intro support for a given product. The main purpose of this extension is to define the class that implements IIntroPart and to specify the binding between a product id and an intro part. For example, the following contribution defines a hypothetical intro part to be shown by the workbench on startup:


<extension  
    point="org.eclipse.ui.intro">
    <intro
        class="com.example.SampleIntroPart"
        id="someId">
        icon="someIcon.gif"
    </intro>
    <introProductBinding
        introId="someId"
        productId="com.example.someProductId">
    </introProductBinding>
</extension>

This contribution first defines the intro part and assigns it the id "someId". It then binds this intro part to a product whose id is "com.example.someProductId". On platform startup, the class specified in the class attribute will be instantiated by the workbench and presented to the user as the introduction to the product. This is the lowest level integration into the IIntroPart interface.

The platform supplies its own IIntroPart implementation called CustomizableIntroPart that allows for the content and presentation of the intro to be customized. Below is the snippet that defines the intro part for the workbench. We won't go over the mechanics of implementing an intro part since we want to focus on defining the intro content. (See the extension point documentation and javadoc referenced above for more detail if you need it.)


<extension  
    point="org.eclipse.ui.intro">
    <intro
        class="org.eclipse.ui.intro.config.CustomizableIntroPart"
        id="org.eclipse.platform.intro">
    </intro>
    <introProductBinding
        introId="org.eclipse.platform.intro"
        productId="org.eclipse.platform">
    </introProductBinding>
</extension>

The above contribution defines the CustomizableIntroPart as the intro part to be used for the Eclipse SDK platform. The rest of this discussion shows you how to use and extend this part.

Using the CustomizableIntroPart

The platform's CustomizableIntroPart allows for the content and presentation of the intro to be customized using the org.eclipse.ui.intro.config extension point. (This intro config can be extended using the org.eclipse.ui.intro.configExtension extension point.) This structure allows product plug-in developers to focus on developing their intro content rather than implementing an intro part scheme from scratch. If a different intro class is specified, then these two extension points are not utilized and the specified class must implement its own scheme for intro content format and configuration.

Defining an intro config

org.eclipse.ui.intro.config describes the id of the intro config that is to show our content, and the name of the XML file that contains the specific definition for the intro content. It is expected that only one intro config should be defined for a given CustomizableIntroPart. (Only the first intro config found can be shown in a CustomizableIntroPart.)


<extension   
    id="intro"
    point="org.eclipse.ui.intro.config">
    <config
        introId="org.eclipse.platform.intro"
        id="org.eclipse.platform.introConfig"
        content="$nl$/introContent.xml">
    <presentation
        home-page-id="root" standby-page-id="standby">
            <implementation
                 ws="win32"
                style="css/shared.css"
                kind="html"
                os="win32">
            </implementation>
            <implementation
                kind="swt">
            </implementation>
    </presentation>
    </config>
</extension>

The path for the file is relative to the plug-in's directory. (Note the use of the $nl$ variable in the directory name, which means the file will be located in a directory specific to the national language of the target environment.)

The config extension allows you to specify both the content and the presentation of the content. While the content element focuses on defining pages, the presentation element describes presentation-related attributes that describe how pages will be shown. The page id for the intro home page (in full mode) must be specified, and the standby page id (in standby mode) is optional. The home page is the page that is shown when the product is first started. A presentation can specify one or more implementations for showing the pages. Implementations are specified per platform and windowing system, allowing you to take advantage of platform-specific features for showing page content. For example, the windows platform has a robust HTML browser widget, so an HTML-based implementation is used for intro content. Other platforms without this capability use an SWT-based implementation that maps page descriptions to an SWT-based form. An implementation that does not specify either a windowing system or operating system will be considered the generic implementation; to ensure an intro is shown on all platforms, it is important to define such an implementation. The workbench will first look for an implementation that matches the current operating system and windowing system. If one cannot be found, it will choose the generic implementation. Most of these details are handled at the product configuration level, so we won't discuss them any further here.

Defining intro content

Now we can look at the content itself. Content is described in terms of pages. All pages have an id attribute. This is the id that is used when defining the home and standby pages, and other places where there is a reference to a page. Otherwise, the relevant attributes depend on the kind of page that is defined. There are two basic types of pages:

Static pages are plain HTML files. These pages use the normal HTML mechanisms to link to other pages. Static pages need not be defined in the config content file, except for the home page. Since the home page is specified by id (home-page-id) in the presentation element, there must be a page definition using that id in the content file. This page need only define a url. All other subelements will be ignored since the HTML page itself will describe the page content. All other HTML intro pages contributed by the plug-in must be included with the plug-in, but do not need to be specified in the content file. HTML files located in other plug-ins or on the web may be referenced also.
Dynamic pages are described in the XML content file using subelements that describe the content of the page. The subelements are UI items often found in HTML-like pages. Depending on the implementation, these pages will either be dynamically translated to HTML (when the implementation kind is html) or else dynamically created as SWT-based UI forms (when the implementation kind is swt). The following subelements can be defined in a page:
- A group is used to group other subelements and define a consistent style across the group.
- A link defines a link that can be displayed using an image and text. The link can navigate to another page and optionally run an intro action. Actions are specified as commands in the URL.
- The text and img elements show text and image content.
- The include element includes a previously defined subelement. The element is referred to by its id.
- The head element defines additional HTML to be included in the head section of the page when the html implementation is used.
- The html element defines additional HTML to be included in the body of the page when the html implementation is used.
A title for a page may also be defined. A page may also specify that its content is defined in a separate content file. Breaking up pages into separate files may be useful when performance is a concern, since an intro page's contents won't be initialized until needed.

The best way to get a feel for the content definition format is to browse the implementations in the SDK. The following snippet shows just the first part of the content for the SDK root page, which is the first intro page shown.


<introContent>
  <page alt-style="css/root_swt.properties" style="css/root.css" id="root" style-id="page">
    <title style-id="intro-header">Welcome to Eclipse Platform 3.0</title>
    <group id="links-background">
      <group id="page-links">
        <link label="Overview" url="http://org.eclipse.ui.intro/showPage?id=overview" id="overview" style-id="left">
          <text>Find out what Eclipse is all about</text>
        </link>
        <link label="Tutorials" url="http://org.eclipse.ui.intro/showPage?id=tutorials" id="tutorials" style-id="left">
          <text>Let us guide you through Eclipse end-to-end tutorials</text>
        </link>
        <link label="Samples" url="http://org.eclipse.ui.intro/showPage?id=samples" id="samples" style-id="right">
          <text>Explore Eclipse development through code samples</text>
        </link>
        <link label="Whats New" url="http://org.eclipse.ui.intro/showPage?id=news" id="news" style-id="right">
          <text>Find out what is new in this release</text>
        </link>
      </group>
    </group>

Elements on a page can also be filteredFrom a particular implementation. This allows page designers to design with particular platforms in mind. There are many more powerful attributes that can be used when describing a page and its contents. See the extension point documentation for org.eclipse.ui.intro.config and its associated intro content file format specification for a complete reference of valid elements, subelements, and their attributes.

Extending an intro config

An intro configuration can be extended in three ways:

content of an existing intro config can be extended.
a custom standby content part, such as Cheat Sheet, can be contributed to provide content for the standby area of the Intro part.
custom IntroURL actions can be defined.

Extending the content of an intro config

Plug-ins can contribute intro content to a page defined elsewhere. However, the defining page must define an anchor attribute that acts as a location placeholder for new content. The SDK overview page defines two anchors for adding JDT and PDE related elements on the overview page.

    
<group id="page-content">
    <text style-id="page-title" id="page-title">OVERVIEW</text>
    <text style-id="page-description" id="page-description">Eclipse is a kind of universal tool platform - an open extensible IDE for anything and nothing in particular. It provides a feature-rich development environment that allows the developer to efficiently create tools that integrate seamlessly into the Eclipse Platform.</text>
    <group id="overview-links">
        <link label="Workbench basics" url="http://org.eclipse.ui.intro/showHelpTopic?id=/org.eclipse.platform.doc.user/concepts/concepts-2.htm" id="basics">
            <text>Learn about basic Eclipse workbench concepts</text>
        </link>
        <link label="Team support" url="http://org.eclipse.ui.intro/showHelpTopic?id=/org.eclipse.platform.doc.user/concepts/concepts-26.htm" id="team">
            <text>Find out how to collaborate with other developers</text>
        </link>
        <anchor id="jdtAnchor"/>
        <anchor id="pdeAnchor"/>
    </group>
</group>

These anchors can be referenced by plug-ins that add content to the page. Content is added using the org.eclipse.ui.intro.configExtension extension. In addition to extending page content, this extension point also allows one to contribute standby content parts and custom actions.

To extend an existing intro config, you can use the configExtension element. In this element, you specify the configId of the intro config being extended and the content file that describes the new content.

 
<extension
    point="org.eclipse.ui.intro.configExtension">
    <configExtension
        configId="org.eclipse.platform.introConfig"
        content="$nl$/overviewExtensionContent.xml"/>  
    ...
</extension>

The format of the content file is similar to that of the intro config content, except that it must contain an extensionContent element that defines the path to the anchor where the extension content should be inserted.

 
<introContent>
    <extensionContent alt-style="css/swt.properties" style="css/overview.css" path="overview/page-content/overview-links/jdtAnchor">
        <link label="Java development" url="http://org.eclipse.ui.intro/showHelpTopic?id=/org.eclipse.jdt.doc.user/gettingStarted/qs-BasicTutorial.htm" id="java">
            <text>Get familiar with developing Java programs using Eclipse</text>
        </link>
    </extensionContent>
</introContent>

After contributing custom content to an intro's predefined anchor points, a given product can bind itself to that intro using the org.eclipse.ui.intro discussed above. When the product is run, the intro that was extended will be shown with the additional content. This allows the product to have its own branding and other product-specific information, while reusing a closely related product's intro along with key content of its own.

A given intro could also selectively include pieces of a related product's intro. In this case, the product could define its own intro and intro config, and then reference important elements defined in another intro's config using an include in the content file. This mechanism is valuable in situations where related products are built on top of one another and it is necessary to introduce users to key concepts in the higher level products.

Contributing a standby content part

Plug-ins can also implement a part for displaying alternative content when the intro page is in standby mode. For example, the platform defines a standby part that will show a cheat sheet for related intro content. The part is launched using a page link with a specialized URL. Standby parts are launched using a URL containing a special command for showing a standby part, such as http://org.eclipse.ui.intro/showStandby?partId=somePartId. The part is defined in the standbyContentPart subelement in the org.eclipse.ui.intro.configExtension extension. An id, pluginId, and class must be specified for the part. The class must implement IStandbyContentPart. The following snippet shows how the platform defines a standby part for showing cheat sheets.

 
<extension point="org.eclipse.ui.intro.configExtension">
    <standbyContentPart
        id="org.eclipse.platform.cheatsheet"
        class="org.eclipse.platform.internal.CheatSheetStandbyContent"
        pluginId="org.eclipse.platform"/>
</extension>

This cheat sheet could be launched from an intro page using a link subelement whose URL is http://org.eclipse.ui.intro/showStandby?partId=org.eclipse.platform.cheatsheet&input=org.eclipse.pde.helloworld. This IntroURL would launch the org.eclipse.platform.cheatsheet standby content part and set its input to "org.eclipse.pde.helloworld". The detailed mechanics for implementing a standby part are beyond the scope of this discussion. See IStandbyContentPart and its related classes for more information.

Defining a custom IntroURL action

Using the org.eclipse.ui.intro.configExtension extension point, plug-ins can contribute their own custom actions that can be used as a url value for a link element in a page. For example, consider the following link:

http://org.eclipse.ui.intro/runAction?pluginId=org.eclipse.pde.ui&class=org.eclipse.pde.ui.internal.samples.ShowSampleAction&id=org.eclipse.sdk.samples.swt.examples

This IntroURL will run an action class called ShowSampleAction, which is in a package "org.eclipse.pde.ui.internal.samples" in the plug-in "org.eclipse.pde.ui". The id of the sample to run is "org.eclipse.sdk.samples.swt.examples".

To define a custom version of this intro URL, you can use the following markup:

 
<extension point="org.eclipse.ui.intro.configExtension">
    <action
        name="myCommand"
        replaces="runAction?pluginID=org.eclipse.pde.ui&class=org.eclipse.pde.ui.internal.samples.ShowSampleAction">
    </action>
</extension>

With the above extension you can now use the following URL to run the same action:

http://org.eclipse.ui.intro/myCommand?id=org.eclipse.sdk.samples.swt.examples

The action "myCommand" will be replaced by the value of the replaces attribute and any remaining URL parameters will be appended to the end. Once the substitution is made, the resulting URL will be expanded back into:

http://org.eclipse.ui.intro/runAction?pluginId=org.eclipse.pde.ui&class=org.eclipse.pde.ui.internal.samples.ShowSampleAction&id=org.eclipse.sdk.samples.swt.examples