Muistilistan sisältötiedoston XML-muoto

Versio 3.2

Tässä ohjeessa kuvataan muistilistan sisältötiedoston rakenne DTD-osiksi (tietokoneen XML-skeemaksi) jaettuna.

cheatsheet

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

<Cheatsheet>-elementti määrittää muistilistan sisältötiedoston runko-osan. <Cheatsheet>-elementin määritteet ovat seuraavat:

intro

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

<Intro>-elementti määrittää näytettävän muistilistan esittelyn. <Description>-alielementti sisältää esityksen runko-osan. <Intro>-elementin määritteet ovat seuraavat:

description

<!ELEMENT description EMPTY>
<!ATTLIST description 
>

<Description>-elementti sisältää muistilistan tai muistilistaobjektin kuvauksen. Tämä kuvaus muodostetaan tekstiosista ja perusmuotoilutunnisteista. Muistilista muotoilee ja asettelee tekstin automaattisesti käyttöliittymässä näyttämistä varten. <B>- ja </b>-tunnisteilla rajattu teksti näytetään lihavoituna, ja <br/>-tunniste lisää tekstiin rivinvaihdon. Nykyinen versio tukee vain näitä muotoilutunnisteita, mutta tunnistetukea voidaan laajentaa myöhemmissä versioissa. Tietyt merkit on kirjoitettava erikoismerkeillä XML-jäsennystoimintoja varten. Esimerkiksi merkit <, >, &, ' ja " on kirjoitettava seuraavasti: &lt;, &gt;, &amp;, &apos; ja &quot;. Tyhjämerkit (välilyönnit ja rivinvaihdot) käsitellään sanojen erotinmerkkeinä. Jos tekstissä on useita peräkkäisiä tyhjämerkkejä, ne käsitellään yhtenä tyhjämerkkinä. <Description>- ja <br/>-tunnisteiden jäljessä ja </description>-tunnisteen edellä olevat tyhjämerkit ohitetaan.

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
>

Kukin <item>-elementti määrittää yhden muistilistan ylätason vaiheen. Kyseiset <item>-elementit voivat sisältää <subitem>-elementtejä. <Item>-elementin määritteet ovat seuraavat:

Org.eclipse.ui.cheatsheets.cheatSheetItemExtension-laajennuspisteeseen voidaan määrittää mukautettuja ohjausobjekteja kohtien käyttöliittymässä näyttämistä varten. Tämän laajennuspisteen lisäyksiin määritetään niiden merkkijonomuotoisten lisämääritteiden nimet, joita <item>-elementeissä voidaan käyttää.

Peruskohdat sisältävät kuvauksen ja valinnaisen toiminnon tai komennon. Normaalissa esityksessä muistilistan kohtien otsikot näytetään yleensä käyttäjälle. Kohdan kuvaus näytetään vain, kun kyseistä vaihetta suoritetaan. Elementtien <action>, <command> tai <perform-when> olemassaolo liitetään näppäimeen, jota painamalla käyttäjä voi aloittaa kyseisen vaiheen toiminnon tai komennon. Jos toimintoja tai komentoja ei ole määritetty, käyttäjän on suoritettava vaihe manuaalisesti ja ilmaistava suorittaneensa vaihe.

Vaiheet voidaan jakaa alivaiheisiin <subitem>-alielementtimääritysten mukaisesti. Toisin kuin pääkohdat, jotka käyttäjän on suoritettava tietyssä järjestyksessä, yksittäisten kohtien alikohdat voidaan suorittaa missä tahansa järjestyksessä. Jokaista kohdan alikohtaa on kokeiltava (tai ohitettava ne) ennen seuraavaan kohtaan siirtymistä. (Näiden rajoitusten takia toimintoja, jotka on suoritettava tietyssä järjestyksessä, ei voi määrittää alikohdiksi.)

Vaiheen <conditional-subitem>-alielementin esitystapa määräytyy muistilistan aiemmissa vaiheissa määritettyjen muuttujien arvojen perusteella. <Repeated-subitem>-alielementin avulla vaiheeseen voidaan lisätä samankaltaisia alivaiheita. Myös näiden alivaiheiden koostumus voi määräytyä muistilistan aiemmissa vaiheissa määritettyjen muuttujien arvojen perusteella.

subitem

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

Kukin <subitem>-elementti määrittää yhden muistilistan alatason vaiheen. <Subitem>-elementtiin määritetään tekstimuotoinen otsikko, mutta siihen ei liitetä pitkää kuvausta eikä siihen voi lisätä muita subitem-elementtejä. <Subitem>-elementin määritteet ovat seuraavat:

Alikohtiin voi liittää valinnaisia toimintoja tai komentoja. Elementtien <action>, <command> tai <perform-when> olemassaolo liitetään tavallisesti näppäimeen, jota painamalla käyttäjä voi aloittaa kyseisen vaiheen toiminnon tai komennon. Jos toimintoja tai komentoja ei ole määritetty, käyttäjän on suoritettava alivaihe manuaalisesti ja ilmaistava suorittaneensa se.

Toisin kuin pääkohdat, jotka on suoritettava tietyssä järjestyksessä, yksittäisten kohtien alikohdat voidaan suorittaa missä tahansa järjestyksessä. Jokainen kohdan alikohta on tehtävä loppuun (tai ohitettava) ennen seuraavaan kohtaan siirtymistä. (Näiden rajoitusten takia toimintoja, jotka on suoritettava tietyssä järjestyksessä, ei voi määrittää alikohdiksi.)

conditional-subitem

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

Kukin <conditional-subitem>-elementti määrittää yhden alivaiheen, jonka muoto vaihtelee kohdan laajennuksen toteutushetkellä selvitettävän ehdon mukaan. <Conditional-subitem>-elementin määritteet ovat seuraavat:

<Conditional-subitem>-elementin condition-määrite määrittää merkkijonoarvon (jonka arvo määräytyy poikkeuksetta jonkin muistilistan muuttujan perusteella). Kussakin elementin <subitem>-alielementissä on oltava when-määrite, jonka arvo on jokin määrätty merkkijono. Kun tämän kohdan laajennus toteutetaan, <conditional-subitem>-elementti korvataan sillä <subitem>-elementillä, jonka arvo vastaa ehtoa. Jos ehtoa vastaavaa <subitem>-elementtiä ei löydy, tilanne käsitellään virheenä.

Oletetaan esimerkiksi, että muistilistan muuttujan "v1" arvo on "b", kun seuraavan kohdan laajennus toteutetaan:

<item ...> 
  <conditional-subitem condition="${v1}">
     <subitem when="a" label="Vaihe A." />
     <subitem when="b" label="Vaihe B." />
	</conditional-subitem>
</item>
Tällöin suoritettavaksi valitaan toinen subitem-elementti ja kohdan laajennus toteutetaan seuraavassa muodossa:
<item ...> 
  <subitem label="Vaihe B."/>
</item>

repeated-subitem

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

Kukin <repeated-subitem>-elementti määrittää alikohdan, joka voi toteuttaa yhden tai useamman samankaltaisen alivaiheen tai ei yhtään alivaihetta. <Repeated-subitem>-elementin määritteet ovat seuraavat:

Values-määrite sisältää pilkuin eroteltujen merkkijonojen luettelon. <Subitem>-alielementti määrittää mallipohjan. Kun tämän kohdan laajennus toteutetaan, <repeated-subitem>-elementti korvataan <subitem>-elementin kopioilla, joiden "this"-muuttujat korvataan niitä vastavilla merkkijonoarvoilla.

Oletetaan esimerkiksi, että muistilistan muuttujan "v1" arvo on "1,b,kolme", kun seuraavan kohdan laajennus toteutetaan:

<item ...> 
  <repeated-subitem values="${v1}">
     <subitem label="Vaihe ${this}.">
        <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/>
  </subitem>
	</repeated-subitem>
</item>
Tällöin kohdan laajennus toteutettaisiin seuraavanlaisessa muodossa:
<item ...> 
  <subitem label="Vaihe 1.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="1"/>
  </subitem>
  <subitem label="Vaihe b.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="b"/>
  </subitem>
  <subitem label="Vaihe kolme.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="kolme"/>
  </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
>

Kukin <action>-elementti määrittää jonkin muistilistan toiminnon. <Action>-elementin määritteet ovat seuraavat:

command

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

Kukin <command>-elementti määrittää jonkin muistilistan komennon. Elementin <command> määritteet ovat seuraavat:

Seuraavassa on esimerkki kohdasta, jossa on valintaikkunan avaava ja muistilistamuuttujaan "result" tuloksen tallentava komento.

  <item title="View Selection">
     <description>Select a view which will be opened in the next step.</description>
     <command returns = "result"
      serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Select a view ,buttonLabel1=Search View)"/>  
      <onCompletion> Selected the ${result}. </onCompletion>
</item> 

onCompletion

<!ELEMENT onCompletion EMPTY>
<!ATTLIST onCompletion 
>

Elementti <onCompletion> sisältää tekstin, joka näytetään, kun kohta on tehty loppuun. Tästä on hyötyä etenkin muistilistan viimeisessä kohdassa, jossa voidaan kuitata koko tehtävän loppuun vienti. Tämä kuvaus muodostetaan tekstiosista ja perusmuotoilutunnisteista, jotka noudattavat samoja sääntöjä kuin <description>-elementin yhteydessä. Kyseiset <onCompletion>-elementit voivat myös sisältää viittauksia  "${var}"-muotoisiin muistilistamuuttujiin, jotka laajennetaan muistilistamuuttujan var todellisella arvolla, kun kyseinen vaihe on tehty.

perform-when

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

Kukin <perform-when>-elementti määrittää jonkin muistilistan toiminnon. <Perform-when>-elementin määritteet ovat seuraavat:

<Conditional-subitem>-elementin condition-määrite määrittää merkkijonoarvon (jonka arvo määräytyy poikkeuksetta jonkin muistilistan muuttujan perusteella). Kussakin elementin <subitem>-alielementissä on oltava when-määrite, jonka arvo on jokin määrätty merkkijono. Kun tämän kohdan laajennus toteutetaan, <conditional-subitem>-elementti korvataan sillä <subitem>-elementillä, jonka arvo vastaa ehtoa. Jos ehtoa vastaavaa <subitem>-elementtiä ei löydy, tilanne käsitellään virheenä.

Oletetaan esimerkiksi, että muistilistan muuttujan "v1" arvo on "b", kun seuraavan kohdan laajennus toteutetaan:

<item ...>
  <subitem label="Päävaihe">
     <perform-when condition="${v1}">
        <action when="a" class="com.xyz.action1" pluginId="com.xyz" />
        <action when="b" class="com.xyz.action2" pluginId="com.xyz" />
        <command when="c" serialization="org.eclipse.search.ui.views.SearchView"/>
	</conditional-subitem>
  </subitem>
</item>
Tällöin suoritettavaksi valitaan toinen action-elementti ja kohdan laajennus toteutetaan seuraavassa muodossa:
<item ...> 
  <subitem label="Päävaihe">
     <action class="com.xyz.action2" pluginId="com.xyz" />
  </subitem>
</item>

Esimerkki

Seuraavassa on esimerkki yksinkertaisen muistilistan sisältötiedostosta. Esimerkki esittelee command-, perform-when- ja conditional-alikohtien käyttöä.

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Sample Cheat Sheet">
  <intro>
    <description>A cheat sheet which demonstrates the use of perform-when and conditional subitems</description>
</intro>
  <item title="View Selection">
     <description>Select a view which will be opened in the following steps.</description>
     <command returns = "result"
      serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Select a view ,buttonLabel1=Search View)"/>  
      <onCompletion> Selected the ${result}. </onCompletion>
</item> 
  <item title="Close Views">
     <description>Close the search view and package explorer if open</description>
</item>
  <item title="Open the view from a perform when item" skip = "true">
     <description>Uses perform when to open the view seleted previously.</description> 
     <perform-when condition = "${result}">
           <command when = "Package Explorer" 
            serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.jdt.ui.PackageExplorer)"/>
           <command when = "Search View" 
            serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.search.ui.views.SearchView)"/>      
	</perform-when>
</item> 
  <item title="Close Views">
     <description>Close the search view and package explorer if open</description>
</item>
  <item title="Open the view from a perform when subitem">
     <description>Uses perform when to open the view seleted previously.</description> 
     <subitem label="Perform when subitem" skip = "true">
     <perform-when condition = "${result}">
           <command when = "Package Explorer" 
            serialization="org.eclipse.jdt.ui.PackageExplorer"/>
           <command when = "Search View" 
            serialization="org.eclipse.search.ui.views.SearchView"/>      
	</perform-when>
  </subitem>
</item> 
  <item title="Close Views">
     <description>Close the search view and package explorer if open</description>
</item>
  <item title="Open the view from a conditional subitem">
     <description>Uses perform when to open the view seleted previously.</description> 
      <conditional-subitem condition="${result}">
         <subitem when="Package Explorer" label="Open package explorer.">
             <command serialization = "org.eclipse.jdt.ui.PackageExplorer"/>
  </subitem>
         <subitem when="Search View" label="Open Search View">
             <command serialization = "org.eclipse.search.ui.views.SearchView"/>
  </subitem>
	</conditional-subitem>
</item>
</cheatsheet>