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="https://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".
