Pimp your Intro !

ttoine's picture
ttoine
Blog Categories: 

What is the first thing you see when you start an RCP product? The splash screen.

What is the second thing you see when you start an Eclipse RCP product? The intro page. This page is the first interaction that the user has with your product. It deserves real effort to ensure that your users feel comfortable when opening the product. Also, you can leverage this page to add dynamic content, that can be used, for example, for direct communication between your company and your users. Then it can become a tool for both user-friendliness and marketing, with a relatively low effort. It's worth it!

In this post we will describe how we leverage the intro page extensibility and API to develop a more ergonomic and marketing-friendly intro page. Everything you will read here can be found or taken directly from the Eclipse Help contents, but I'll try to explain it more practically. The intro page can also be defined using SWT, but in this post we will focus only on using (X)HTML to define intro pages, since it is more appropriate to the use case of "out-sourcing" the intro page to design or marketing.

What can you expect from your (X)HTML intro page

While using (X)HTML, you can also use JavaScript. Although most Java developers are not fond of JavaScript, we must admit that it is a very powerful language when it comes to playing with the content of a web page. JavaScript makes your page dynamic, and is something that most web-oriented people can tweak to create nice effects on your page (feedback, images in a carousel, powerful widgets...).

You also can expect 2-way communication between your intro page and your application:

That means that you'll be able to trigger actions in your application from your intro page, for instance to create a new file, or open a wizard, or anything your application can do.

And you can also populate your page with data coming from your application. A use-case we chose for Bonita Studio is to show the "Recently opened" files on the intro page. This requires the page to look at the files in the workspace and show the ones last modified. We also use it to show the content of some RSS streams.

With all this stuff, you can create a highly dynamic page well integrated into your application! Here is a video of what we've got for the current release of Bonita Open Solution - 5.4.1:

Here is the recipe:

Define an intro for your product

This step is just about overriding the default Eclipse intro page for your product and defining contents for the intro. Since we want the intro page to be easily maintained by the design and marketing teams, we chose to use XHTML to define it. XHTML is much more accessible than Java and SWT for them ;). In this post, we will only focus only on using HTML or XHTML, skipping SWT.

In one of your plugin.xml files (for instance in the plugin that contains your html page), add: [cc lang="xml"]
[/cc]

This means that for org.bonitasoft.studio.product, you'll show the intro as defined in content/introContent.xml, starting from the page with id root, in html mode (you can use swt if you want).

As you can see, this extension binds an introContent.xml file to your product. Now, add it to your bundle, along with the html file of the page. Note that the page that will be displayed as intro is the one with id root:

Intro plugin tree, and introContent.xml

Contents of the file

XHTML or HTML

In your introContent.xml, you have 2 ways to reference the file you want to show, depending on the attribute you use to locate the page in the page element of introContent.xml:

url="myPage.html"

With a url, you will be able to show any HTML or JavaScript you want. Everything will be simply displayed in a web browser. You'll be able to call some of your application code by clicking links. (See "Links to actions in your application"), however you won't be able to add contents to that page at runtime depending on your application state. This method is preferable when you don't need to fill the page with data from your application, since it provides full support for JavaScript.

content="myPage.html"

The content of your HTML must be valid XHTML. Thus your file can have the same content as any HTML file, except that it has to start with the XHTML header ( ) and all your tags must be closed. If you are generally using Java, you probably often edit XML, then nothing shocking here. (By the way, I do not understand why XHTML is not the de facto standard nowadays...)

Your file must conform to the W3C specification. The W3C validator is very helpful while debugging it.

[cc lang="xml"]

<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Welcome to Bonita Studio</title>
<link href="css/style.css" rel="stylesheet" type="text/css" />
<script type="text/javascript">
function setClass(elementId,cssclass)
{
var e = document.getElementById(elementId);
if(e != null)
{
e.className = cssclass;
return true;
}
return false;
}
...
</script>
</head>

<body onload="initCarrousel();" class="body_custom">
<div id="template-gen">
<div id="containerCenter">

<div id="left" class="left">
<div id="col-top" class="col-top">

<h1><img src="images/design.png" width="200" height="60" alt="" /></h1>
</div>
<div id="col-mid" class="col-mid">
<div id="col-mid-bg" class="col-mid-bg">
<div id="actions">
<ul>
...
</ul>
</div>
</div>
</div>
...
</div>
</div>
...
</div>
</div>
</body>
[/cc]

Since your XHTML intro page will be displayed in the internal Browser of Eclipse, there is obviously support for JavaScript! Except if you use contentProviders in your page, you have to use the <em>content</em> XML attribute in your <em>introConent.xml</em> instead of the <em>url</em> attribute, and there is currently a<strong> limitation for JavaScript</strong> support that is reported on bug <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=332416">332416</a>, that makes impossible to execute JS code that contains "<" or "&", and possibly others.

However, only the <em>
content</em> mode allows you to use contentProviders.
<h3>Links to actions in your application</h3>
This is well described in the <a href="http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.platform.doc...>Eclipse help</a>, and is pretty easy to set up. For each action you want to call from your intro page, implement your action as a class that extends <a href="http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.platform.doc...>IIntroAction</a>. Then, whenever the internal intro web browser reaches the URL<em> http://org.eclipse.ui.intro/runAction?pluginId=org.bonitasoft.studio.intro&amp;class=org.bonitasoft.studio.intro.actions.NewProcessAction</em>, the NewProcessAction will be executed.

Then simply add links from your HTML page to your actions:

[cc lang="xml"]
<!-- Simple anchor -->
<a href="http://org.eclipse.ui.intro/runAction?pluginId=org.bonitasoft.studio.int...>click me</a>
<!-- JavaScript-->
<div onclick="location.href='http://org.eclipse.ui.intro/runAction?pluginId=org.bonitasoft.studio.int...'">click me</div>
[/cc]

<h3>Content depending on your application state (contentProvider)</h3>
This only works when you reference your page using the <em>content </em>attribute, in your introConfig.xml. The official documentation is <a href="http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.platform.doc...>here</a>.

The key is to create a class that implements <a href="IIntroXHTMLContentProvider">IIntroXHTMLContentProvider</a>. With XHTML, it is generally more comfortable to implement the <em>createContent(String id, Element parent) </em>method. Here is the content provider we use for internationalization of messages in our intro page:

[cc lang="java"]
/**
* Copyright (C) 2010 BonitaSoft S.A.
* BonitaSoft, 31 rue Gustave Eiffel - 38000 Grenoble
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 2.0 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/
package org.bonitasoft.studio.intro.content;

import java.io.PrintWriter;

import org.bonitasoft.studio.intro.Messages;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.ui.forms.widgets.FormToolkit;
import org.eclipse.ui.intro.config.IIntroContentProviderSite;
import org.eclipse.ui.intro.config.IIntroXHTMLContentProvider;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.Text;

/**
* @author Mickael Istria
*
*/
public class I18NContentProvider implements IIntroXHTMLContentProvider {

/* (non-Javadoc)
* @see org.eclipse.ui.intro.config.IIntroContentProvider#init(org.eclipse.ui.intro.config.IIntroContentProviderSite)
*/
public void init(IIntroContentProviderSite site) {
}

/* (non-Javadoc)
* @see org.eclipse.ui.intro.config.IIntroContentProvider#createContent(java.lang.String, java.io.PrintWriter)
*/
public void createContent(String id, PrintWriter out) {
}

/* (non-Javadoc)
* @see org.eclipse.ui.intro.config.IIntroContentProvider#createContent(java.lang.String, org.eclipse.swt.widgets.Composite, org.eclipse.ui.forms.widgets.FormToolkit)
*/
public void createContent(String id, Composite parent, FormToolkit toolkit) {
}

/* (non-Javadoc)
* @see org.eclipse.ui.intro.config.IIntroContentProvider#dispose()
*/
public void dispose() {
}

/* (non-Javadoc)
* @see org.eclipse.ui.intro.config.IIntroXHTMLContentProvider#createContent(java.lang.String, org.w3c.dom.Element)
*/
public void createContent(String id, Element parent) {
Document dom = parent.getOwnerDocument();
Text text = dom.createTextNode(Messages.getMessage(id));
parent.appendChild(text);
}

}

[/cc]

And then, we can include a message from our NLS messages class in the XHTML page using:

[cc lang="xml"]
<contentProvider id="myMessageKey" pluginId="org.bonitasoft.studio.intro" class="org.bonitasoft.studio.intro.content.I18NContentProvider"/>
[/cc]
<h2>Examples</h2>
All this stuff, and much more, can be found in our <a href="http://www.bonitasoft.org/websvn/listing.php?repname=Bonita+Open+Solutio...>SVN repo</a>. You'll hopefully find some clues and ideas if you're stuck ;)
Notifications