Format XML pliku treści ściągawki

Wersja 3.0

W tym dokumencie opisano strukturę pliku treści ściągawki w postaci zbioru fragmentów definicji DTD (schemat XML w formie zapisu maszynowego).

cheatsheet

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

Element <cheatsheet> definiuje treść pliku treści ściągawki. Poniżej przedstawiono atrybuty elementu <cheatsheet>:

intro

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

Element <intro> służy do opisania wyświetlanego wprowadzenia do ściągawki. Podelement <description> zawiera treść wprowadzenia. Poniżej przedstawiono atrybuty elementu <intro>:

description

<!ELEMENT description EMPTY>
<!ATTLIST description 
>

Element <description> zawiera opis ściągawki lub jej elementu. Opis składa się z tekstu przeplatanego prostymi znacznikami formatowania. Tekst jest automatycznie formatowany i rozmieszczany przez ściągawkę w celu jego poprawnego wyświetlenia w interfejsie użytkownika. Użyte w obrębie tekstu pary znaczników <b>...</b> powodują renderowanie znajdującego się między nimi tekstu za pomocą pogrubionej czcionki, natomiast znacznik <br/> służy do wymuszenia końca wiersza. Są to jedyne obsługiwane obecnie znaczniki formatowania, chociaż w przyszłości mogą zostać dodane inne znaczniki. Niektóre znaki w tekście mają specjalne znaczenie dla analizatorów składni XML. W szczególności zamiast symboli "<", ">", "&", "'" i """ (cudzysłów) należy używać odpowiednio łańcuchów "&lt;", "&gt;", "&amp;", "&apos;" i "&quot;". Znaki spacji, tabulacji lub nowego wiersza są traktowane jako separatory słów. Przylegające spacje i znaki podziału wiersza są traktowane jako pojedyncza jednostka i renderowane jako pojedyncza spacja lub znak podziału wiersza. Znaki spacji znajdujące się po znacznikach <description> i <br/> są ignorowane, podobnie jak analogiczne znaki umieszczone bezpośrednio przed znacznikiem </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
>

Każdy element <item> opisuje jeden krok najwyższego poziomu w ściągawce. Element <item> może być prosty lub złożony. Poniżej przedstawiono atrybuty elementu <item>:

Rozszerzenie org.eclipse.ui.cheatsheets.cheatSheetItemExtension umożliwia wyświetlanie w interfejsie użytkownika dodatkowych, niestandardowych pól sterujących dla danego elementu. Uzupełnienia tego punktu rozszerzenia deklarują nazwy dodatkowych atrybutów o wartościach w postaci łańcuchów, które mogą być używane w elementach <item>.

Proste elementy mają opis i opcjonalną akcję. W przypadku typowej prezentacji tytuły elementów ściągawki są wyświetlane przez większość czasu. Opis elementu jest wyświetlany tylko podczas wykonywania kroku w procesie. Obecność elementu <action> (lub <perform-when>) jest zwykle powiązana z przyciskiem, który użytkownik może kliknąć w celu wykonania akcji danego kroku. W przypadku braku akcji użytkownik musi wykonać dany krok ręcznie, a następnie zasygnalizować jego pomyślne zakończenie.

Kroki złożone są podzielone na podkroki określane za pomocą podelementów <subitem>. W przeciwieństwie do elementów, które muszą zostać wykonane przez użytkownika w ściśle określonej kolejności, podelementy danego elementu mogą zostać wykonane w dowolnej kolejności. Należy wykonać (lub pominąć) wszystkie podelementy danego elementu, aby możliwe było przejście do kolejnego elementu. Oznacza to, że akcje, które należy wykonać w ustalonej kolejności, nie mogą być przedstawiane jako podelementy.

Podelement <conditional-subitem> umożliwia dostosowanie prezentacji podkroku w zależności od zmiennych ściągawki, których wartości zostały uzyskane we wcześniejszych krokach. Podelement <repeated-subitem> umożliwia zawarcie w danym kroku zestawu podobnych podkroków. Również w tym przypadku treść takiego zestawu podkroków może zależeć od zmiennych ściągawki uzyskanych we wcześniejszych krokach.

subitem

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

Każdy element <subitem> opisuje podkrok w ściągawce. Z elementem <subitem> powiązana jest prosta etykieta tekstowa, ale nie ma on długiego opisu ani dalszych podelementów. Poniżej przedstawiono atrybuty elementu <subitem>:

Podelementy mają opcjonalną akcję. Obecność elementu <action> (lub <perform-when>) jest zwykle powiązana z przyciskiem, który użytkownik może kliknąć w celu wykonania akcji danego podkroku. W przypadku braku akcji użytkownik musi wykonać dany podkrok ręcznie, a następnie zasygnalizować jego pomyślne zakończenie.

W przeciwieństwie do elementów, które muszą zostać wykonane w ściśle określonej kolejności, podelementy danego elementu mogą zostać wykonane w dowolnej kolejności. Należy wykonać (lub pominąć) wszystkie podelementy danego elementu, aby możliwe było przejście do kolejnego elementu. Oznacza to, że akcje, które należy wykonać w ustalonej kolejności, nie powinny być przedstawiane jako podelementy.

conditional-subitem

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

Każdy element <conditional-subitem> opisuje pojedynczy podkrok, którego forma może się różnić zależnie od warunku, który będzie znany w momencie rozwinięcia elementu. Poniżej przedstawiono atrybuty elementu <conditional-subitem>:

Atrybut condition elementu <conditional-subitem> udostępnia wartość typu łańcuchowego (wartość ta pochodzi zawsze ze zmiennej ściągawki). Każdy element podrzędny <subitem> musi zawierać atrybut when wraz z odmienną wartością typu łańcuchowego. Po rozwinięciu elementu dany element <conditional-subitem> jest zastępowany elementem <subitem> o zgodnej wartości. Brak elementu <subitem> o zgodnej wartości jest traktowany jako błąd.

Na przykład jeśli podczas rozwijania następującego elementu zmienna ściągawki o nazwie "v1" ma wartość "b":

<item ...> 
  <conditional-subitem condition="${v1}">
     <subitem when="a" label="Krok dla wartości A." />
     <subitem when="b" label="Krok dla wartości B." />
     </conditional-subitem>
</item>
wybrany zostanie drugi podelement, a sam element zostanie rozwinięty do następującej postaci:
<item ...> 
  <subitem label="Krok dla wartości B."/>
</item>

repeated-subitem

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

Każdy element <repeated-subitem> opisuje podelement, który jest rozwijany do jednego lub większej liczby podobnych podkroków (albo też do żadnego). Poniżej przedstawiono atrybuty elementu <repeated-subitem>:

Atrybut values udostępnia listę rozdzielonych przecinkami łańcuchów, natomiast element podrzędny <subitem> udostępnia szablon. Po rozwinięciu elementu dany element <repeated-subitem> jest zastępowany kopiami elementu <subitem> z wystąpieniami zmiennej "this" zamienionymi na odpowiednie wartości typu łańcuchowego.

Na przykład jeśli podczas rozwijania następującego elementu zmienna ściągawki o nazwie "v1" ma wartość "1,b,trzeci":

<item ...> 
  <repeated-subitem values="${v1}">
     <subitem label="Krok ${this}.">
        <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/>
  </subitem>
  </repeated-subitem>
</item>
element zostanie rozwinięty do następującej postaci:
<item ...> 
  <subitem label="Krok 1.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="1"/>
  </subitem>
  <subitem label="Krok b.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="b"/>
  </subitem>
  <subitem label="Krok trzeci.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="trzy"/>
  </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
>

Każdy element <action> opisuje akcję w ściągawce. Poniżej przedstawiono atrybuty elementu <action>:

perform-when

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

Każdy element <perform-when> opisuje akcję w ściągawce. Poniżej przedstawiono atrybuty elementu <perform-when>:

Atrybut condition elementu <conditional-subitem> udostępnia wartość typu łańcuchowego (wartość ta pochodzi zawsze ze zmiennej ściągawki). Każdy element podrzędny <subitem> musi zawierać atrybut when wraz z odmienną wartością typu łańcuchowego. Po rozwinięciu elementu dany element <conditional-subitem> jest zastępowany elementem <subitem> o zgodnej wartości. Brak elementu <subitem> o zgodnej wartości jest traktowany jako błąd.

Na przykład jeśli podczas rozwijania następującego elementu zmienna ściągawki o nazwie "v1" ma wartość "b":

<item ...>
  <subitem label="Krok główny">
     <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>
wybrana zostanie druga akcja, a sam element zostanie rozwinięty do następującej postaci:
<item ...> 
  <subitem label="Krok główny">
     <action class="com.xyz.action2" pluginId="com.xyz" />
  </subitem>
</item>

Przykład

Poniżej przedstawiono przykład bardzo prostego pliku treści ściągawki:

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Przykład">
  <intro>
    <description>Przykładowa ściągawka z dwoma krokami.</description>
</intro>
  <item title="Krok 1">
     <description>Jest to krok zawierający akcję.</description>
     <action class="com.xyz.myaction" pluginId="com.xyz"/>
</item>
  <item title="Krok 2">
     <description>Jest to krok wykonywany w całości ręcznie.</description>
</item>
</cheatsheet>