bundles/org.eclipse.platform.doc.isv/guide/ua_intro_universal_extending.htm - platform/eclipse.platform.common - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <html>
 <head>
 <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2006. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
 <meta http-equiv="Content-Style-Type" content="text/css">
 <link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css">
 <script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script>
 <title>Extending the universal intro</title>
 </head>
 <body>

 <h2>Extending the universal intro</h2>

 <p>
 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.
 </p>

 <p>
 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.
 </p>

 <p>
 Config extensions that want to use late target path resolution need to
 fulfill three conditions:
 </p>

 <ol>
 	<li>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.</li>
 	<li>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.</li>
 	<li>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.</li>
 </ol>

 <p>
 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.
 </p>

 <p>
 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:
 </p>

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

 <p>
 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 <code>importance</code> attribute that
 can have four valid values: <b>high</b>, <b>medium</b>, <b>low</b> and <b>
 callout</b>, with <b>low</b> 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 (<b>callout</b>) is used to single out
 contributions that are of a completely different nature (for example, a
 contribution that offers links to videos or animation).
 </p>

 <p>
 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.
 </p>

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

 <h3>Contributing into extensions</h3>

 <p>
 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:
 </p>

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

          &lt;/link&gt;
          &lt;anchor id="additions"/&gt;
       &lt;/group&gt;
    &lt;/extensionContent&gt;
 &lt;/introContent&gt;</pre>
 </blockquote>

 <p>
 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".
 </p>

 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	<html>
	<head>
	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2006. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
	<meta http-equiv="Content-Style-Type" content="text/css">
	<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css">
	<script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script>
	<title>Extending the universal intro</title>
	</head>
	<body>

	<h2>Extending the universal intro</h2>

	<p>
	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.
	</p>

	<p>
	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.
	</p>

	<p>
	Config extensions that want to use late target path resolution need to
	fulfill three conditions:
	</p>

	<ol>
	<li>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.</li>
	<li>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.</li>
	<li>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.</li>
	</ol>

	<p>
	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.
	</p>

	<p>
	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:
	</p>

	<pre>
	<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>
	</pre>

	<p>
	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 <code>importance</code> attribute that
	can have four valid values: <b>high</b>, <b>medium</b>, <b>low</b> and <b>
	callout</b>, with <b>low</b> 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 (<b>callout</b>) is used to single out
	contributions that are of a completely different nature (for example, a
	contribution that offers links to videos or animation).
	</p>

	<p>
	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.
	</p>

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

	<h3>Contributing into extensions</h3>

	<p>
	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:
	</p>

	<blockquote>
	<pre><?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></pre>
	</blockquote>

	<p>
	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".
	</p>

	</body>
	</html>