延伸點綱目編輯器

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

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

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

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

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

我們要執行下列作業:

  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" 參照,在內容表中變更 minOccurs 內容成為 0,變更 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" 影像套印格式。 這個小型指示器告訴您有問題的元素有一些相關的文字 - 這是檢查文件是否 有遺漏的快速方法。

完成文件之後,我們可以在 "doc" 資料夾中查看參考文件 parsers.html。 由登錄的 PDE 建立器建立它以反應延伸點綱目檔中的變更。 這個範例的結果文件外觀類似這個