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>

Этот элемент служит для описания отображаемой страницы. Во введении могут быть показаны как динамические, так и статические страницы.

Содержимое динамических страниц создается из субэлементов страницы, описанных ниже. К странице будет применен стиль style или alt-style, в зависимости от оформления. Стили можно дополнять, указывая ссылки на id или class-id.

Статические страницы позволяют повторно использовать существующие документы HTML во введении; с ними можно связывать любые статические или динамические страницы. Статические страницы не определяются в элементе page. Это просто файлы HTML, с которыми могут быть связаны другие страницы.

Домашняя страница, идентификатор которой указан в элементе оформления, относящемся к точке расширения конфигурации введения, может содержать URL, указывающий, что это страница является статической. Если URL не задан, то домашняя страница считается динамической. Все остальные страницы, описанные с помощью элемента page, являются динамическими.
Обратите внимание также на то, что, когда используется SWT-оформление и необходимо показать статическую страницу, запускается внешний браузер и текущая страница остается видимой.

В динамической странице используются следующие субэлементы: субэлемент group применяется для объединения связанного содержимого и применения к нему единого стиля. Субэлемент link определяет ссылку, позволяющую установить связь со статической или динамической страницей и запустить действие или команду введения. Ссылка обычно определяется на уровне страницы, чтобы обеспечить переход с основных страниц на ссылки на странице и обратно. Субэлемент text определяет текстовое содержимое на уровне страницы. Субэлемент head применим только в случае Web-оформления. Он позволяет размещать дополнительный html в разделе head HTML. Это помогает добавлять сценарии Java и дополнительные таблицы стилей. Субэлемент img определяет графическое содержимое на уровне страницы. Субэлемент include позволяет повторно использовать любой элемент, отличный от page. Субэлемент html применим только в случае Web-оформления. Он позволяет встраивать или включать html в содержимое страницы. Встраивание позволяет внедрить полностью определенный файл HTML путем создания ссылки на этот файл в элементе object 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 или внешний Web-сайт, а также запустить действие URL введения.




Предопределенные действия описываются с помощью следующего формата:

имя действия - описание действия
параметр1 действия - описание параметра
параметр2 действия (необязательный) - описание параметра
параметр3 действия (необязательный) = ("true" | "false") "false" - описание параметра, выбор между true и false, значение по умолчанию - "false"


В структуру введения входят следующие предопределенные действия:

close - закрывает компонент введение
параметры не требуются

navigate - переместиться по страницам введения в заданном направлении или вернуться к домашней странице
direction = ("backward" | "forward" | "home") - задает направление перемещения

openBrowser - открыть URL во внешнем браузере. Начиная с версии 3.1 это действие выполняется с помощью поддержки браузера рабочей средой. Это значит, что будут учтены любые установки пользователя в отношении поддержки браузера.
url - допустимый URL внешнего Web-сайта или статического файла HTML
pluginId (необязательный) - обязателен, только если указан статический файл HTML. Это идентификатор модуля, содержащего файл.

openURL - открывает URL во встроенном браузере, вместо начальной страницы. Если используется оформление SWT, то запускается внешний браузер(аналогично действию openBrowser выше). Начиная с 3.1.
url - допустимый URL внешнего web-сайта или локального файла HTML
pluginId (необязательный) - если URL относительный, то этот атрибут указывает id модуля, содержащего файл.

runAction - выполняет указанное действие
class - полное имя класса, реализующего одно из действий org.eclipse.ui.intro.config.IIntroAction, org.eclipse.jface.action.IAction или org.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 в документации по Java)
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. Для раскодирования этих параметров предусмотрен особый параметр 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, который нужно добавить на страницу путем встраивания всего документа или включения фрагмента in-place HTML. Для вывода альтернативного SWT-оформления должно быть определено резервное изображение или текст.
    Встраивание позволяет внедрить полностью определенный файл HTML в содержимое динамической страницы. Для этого создается элемент object HTML, ссылающийся на файл HTML.
    Включение позволяет добавить фрагмент HTML непосредственно из файла на динамическую страницу HTML.


    title


    <!ELEMENT title EMPTY>

    <!ATTLIST title

    id           CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    Фрагмент текста, который может содержать esc-теги HTML. Он используется только в качестве заголовка страницы, поэтому у каждой страницы может быть не более одного элемента title.


    text


    <!ELEMENT text EMPTY>

    <!ATTLIST text

    id           CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    Фрагмент текста, который может содержать esc-теги 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 и дополнительные таблицы стилей. Этот язык описания следует применять только в том случае, если введение реализуется на основе HTML. В случае реализации на основе UI Forms этот язык описания просто игнорируется. У страницы может быть несколько элементов 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 можно указывать только метки привязки.


    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.