Формат XML файла содержимого памятки

Версия 3.0

Данный документ описывает структуру файла содержания памятки как ряд фрагментов DTD (машинное представление схемы XML).

cheatsheet

<!ELEMENT cheatsheet (intro, item+)> 
<!ATTLIST cheatsheet 
  title               CDATA #REQUIRED
>

Элемент <cheatsheet> задает тело файла содержимого памятки. Ниже перечислены атрибуты <cheatsheet>:

intro

<!ELEMENT intro (description)>
<!ATTLIST intro 
  contextId           CDATA #IMPLIED 
  href                CDATA #IMPLIED 
>

Элемент <intro> служит для описания показываемого введения памятки. Вложенный элемент <description> содержит тело введения. Ниже перечислены атрибуты <intro>:

description

<!ELEMENT description EMPTY>
<!ATTLIST description 
>

Элемент <description> содержит описание памятки или элемента памятки. Описание - это текст с простыми тегами форматирования. Памятка автоматически форматирует и макетирует текст, чтобы он был показан более или менее правильно в пользовательском интерфейсе. Парные теги <b>...</b> выделят текст жирным шрифтом, <br/> приведет к переносу строки. В настоящее время поддерживаются только эти теги (возможно, в будущем будут поддерживаться и другие). Некоторые символы обрабатываются особым образом анализатором XML. Например, для того чтобы написать "<", ">", "&", "'" и """ (кавычка) пишите "&lt;", "&gt;", "&amp;", "&apos;" и "&quot;" соответственно. Пробелы (обычные и символы переноса строк) обрабатываются как разделитель слов; несколько пробелов подряд (равно как и переносы строк) считаются одним пробелом. Пробел сразу после тегов <description> и <br/> игнорируется, как и пробел непосредственно перед тегом </description>.

item

<!ELEMENT item (description ([action|perform-when] | (subitem|repeated-subitem|conditional-subitem)*))> 
<!ATTLIST item 
  title               CDATA #REQUIRED
  skip                ("true" | "false") "false"
  contextId           CDATA #IMPLIED 
  href                CDATA #IMPLIED
>

Каждый элемент <item> описывает один шаг верхнего уровня в памятке. <item> бывает простым и составным. Ниже перечислены атрибуты <item>:

org.eclipse.ui.cheatsheets.cheatSheetItemExtension предоставляет дополнительные управляющие элементы для показа в интерфейсе программы. Вклады в эту точку расширения объявляют имена дополнительных строковых атрибутов, которые могут входить в элементы <item>.

Простые элементы могут иметь описание и необязательное действие. В типичном варианте заголовки элементов памятки большую часть времени показываются пользователю. Описание элемента показывается только в процессе выполнения данного шага. Наличие элемента <action> (или <perform-when>) обычно связывается с кнопкой, которую пользователь нажимает для выполнения действия шага. Если действие не задано, то этот шаг пользователь должен выполнить вручную и явно указать, что шаг выполнен успешно.

Составные шаги могут разбиваться на ряд вложенных шагов, на которые указывают вложенные элементы <subitem>. Если шаги задают жестко последовательность своего выполнения, то действия вложенных шагов можно выполнять в произвольном порядке. Все вложенные шаги должны быть завершены (или пропущены) перед переходом к следующему шагу. Это означает, что жесткую последовательность шагов нельзя представить в виде вложенных элементов.

Вложенный элемент <conditional-subitem> позволяет изменить презентацию этапа внутри шага в зависимости от переменных памятки, заданных на предыдущих шагах. Субэлемент <repeated-subitem> позволяет включить в шаг набор похожих вложенных шагов. Сам набор вложенных шагов также может зависеть от переменных памятки, заданных на предыдущих шагах.

subitem

<!ELEMENT subitem ( [action|perform-when] )> 
<!ATTLIST subitem 
  label               CDATA #REQUIRED
  skip                ("true" | "false") "false"
  when                CDATA #IMPLIED
>

Каждый вложенный элемент <subitem> описывает один вложенный шаг в памятке. <subitem> содержит простую метку текста, но не длинное описание или свои вложенные субэлементы. Ниже перечислены атрибуты <subitem>:

Вложенные элементы могут иметь необязательное действие. Наличие элемента <action> (или <perform-when>) обычно связывается с кнопкой, которую пользователь нажимает для выполнения действия вложенного шага. Если действие не задано, то этот вложенный шаг пользователь должен выполнить вручную и явно указать, что шаг выполнен успешно.

Если шаги задают жестко последовательность своего выполнения, то действия вложенных шагов внутри шага можно выполнять в произвольном порядке. Все вложенные шаги должны быть завершены (или пропущены) перед переходом к следующему шагу. Это означает, что жесткую последовательность шагов не следует представлять в виде вложенных элементов.

conditional-subitem

<!ELEMENT conditional-subitem (subitem+)> 
<!ATTLIST conditional-subitem 
  condition               CDATA #REQUIRED
>

Каждый элемент <conditional-subitem> описывает вложенный шаг, форма которого может зависеть от условия, известного в момент обработки элемента. Ниже перечислены атрибуты <conditional-subitem>:

Атрибут condition элемента <conditional-subitem> задает строку, которая определяется по значению переменной памятки. Каждый вложенный элемент <subitem> должен содержать атрибут when с уникальной строкой. При обработке элемент <conditional-subitem> заменяется на <subitem> с соответствующим значением. Если такой элемент не будет найден, это приведёт к ошибке.

Например, если переменная памятки "v1" будет иметь значение "b" на момент обработки следующего участка

<item ...> 
  <conditional-subitem condition="${v1}">
     <subitem when="a" label="Шаг для A." />
     <subitem when="b" label="Шаг для B." />
	</conditional-subitem>
</item>
то будет выбран второй вложенный элемент и участок приобретет следующий вид:
<item ...> 
  <subitem label="Шаг для B."/>
</item>

repeated-subitem

<!ELEMENT repeated-subitem (subitem)> 
<!ATTLIST repeated-subitem 
  values               CDATA #REQUIRED
>

Каждый элемент <repeated-subitem> описывает вложенный элемент, который выполняется 0, 1 или более раз. Ниже перечислены атрибуты <repeated-subitem>:

Атрибут values задает список строк, разделенных запятыми; <subitem> - шаблон. При обработке элемент <repeated-subitem> заменяется на копии <subitem>, где переменная "this" принимает соответствующие значения строк.

Например, если переменная памятки "v1" равна "1,b,три", то следующий элемент обрабатывается так:

<item ...> 
  <repeated-subitem values="${v1}">
     <subitem label="Шаг ${this}.">
        <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/>
     </subitem>
	</repeated-subitem>
</item>
и элемент приобретает вид:
<item ...> 
  <subitem label="Шаг 1.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="1"/>
  </subitem>
  <subitem label="Шаг b.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="b"/>
  </subitem>
  <subitem label="Шаг три.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="три"/>
  </subitem>
</item>

action

<!ELEMENT action EMPTY> 
<!ATTLIST action 
  class               CDATA #REQUIRED
  pluginId            CDATA #REQUIRED
  param1              CDATA #IMPLIED
  ...
  param9              CDATA #IMPLIED
  confirm             ("true" | "false") "false"
  when                CDATA #IMPLIED
>

Каждый элемент <action> описывает действие в памятке. Ниже перечислены атрибуты <action>:

perform-when

<!ELEMENT perform-when (action+)> 
<!ATTLIST perform-when 
  condition               CDATA #REQUIRED
>

Каждый элемент <perform-when> описывает действие в памятке. Ниже перечислены атрибуты <perform-when>:

Атрибут condition элемента <conditional-subitem> задает строку, которая определяется по значению переменной памятки. Каждый вложенный элемент <subitem> должен содержать атрибут when с уникальной строкой. При обработке элемент <conditional-subitem> заменяется на <subitem> с соответствующим значением. Если такой элемент не будет найден, это приведёт к ошибке.

Например, если переменная памятки "v1" будет иметь значение "b" на момент обработки следующего участка

<item ...>
  <subitem label="Главный шаг">
     <perform-when condition="${v1}">
        <action when="a" class="com.xyz.action1" pluginId="com.xyz" />
        <action when="b" class="com.xyz.action2" pluginId="com.xyz" />
	</conditional-subitem>
  </subitem>
</item>
то будет выбрано второе действие и участок приобретет следующий вид:
<item ...> 
  <subitem label="Главный шаг">
     <action class="com.xyz.action2" pluginId="com.xyz" />
  </subitem>
</item>

Пример

Ниже приведен пример очень простого файла содержимого памятки:

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Пример">
  <intro>
    <description>Простая памятка для двух шагов.</description>
  </intro>
  <item title="Шаг 1">
     <description>На этом шаге выполняется действие.</description>
     <action class="com.xyz.myaction" pluginId="com.xyz"/>
  </item>
  <item title="Шаг 2">
     <description>Этот шаг выполняется вручную.</description>
  </item>
</cheatsheet>