Formato XML do Arquivo de Conteúdo da Folha de Apontamentos

Versão 3.0

Este documento descreve a estrutura do arquivo de conteúdo da folha de apontamentos como uma série de fragmentos DTD (esquema XML legível da máquina).

cheatsheet

<folha de apontamentos do !ELEMENT (intro, item+)> 
<folha de apontamentos do !ATTLIST 
  título               CDATA #REQUIRED
>

O elemento <cheatsheet> define o corpo de um arquivo de conteúdo da folha de apontamentos. Os atributos de <cheatsheet> são os seguintes:

intro

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

O elemento <intro> é utilizado para descrever a introdução da folha de apontamentos a ser exibida. O sub-elemento <description> contém o corpo da introdução. Os atributos de <intro> são os seguintes:

description

<!ELEMENT description EMPTY>
<!ATTLIST description 
>

O elemento <description> mantém a descrição de uma folha de apontamentos ou de um item da folha de apontamentos. A descrição consiste no texto intercalado com marcações de formato simples. A folha de apontamentos formata e define o layout automaticamente do texto para que seja exibido corretamente na UI. Dentro do texto, marcações <b>...</b> compensadas fazem com que o texto incluído seja processado em fonte negrito e o elemento <br/> pode ser utilizado para forçar uma quebra de linha. Essas são as únicas marcações de formato suportadas nesse momento (contudo, outras podem ser incluídas no futuro). Determinados caracteres no texto possuem significância especial para analisadores XML; em particular, para gravar "<", ">", "&", "'" e """ (aspas) em vez de gravar "&lt;", "&gt;", "&amp;", "&apos;" e "&quot;" respectivamente. Espaço em branco (espaços e quebras de linha) é tratado como um separador de palavras; espaços adjacentes e quebras de linha são tratados como unidade individual e processados como um espaço individual ou uma quebra de linha. Espaço em branco imediatamente após as marcações <description> e <br/> é ignorado, assim como imediatamente antes da marcação </description>.

item

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

Cada elemento <item> descreve uma etapa de nível superior em uma folha de apontamentos. O <item> é simples ou composto. Os atributos <item> são os seguintes:

O org.eclipse.ui.cheatsheets.cheatSheetItemExtension permite controles personalizados adicionais para o item a ser exibido na UI. As contribuições para este ponto de extensão declaram os nomes dos atributos de valor de cadeia adicionais que podem aparecer nos elementos <item>.

Itens simples possuem uma descrição e uma ação opcional. Na apresentação típica, os títulos dos itens da folha de apontamentos são mostrados para o usuário na maior parte do tempo. A descrição de um item só é mostrada enquanto a etapa está em processo de ser executada. A presença de um elemento <action> (ou <perform-when>) normalmente está associada a um botão que o usuário pode pressionar para executar a ação da etapa. Se nenhuma ação estiver presente, a etapa será a única que o usuário deverá executar manualmente e depois indicar abertamente que a etapa foi concluída com êxito.

Etapas compostas são divididas em subetapas, conforme especificado pelos subelementos <subitem>. Ao contrário dos itens, que o usuário deve seguir na seqüência estrita, os sub-itens de um determinado item podem ser executados em qualquer ordem. Todos os sub-itens em um item devem ser tentados (ou ignorados) antes do processamento do próximo item. (O que significa que as ações que devem ser executadas em uma seqüência obrigatória não podem ser representadas como sub-itens.)

Um subelemento <conditional-subitem> permite que uma etapa adapte a apresentação de uma subetapa com base nas variáveis de folha de apontamentos cujos valores são obtidos em etapas anteriores. Um subelemento <repeated-subitem> permite que uma etapa inclua um conjunto de subetapas semelhantes. Novamente, o conjunto exato de subetapas pode basear-se nas variáveis de folha de apontamentos cujo valor seja obtido em etapas anteriores.

subitem

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

Cada elemento <subitem> descreve uma subetapa em uma folha de apontamentos. Um <subitem> transporta uma etiqueta de texto simples, mas não tem uma descrição longa nem sub-itens adicionais. Os atributos <subitem> são os seguintes:

Sub-itens possuem uma ação opcional. A presença de um elemento <action> (ou <perform-when>) normalmente está associada a um botão que o usuário pode pressionar para executar a ação da subetapa. Se nenhuma ação estiver presente, a subetapa será a única que o usuário deverá executar manualmente e depois indicar abertamente que a etapa foi concluída com êxito.

Diferente dos itens, que devem ser seguidos em uma seqüência estrita, os sub-itens de um determinado item podem ser executados em qualquer outra ordem. Todos os sub-itens em um item devem ser tentados (ou ignorados) antes do processamento do próximo item. (Isso significa que ações que devem ser executadas em uma seqüência obrigatória não devem ser representadas como sub-items.)

conditional-subitem

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

Cada elemento <conditional-subitem> descreve uma única subetapa cujo formato pode diferir, com base em uma condição conhecida no momento que o item é expandido. Os atributos <conditional-subitem> são os seguintes:

O atributo condition no elemento <conditional-subitem> fornece um valor de cadeia (esse valor provém invariavelmente de uma variável de folha de apontamentos). Cada filho do elemento <subitem> deve conter um atributo when com um valor de cadeia distinto. Quando o item é expandido, o elemento <conditional-subitem> é substituído pelo elemento <subitem> com o valor de correspondência. Isso será considerado um erro, se não houver o elemento <subitem> com um valor de correspondência.

Por exemplo, se a variável de folha de apontamentos denominada "v1" possuir o valor "b" quando o seguinte item for expandido

<item ...> 
  <conditional-subitem condition="${v1}">
     <subitem when="a" label="Step for A." />
     <subitem when="b" label="Step for B." />
     </conditional-subitem>
</item>
o segundo sub-item será selecionado e o item será expandido para algo equivalente a
<item ...> 
  <subitem label="Step for B."/>
</item>

repeated-subitem

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

Cada elemento <repeated-subitem> descreve um sub-item que é expandido em 0, 1 ou mais subetapas semelhantes. Os atributos <repeated-subitem> são os seguintes:

O atributo values fornece uma lista de cadeias separadas por vírgula; o <subitem> filho fornece o gabarito. Quando o item é expandido, o elemento <repeated-subitem> é substituído por cópias do elemento <subitem> com ocorrências da variável "this" substituídas pelo valor de cadeia correspondente.

Por exemplo, se a variável de folha de apontamentos denominada "v1" possuir o valor "1,b,three" quando o seguinte item for expandido

<item ...> 
  <repeated-subitem values="${v1}">
     <subitem label="Step ${this}.">
        <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/>
  </subitem>
  </repeated-subitem>
</item>
o item será expandido para algo equivalente a:
<item ...> 
  <subitem label="Step 1.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="1"/>
  </subitem>
  <subitem label="Step b.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="b"/>
  </subitem>
  <subitem label="Step three.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="three"/>
  </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
>

Cada elemento <action> descreve uma ação em uma folha de apontamentos. Os atributos <action> são os seguintes:

perform-when

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

Cada elemento <perform-when> descreve uma ação em uma folha de apontamentos. Os atributos <perform-when> são os seguintes:

O atributo condition no elemento <conditional-subitem> fornece um valor de cadeia (esse valor provém invariavelmente de uma variável de folha de apontamentos). Cada filho do elemento <subitem> deve conter um atributo when com um valor de cadeia distinto. Quando o item é expandido, o elemento <conditional-subitem> é substituído pelo elemento <subitem> com o valor de correspondência. Isso será considerado um erro, se não houver o elemento <subitem> com um valor de correspondência.

Por exemplo, se a variável de folha de apontamentos denominada "v1" possuir o valor "b" quando o seguinte item for expandido

<item ...>
  <subitem label="Main step">
     <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>
a segunda ação será selecionada e o item será expandido para algo equivalente a:
<item ...> 
  <subitem label="Main step">
     <action class="com.xyz.action2" pluginId="com.xyz" />
  </subitem>
</item>

Exemplo

Segue um exemplo de arquivo simples de conteúdo de folha de apontamentos:

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Example">
  <intro>
    <description>Exemplo de folha de apontamentos com duas etapas.</description>
  </intro>
  <item title="Etapa 1">
     <description>Esta é uma etapa com uma ação.</description>
     <action class="com.xyz.myaction" pluginId="com.xyz"/>
  </item>
  <item title="Etapa 2">
     <description>Esta é uma etapa totalmente manual.</description>
  </item>
</cheatsheet>