注意:帮助系统仍在开发中,可能在获得稳定版本之前还会作些更改。在现阶段提供它的目的是为了获取早期使用者的反馈,因为我们知道添加机制的具体细节可能会断断续续地进行更改。 |
描述:用于为个别插件注册联机帮助添加项。
向帮助文件进行添加的每个插件一般应执行下列操作:
<!ELEMENT topics EMPTY>
<!ATTLIST topics name CDATA #REQUIRED>
<!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">(在 topicsActions.xml 文件中)
<insert from="org.eclipse.help.examples.ex1.topLevelTopics"
to="org.eclipse.help.examples.ex1.topicsView" as="child"/>
</actions>
<actions infoview="org.eclipse.help.examples.ex1.topicsView">以下是“Eclipse 工作台”中的结果文档层次结构
<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>
API 信息: 使用此扩展点不需要任何代码。所需要的只是提供
在 plugin.xml 文件中提到的适当清单文件。
提供的实现:随 Eclipse 平台一起提供的帮助系统用户界面的可选缺省实现完全支持添加项扩展点。