Esittelyn sisältötiedoston XML-muoto

Versio 3.1.0

Tässä ohjeessa kuvataan esittelyn sisältötiedoston rakenne DTD-osiksi jaettuna.

introContent


<!ELEMENT introContent (page+ , group* , extensionContent*)>

IntroContent-elementti määrittää esittelyn sisältötiedoston runko-osan. Sisältötiedosto koostuu sivuista, jaetuista ryhmistä, joita voi käyttää useilla sivuilla, ja muissa rakenteissa määritetyistä alkukohtien laajennuksista.



page


<!ELEMENT page (group* | link* | text* | head* | img* | include* | html* | hr* | title? | anchor* | contentProvider*)>

<!ATTLIST page

url          CDATA #IMPLIED

id           CDATA #REQUIRED

style        CDATA #IMPLIED

alt-style    CDATA #IMPLIED

filteredFrom (swt|html)
bgImage      CDATA #IMPLIED

content      CDATA #IMPLIED

style-id     CDATA #IMPLIED>

Tämä elementti määrittää näytettävän sivun. Esittelyssä voidaan näyttää sekä dynaamisia että staattisia sivuja.

Dynaamisten sivujen sisältö luodaan sivun alielementtien mukaisesti jäljempänä kuvatulla tavalla. Esityksessä käytetään style- tai alt-style-määritteen mukaista tyyliasetusta. Tyylejä voi tehostaa id- ja class-id-tunnusviittauksilla.

Staattisten sivujen avulla esittelyssä voi käyttää aiemmin luotuja HTML-asiakirjoja, jotka voi linkittää miltä tahansa staattiselta tai dynaamiselta sivulta. Staattisia sivuja ei määritetä page-elementissä, vaan ne ovat html-tiedostoja, joihin muut sivut voidaan linkittää.

Aloitussivu, jonka tunnus on määritetty esittelyn config-laajennuspisteen presentation-elementissä, voidaan määrittää staattiseksi sivuksi lisäämällä sivulle URL-määritys. Jos aloitussivulla ei ole URL-määritystä, se käsitellään dynaamisena. Muut page-elementissä määritetyt sivut ovat dynaamisia.
Huomaa, että kun SWT-esitystapaa käytettäessä näytetään staattinen sivu, käytössä oleva sivu pysyy näkyvissä ja staattinen sivu avataan ulkoiseen selaimeen.

Dynaamisella sivulla käytetään seuraavia alielementtejä: Group-alielementti ryhmittelee kytketyn sisällön ja määrittää saman ryhmän sisällölle yhteisen tyylin. Link-alielementti sisältää linkkimäärityksen, jolla sivuun voi linkittää staattisen tai dynaamisen sivun tai suorittaa esittelyn toimintoja tai komentoja. Linkki määritetään yleensä sivutasolla pääsivujen ja muiden sivujen linkkien välisiä siirtymiä varten. Text-alielementti määrittää sivun tekstisisällön. Head-alielementin voi määrittää vain Web-esityksiin. Sen avulla voi lisätä HTML-lisäkoodia HTML-koodin head-osaan. Tätä alielementtiä voi käyttää Java-komentosarjojen tai lisätyylisivujen lisäykseen. Img-alielementti määrittää sivun kuvasisällön. Include-alielementin avulla sivulle voi lisätä aiemmin määritettyjä elementtejä (muita kuin sivuja). HTML-alielementin voi määrittää vain Web-esityksiin. Sen avulla sivun sisältöön voi upottaa tai lisätä HTML-sisältöä. Upottamalla HTML-koodin object-määritykseen voidaan lisätä kokonainen HTML-tiedosto määrittämällä viittaus HTML-tiedostoon. Vaihtoehtoisesti koodiin voidaan lisätä vain HTML-katkelma jostakin HTML-tiedostosta. Title-alielementti määrittää sivun otsikon. Anchor-alielementti määrittää pisteen, johon voidaan lisätä ulkoisia muokkauksia <extensionContent>-elementin avulla.


group


<!ELEMENT group (group* | link* | text* | img* | include* | html* | anchor*)>

<!ATTLIST group

id           CDATA #REQUIRED

label        CDATA #IMPLIED

style-id     CDATA #IMPLIED

computed     CDATA (true|false) "false"
bgImage      CDATA #IMPLIED

filteredFrom (swt|html) >

Tämä elementti ryhmittelee kytketyn sisällön, sisällön, jolle on määritettävä samankaltainen tyyli, tai sisällön, joka lisätään yhdessä muille sivuille.


link


<!ELEMENT link (text? , img?)>

<!ATTLIST link

id           CDATA #IMPLIED

label        CDATA #IMPLIED

url          CDATA #REQUIRED

style-id     CDATA #IMPLIED

filteredFrom (swt|html) >

Tämän elementin avulla voi linkittää staattisen HTML-tiedoston tai ulkoisen Web-sivuston tai suorittaa esittelyn URL-toiminnon.




Aiemmin määritetyt toiminnot määritetään seuraavassa muodossa:

toiminnon nimi - toiminnon kuvaava nimi
parametri_1 - parametrimääritys
parametri_2 (valinnainen) - parametrimääritys
parametri_3 (valinnainen) = ("true" | "false") "false" - parametrimääritys, jonka arvo voi olla true (tosi) tai false (epätosi); oletusarvo on false


Esittelykehys sisältää seuraavat valmiiksi määritetyt toiminnot:

close - sulkee esittelyosan.
Parametreja ei tarvita.

execute - toteuttaa määritetyn komennon. Lisätietoja komennon sarjamuodosta on metodissa serialize() kohteessa org.eclipse.core.command.ParameterizedCommand. Käytössä versiosta 3.2 alkaen.
command - sarjamuotoinen ParameterizedCommand.
standby (valinnainen) = ("true" | "false") "false" - määrittää, asetetaanko esittely valmiustilaan komennon ajon jälkeen.

navigate - siirtää valittuun suuntaan esittelyn sivuilla tai palauttaa näkymän aloitussivulle.
direction = ("backward" | "forward" | "home") - siirtymissuunnan määrittävä parametri.

openBrowser - avaa URL-osoitteen ulkoiseen selaimeen. Versiosta 3.1 alkaen tämä toiminto käyttää työympäristön selaintukea. Tällöin käsittelyssä käytetään käyttäjän mahdollisesti asettamia selaimen oletusasetuksia.
url - ulkoisen Web-sivuston tai staattisen HTML-tiedoston kelvollinen URL-osoite.
pluginId (valinnainen) - tämä määrite on pakollinen vain, jos kyseessä staattisen HTML-tiedoston määritys. Tämä arvo on tiedoston sisältävän lisäosan tunnus.

openURL - avaa aloitussivulle upotetun URL-osoitteen. SWT-esityksissä URL-osoite näytetään ulkoisessa selaimessa (samalla tavalla kuin edellä kuvatussa openBrowser-toiminnossa). Käytettävissä versiosta 3.1 alkaen.
url - ulkoisen Web-sivuston tai paikallisen HTML-tiedoston kelvollinen URL-osoite.
pluginId (valinnainen) - tiedoston sisältävän lisäosan tunnus (jos URL-osoite on määritetty suhteellisesti).

runAction - suorittaa määritetyn toiminnon.
class - sen luokan tarkka luokkanimi, joka toteuttaa jonkin liittymistä org.eclipse.ui.intro.config.IIntroAction, org.eclipse.jface.action.IAction tai org.eclipse.ui.IActionDelegate.
pluginId - luokan sisältävän lisäosan tunnus.
standby (valinnainen) = ("true" | "false") "false" - parametri, joka määrittää, asetetaanko esittely valmiustilaan toiminnon suorituksen jälkeen.
lisäparametrit - muut lisäparametrit välitetään org.eclipse.ui.intro.config.IIntroAction-liittymän toteuttaville toiminnoille.

setStandbyMode - asettaa esittelyosan tilan.
standby = ("true" | "false") - jos arvo on true, esittelyosa asetetaan osittain näkyvissä olevaan valmiustilaan. Jos arvo on false, esittelyosa on näkyvissä kokonaan.

showHelp - avaa ohjejärjestelmän.
Parametreja ei tarvita.

showHelpTopic - avaa ohjeaiheen.
id - ohjeresurssin URL-osoite. Lisätietoja on org.eclipse.ui.help.WorkbenchHelp.displayHelpResource-osan Javadoc-ohjeissa.
embed (valinnainen) = ("true" | "false") "true" - tämä parametri määrittää, näytetäänkö ohjeresurssi aloitussivuille upotettuna. Oletusarvo on false (ei upotusta). SWT-esitystä käytettäessä tämä merkintä ohitetaan. Käytettävissä versiosta 3.1 alkaen.
embedTarget (valinnainen) - sen nykyisen aloitussivun div-osan polku, johon ohjeaiheen sisältö lisätään. Jos tälle parametrille on määritetty arvo, embed-parametrin arvoksi oletetaan true ja upotetut URL-tiedot lisätään määritetyn polun mukaiseen div-osaan. Polku määritetään suhteessa sivuun, joten polkumäärityksen alussa ei tarvita sivun tunnusta. URL-osoitteen sisältö korvaa div-osan aliobjektit. Vain yhden sivun div-osan voi määrittää upotuskohteeksi. SWT-esitystä käytettäessä tämä merkintä ohitetaan. Lisäksi merkintää ei voi käyttää, kun esittelyn sisältö on XHTML-muodossa. Käytettävissä versiosta 3.1 alkaen.


showMessage - näyttää käyttäjälle sanoman vakiovalintaikkunassa.
message - käyttäjälle näytettävä sanoma.

showStandby - asettaa esittelyosan valmiustilaan ja näyttää standbyContentPart-osan mukaisen syötteen.
partId - näytettävän standbyContentPart-osan tunnus.
input - standbyContentPart-osan syöte.

showPage - näyttää määritettyä tunnusta vastaavan esittelysivun.
id - näytettävän esittelysivun tunnus.
standby (valinnainen) = ("true" | "false") "false" - parametri, joka määrittää, asetetaanko esittely valmiustilaan sivun näyttämisen jälkeen.

Jos jokin näihin toimintoihin välitetyistä parametreista sisältää erikoismerkkejä (URL-muodon vastaisia merkkejä), ne on koodattava URL-koodauksen UTF-8-muodossa. Jotta tällaiset parametrit näkyisivät varmasti koodauksen mukaisessa muodossa, määritykseen voi lisätä erikoisparametrin decode = ("true" "false"), joka pakottaa esittelykehyksen koodaamaan erikoismerkit.
Oletetaan esimerkiksi, että esittelyn URL-osoite on seuraava:
http://org.eclipse.ui.intro/showMessage?message=Luet+nyt+sanomaa
Tällöin sanomaparametrin (message) arvo näkyy muodossa "Luet+nyt+sanomaa".
URL-osoitteen voi määrittää myös seuraavasti:
http://org.eclipse.ui.intro/showMessage?message=Luet+nyt+sanomaa&amp;decode=true
Tällöin sanomaparametrin arvo näkyy muodossa "Luet nyt sanomaa".


  • style-id - tämän linkin luokkamääritys. Saman luokan linkeille voidaan määrittää yhteinen tyyli.
  • filteredFrom - valinnainen määrite, jonka avulla tietty elementti voidaan suodattaa tietystä toteutuksesta. Jos ryhmässä on esimerkiksi määrite filteredFrom = swt, kyseinen ryhmä ei näy sisältönä swt-toteutusta käytettäessä.
  • html


    <!ELEMENT html (img | text)>

    <!ATTLIST html

    id           CDATA #REQUIRED

    src          CDATA #REQUIRED

    type         (inline|embed)

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    encoding     CDATA #IMPLIED

    Tämä elementti lisää sivulle HTML-koodia joko upottamalla sivulle kokonaisen asiakirjan tai lisäämällä sen koodiin HTML-katkelman. Vaihtoehtoista SWT-esitysmuotoilua varten on määritettävä varakuva tai -teksti. Jos sisällössä on $plugin:plugin_id$-muotoisia korvaussegmenttejä, ne korvataan sen lisäosan tarkalla polulla, jonka tunnus on plugin_id.
    Upottamalla dynaamisen sivun sisältöön voidaan lisätä kokonainen HTML-tiedosto. HTML-koodiin luodaan object-elementti, jossa on viittaus HTML-tiedostoon.
    Dynaamiselle HTML-sivulle voidaan lisätä myös vain HTML-katkelma jostakin tiedostosta.


    hr


    <!ELEMENT hr EMPTY>

    <!ATTLIST hr

    id           CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    Vaakaviiva.


    title


    <!ELEMENT title EMPTY>

    <!ATTLIST title

    id           CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    Tekstikatkelma, johon voi valinnaisesti lisätä HTML-koodinvaihtotunnisteita. Tätä elementtiä käytetään vain sivun otsikkona. Yhdellä sivulla voi olla vain yksi title-elementti.


    text


    <!ELEMENT text EMPTY>

    <!ATTLIST text

    id           CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    Tekstikatkelma, johon voi valinnaisesti lisätä HTML-koodinvaihtotunnisteita. Katkelmassa voi käyttää b- ja li-tunnisteita sekä URL-osoitteiden ankkureita. Tekstin voi jakaa useaan kappaleeseen lisäämällä haluttujen kappaleiden alkuun ja loppuun p-tunnisteen.


    include


    <!ELEMENT include EMPTY>

    <!ATTLIST include

    configId    CDATA #IMPLIED

    path        CDATA #REQUIRED

    merge-style (true | false) >

    Tämä elementti lisää määritetyn polun ja valinnaisten configId-määritteiden mukaisen elementin laajennuksen. Polun on määritettävä määritetyn rakenteen yksilöllinen elementti. Polku voi olla viittaus kokoonpanotasolla määritettyyn jaettuun ryhmään tai jonkin sivun elementtiin.


    head


    <!ELEMENT head EMPTY>

    <!ATTLIST head

    src CDATA #REQUIRED>

    encoding     CDATA #IMPLIED

    Sivun HEAD-sisältöalueelle lisättävä suora HTML-koodi. Tämän elementin avulla voi lisätä HTML-koodia HTML-ylätunnisteosaan (HTML HEAD). Tätä alielementtiä voi käyttää Java-komentosarjojen tai lisätyylisivujen lisäykseen. Jos sisällössä on $plugin:plugin_id$-muotoisia korvaussegmenttejä, ne korvataan sen lisäosan tarkalla polulla, jonka tunnus on plugin_id. Tätä merkintää voi käyttää vain HTML-muotoisissa esittelyosan toteutuksissa. Käyttöliittymän lomaketoteutuksessa se ohitetaan. Sivulla voi olla useampi kuin yksi head-elementti. Toteutuksella voi olla vain yksi head-elementti (joka on yhteinen kaikilla toteutuksen sivuilla).


    img


    <!ELEMENT img EMPTY>

    <!ATTLIST img

    id           CDATA #REQUIRED

    src          CDATA #REQUIRED

    alt          CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    Kuva, joka sisältää esittelyn sisältöä. Tämä kuva ei liity sisällön esitystapaan, kuten tyylien avulla määritetyt koristekuvat.


    extensionContent


    <!ELEMENT extensionContent (text | group | link | html | include)>

    <!ATTLIST extensionContent

    style     CDATA #IMPLIED

    alt-style CDATA #IMPLIED
    id       CDATA #IMPLIED

    name     CDATA #IMPLIED

    path      CDATA #REQUIRED>

    Anchor-kohtaan lisättävä sisältö. Kuhunkin configExtension-elementtiin voi määrittää vain yhden extensionContent-määritteen, koska jos laajennuksen selvitys ei onnistu (config-rakennetta tai anchor-kohde-elementtiä ei löydy), laajennuksen sivut ja/tai ryhmät on ohitettava.


    anchor


    <!ELEMENT anchor EMPTY>

    <!ATTLIST anchor

    id CDATA #REQUIRED>

    Anchor-elementti määrittää laajennusmahdollisuuden. Se määrittää sen rakenteen sijainnin, johon voidaan lisätä ulkoisia muokkauksia. ExtensionContent-elementin polkumääritteen (path) arvoina voi käyttää vain anchor-määritteitä.


    contentProvider

     

    <!ELEMENT contentProvider (text)>

    <!ATTLIST contentProvider

    id       CDATA #REQUIRED

    pluginId CDATA #IMPLIED

    class    CDATA #REQUIRED>

     

    Tämä on sen esittelyn sisällön toimittajan välitysmääritys, jonka avulla esittelysivulle voidaan noutaa tietoja dynaamisesti erilaisista lähteistä (kuten Web-sivuilta ja Eclipse-ympäristöstä). Tällaisista dynaamisista tiedoista voidaan tuottaa sisältöä ajonaikaisesti. Jos class-määritteen mukaisen IIntroContentProvider-luokan lataus ei onnistu, sisältö muodostetaan text-elementin arvon mukaisen tekstisisällön perusteella. Tämä on HTML-koodin intro-tunnisteen dynaaminen versio. HTML-tunnisteen avulla luodulle HTML-esittelysivulle voi upottaa tai lisätä staattista HTML-sisältöä. ContentProvider-tunnisteen avulla tämä sisältö voidaan luoda dynaamisesti ja ajonaikaisesti. Lisäksi tunnisteet eroavat toisistaan siten, että HTML-tunnistetta voi käyttää vain HTML-esityksissä mutta contentProvider-tunnistetta voi käyttää sekä HTML- että SWT-esityksissä. Käytettävissä versiosta 3.0.1 alkaen.