簡介支援

簡介支援是一組延伸點和工作台部分, 可讓外掛程式定義專用網頁,為新使用者介紹平台產品。 簡介資訊通常是在產品第一次啟動時顯示。 雖然個別的外掛程式可以提供簡介資訊給已知的產品簡介配置,但是簡介支援一般是在產品層次配置。

從工作台的觀點看來,簡介支援的根目錄是在簡介部分。 這個部分是在延伸定義中指定。 當工作台起始設定時,它會建立一個簡介網站,保留空間給簡介網頁使用。 網站的簡介部分實作,是由產品配置資訊所決定。 當簡介部分顯示時,可以在兩個模式之間切換:

簡介部分建立之後,必須以簡介資訊加以配置。 其方法是利用簡介配置,而簡介配置也是利用延伸而提供。 您可以利用個別外掛程式自己的延伸,把個別的外掛程式加到基本產品簡介配置中。

接下來讓我們看看一個平台 SDK 簡介網頁的範例,藉此瞭解這些概念。

定義簡介部分

您可以利用由 IIntroPart 介面和 org.eclipse.ui.intro 延伸點所組成的通用機制, 為產品建立自己的簡介支援。 這個延伸的主要目的, 是定義實作 IIntroPart 的類別, 並且指定產品 ID 和簡介部分之間的連結。 比方說,下面這個構成要素,就是定義工作台在啟動時所顯示的假設簡介部分:


<extension
	point="org.eclipse.ui.intro">
	<intro
		class="com.example.SampleIntroPart"
		id="someId">
		icon="someIcon.gif"
	</intro>
	<introProductBinding
		introId="someId"
		productId="com.example.someProductId">
	</introProductBinding>
</extension>
這個構成要素會先定義簡介部分,將 "someId" 這個 ID 指派給它。 然後再將這個簡介部分連結到 ID 為 "com.example.someProductId" 的產品。 在平台啟動時,class 屬性所指定的類別,將由工作台建立實例, 並且以產品簡介的形式,出現在使用者面前。 這是與 IIntroPart 介面最低層的整合作業。

該平台會提供自己的 IIntroPart 實作(稱為 CustomizableIntroPart), 讓使用者自訂簡介的內容和呈現方式。 下面就是定義工作台簡介部分的片段。 我們將把重點放在簡介內容的定義上,至於實作簡介部分的機制就略過不提。 (如果需要其他詳細資料,請參閱前面參照的延伸點文件和 Javadoc)。


<extension
	point="org.eclipse.ui.intro">
	<intro
		class="org.eclipse.ui.intro.config.CustomizableIntroPart"
		id="org.eclipse.platform.intro">
	</intro>
	<introProductBinding
		introId="org.eclipse.platform.intro"
		productId="org.eclipse.platform">
	</introProductBinding>
</extension>
上面的構成要素主要在定義 Eclipse SDK 平台所用的簡介部分 -- CustomizableIntroPart。 剩下的內容則說明如何使用和延伸這個部分。

使用 CustomizableIntroPart

該平台的 CustomizableIntroPart 可讓您利用 org.eclipse.ui.intro.config 延伸點, 來自訂簡介的內容和呈現方式。 (您可以利用 org.eclipse.ui.intro.configExtension 延伸點,來延伸這個簡介配置)。 這個結構可讓產品外掛程式開發人員專心開發他們的簡介內容,而不必從頭實作簡介部分架構。 不過如果您所指定的簡介類別不同,就不會使用這兩個延伸點,指定的類別必須針對簡介內容格式和配置,實作它自己的架構。

定義簡介配置

org.eclipse.ui.intro.config 主要在說明簡介配置的 ID(該配置可以顯示我們的內容),以及 XML 檔的名稱(該檔含有簡介內容專用的定義)。 一個給定的 CustomizableIntroPart 應該只定義一個專有的簡介配置。(只有第一個找到的簡介配置,才能顯示在 CustomizableIntroPart)。


<extension
	id="intro"
	point="org.eclipse.ui.intro.config">
	<config
		introId="org.eclipse.platform.intro"
		id="org.eclipse.platform.introConfig"
		content="$nl$/introContent.xml">
	<presentation
		home-page-id="root" standby-page-id="standby">
			<implementation
 				ws="win32"
				style="css/shared.css"
				kind="html"
				os="win32">
			</implementation>
			<implementation
				kind="swt">
			</implementation>
	</presentation>
	</config>
</extension>
該檔的路徑,是相對於外掛程式目錄的路徑。 (請注意目錄名稱中所用的 $nl$ 變數 ,表示該檔將位於目標環境的國家語言專用目錄下)。

配置延伸可讓您指定內容以及內容的呈現方式。content 元素的重點是定義網頁,presentation 元素則是說明與呈現方式相關的屬性,說明如何顯示網頁。 簡介首頁的網頁 ID(完整模式)是一定要指定的,而待命網頁 ID(待命模式)則是選用的。 首頁是在產品第一次啟動時所出現的頁面。 呈現方式可以指定一或多個顯示網頁的實作方式。 每一個平台和視窗化系統都會指定實作,讓您利用平台專屬的特性來顯示網頁內容。 比方說,視窗平台具有強大的 HTML 瀏覽器小組件,因此簡介內容是採用 HTML 型的實作。 其他不具這項功能的平台,則是使用 SWT 型的實作,將網頁說明對映到 SWT 型格式。 沒有指定視窗化系統或作業系統的實作,則被視為通用實作; 如果要確保簡介能夠顯示在所有的平台上,一定要定義這類實作。 工作台會先察看實作,找出與目前作業系統和視窗化系統相符的實作。 如果找不到相符的實作,就選擇通用實作。 大部分這類詳細資料,都是在產品配置層次處理,因此這裡不再詳加討論。

定義簡介內容

現在我們可以看看內容本身了。 內容是以網頁層面加以說明。 所有的網頁都有一個 id 屬性。 這是在定義首頁和待命頁以及其他用到網頁參照之處所使用的 ID。 否則的話,相關屬性會根據所定義的網頁種類而定。 網頁有下列兩種基本類型:

要瞭解內容定義格式的最佳方式,就是瀏覽 SDK 中的實作。 下面這個片段只示範 SDK 根網頁內容的第一個部分,這也是第一個顯示的簡介網頁。


<introContent>
  <page alt-style="css/root_swt.properties" style="css/root.css" id="root" style-id="page">
    <title style-id="intro-header">Welcome to Eclipse Platform 3.0</title>
    <group id="links-background">
      <group id="page-links">
        <link label="Overview" url="http://org.eclipse.ui.intro/showPage?id=overview" id="overview" style-id="left">
          <text>Find out what Eclipse is all about</text>
        </link>
        <link label="Tutorials" url="http://org.eclipse.ui.intro/showPage?id=tutorials" id="tutorials" style-id="left">
          <text>Let us guide you through Eclipse end-to-end tutorials</text>
        </link>
        <link label="Samples" url="http://org.eclipse.ui.intro/showPage?id=samples" id="samples" style-id="right">
          <text>Explore Eclipse development through code samples</text>
        </link>
        <link label="Whats New" url="http://org.eclipse.ui.intro/showPage?id=news" id="news" style-id="right">
          <text>Find out what is new in this release</text>
        </link>
      </group>
    </group>

網頁上的元素也可以是 filteredFrom,這是一種特殊的實作。 它可以讓網頁設計人員,以心目中的特殊平台來設計。 其他還有許多強大的屬性,可以用來說明網頁及其內容。 如果需要有效元素、子元素及其屬性的完整參照,請參閱 org.eclipse.ui.intro.config 及其相關簡介內容檔案格式規格的延伸點文件。

延伸簡介配置

簡介配置可以用下列三種方式加以延伸:

延伸簡介配置的內容

外掛程式可以把簡介內容提供給在其他地方定義的網頁。 不過,負責定義的網頁必須定義一個 anchor 屬性,作為新內容的位置保留區。 SDK 概觀網頁定義了兩個錨點,讓您在概觀網頁加入 JDT 和 PDE 相關元素。

    
<group id="page-content">
	<text style-id="page-title" id="page-title">OVERVIEW</text>
	<text style-id="page-description" id="page-description">Eclipse is a kind of universal tool platform - an open extensible IDE for anything and nothing in particular. It provides a feature-rich development environment that allows the developer to efficiently create tools that integrate seamlessly into the Eclipse Platform.</text>
	<group id="overview-links">
		<link label="Workbench basics" url="http://org.eclipse.ui.intro/showHelpTopic?id=/org.eclipse.platform.doc.user/concepts/concepts-2.htm" id="basics">
			<text>Learn about basic Eclipse workbench concepts</text>
        </link>
        <link label="Team support" url="http://org.eclipse.ui.intro/showHelpTopic?id=/org.eclipse.platform.doc.user/concepts/concepts-26.htm" id="team">
			<text>Find out how to collaborate with other developers</text>
        </link>
		<anchor id="jdtAnchor"/>
		<anchor id="pdeAnchor"/>
	</group>
</group>
這些錨點可以提供給把內容加到網頁上的外掛程式,讓它們參照。 內容是利用 org.eclipse.ui.intro.configExtension 延伸所加入。 除了延伸網頁內容之外,這個延伸點還可以讓您提供待命內容部分和自訂動作。

如果要延伸現有的簡介配置,可以使用 configExtension 元素。 您可以在這個元素中,指定所要延伸之簡介配置的 configId, 以及負責說明新內容的 content 檔。

 
<extension
	point="org.eclipse.ui.intro.configExtension">
	<configExtension
		configId="org.eclipse.platform.introConfig"
		content="$nl$/overviewExtensionContent.xml"/>
    ...
</extension>
內容檔的格式,與簡介配置內容的格式很類似, 只是它必須含有 extensionContent 元素,而該元素負責定義通往要插入延伸內容的錨點路徑。
 
<introContent>
	<extensionContent alt-style="css/swt.properties" style="css/overview.css" path="overview/page-content/overview-links/jdtAnchor">
		<link label="Java development" url="http://org.eclipse.ui.intro/showHelpTopic?id=/org.eclipse.jdt.doc.user/gettingStarted/qs-BasicTutorial.htm" id="java">
			<text>Get familiar with developing Java programs using Eclipse</text>
		</link>
	</extensionContent>
</introContent>
當您把自訂內容提供給簡介預先定義的定錨點之後, 產品便可以利用前面說明的 org.eclipse.ui.intro,將它本身連結到該簡介。 當產品執行時,被延伸的簡介會連同其他內容一起顯示。 此舉可讓產品具有自己的品牌行銷,以及其他產品特有的資訊, 讓該產品在使用自己的主要內容時,得以重複使用密切相關的產品簡介。

簡介也可以選擇性地加入一些相關產品的簡介。 在本案例中,產品可以定義它自己的簡介和簡介配置, 然後利用內容檔中的 include,參照在另一個簡介配置中定義的重要元素。 如果要在產品最上層建置另一個相關產品, 而且必須對使用者介紹較高層次產品的重要概念時,不妨使用這項機制。

提供待命內容部分

當簡介網頁處於待命模式時,外掛程式也可以實作一個部分來顯示替代內容。 舉例來說,平台會定義一個待命部分,顯示相關簡介內容的提要。 這個部分是利用與專用 URL 的網頁鏈結來啟動。 待命部分則是利用含有顯示待命部分之特殊指令的 URL 來啟動, 例如 http://org.eclipse.ui.intro/showStandby?partId=somePartId。 這個部分是在 org.eclipse.ui.intro.configExtension 延伸的 standbyContentPart 子元素中定義。 您必須為這個部分指定 idpluginIdclass。 該類別必須實作 IStandbyContentPart。 下述片段所示範的是,平台如何定義待命部分來顯示提要。

 
<extension point="org.eclipse.ui.intro.configExtension">
	<standbyContentPart
		id="org.eclipse.platform.cheatsheet"
		class="org.eclipse.platform.internal.CheatSheetStandbyContent"
		pluginId="org.eclipse.platform"/>
</extension> 
本提要可以利用 URL 為 http://org.eclipse.ui.intro/showStandby?partId=org.eclipse.platform.cheatsheet&input=org.eclipse.pde.helloworldlink 子元素,從簡介網頁啟動。 這個 IntroURL 會啟動 org.eclipse.platform.cheatsheet 待命內容部分,並且將其輸入設為 "org.eclipse.pde.helloworld"。 不過,有關實作待命部分的詳細機制,就不在本文的討論範圍內了。 如果需要詳細資訊,請參閱 IStandbyContentPart 及其相關類別。

定義自訂 IntroURL 動作

外掛程式可以使用 org.eclipse.ui.intro.configExtension 延伸點, 提供它自己的自訂動作,而這些自訂動作可以作為網頁中鏈結元素的 url 值使用。 舉例來說,讓我們看看下面這個鏈結:

http://org.eclipse.ui.intro/runAction?pluginId=org.eclipse.pde.ui&class=org.eclipse.pde.ui.internal.samples.ShowSampleAction&id=org.eclipse.sdk.samples.swt.examples

這個 IntroURL 會執行一個名叫 ShowSampleAction 的動作類別, 而這個動作類別是位於外掛程式 "org.eclipse.pde.ui" 的套件 "org.eclipse.pde.ui.internal.samples" 中。 這裡所要執行之範例的 ID 是 "org.eclipse.sdk.samples.swt.examples"。

如果要定義這個簡介 URL 的自訂版本,可以使用下列標記:

 
<extension point="org.eclipse.ui.intro.configExtension">
	<action
		name="myCommand"
		replaces="runAction?pluginID=org.eclipse.pde.ui&class=org.eclipse.pde.ui.internal.samples.ShowSampleAction">
	</action>
</extension>
有了上述延伸,就可以使用下列 URL 來執行同樣的動作了:

http://org.eclipse.ui.intro/myCommand?id=org.eclipse.sdk.samples.swt.examples

"myCommand" 動作將換成 replaces 屬性的值,而剩下的 URL 參數則會附加到結尾。 代換之後所得出的 URL,會再展開為:

http://org.eclipse.ui.intro/runAction?pluginId=org.eclipse.pde.ui&class=org.eclipse.pde.ui.internal.samples.ShowSampleAction&id=org.eclipse.sdk.samples.swt.examples

法律注意事項