附註:說明系統仍在開發中,應該還需要有些更動,才能夠進入穩定狀態。 在這個階段將它提供出來是為了取得先期使用者的意見,但使用者必須瞭解,提供機制的細節可能會有截然不同的更動。

構成要素

識別碼:org.eclipse.help.contributions

說明:用來登錄個別外掛程式的線上說明構成要素。

每個提供說明檔的外掛程式通常都應該執行下列動作:

contribution 延伸點的配置標記:

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

    <!ELEMENT actions EMPTY>
    <!ATTLIST actions name CDATA #REQUIRED>     <!ELEMENT infoset EMPTY>
    <!ATTLIST infoset name CDATA #REQUIRED> topic 的配置標記(這是放在 topic 處理檔的項目)

    <!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 的配置標記(這是放在 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 >

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

一般來說,需要提供線上說明的外掛程式通常會定義它自己的主題處理及將主題佈線到正確位置所需要的動作處理。 最後,說明系統會配置成當作某些動作來啟動,且可以利用資訊集的 ID 來執行這些動作。

外掛程式所能使用的 XML 元素有四個類型:主題、資訊集、動作及插入等元素。

主題元素

關於主題元素,所有主題都會作為主題儲存器元素的一部份來提供。 它們可以採用階層式結構,也可以列成單純的清單。 主題處理可視為資料來源,可供進一步將主題交錯和組織到含不同檢視畫面視景的整合 Web 中。 另外,主題也可以藉由指定其 ID 來加以處理,但您也可以指定包含主題群組的主題或主題元素之 ID 來處理一群主題。 稍後,在要檢視的主題或其它主題在佈線時,會維護主題處理中所定義的結構(遵循插入動作所進行的改變)。

主題元素是導覽結構的基礎。 主題元素有三個典型用法:

1.  避免提供文件檔的鏈結 - 通常是 HTML 檔。
2.  在相同或不同的處理中,作為其它主題的儲存器。
3.  在相同或不同的處理中,提供其它主題的插入點。

1. 作為鏈結的 topic
topic 最簡單的用法是作為文件檔的鏈結。

<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
topic 第二常用的用途是作為其它主題的儲存器。儲存器主題本身也永遠可以指向特定檔案。

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

3. 作為插入點的 topic
topic 可以作為插入點來使用。它們會提供一個邏輯位置,供其它 topic 來嘗試及合併。如果要作為插入點,topic 必須有 id 屬性。
 
 

infoset 元素

資訊集元素是文件 Web 的進入點。它可算是檢視畫面的集成。

檢視畫面用來進行文件 Web 的高層次語意分組。它們是用資訊集所定義的 infoview 元素來定義的。 文件團隊可以利用檢視畫面來產生入門、作業和參照區段(或產品團隊所定義的其它檢視畫面)。 平台不會指定實際的區段,只會指定定義它們的機制。

比方說,可能會有一個定義的「作業檢視畫面」是「如何執行某些動作」視景中的所有主題的合併。 另外還可以定義一個「元件檢視畫面」來作為顯示所有元件及其文件的主題樹。

infoview 元素代表可跨越不同外掛程式來「共用」之主題的儲存器。它是整份文件的視景。 有時會有些不同的外掛程式提供到相同的邏輯文件元件。這個元素可確保在「元件檢視」期間,它們能正確合併到一致的檢視畫面中。

actions 元素

動作處理含有要在主題和檢視畫面上執行的 Scripting 動作。 目前只有一種插入動作,它用來將主題和檢視畫面一起寫到含多個檢視畫面的整合資訊 Web 中。

動作是結構化的動作(插入),因而適用於某些資訊檢視畫面。 因此,處理中的所有插入動作都會在單一資訊檢視畫面中建置主題階層。

insert 元素

元件化導覽最複雜的部份之一,就是如何以導覽的連續流程來建立整合的資訊結構。 如果要執行這個動作,我們需要有發佈插入點的機制,選取要使用哪個插入點,以及指出要在哪裡插入主題(母項、子項、之前、之後)。

插入點可以是主題或檢視畫面。主題藉由提供 ID 來指出它要成為插入點。 檢視畫面必須有 ID。只有完整的 ID 才能作為參照。 比方說,org.eclipse.help.examples.ex1 外掛程式中 <topic id="concepts" label="concepts">  主題的完整主體 ID 是 org.eclipse.help.examples.ex1.concepts。

由於插入點通常是在其它外掛程式中,且這些外掛程式無法安裝,因此,使用者可以指定替代的插入點。 依預設,如果沒有任何選項順利完成的話,主題會停在它的元件階層之下。 "to" 屬性指定目標插入點。 "from" 屬性所指定的主題是插入的主題。以下是插入主題的可能方式,它們是利用 as 屬性來指定的:

目前,主題只能在資訊檢視畫面中插入一次;不過,它可以插入多個資訊檢視畫面中。 這表示如果母項主題及其子樹插入資訊集中,不會有任何它的子項可以重新插入相同的資訊檢視畫面中。 基本上,插入會建立特定資訊檢視畫面的不可分割的分割區。

這時會提供替代的插入點,且會在上一個無法執行時執行它。 插入元素的巢狀插入子元素提供了這些替代項。 這可以視是插入動作失敗時的「後退」機制,這時會執行巢狀插入動作。 滿足第一個選項插入點之後,會忽略另一個替代的插入點。
 

範例:

以下是使用 contributions 延伸點的範例 : 假設下列項目適用於 ID 為 "org.eclipse.help.examples.ex1" 的外掛程式。 (這個範例要作為一般範例,且應該記住,從下列中所有提供檔案產生的相同文件階層也可以利用主題和動作檔案的各種組合來建立。)

(在 plugin.xml 檔中)
 

   <!-- 利用說明系統構成要素延伸點來定義資訊集、-->
   <!-- 主題以及動作提供檔。為了清晰而使用兩次 -->
   <!-- 延伸點,一次定義資訊集及其檢視畫面,另 -->
   <!-- 一次定義主題及其相關動作。 -->
   <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>

   <!-- 配置這個外掛程式的說明構成要素 -->
   <!-- 這部份應該在文件外掛程式中 -->
   <extension point="org.eclipse.help.contributions">
        <topics name="topics.xml"/>
        <actions name="topicsActions.xml" />
   </extension>
 
 

(在 infoset.xml 檔中)

<!-- 定義 Infoset 及它所擁有的任何檢視畫面。-->
<infoset id="ex1InfosetId" label="%help_system_example">
      <infoview id="topicsView" label="%topics"/>
</infoset>


(在 infosetTopics.xml 檔中)

<!-- 現在,定義保留一般主題的「儲存器」主題。如此 -->
<!-- 能夠將所有這些一般主題快速插入資訊集中的 -->
<!-- 檢視畫面之下。 -->
<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 平台所提供的說明系統 UI 之預設實作能充分支援 contributions 延伸點。

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