简介内容文件 XML 格式

版本 3.1.0

本文档将简介内容文件结构描述为一系列 DTD 段。

introContent


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

introContent 元素定义简介内容文件的主体。内容文件包括页面、可包括在多个页面中的共享组以及在其它配置中定义的锚点的扩展。



page


<!ELEMENT page (group* | link* | text* | head* | img* | include* | html* | title? | anchor* | 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>

此元素用来描述要显示的页面。此简介可显示动态和静态页面。

动态页面的内容是从页面的子元素生成的,如下所述。将根据表示应用样式或 alt 样式。该样式可通过引用标识或类标识进一步增强。

静态页面允许在某项简介中重用现有 HTML 文档并可从任何静态或动态页面链接。静态页面未在页面元素中定义,它们只是可由其它页面链接的 HTML 文件。

其标识在简介配置扩展点的表示元素中指定的主页可能有一个 URL 指示它是静态页面。如果未指定任何 URL,则会假定主页是动态的。使用页面元素描述的所有其它页面都是动态的。
而且还要注意,在使用 SWT 表示且要显示静态页时,将启动外部浏览器而且当前页面仍然可视。

动态页面中使用的子元素如下所示:group 子元素用于组合相关内容并在组合内容间应用样式。link 子元素定义可用来链接至静态或动态页面的链接并运行简介操作/命令。链接通常是在页面级别定义的,用于在主页与页面中的链接之间进行导航。text 子元素在页面级别定义文本内容。head 子元素仅适用于基于 Web 的表示并允许将其它 HTML 添加至 HTML head 节。这在添加 java 脚本或其它样式表时特别有用。img 子元素定义页面级别的图像内容。include 子元素允许重用除页面以外的任何元素。html 子元素仅适用于基于 Web 的表示并允许在页面的内容中嵌入或包括 HTML。嵌入允许通过引用 HTML 文件将严格定义的文件嵌入到 HTML object 中。包括允许包括直接取自 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 文件、外部 Web 站点或可运行简介 URL 操作。




预定义操作将使用以下格式描述:

action name - 操作的描述
action parameter1 - 参数的描述
action parameter2(可选) - 参数的描述
action parameter3(可选)= ("true" | "false") "false" - 参数的描述,选择 true 或 false,“false”是缺省值


下列预定义操作包括在简介框架中:

close - 关闭简介部分
不需要任何参数

navigate - 按给定方面浏览简介页面或返回至主页
direction = ("backward" | "forward" | "home") - 指定要浏览的方向

openBrowser - 在外部浏览器中打开 URL。自 3.1 开始,此操作依赖于工作台浏览器支持。这意味着将采用对浏览器设置的任何用户首选项。
url - 指向外部 Web 站点或静态 HTML 文件的有效 URL
pluginId(可选)- 仅当指定静态 HTML 文件时才需要。这是包含该文件的插件的标识。

openURL - 打开“欢迎”页面中嵌入的 URL。在 SWT 表示的情况下,该 URL 显示在外部浏览器中(类似于以上的 openBrowser 操作)。 起始版本为 3.1
url - 外部 Web 站点或本地 HTML 文件的有效 URL
pluginId(可选) - 如果 URL 是相对的,则它指定了包含此文件的插件的标识。

runAction - 运行指定操作
class - 实现 org.eclipse.ui.intro.config.IIntroActionorg.eclipse.jface.action.IActionorg.eclipse.ui.IActionDelegate 的其中一个的类的标准类名
pluginId - 包含该类的插件的标识。
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(可选) - 当前欢迎页面中将存储帮助主题内容的 div 的路径。如果指定此项,则缺省情况下 embed 为 true,且嵌入的 URL 插入在具有指定路径的 div 内。此路径相对于该页,因此它不应以页面标识开头。div 的子部分由 URL 的内容所替换。每页只有一个 div 可用于嵌入的目标。在 SWT 表示的情况下,只需忽略此标志。当使用 XHTML 作为简介内容时,它不受支持。起始版本为 3.1


showMessage - 使用标准信息对话框对用户显示消息。
message - 要对用户显示的消息

showStandby - 将简介部分设置为备用方式并显示带有给定输入的 standbyContentPart
partId - 要显示的 standbyContentPart 的标识
input - 要在 standbyContentPart 上设置的输入

showPage - 显示带有给定标识的简介页面
id - 要显示的简介页面的标识
standby(可选)= ("true" | "false") "false" - 指示是否在显示页面后将简介设置为备用方式

如果任何传递给这些操作的参数包含特殊字符(即在 URL 中不合法的字符),则应使用 UTF-8 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 片段来包括在页面中。必须定义回退图像或文本以便呈示备用 SWT 表示。
    嵌入允许在动态页面的内容中嵌入严格定义的 HTML 文件。将创建引用 HTML 文件的 HTML object 元素。
    包括允许在动态 HTML 页面中包括直接取自文件的 HTML 片段。


    title


    <!ELEMENT title EMPTY>

    <!ATTLIST title

    id           CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    可选择包含转义 HTML 标记的文本片段。它仅被用作页面标题,所以给定页面最多只能有一个标题元素。


    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 添加至 HTML HEAD 节。这在添加 java 脚本或其它样式表时特别有用。此标记仅将与基于 HTML 的简介部分实现配合使用。只是在用户界面表单实现的情况下会忽略它。一个页面可有多个头元素。实现可有且只能有一个头元素(因为它是在所有页面间共享的)。


    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 中的路径属性的有效值。


    contentProvider

     

    <!ELEMENT contentProvider (text)>

    <!ATTLIST contentProvider

    id       CDATA #REQUIRED

    pluginId CDATA #IMPLIED

    class    CDATA #REQUIRED>

     

    简介内容提供程序的代理,它允许简介页面从各种源(例如,Web 和 Eclipse 等)动态地获取数据并在运行时基于此动态数据提供内容。如果在类属性中指定的 IIntroContentProvider 类不能装入,则将改为呈示文本元素的内容。这是 HTML intro 标记的动态版本。虽然该 HTML 标记允许将静态 HTML 内容嵌入或直接插入至生成的 HTML intro 页面,但 contentProvider 标记允许在运行时动态地创建该内容。这两个标记之间的另一个差别是该 HTML 标记仅受 HTML 表示的支持,而 contentProvider 这个标记同时受 HTML 和 SWT 表示的支持。起始版本为 3.0.1