簡介內容檔 XML 格式

3.1.0 版

這份文件用一系列的 DTD 片段來說明簡介內容檔的結構。

introContent


<!ELEMENT introContent (page+ , group* , extensionContent*)>

introContent 元素定義簡介內容檔的主體。 內容檔包含頁面、可併入多個頁面的共用群組,以及其他配置中所定義之定錨點的延伸規格。



page


<!ELEMENT page (group* | link* | text* | head* | img* | include* | html* | title? | 錨點* | contentProvider*)>

<!ATTLIST page

url          CDATA #IMPLIED

id           CDATA #REQUIRED

style        CDATA #IMPLIED

alt-style    CDATA #IMPLIED

filteredFrom (swt|html)

content      CDATA #IMPLIED

style-id     CDATA #IMPLIED>

這個元素用來說明要顯示的頁面。 簡介可以顯示動態和靜態頁面。

動態頁面的內容是從頁面的子元素產生,如下所述。 style 或 alt-style 會依呈現方式而套用。 參照 id 或 class-id 可以進一步加強樣式。

靜態頁面可讓您重複使用簡介中現有的 HTML 文件,且可以從任何其他靜態或動態頁面鏈結到它。 靜態頁面不定義在 page 元素中,它們只是其他頁面所能鏈結的 HTML 檔。

在簡介配置延伸點的呈現元素中指定了 ID 的首頁,可以有一個指示它是靜態頁面的 URL。 如果沒有指定任何 URL,就會假設首頁是動態的。 所有利用 page 元素來說明的其他頁面都是動態的。
另外,請注意在使用 SWT 呈現時,如果要顯示靜態頁面,就會啟動一個外部瀏覽器,而現行頁面仍會維持可見狀態。

動態頁面中所用的子元素如下:group 子元素用來分組相關內容,以及在分組內容中套用樣式。 link 子元素用來定義鏈結,以便鏈結到某個靜態或動態頁面以及執行簡介動作/指令。 鏈結通常定義在頁面層次,以在各主要頁面之間導覽,而不是在頁面各鏈結之間導覽。 text 子元素用來定義頁面層次的文字內容。head 子元素只適用於 Web 型呈現,可在 HTML head 區段中加入其他 html。 在加入 Java Script 或額外的樣式表時,這非常有用。img 子元素用來定義頁面層次的影像內容。include 子元素可供重複使用頁面外的任何元素。html 子元素只適用於 Web 型呈現,可供在頁面內容中內嵌或併入 html。 內嵌可在 HTML object 內,藉由參照 html 檔來內嵌定義完整的 html 檔。 併入可直接從 HTML 檔併入 HTML 片段。 title 子元素用來定義頁面的標題。 anchor 子元素定義一個點,供 <extensionContent> 元素從外部提供內容。


group


<!ELEMENT group (group* | link* | text* | img* | include* | html* | anchor*)>

<!ATTLIST group

id           CDATA #REQUIRED

label        CDATA #IMPLIED

style-id     CDATA #IMPLIED

filteredFrom (swt|html) >

用來分組相關內容、應該已套用類似樣式的內容,或將一起併入其他頁面的內容。


link


<!ELEMENT link (text? , img?)>

<!ATTLIST link

id           CDATA #IMPLIED

label        CDATA #IMPLIED

url          CDATA #REQUIRED

style-id     CDATA #IMPLIED

filteredFrom (swt|html) >

可以鏈結到靜態 HTML 檔、外部網站,也能夠執行簡介 URL 動作。




預先定義的動作將利用這個格式來說明:

action name - 動作說明
action parameter1 - 參數說明
action parameter2(選用) - 參數說明
action parameter3 (optional) = ("true" | "false") "false" - 參數的說明,選項為 true 或 false,"false" 是預設值


以下是併入簡介組織架構的預先定義的動作:

close - 關閉簡介部分
沒有必要的參數

navigate - 依給定方向來導覽簡介頁面,或返回首頁
direction = ("backward" | "forward" | "home") - 指定要導覽的方向

openBrowser - 在外部瀏覽器中開啟 URL。自 3.1 後,這個動作取決於工作台「瀏覽器」支援。 這表示為瀏覽器設定的任何使用者喜好設定都會被接受。
url - 指向外部網站或靜態 HTML 檔的有效 URL
pluginId (optional) - 只有在指定了靜態 HTML 檔時,才需要。這是包含檔案之外掛程式的 ID。

openURL - 開啟在「歡迎使用」頁面中內嵌的 URL。如果是 SWT 呈現,則 URL 會顯示在外部瀏覽器中(與上面的 openBrowser 動作類似)。 自 3.1 後
url - 連接至外部網站或本端 HTML 檔案的有效 URL
pluginId (optional) - 如果該 URL 是相對的,則這表示包含該檔案的外掛程式 ID。

runAction - 執行指定的動作
class - 實作 org.eclipse.ui.intro.config.IIntroActionorg.eclipse.jface.action.IActionorg.eclipse.ui.IActionDelegate 之一的類別的完整名稱
pluginId - 包含類別的外掛程式 ID。
standby(選用)= ("true" | "false") "false" - 指示在執行動作之後,是否要將簡介設成待機模式
其他參數 - 任何其他參數都會傳給實作 org.eclipse.ui.intro.config.IIntroAction 的動作

setStandbyMode - 設定簡介部分的狀態。
standby = ("true" | "false") - true 會使簡介部分處於局部可見的待命模式,而 false 則是完全可見

showHelp - 開啟說明系統。
沒有必要的參數

showHelpTopic - 開啟說明主題。
id - 說明資源的 URL。(請參閱 org.eclipse.ui.help.WorkbenchHelp.displayHelpResource 的 Javadoc)
embed (選用)= ("true" | "false") "true" - 指出要將說明資源當作歡迎使用頁面的內嵌畫面來顯示。預設值是 false。 在 SWT 呈現中,會忽略這個旗標。自 3.1 後
embedTarget (optional) - div 的路徑,其位於具有「說明」主題之內容的現行「歡迎使用」頁面中。若指定此值,則 embed 依預設為 true,且內嵌的 URL 會插入具有指定路徑的 div。 該路徑相對於該頁面,所以不應以頁面 ID 開頭。div 的子項會由 URL 的內容所取代。每一個頁面只能使用一個 div 作為內嵌目標。在 SWT 呈現中,會忽略這個旗標。使用 XHTML 作為簡介內容時,也不受支援此旗標。 自 3.1 後


showMessage - 使用標準資訊對話框的顯示訊息給使用者。
message - 顯示給使用者的訊息

showStandby - 將簡介部分設成待機模式,並以給定輸入來顯示 standbyContentPart
partId - 要顯示 standbyContentPart 的 ID
input - 設定在 standbyContentPart 中的輸入

showPage - 顯示含給定 ID 的簡介頁面
id - 要顯示的簡介頁面的 ID
standby(選用)= ("true" | "false") "false" - 指示在顯示頁面之後,是否要將簡介設成待機模式

如果傳送到這些動作的任何參數具有特殊字元(即在 URL 中為不合法的字元),則必須使用 big5 URL 編碼方式來編碼。 如果要在將狀態解碼為特殊參數的地方接收這些參數,您可以在「簡介」組織架構處理這些參數時,使用 decode = ("true" "false") 來強制解碼這些參數。
例如,以下簡介 URL:
http://org.eclipse.ui.intro/showMessage?message=This+is+a+message
會將訊息參數當作 "This+is+a+message" 處理,

http://org.eclipse.ui.intro/showMessage?message=This+is+a+message&amp;decode=true
會將訊息參數當作 "This is a message" 處理。


  • style-id - 將這個鏈結分類到某個給定種類的方法,以便套用共用樣式。
  • filteredFrom - 可用來過濾特定實作中之給定元素的選用屬性。 比方說,如果群組 filteredFrom = swt,就表示這個群組不會表現為 swt 實作中的內容。
  • html


    <!ELEMENT html (img | text)>

    <!ATTLIST html

    id           CDATA #REQUIRED

    src          CDATA #REQUIRED

    type         (inline|embed)

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    encoding     CDATA #IMPLIED

    內嵌整份文件或就地列入 HTML 片段來引導 HTML 併入頁面中。 Fallback 影像或文字必須定義給替代的 swt 呈現。
    內嵌可將完整定義的 HTML 檔內嵌在動態頁面的內容中。 將建立一個 HTML object 元素來參照這個 HTML 檔。
    併入可直接從檔案中將 HTML 片段併入動態 HTML 頁面中。


    title


    <!ELEMENT title EMPTY>

    <!ATTLIST title

    id           CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    文字片段可以選用地包含跳出的 HTML 標示。 它只用來作為頁面標題,因此,給定的頁面最多可有一個 title 元素。


    text


    <!ELEMENT text EMPTY>

    <!ATTLIST text

    id           CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    文字片段可以選用地包含跳出的 HTML 標示。 它可以包括 b 和 li 標示。 它也可以包含 URL 的錨點。 如果需要多個段落,則文字可以分成多個區段,每一個區段都是以 p 標示來開始和結束。


    include


    <!ELEMENT include EMPTY>

    <!ATTLIST include

    configId    CDATA #IMPLIED

    path        CDATA #REQUIRED

    merge-style (true | false) >

    展開給定路徑和選用 configId 屬性所鎖定的元素。 路徑應該能夠唯一定址在指定配置內的元素。 它可以指向配置層次所定義的共用群組,或頁面中的任何元素。


    head


    <!ELEMENT head EMPTY>

    <!ATTLIST head

    src CDATA #REQUIRED>

    encoding     CDATA #IMPLIED

    引導 HTML 併入頁面 的 HEAD 內容區中。 它可在 HTML HEAD 區段中加入其他 html。 在新增 Java Script 或額外的樣式表時,這非常有用。這個標記只用來搭配 HTML 型簡介部分實作。 在 UI 表單實作中,會忽略它。 一個頁面可以有多個 head 元素。 實作只能有正好一個 head 元素(因為所有頁面都會共用它)。


    img


    <!ELEMENT img EMPTY>

    <!ATTLIST img

    id           CDATA #REQUIRED

    src          CDATA #REQUIRED

    alt          CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    代表簡介內容且不含呈現方式的影像(有別於樣式中所定義的裝飾影像)。


    extensionContent


    <!ELEMENT extensionContent (text | group | link | html | include)>

    <!ATTLIST extensionContent

    style     CDATA #IMPLIED

    alt-style CDATA #IMPLIED

    path      CDATA #REQUIRED>

    要加到目標錨點中的內容。 在給定的 configExtension 中,只能有一個 extensionContent, 因為如果無法解析這個延伸規格(若找不到配置,或找不到目標錨點元素), 就必須忽略延伸規格中的頁面及(或)群組。


    anchor


    <!ELEMENT anchor EMPTY>

    <!ATTLIST anchor

    id CDATA #REQUIRED>

    錨點是用來宣告延伸的元素。 它是配置中用來接受外部構成要素的一個位置。 在 extensionContent 中的 path 屬性,只有錨點是有效的目標值


    contentProvider

     

    <!ELEMENT contentProvider (text)>

    <!ATTLIST contentProvider

    id       CDATA #REQUIRED

    pluginId CDATA #IMPLIED

    class    CDATA #REQUIRED>

     

    這是簡介內容提供者的 Proxy, 它能讓簡介頁面以動態方式從各種來源取得資料(例如,Web、eclipse 等), 並且在執行時期根據這個動態資料來提供內容。如果無法載入類別屬性中指定的 IIntroContentProvider 類別, 就會改為呈現文字元素的內容。這是 HTML 簡介標示的動態版本。HTML 標示可容許將靜態 HTML 內容內嵌或列入到產生的 HTML 簡介頁面中, 而 contentProvider 標示可容許在執行時期以動態方式建立該內容。標示之間的另一個差異在於只有 HTML 呈現才支援 HTML 標示, 而這個 contentProvider 標示在 HTML 呈現和 SWT 呈現中都可以支援。這是從 3.0.1 開始