Intro Part Configuration

Identifier:

org.eclipse.ui.intro.config

Since:

3.0

Description:

This extension point is used to register an intro configuration. This configuration provides presentation implementations and content for a given intro contribution. An intro appears when the workbench is first launched and as a choice from the "Help" menu. The intro is typically used to introduce a user to a product built on Eclipse.

The intros are organized into pages which usually reflect a particular category of introductory material. For instance, a What's New page may introduce new concepts or functionality since previous versions. The content defined by one intro configuration can be referenced and extended from other plug-ins using the org.eclipse.ui.intro.configExtension extension point.

Configuration Markup:

<!ELEMENT extension (config)+>

<!ATTLIST extension

point CDATA #REQUIRED

id CDATA #IMPLIED

name CDATA #IMPLIED>

point - a fully qualified identifier of the target extension point
id - an optional identifier of the extension instance
name - an optional name of the extension instance

<!ELEMENT config (presentation)>

<!ATTLIST config

introId IDREF #REQUIRED

id CDATA #REQUIRED

content CDATA #REQUIRED

configurer CDATA #IMPLIED>

A config element can be used to configure a customizable Intro Part. A config element must specify an id, an introId, and a content file. The intro content file is an XML file that describes the pages, groups and links that the intro has.

introId - the id of an intro part contribution that this configuration will be associated with.
id - a unique name that can be used to identify this intro configuration
content - an intro content file. The content file is an XML file that contains the specifics of the intro (intro content file format specification). The content file is parsed at run time by the intro framework. Based on the settings in this file, a certain number of pages, groups, and links are shown to the user when the intro is opened.
configurer - a name of the fully qualified class that provides for dynamic aspects of the intro configuration. This class can provide values of the substitution variables, children of the dynamic groups and resolve incomplete target paths. The class must extend org.eclipse.ui.intro.IntroConfigurer.

<!ELEMENT presentation (implementation+ , launchBar?)>

<!ATTLIST presentation

home-page-id CDATA #REQUIRED

standby-page-id CDATA #IMPLIED>

Presentation element that defines all the possible implementations of an intro part's presentation. It can have one or more implementation defined in it. Only one implementation will be chosen at startup, based the os/ws attributes of the implementations. Otherwise, the first one with no os/ws attributes defined will be chosen.

home-page-id - the id of the home (root) page, which is the first page of the introduction. This page can be used as an entry point to the other main pages that make up the intro.
standby-page-id - an optional attribute to define the id of the standby page. The standby page will be shown to the user when the Intro is set to standby.

<!ELEMENT implementation (head?)>

<!ATTLIST implementation

kind (swt|html)

style CDATA #IMPLIED

os CDATA #IMPLIED

ws CDATA #IMPLIED>

The presentation of the Platform's out of the box experience has two implementations. One of them is SWT Browser based, while the other is UI Forms based. The customizable intro part can be configured to pick one of those two presentations based on the current OS and WS. The type of the implementation can be swt or html.

kind - Specifies the type of this implementation. The swt kind indicates a UI Forms based implementation, and the html kind indicates an SWT Browser based implementation
style - The shared style that will be applied to all pages presented by this intro presentation implementation.
os - The optional operating system specification used when choosing the presentation's implementation. It can be any of the os designators defined by Eclipse, e.g., win32, linux, etc (see Javadoc for org.eclipse.core.runtime.Platform).
ws - The optional windowing system specification used when choosing the presentation's implementation. It can be any of the ws designators defined by Eclipse (see Javadoc for org.eclipse.core.runtime.Platform).

<!ELEMENT launchBar (handle? , shortcut*)>

<!ATTLIST launchBar

location (left|bottom|right|fastview) "fastview"

bg CDATA #IMPLIED

fg CDATA #IMPLIED

computed (true | false) "false">

Launch bar works in conjuction with 'switchToLaunchBar' command. When executed, the command will close intro and create a launch bar in one of the trim areas of the main window. The launch bar will contain at least one button that would allow users to return to the last intro page. Optionally, it can contain additional buttons defined using shortcut elements. These buttons can be used to quickly go to a certain intro page. since 3.1

location - the location of the launch bar relative to the content area in the main window (one of left, bottom or right). If the choice is set to fastview (the default), the launch bar will be initially created where the fast view bar is.
bg - background color that will be applied to the launch bar if specified. Expected format is hex, as in: #rrggbb (for example, #80a4a1).
fg - foreground color that will be used to paint the border of the launch bar if specified. Expected format is hex, as in: #rrggbb (for example, #80a4a1).
computed - an optional boolean flag that indicates whether the launch bar shortcuts will be computed by the intro configurer. When set to true, static shortcut elements defined in plugin.xml will be ignored.

<!ELEMENT shortcut EMPTY>

<!ATTLIST shortcut

tooltip CDATA #IMPLIED

icon CDATA #REQUIRED

url CDATA #REQUIRED>

a button will be created in the intro launch bar for each shortcut element. The URL defined in the shortcut will be executed when the button is pressed. since 3.1

tooltip - a tooltip to be used for this shortcut
icon - a relative path to the image icon that should be used for this shortcut in the intro launch bar.
url - the URL to execute when the shortcut in the launch bar is activated

The handle element is deprecated

<!ELEMENT handle EMPTY>

<!ATTLIST handle

close (true | false) "true"

image CDATA #IMPLIED>

an optional element that controls how launch bar handle is rendered. since 3.1. Deprecated because the workbench now handles all aspects of window trim.

close - an optional flag that controls if the handle will have a close button (default is true).
image - a plug-in-relative path of the branding image to be tiled on the handle.

Examples:

Here is a sample usage of the config extension point.


<extension id="intro" point="org.eclipse.ui.intro.config">
   <config
      introId="com.org.xyz.intro"
      id="com.org.xyz.introConfig"
      content="introContent.xml">
      <presentation
         home-page-id="root"
         title="%intro.title">
         <implementation
            ws="win32"
            style="css/shared.css"
            kind="html"
            os="win32">
         </implementation>
         <implementation
            style="css/shared_swt.properties"
            kind="swt">
         </implementation>
      </presentation>
   </config>
</extension>

API Information:

For further details see the spec for the org.eclipse.ui.intro.config API package.

Supplied Implementation:

The intro contributed by the org.eclipse.platform plugin is the only implementation within Eclipse.

Copyright (c) 2004, 2006 IBM Corporation and others.
This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which accompanies this distribution, and is available at https://www.eclipse.org/legal/epl-v20.html/ SPDX-License-Identifier: EPL-2.0