扩展通用简介

在启动按以上方式配置的“通用欢迎”时,您会注意到,所有从根页面分支出来的二级页面 的内容区域都是空的。这是因为共享的“欢迎”没有自己的内容。这些区域是使用简介配置扩展填充的。

添加配置扩展的传统做法是指定目标页面中锚点元素的完整路径。仍支持此方法,但经证明,此方法有些脆弱。如上所述,指定扩展在目标中所处的确切位置对于扩展作者来说为时过早。他们可能不了解他们的扩展最终将在哪些产品中,因此不知道它们根据每个产品的焦点应该出现在什么位置。在通用欢迎中,此决策由产品作者进行。现在,扩展作者可以选择指定不完整的路径,从而允许产品作者填写空白内容。

要使用延迟目标路径解析功能的配置扩展需满足三个条件:

  1. 配置扩展需要使用“id”属性来指定唯一的标识。不带标识的扩展将被忽略。由于产品作者将使用标识来引用扩展,所以这一点十分重要。
  2. 配置扩展需要使用“name”属性来指定对用户友好的名称。如果将要使用定制首选项页,这一点就很重要,这是因为扩展将显示在 UI 中。
  3. 目标路径的格式是“page_id/@”,其中“page_id”是目标页面的标识。当在目标路径中检测到“/@”时,就会尝试动态地将路径解析为所期望的完整格式。

解析扩展目标路径的能力是 Eclipse 3.2 中新增的简介支持功能,添加此功能的目的是使通用帮助的功能更强大。此功能本身是通用的,它不仅仅适用于通用帮助,还能用于其他欢迎实现。在 Eclipse 3.2 中,CustomizableIntroPart 可以接受可选的简介定制程序类,该定制程序类可以在许多方面影响 CustomizableIntroPart 的行为。定制程序的其中一个角色是执行延迟目标路径解析工作。当然,在产品作者的关注范围内,这全都仅仅是实现细节。这是因为,在通用欢迎实现中,延迟目标路径解析工作是使用前面提到的数据文件执行的。此文件是使用 org.eclipse.ui.intro/INTRO_DATA 首选项存储的。

“INTRO_DATA”文件使用 XML 格式,并允许产品作者控制主欢迎页面的内容。欢迎添加项作者在目标路径中必须只指定页面标识。其余内容是在此文件中定义的。此文件包含一系列“page”元素,每个“page”元素都包含许多“group”元素。Group 元素指定相对于页面的路径,并且带有子代添加项。使用添加项元素来指定两方面的内容:

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

在以上示例中,添加项“foo1”、“bar”和“foo2”将在页面上的左列中,“foo3”、“foo4”和“foo5”在页面上的右列中。添加项的相对顺序也是从此文件中抽取的。此外,添加项将根据 importance 属性进行分类,该属性具有四个有效值:highmediumlowcallout,其中 low 是缺省值。每个值都有匹配的表示,该表示使该值在页面中突出显示。前三个值仅仅是产品作者指定的不同重要性级别(注意,同一个添加项在两个不同的产品中可以具有不同的重要性分类)。最后一个值(callout)用来指示添加项具有完全不同的性质(例如,提供视频或动画链接的添加项)。

未列示的添加项将被追加到已连接的添加项之后,并且将被指定低重要性值。这一点对于产品交付后添加的添加项来说十分重要 - 它们仍需要显示。

对于与项目无关的添加项来说,可以通过将它们列示为“hidden”元素的子代来将它们隐藏。

添加到扩展中

对于添加到其中一个根页面中的扩展来说,它们本身可以包含锚点,从而允许其他用户添加内容。这会引起问题,这是因为扩展中的内容的最终解析得到的路径事先是未知的。因此,扩展中使用延迟路径解析功能的内容的目标路径本身必须已解析:

<?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>

为了对以上扩展中的锚点“additions”添加内容,我们应该使用以下路径:“overview/@extra/extra-group/additions”。“@extra”段将被替换为“overview”页面中标识为“extra”的扩展的已解析路径。例如,如果将此扩展放在页面的左上区域中,则解析得到的路径将是:“overview/page-content/upper-left/extra-group/additions”。