Extending the universal intro

When launching the universal Welcome configured as shown above, you will notice that all of the second level page that branch off the root page have an empty content area. This is because shared Welcome does not have content of its own. These areas are populated using intro config extensions.

The traditional way of contributing config extensions is to specify a full path of the anchor element in the target page. This method is still supported but it has proven to be somewhat fragile. As mentioned before, specifying an exact place where the extension will end up in the target is premature for extension authors. They may not know all the products in which their extension will end up, and therefore don't know where they should appear according to each product's focus. In the universal Welcome, this decision is left to product authors. Extension authors now have the option of specifying an incomplete target path, allowing the product author to fill in the blanks.

Config extensions that want to use late target path resolution need to fulfill three conditions:

Config extension needs to specify a unique identifier using the 'id' attribute. Extensions without the id will be ignored. This is important because id will be used to refer to the extension by the product author.
Config extension needs to specify a user-friendly name using the 'name' attribute. This is important if the customization preference page will be used because extensions will show up in the UI.
The target path should have the following form: "page_id/@" where 'page_id' is the identifier of the target page. When '/@' is detected in the target path, an attempt will be made to dynamically resolve the path into the expected full form.

The ability to resolve extension target paths is a new intro support feature in Eclipse 3.2 added to make universal Welcome more powerful. The feature itself is generic in that it can be used in other Welcome implementations, not just the universal one. In Eclipse 3.2, CustomizableIntroPart can accept an optional intro customizer class that can affect its behavior in several ways. One of the roles of the customizer is to perform late target path resolution. Of course, as far as product authors are concerned, this is all just implementation detail because in universal Welcome implementation, late target path resolution is performed using the data file mentioned earlier. This file is stored using the org.eclipse.ui.intro/INTRO_DATA preference.

The 'INTRO_DATA' file uses XML format and allows product authors to control the content of the main Welcome pages. Welcome contribution authors are required to specify only the page Id in their target paths. The rest is defined in this file. The file contains a sequence of 'page' elements, each containing a number of 'group' elements. Group elements specify page-relative path and have contributions for children. Contribution elements are used to specify two aspects:

   <extensions>
      <page id="overview">
         <group path="page-content/top-left">
            <extension id="foo1" importance="high"/>
            <extension id="bar"  importance="high"/>
            <extension id="foo2" importance="medium"/>
         </group>
         <group path="page-content/top-right">
            <extension id="foo3" importance="low"/>
            <extension id="foo4" importance="low"/>
            <extension id="foo5" importance="callout"/>
         </group>
         <hidden>
            <extension id="foo6"/>
            <extension id="foo7"/>
         </hidden>
      </page>
      <page id="whatsnew">
      ...
      </page>
   </extensions>

In the example above, contributions 'foo1', 'bar' and foo2' will be in the left, and 'foo3', 'foo4' and 'foo5' in the right column on the page. The relative order of contributions is also extracted from this file. In addition, contributions are classified based on the importance attribute that can have four valid values: high, medium, low and callout, with low as the default. Each value has matching presentation that makes it stand out on the page. First three are simply different levels of importance according to the product author (note that the same contribution may receive a different importance classification in two separate products). The last one (callout) is used to single out contributions that are of a completely different nature (for example, a contribution that offers links to videos or animation).

Contributions that are not listed are appended after the listed contributions and assigned a low importance value. This is important for contributions added after the product has shipped - they still need to show up.

Contributions not relevant to the project can be hidden by explicitly listing them as children of the 'hidden' element.

Contributing into extensions

An extension contributed into one of the root pages can itself contain anchors, providing for others to add content. This causes a problem because the final resolved path of the content in the extension is not known in advance. For this reason, target paths for content in extensions that use late path resolution must itself be resolved:

<?xml version="1.0" encoding="utf-8" ?>
<introContent>
   <extensionContent id="extra" name="Extra" alt-style="css/swt.properties" style="css/overview.css" path="overview/@">
      <group id="extra-group" style-id="content-group">
         <link label="Extra Overview link" url="http://org.eclipse.ui.intro/showPage?id=extraOverview" 
					  id="extra-overview">
      	    <text>Showing the third-level extra page for overview</text>

         </link>
         <anchor id="additions"/>
      </group>
   </extensionContent>
</introContent>

In order to contribute into the anchor 'additions' in the extension above, we should use the following path: "overview/@extra/extra-group/additions". The segment '@extra' will be replaced with the resolved path of the extension with the id 'extra' in the 'overview' page. For example, if the extension is placed in the upper left segment of the page, the resolved path will be: "overview/page-content/upper-left/extra-group/additions".