注意:帮助系统仍在开发中,可能在获得稳定版本之前还会作些更改。在现阶段提供它的目的是为了获取早期使用者的反馈,因为我们知道添加机制的具体细节可能会断断续续地进行更改。

添加项

标识符:org.eclipse.help.contributions

描述:用于为个别插件注册联机帮助添加项。

向帮助文件进行添加的每个插件一般应执行下列操作:

添加项扩展点的配置标记:

    <!ELEMENT topics EMPTY>
    <!ATTLIST topics name CDATA #REQUIRED>

    <!ELEMENT actions EMPTY>
    <!ATTLIST actions name CDATA #REQUIRED>     <!ELEMENT infoset EMPTY>
    <!ATTLIST infoset name CDATA #REQUIRED> 主题的配置标记(这是主题(topics)清单文件的内容)

    <!ELEMENT topics (topic)* ) >
    <!ATTLIST topics id  ID #REQUIRED >

    <!ELEMENT topic (topic)* >
    <!ATTLIST topic id ID #IMPLIED >
    <!ATTLIST topic label CDATA #REQUIRED >
    <!ATTLIST topic href  CDATA #IMPLIED >

信息集的配置标记(这是信息集(infoset)清单文件的内容)

    <!ELEMENT infoset (infoview)*  >
    <!ATTLIST infoset  id  ID  #REQUIRED >
    <!ATTLIST infoset  label  CDATA  #REQUIRED >
    <!ATTLIST infoset  href  CDATA #IMPLIED >
    <!ATTLIST infoset  standalone  (false|true) false  #IMPLIED >

    <!ELEMENT infoview EMPTY>
    <!ATTLIST infoview id ID #REQUIRED >
    <!ATTLIST infoview label CDATA #IMPLIED >

插入操作的配置标记(这是操作(actions)清单文件的内容)

    <!ELEMENT actions (insert)* >
    <!ATTLIST actions infoview CDATA #REQUIRED >
    <!ATTLIST actions standalone (true | false) false #IMPLIED >

    <!ELEMENT insert (insert) >
    <!ATTLIST insert from CDATA #REQUIRED >
    <!ATTLIST insert to CDATA #REQUIRED >
    <!ATTLIST insert as (child | first-child | last-child | prev-sib | next-sib) "child" >
    <!ATTLIST insert label CDATA #IMPLIED >

通常,需要提供联机帮助的插件将定义它自己的主题清单和必要操作清单以将主题与正确位置相连。最后,将帮助系统配置为如某些操作那样启动,而信息集的标识可用来执行此操作。

插件可使用四种类型的 XML 元素:主题(topic)、信息集(infoset)、操作(actions)和插入(insert)元素。

主题元素

就主题元素而言,所有主题都是作为主题容器元素的一部分添加的。它们可具有分层结构,或可列示为平面列表。主题清单被视作是用于进一步的主题交错和组织到集成的 Web 中的数据源,它具有不同的视图透视图。另外,可通过指定主题的标识来对主题进行操作,但人们还可通过指定包含主题或主题元素的标识来对一组主题进行操作。以后,当将主题与视图或其他主题相连时,就会维护在主题清单中定义的结构(遵从由插入操作完成的改变)。

主题元素是导航结构的骨干部分。主题元素有三种典型用法:

1.  提供文档文件(通常是 HTML 文件)的链接。
2.  充当在同一清单或另一清单中的其他主题的容器。
3.  为在同一清单或另一清单中的其他主题提供插入点。

1.  作为链接的主题
主题最简单的用法就是用作文档文件的链接。

<topic label="Some concept file" href="concepts/some_file.html"/>

href 属性是与清单文件所属的插件相关的。如果您需要访问另一插件中的文件,可使用以下的语法:

<topic label="topic in another plug-in" href="/other.plugin.id/concepts/some_other_file.html" />

2.  作为容器的主题
主题的下一个常见用法是将它用作其他主题的容器。容器主题本身也可总是引用某个特定文件。

<topic label="Integrated Development Environment" href="concepts/ciover.htm" >
  <topic label="Starting the IDE" href="concepts/blah.htm" />
  ...
</topic>

3.  作为插入点的主题
主题可用作插入点。它们为其他主题提供了逻辑位置以进行尝试和合并。 要充当插入点,主题必须具有标识属性。
 
 

信息集元素

信息集是进入文档 web 的入口点。 可将它认为是一个视图集合。

视图将会用来提供文档 web 内的高级语义分组。 是使用在信息集内定义的 infoview 元素来定义这些视图的。文档小组可使用视图来生成“入门”、“任务”和“参考”部分(或产品小组定义的其他视图)。 平台不指定实际的各个部分,仅指定用于定义这些部分的机制。

例如,可定义一个“任务视图”, 该视图是“如何执行一些操作”透视图中所有主题的合并。还可定义另一视图,即“组件视图”,该视图是一个显示所有组件及其文档的主题树。

Infoview 元素表示可在各插件中“共享”的主题的容器。它是有关整个文档的透视图。可能会有许多不同的插件都向同一逻辑文档组件进行添加的时候。此元素确保在使用“组件视图”期间,这些插件正确地一起合并到相干视图中。

操作元素

操作清单包含要对主题和视图执行的脚本编制操作。目前,只有一种操作 (插入操作)用来将主题和视图一起写入到一个有多个视图的集成信息 web 中。

这些操作都是结构性操作(插入),因而适用于某个信息视图。因此, 清单中的所有插入操作都在一个信息视图中构建主题层次结构。

插入元素

组件化导航最复杂的部件之一就是如何创建具有连续导航流的集成的信息结构。为此,需要一个机制来发布插入点、选择要使用的插入点以及指示想要在何处插入主题(父代、子代、之前、之后)。

插入点可以是主题或视图。主题通过提供标识来指示其成为插入点的意愿。视图需要具有标识。仅将全限定标识用作引用。例如,org.eclipse.help.examples.ex1 插件 中的主题 <topic id="concepts" label="concepts"> 的全限定主题标识为 org.eclipse.help.examples.ex1.concepts。

由于插入点通常位于其他插件中,而可能未安装这些插件,所以您可指定备用插入点。缺省情况下,如果所选的插入点都不成功,则主题仍保留在其组件层次结构之下。“to”属性指定目标插入点。“from”属性指定的主题就是要插入的主题。下面是一些插入主题的可能方法,使用 as 属性来指定它们:

目前,仅可在信息视图中插入某个主题一次,但是,可将它插入到多个信息视图中。这意味着,如果将一个父主题(从而连同其子树)插入到某个信息集中, 就不能再将它的任何一个子代插入到同一信息视图中。本质上,插入创建的特定信息视图的各部分是不可分的。

提供了备用插入选项,且将在不能执行前面的插入操作时执行它。插入元素的嵌套插入子元素提供了这些备用项。这可看作是“撤退”机制,即如果某插入操作失败,则将执行嵌套的插入操作。一旦对选择的第一个插入点感到满意,就忽略其他备用插入点。
 

示例:

下面是使用添加项扩展点的一个示例。假设以下示例是关于其标识名为 "org.eclipse.help.examples.ex1" 的插件的。(示例的目的是作为一个普通样本,应注意,同一文档层次结构(生成自下列所有添加文件)还可用各种主题和操作文件组合来创建。)

(在 plugin.xml 文件中)
 

   <!-- Use the Help System contribution extension point to define Infosets, topics, -->
   <!-- and actions contribution files. For clarity, the extension point is used     -->
   <!-- twice, once to define the Infoset and it's view, and another to define the   -->
   <!-- Topics and their associated actions.                                         -->
   <extension point="org.eclipse.help.contributions">
    <infoset  name="infoset.xml"/>
   </extension>

   <extension point="org.eclipse.help.contributions">
     <topics  name="infosetTopics.xml"/>
     <actions name="infosetActions.xml"/>
   </extension>

   <!-- Configure the help contribution for this plugin -->
   <!-- This part should be in a documentation plugin -->
   <extension point="org.eclipse.help.contributions">
        <topics name="topics.xml"/>
        <actions name="topicsActions.xml" />
   </extension>
 
 

(在 infoset.xml 文件中)

<!-- Define the Infoset, and any views it has. -->
<infoset id="ex1InfosetId" label="%help_system_example">
      <infoview id="topicsView" label="%topics"/>
</infoset>


(在 infosetTopics.xml 文件中)

<!-- Now define a "container" topic that holds your general topics. This makes it -->
<!-- easier to quickly insert all these general topics under the view in the      -->
<!-- Infoset.                                                                     -->
<topics id="topLevelTopics">
  <topic id="concepts" label="%concepts"/>
  <topic id="tasks" label="%tasks"/>
  <topic id="references" label="%references"/>
  <topic id="samples" label="%samples"/>
</topics>


定义包含在以上一般主题中的主题:

(在 topics.xml 文件中)

<topics id="topics">
 <topic id="aConceptId" label="%introduction" href="concepts/concept.html"/>
 <topic id="aTaskId" label="%creating_a_project" href="tasks/task1.html">
  <topic id="aSubTaskId1" label="%creating_a_web_project" href="tasks/task2.html"/>
  <topic id="aSubTaskId2" label="%creating_a_java_project" href="tasks/task3.html"/>
 </topic>
 <topic id="aReferenceId" label="%interfaces" href="ref/ref1.html"/>
 <topic id="aSampleId" label="%help_system_sample" href="MissingFile.html"/>
</topics>


现在,定义创建文档层次结构所必需的插入操作:

(在 infosetActions.xml 文件中)

<actions infoview="org.eclipse.help.examples.ex1.topicsView">
 <insert from="org.eclipse.help.examples.ex1.topLevelTopics"
   to="org.eclipse.help.examples.ex1.topicsView" as="child"/>
</actions>
(在 topicsActions.xml 文件中)
<actions infoview="org.eclipse.help.examples.ex1.topicsView">
 <insert from="org.eclipse.help.examples.ex1.aConceptId"
   to="org.eclipse.help.examples.ex1.concepts" as="child"/>

 <insert from="org.eclipse.help.examples.ex1.aTaskId"
   to="org.eclipse.help.examples.ex1.tasks" as="child"/>

 <insert from="org.eclipse.help.examples.ex1.aReferenceId"
   to="org.eclipse.help.examples.ex1.references" as="child"/>

 <insert from="org.eclipse.help.examples.ex1.aSampleId"
   to="org.eclipse.help.examples.ex1.samples" as="child"/>
</actions>
 
 

以下是“Eclipse 工作台”中的结果文档层次结构


 

非集成组件

有时,插件会自行安装,而在其他情况下,它是作为较大型组件或产品的一部分来安装的。当它是一个自由浮动的插件时,应确保信息集是可视的。当将主题集成到较大的 web 中时,再显示单独的一本书可能没有任何意义。要支持此非集成的或松散集成的文档, 插件可定义一个信息集及相关联的操作,并将它们的 standalone 属性设置为 true。仅当从未在别的任何地方添加过那些主题时,这才会对插入操作有影响, 且仅显示信息集(如果它非空的话)。在提供“全部捕获”方案时对操作和信息集设置 standalone 属性是很有用的(此时不能将文档添加到大家都知道的信息集但插件文档还是应该出现在某处)。

外部化字符串

Plugin.xml 文件通过将字符串替换为键(如 %pluginName)以及在 plugin.properties 文件中创建下列格式的条目来外部化其字符串:
    pluginName = "Online Help Sample Plugin"
使用类似的方法来外部化添加项 XML 文件。 要外部化 <topic id="plainTasks" label="Plain Stuff">,将其标号替换为键 %plainStuff。主题将变为:
    <topic id="plainTasks" label="%plainStuff">
在包含下列条目的 doc.properties 文件中创建一个条目:
    plainStuff = Plain Stuff
当查找由联机帮助添加项外部化的字符串时,帮助系统将使用 doc.properties。
 

API 信息 使用此扩展点不需要任何代码。所需要的只是提供 在 plugin.xml 文件中提到的适当清单文件。
 

提供的实现:随 Eclipse 平台一起提供的帮助系统用户界面的可选缺省实现完全支持添加项扩展点。

Copyright IBM Corp. 2000, 2001.  All Rights Reserved.