Eclipse Tip: Making a Good First Impression
In the business world, few will question the importance of a good first impression. The initial encounter with someone tends to significantly influence the way you perceive them going forward, be it a new partner, customer, vendor, or employee. As any experienced developer or business user will attest, it is very much the same with software. Although a good marketing image of a product helps attract new customers, it also tends to set up high expectations for the user.
In today’s competitive try-before-you-buy world, there is no greater shame than losing a potential customer because their initial experience with your product was unsatisfactory.
The Eclipse platform provides its extenders with several mechanisms to manage initial user experience. Ordinarily, when the user starts the application for the first time, they are greeted with the Welcome screen. The purpose of this feature is to introduce the product, as well as serve as a sort of a launch pad for the various pieces of functionality provided. A good welcome screen contains a high-level overview of the product and its features, with more detailed documentation available in the online help facility. Additionally, complex functions and processes are more easily explained using Cheat Sheets, which are typically accessible directly from the welcome screen. Subsequent product releases should also provide a brief summary of updated features for the benefit of users who are already familiar with older versions of the product.
The Welcome screen, also referred to as the “Intro” view throughout platform documentation, has evolved over several Eclipse releases. Users familiar with versions prior to 3.0 may still recall the Welcome editor, which would be automatically opened after installing a new feature (and restarting the workbench). This form of welcome wasn’t particularly visually appealing—the editor content typically consisted of a set of bullet points with links to online Help. There was little visual customization that could be done.
In Eclipse 3.0, the concept of a full-featured Welcome screen was introduced, with the ability to populate it with almost arbitrary HTML-based content, including rich graphics, links, actions, and dynamic (in other words, generated live) content. Even though this framework provided a great deal of extensibility, it proved too difficult for large-product assemblers to customize, particularly when a number of disparate features were to be included in the product. Thus, version 3.2 brought about the Universal Intro, which gave product assemblers the ability to customize the layout and content of the Welcome screen based on the various contributions included in the final product.
The Intro framework is extensible and customizable at virtually every level. Product vendors can even replace the entire implementation with their own. However, when products are assembled from multiple features, and the user’s ability to install new and unknown features is desired, the default implementation—the Universal Intro—is the preferred way to go.
Visually, the Welcome screen resembles a portal-like web page with links to several other pages. By default, Overview, What’s New, Samples, and Tutorials are shown, but additional pages are available (First Steps, Migrate, and Web Resources). Each of these pages can be extended by contributing content to pre-defined “anchors.” The user can customize both layout and content of these pages using Preferences (General -> Welcome).
The Intro view can actually be displayed in two modes—full and stand-by. In full mode the view is maximized across the whole window, whereas in stand-by mode it only shows up as a regular view. It is possible (and customary) to contribute different content for each mode (for example, a stream-lined version of the full page is typically displayed when in stand-by mode). The user is free to switch between the two modes at any time.
Contributing Intro Content
Although no substitute for solid functionality and accessible user interface (supported by context-sensitive help and supplemented by cheat sheets, when appropriate), the often underutilized welcome screen proves a good investment particularly for small add-in providers, who don’t get to control the overall product branding and whose plug-in contributions often get “lost” in the context of a large product. Like most extensible features in Eclipse, the Universal Intro can be customized by means of an extension point. The org.eclipse.ui.intro.configExtension extension point allows you to extend a particular intro configuration, such as the default Universal Intro set up by the platform. In addition to intro content, stand-by parts, themes, and actions can also be contributed.
The actual content is not spelled out in the extension, but rather it is located in a separate XML file referenced in the extension, because it can potentially grow quite large. The intro content file has special format documented in the Platform Developer’s Guide (see Resources). In a typical scenario, an extensionContent element is used to contribute content to an anchor defined elsewhere (in other words, specific page locations where add-in providers are expected to contribute their content). This element can further include simple text, links, entire HTML files (full pages or just snippets), or content groups defined elsewhere. It also can define its own groups of content (which can then be further reused). Hyperlinks can point to arbitrary URLs, but using specially formatted URLs of the form http://org.eclipse.ui.intro/<action name>?param1=value1¶m2=value2 makes it possible to invoke plug-in-contributed code.
To illustrate how to contribute custom content to the welcome page, you can create a simple plug-in that adds a section to the Overview page. I shall also provide a custom action and use it as a hyperlink target.
Just about the easiest way to get started is to create a new Plug-in project using the Custom plug-in wizard template:
- In the PDE perspective, click File -> New -> Project… and choose Plug-in Project from the list. Click Next.
- Give the project a meaningful name (which will also double as its plug-in ID). In the attached sample project, you use com.developer.welcome. Click Next.
- The defaults in the Plug-in content page should be fine, so just click Next.
- On the Templates page, select Custom plug-in wizard from the available templates and click Next.
- Uncheck all templates (click Deselect All) and check Universal Welcome Contribution. Click Next.
- On the last page, the defaults are fine, too (for illustration purposes). You can modify the Link URL if you wish. Click Finish.
When you now examine the newly created plug-in project, you will notice that there is an intro folder with some generated files. The file of interest is called sample.xml. This is the file that defines the content of our contribution. You may modify the text as you wish, but be careful to preserve the style-ids—they refer to CSS styles defined in sample.css. Finally, note that the file is referenced by the org.eclipse.ui.intro.configExtension extension in plugin.xml.
To make things just a bit more interesting, place a link at the bottom of your contributed section that will close the Welcome view and switch to the PDE perspective when clicked (that way, the user can start developing Eclipse plug-ins right away). The complete example of contributed content is shown in Listing 1.
There is no pre-defined action that would accomplish what you want, so you have to implement our own. All intro actions must implement the IIntroAction interface. This really consists of only one method—run(IIntroSite, Properties). The first argument is the workbench site that hosts the intro from which the action is invoked, and the second argument contains a map of arguments specified as part of the link’s URL. The body of this method can be relatively simple—first, close the intro part, and then open the desired perspective (whose ID is provided as a URL parameter). This way, you can reuse the same action whenever you want to open an arbitrary perspective by simply specifying the corresponding perspective ID in the parameter list.
Finally, you could reference this action using the rather verbose “runAction” form, which requires its plug-in ID, class name, and all parameters. Instead, register the action under a short name—goPDE—in plugin.xml (as part of the same extension). You can see that this really simplifies its use and decouples the content from its implementation details.
- Source code (Eclipse projects) for the example (requires Eclipse 3.3)
- Platform Plug-in Developer Guide: Universal intro
- Extending the content of an intro config
- Intro Content File XML Format
About the Author
Peter Nehrer is a software consultant specializing in Eclipse-based business applications and development tools. He is the founder of Ecliptical Software Inc. and a contributor to several Eclipse-related Open Source projects. He holds an M.S. in Computer Science from the University of Massachusetts at Amherst, MA. Peter can be reached at pnehrer AT eclipticalsoftware DOT com.