Welcome Page

Today we will have a look at the welcome screen. We will start by following A short tutorial on Intro/Welcome. Then we will add a custom entry to the news section. Finally we are going to implement code to trigger the welcome screen a second time.

Source code for this tutorial is available on googlecode as a single zip archive, as a Team Project Set or you can checkout the SVN projects directly.

Step 1: Creating a basic product

Create a new Plug-in project called com.codeandme.welcome. We do not need an Activator nor contributions to the UI.

An Intro needs a product, so we need to create one. Therefore create a new Product Configuration with basic settings. Name your product file Example.product.

In the Product Definition click on New... and set the Product ID to example. Select the Application org.eclipse.ui.ide.workbench. This will start the default workbench. For a real life implementation you would of course use your own application here.

Back at the product definition save and click Launch an Eclipse Application. This will create a new launch configuration and furthermore synchronize the product definition with the plugin.xml. Changes of the product definition will not automatically be synchronized so remember to hit either Synchronize or Launch an Eclipse Application on any change.

Step 2: Defining the Intro


Switch to the Extensions tab of your plugin.xml. Add a new extension for org.eclipse.ui.intro. Add a new introProductBinding to it. Enter your productId com.codeandme.welcome.product and the introId of the universal intro org.eclipse.ui.intro.universal.

Make sure your plugin dependencies include org.eclipse.ui.intro and org.eclipse.ui.intro.universal.

Now add some branding to the intro by adding properties to the product definition. Add a property introBrandingImage for the logo in the upper left corner. Set product:<path/to/image.png> as property value and put the image into the com.example.welcome Plug-in. Add another property introTitle containing the main heading of your welcome page.

Your final plugin.xml should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>
   <extension
         point="org.eclipse.ui.intro">
      <introProductBinding
            introId="org.eclipse.ui.intro.universal"
            productId="com.example.welcome.product">
      </introProductBinding>
   </extension>
   <extension
         id="product"
         point="org.eclipse.core.runtime.products">
      <product
            application="org.eclipse.ui.ide.workbench"
            name="example">
         <property
               name="introBrandingImage"
               value="product:images/logo.png">
         </property>
         <property
               name="introTitle"
               value="My Example RCP Application">
         </property>
      </product>
   </extension>
</plugin>

Finally we need to add a theme for our intro. Therefore create a file plugin_customization.ini in the root directory of your Plug-in with following content:

org.eclipse.ui.intro/INTRO_THEME = org.eclipse.ui.intro.universal.slate
org.eclipse.ui.intro.universal/INTRO_ROOT_PAGES = overview,tutorials,samples,whatsnew,webresources

Line 2 lists all the root pages that should be available. Adapt this list to your own needs.

Save and launch your product to see the welcome page in its full beauty. If you do not see the welcome screen you might have forgotten to clear your workspace. You can activate this setting in your launch configuration on the Main tab.

Step 3: Adding content to the Whats New section

Open the Extensions tab of your plugin.xml. Now add an extension for org.eclipse.ui.intro.configExtension and use the template Universal Welcome Contribution.

The wizard lets you select where to place content and creates sample files automatically.

By editing /intro/sample.xml you can easily adapt the example to your needs.

Reactivating welcome screen

Eclipse will automatically deactivate the welcome screen once it was presented to the user. Sometimes you might want to reactivate the screen for the next workbench startup. You can do this with this line of code.

PlatformUI.getPreferenceStore().setValue(IWorkbenchPreferenceConstants.SHOW_INTRO, true);

You might want to use this to display news after an update. Therefore you can combine this with a Custom Installation Step.

Custom Installation Step

Update:
Last time I tried you could not use custom touchpoint actions that came with the current installation package. It seems eclipse has a but there and does not consider fresh installed actions when it searches for it. So you can only use actions that were installed with a previous installation step.


When you provide a feature via an update site sometimes it would be nice to do extra stuff once the feature is installed. For example we could automatically open a configuration dialog or the welcome screen providing new information.

Before p2 we could use a custom installation handler. Now we need to use touchpoints.

Source code for this tutorial is available on googlecode as a single zip archive, as a Team Project Set or you can checkout the SVN projects directly.

Step 1: Prerequisites

Create a simple Plug-in project called com.example.touchpoint.action. You do not need to provide an Activator or UI components.

Create a Feature project called com.example.custominstall.feature. Add com.example.touchpoint.action to the included Plug-ins.

Step 2: Preparing touchpoint action

There already exist lots of actions which you could use for your own purposes.

In this example we want to create a new action. Therefore open the plugin.xml from your com.example.touchpoint.action project. Switch to the Extensions tab and add a new action by adding an org.eclipse.equinox.p2.engine.actions extension. Set the touchpointType to org.eclipse.equinox.p2.osgi and find a unique name for your action.

Afterwards create a new class called com.example.touchpoint.action.MyAction.

package com.example.touchpoint.action;

import java.util.Map;

import org.eclipse.core.runtime.IStatus;
import org.eclipse.core.runtime.Status;
import org.eclipse.equinox.p2.engine.spi.ProvisioningAction;
import org.eclipse.jface.dialogs.MessageDialog;
import org.eclipse.swt.widgets.Display;

public class MyAction extends ProvisioningAction {

 @Override
 public IStatus execute(Map<String, Object> parameters) {
  System.out.println("**************************************************** Feature installation");
  for (String key : parameters.keySet())
   System.out.println("Key: " + key + ", value: " + parameters.get(key));

  if (Display.getDefault() != null)
   Display.getDefault().asyncExec(new Runnable() {

    @Override
    public void run() {
     MessageDialog.openInformation(Display.getDefault().getActiveShell(), "Feature installation",
       "Your feature is in the process of being installed.");
    }
   });

  return Status.OK_STATUS;
 }

 @Override
 public IStatus undo(Map<String, Object> parameters) {
  return Status.OK_STATUS;
 }
}

Now we need to register our custom action with p2. Therefore create a new file /META_INF/p2.inf with following content:

provides.0.namespace=org.eclipse.equinox.p2.osgi
provides.0.name=myAction
provides.0.version=1.0

Line 2 contains the name parameter of our action definition. The "0" in the key is an index which needs to be incremented if you define multiple actions within the same p2.inf file.

Make sure your p2.inf file is included in your build!

 
Step 3: Activating install action

We want our action to be called right when our feature is installed. So  switch to the com.example.custominstall.feature and create a new file /p2.inf.

metaRequirements.0.namespace=org.eclipse.equinox.p2.osgi
metaRequirements.0.name=myAction
metaRequirements.0.range=1.0

instructions.configure=myAction(key1:value1,key2:value2);
instructions.configure.import=com.example.plugin.myAction

This will call our custom action when our feature is configured. You can find a list of available phases at the end of this wiki entry.

The import and the action need to use the same phase identifier, otherwise the action will not be found.
As you can see from the action implementation the parameters will be stored in a Map<String,String>.

Again make sure to add the p2.inf to the build.

Step 4: Try it out

To give it a try we need to create a p2 repository from which we can install. We can do this quickly by using a special export wizard. Open File / Export... and start the Plug-in Development / Deployable features wizard. Select the feature you want to export and provide a destination directory where the p2 update site should be created.

Afterwards try to install the feature from that directory.

Additional Notes

When your action uses GUI code make sure that a GUI is available. Remember that the action might be run by a headless install.

Once an action is installed, it can be used by other features too. So Action provider and the feature using the action do not necessarily need to be the same.