Format XML pliku treści ściągawki

Wersja 3.2

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 poprawnego wyświetlenia go 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, aczkolwiek inne znaczniki mogą zostać dodane w przyszłości. 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 ograniczniki 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|command|perform-when] | (subitem|repeated-subitem|conditional-subitem)*) [onCompletion])> 
<!ATTLIST item 
  title               CDATA #REQUIRED
  dialog              ("true" | "false") "false"
  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 zawierać elementy <subitem>. Poniżej przedstawiono atrybuty elementu <item>:

Rozszerzenie org.eclipse.ui.cheatsheets.cheatSheetItemExtension umożliwia wyświetlanie w interfejsie użytkownika dodatkowych elementów 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 oraz opcjonalną akcję lub komendę. 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>, <command> lub <perform-when> jest zwykle związana z przyciskiem, który użytkownik może kliknąć w celu wykonania akcji lub komendy w ramach danego etapu. W przypadku braku akcji lub komendy użytkownik musi wykonać dany etap ręcznie, a następnie jawnie zasygnalizować jego pomyślne zakończenie.

Etapy mogą dzielić się na etapy podrzędne 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ć reprezentowane w postaci podelementów.

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|command|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>:

W ramach podelementów mogą występować opcjonalne akcje lub komendy. Obecność elementu <action>, <command> lub <perform-when> jest związana z przyciskiem, który użytkownik może kliknąć w celu wykonania akcji lub komendy w ramach danego etapu. W przypadku braku akcji lub komendy użytkownik musi wykonać dany etap podrzędny ręcznie, a następnie jawnie 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. Przed przejściem do następnego elementu należy wykonać lub pominąć wszystkie podelementy w ramach bieżącego elementu. Oznacza to, że akcje, które należy wykonać w ustalonej kolejności, nie powinny być reprezentowane w postaci podelementów.

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ść łańcucha (wartość ta pochodzi zawsze ze zmiennej ściągawki). Każdy element podrzędny <subitem> musi zawierać atrybut when wraz z odmienną wartością łańcucha. 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 łańcucha.

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.moja_akcja" 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.moja_akcja" pluginId="com.xyz" param1="1"/>
  </subitem>
  <subitem label="Krok b.">
     <action class="com.xyz.moja_akcja" pluginId="com.xyz" param1="b"/>
  </subitem>
  <subitem label="Krok trzeci.">
     <action class="com.xyz.moja_akcja" pluginId="com.xyz" param1="trzeci"/>
  </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>:

command

<!ELEMENT command EMPTY> 
<!ATTLIST command 
  serialization       CDATA #REQUIRED
  returns             CDATA #IMPLIED
  confirm             ("true" | "false") "false"
  when                CDATA #IMPLIED
>

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

Poniżej przedstawiono przykładowy element z komendą otwierającą okno dialogowe i zapisującą rezultaty w zmiennej ściągawki "wynik".

<item title="Wybór widoku">
     <description>Wybierz widok, który ma zostać otwarty w następnym etapie.</description>
     <command returns = "wynik"
      serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Wybór widoku,buttonLabel0=Eksplorator pakietów,message=Wybierz widok,buttonLabel1=Widok wyszukiwania)"/>
      <onCompletion> Wybrano opcję ${wynik}. </onCompletion>
</item>

onCompletion

<!ELEMENT onCompletion EMPTY>
<!ATTLIST onCompletion 
>

Element <onCompletion> zawiera tekst, który ma być wyświetlany po wykonaniu danego elementu ściągawki. Jest on szczególnie przydatny na końcowych etapach ściągawek, umożliwia bowiem potwierdzanie wykonania całej czynności. Opis ma postać tekstu z prostymi znacznikami formatowania, w przypadku których obowiązują te same reguły, co w przypadku elementu <description>. Elementy <onCompletion> mogą także zawierać odwołania do zmiennych ściągawki w postaci "${zmienna}". Po zakończeniu danego etapu element zmienna zostaje zastąpiony odpowiadającą mu wartością.

perform-when

<!ELEMENT perform-when ((action|command)+)> 
<!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ść łańcucha (wartość ta pochodzi zawsze ze zmiennej ściągawki). Każdy element podrzędny <subitem> musi zawierać atrybut when wraz z odmienną wartością łańcucha. 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.akcja1" pluginId="com.xyz" />
        <action when="b" class="com.xyz.akcja2" pluginId="com.xyz" />
        <command when="c" serialization="org.eclipse.search.ui.views.SearchView"/>
     </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.akcja2" pluginId="com.xyz" />
  </subitem>
</item>

Przykład

Poniżej przedstawiono przykładowy plik treści ściągawki prostej, w którym zademonstrowano zastosowanie elementów <command>, <perform-when> i <conditional-subitem>.

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Przykładowa ściągawka">
  <intro>
    <description>Ściągawka ta ma na celu zademonstrowanie zastosowania elementów typu perform-when oraz elementów conditional-subitem.</description>
  </intro>
<item title="Wybór widoku">
     <description>Wybierz widok, który ma zostać otwarty w następnym etapie.</description>
     <command returns = "wynik"
      serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Wybór widoku,buttonLabel0=Eksplorator pakietów,message=Wybierz widok,buttonLabel1=Widok wyszukiwania)"/>
      <onCompletion> Wybrano opcję ${wynik}. </onCompletion>
</item>
  <item title="Zamykanie widoków">
     <description>Zamykanie widoku wyszukiwania i Eksploratora pakietów, jeśli są otwarte</description>
</item>
  <item title="Otwieranie widoku za pomocą elementu perform-when" skip = "true">
     <description>Zastosowanie elementu perform-when do otwarcia wcześniej wybranego widoku</description>
     <perform-when condition = "${wynik}">
           <command when = "Eksplorator pakietów"
            serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.jdt.ui.PackageExplorer)"/>
           <command when = "Widok wyszukiwania"
            serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.search.ui.views.SearchView)"/>      
	</perform-when>
</item>
  <item title="Zamykanie widoków">
     <description>Zamykanie widoku wyszukiwania i Eksploratora pakietów, jeśli są otwarte</description>
</item>
  <item title="Otwieranie widoku za pomocą podelementu perform-when">
     <description>Zastosowanie elementu perform-when do otwarcia wcześniej wybranego widoku</description>
     <subitem label="Podelement perform-when" skip = "true">
     <perform-when condition = "${wynik}">
           <command when = "Eksplorator pakietów"
            serialization="org.eclipse.jdt.ui.PackageExplorer"/>
           <command when = "Widok wyszukiwania"
            serialization="org.eclipse.search.ui.views.SearchView"/>      
	</perform-when>
  </subitem>
</item>
  <item title="Zamykanie widoków">
     <description>Zamykanie widoku wyszukiwania i Eksploratora pakietów, jeśli są otwarte</description>
</item>
  <item title="Otwieranie widoku za pomocą elementu conditional-subitem">
     <description>Zastosowanie elementu perform-when do otwarcia wcześniej wybranego widoku</description>
      <conditional-subitem condition="${wynik}">
         <subitem when="Eksplorator pakietów" label="Otwórz Eksplorator pakietów">
             <command serialization = "org.eclipse.jdt.ui.PackageExplorer"/>
  </subitem>
         <subitem when="Widok wyszukiwania" label="Otwórz widok wyszukiwania">
             <command serialization = "org.eclipse.search.ui.views.SearchView"/>
  </subitem>
     </conditional-subitem>
</item>
</cheatsheet>