延伸點綱目編輯器

您可以使用兩種方法開啟延伸點綱目編輯器:依產品建立新延伸點或開啟現存的 延伸點綱目。依慣例,新綱目的名稱與含有 .exsd 副檔名的延伸點 ID 同名。 它們存放在外掛程式目錄樹中的 schema 目錄。

在 PDE 建立新延伸點時,也會建立起始綱目檔而且會開啟綱目編輯器供您編輯。 您可以立即定義綱目或關閉它,等以後再定義它。 製作完整延伸點綱目可讓 PDE 對延伸點的使用者提供自動協助。

PDE 綱目編輯器依據與外掛程式 Manifest 編輯器相同的概念。它有兩個套表 頁面和一個來源頁面。因為 XML 綱目是贅述而且它的來源形式很難令人 讀懂,所以您應該使用套表頁面執行大部份編輯。對於閱讀結果原始碼來說,來源頁面很有用。

範例:建立「範例剖析器」延伸點的綱目

我們先前已建立「範例剖析器」延伸點和起始綱目。 現在可以移至專案的 schema 資料夾並按兩下 parsers.exsd 檔案來 開啟綱目。這樣會開啟綱目編輯器。

我們要執行下列作業:

  1. 定義延伸點的有效 XML 元素和屬性。
  2. 定義文法(內容模型)。
  3. 提供會合併到參考文件的文件片段。

每一個延伸點綱目以「宣告」元素的宣告為開頭。我們會新增 名稱是「parser 的新 XML 元素」。

  1. 延伸點元素區段中按下新元素按鈕。
  2. 移到「內容」檢視畫面並將它的名稱從 "New_Element" 變更為 "parser"
  3. 仍選取新元素時,按新屬性按鈕。 這樣會建立 "new_attribute" 作為它的子項。 在內容表變更它的名稱成為 "id" 以及變更 use 成為 "required"。
  4. 仍在內容表時,按本端工具列上的「複製這個屬性」按鈕。 這樣會建立屬性的副本。這個動作很有用,因為可讓我們快速定義所有屬性 而不必離開內容表。
  5. 變更新屬性的名稱成為 "name"。
  6. 重新複製屬性。這一次變更名稱成為 "class"。會使用這 個屬性代表必須實作特定 Java 介面的 Java 類別的完整名稱。 我們需要指定這個名稱,這樣 PDE 以後才能使用它。 將種類從 "string" 變更成 "java"。對 com.example.xyz.IParser 設定 basedOn 內容。(這個介面 尚不存在,但我們以後會讓它存在)。

目前為止,綱目編輯器應如下:

延伸點綱目編輯器 - 定義頁面

現在我們要新增另一個屬性,該屬性從離散的選項清單選取值。這表示我們需要建立基礎 string 類型的列舉限制。另外,我們會設定屬性的預設值。

  1. 選取「剖析器」元素時,請按新屬性按鈕。 在內容表變更它的名稱成為 "mode"。
  2. 按一下「限制」內容的值資料格以顯示限制對話框。
  3. 將限制類型從「無」變更成「列舉」。
  4. 新增下列三個選項:"never"、 "always" 和 "manual"。(這些是剖析器延伸的三個 假設模式。)

限制對話框應如下:

類型限制對話框

關閉對話框時,變更 "use" 屬性成為 "default",變更 "value" 屬性成為 "always "。這樣會建立預設值。請注意:當您鍵入此值時狀態行會顯示 錯誤訊息,因為它限制有效值為三個列舉選項。 結束鍵入之後,錯誤訊息會消失,因為 "always" 是有效值。

現在我們已定義所有元素和屬性,接下來我們需要定義文法。 我們的目標是定義 "extension" 元素可以有任何數目的 "parser" 元素作為子項。

  1. 選取 "extension" 元素。它的起始內容模型顯示空的序列組合字元。
  2. 選取序列組合字元,然後從蹦現功能表選取新建->參照->剖析器。這樣會新增剖析器參照到序列組合字元。
  3. 參照的預設基礎項目是 [1,1],這表示只能有一個 "parser" 元素。但這不是我們想要的情況。我們選取 "parser" 參照並變更 maxOccurs 為 "unbounded"。

定義文法之後,文法區段下面的 DTD 近似值說明在 DTD 中選取的 元素的文法會呈現什麼外觀。提供這個資訊來協助比較偏好使用 DTD 而不是 XML 綱目的開發人員。

延伸點綱目編輯器 - 元素文法

現在我們已定義有效元素、屬性和文法,我們需要提供關於延伸點 的部份資訊。 有兩種綱目文件片段類型:

綱目處理的「定義」頁面提供第一個片段類型。 選取元素和屬性時,您可以在「說明」區段新增關於它們的短提示文。 預期的格式是原始 HTML(Javadoc 也相同)而且會如實複製文字到最終參考文件。

  1. 選取 "parser" 元素的 "id" 屬性,然 後在「說明」編輯器鍵入下列文字:
    會用來參照這個剖析器的唯一名稱。
  2. 選取 "name" 屬性並新增下列文字:
    會在 UI 中用來代表這個剖析器的可轉換的名稱。
  3. 選取 "class" 屬性並新增下列文字(請注意 HTML 標示):
    實作 <samp>com.example.xyz.IParser</samp> 介面的 Java 類別完整名稱。
  4. 選取 "mode" 屬性並新增下列文字:
    一個選用性旗標,它指出執行這個剖析器實例的頻率(預設值是 <samp>always</samp>)。

現在我們必須提供延伸點本身的短提示文說明。 為了提供該說明,我們切換至「文件」頁面:

  1. 從文字編輯器上面的組合框選取「總覽」並新增下列文字:
    使用這個延伸點插入其他剖析器。 實際上剖析器並沒有作用 - 我們只是使用它們作為延伸點綱目範例。
    套用
  2. 從組合框選取「範例」並新增下列文字:
       下列是延伸點用法的範例:   <p>
       <pre>
          <extension point="com.example.xyz.parsers">
          <parser
             id="com.example.xyz.parser1"
             name="Sample Parser 1"
             class="com.example.xyz.SampleParser1">
          </parser>
          </extension>
       </pre>
       </p>
    

    套用

  3. 選取「API 資訊」並新增下列文字:
    需要延伸這個延伸點的外掛程式必須實作 <samp>com.example.xyz.IParser</samp> 介面。
    套用
  4. 選取「提供的實作」並新增下列文字:
    「XYZ 外掛程式」提供剖析器的預設實作。
    套用
附註:提供範例時必須採取特殊考量。 通常 PDE 會將提供的文字視為原始 HTML 而且將換行和空格只當作一個字元(例如 ,可忽略的空格)。 以一般文字來說我們期望這種情形,但是當提供範例時則非常令人困擾,因為範例外 觀要求美觀,所以跳欄和垂直對齊就很重要。 PDE 有這個狀況的折衷方案:如果它偵測到 HTML 標示 <pre>,那麼它會依現 狀使用內容(保留全部字元而不修改)直到看到關閉標示 </pre> 為止。 這就是為什麼我們能提供類似上述的範例,而且有信心它在最終參考文件中會有很美 的外觀。

當您鍵入文件時您可能已注意到編輯器「概要」檢視畫面中有愈來愈多元素獲得 "pen" 影像套印格式。 這個小型指示器告訴您有問題的元素有一些相關的文字 - 這是檢查文件是否 有遺漏的快速方法。

延伸點綱目編輯器概要

完成文件之後,我們就可以查看參考文件。做法有兩種。在您工作期間, 您可以從蹦現功能表選取「預覽參考文件」項目,來預覽參考文件。 另外,您可以設定 PDE 喜好設定(喜好設定>外掛程式開發>編譯器,位在「綱目」標籤之下), 來自動根據每一個綱目檔變更,建立參考文件。 不管建立它的方法為何,這個範例的結果文件看起來像這樣

 
Copyright IBM Corporation and others 2000, 2003