Introduktionsindholdsfil - XML-format

Version 3.1.0

Dette dokument beskriver introduktionens indholdsfilstruktur som en række DTD-fragmenter.

introContent


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

Elementet introContent definerer indholdet i indholdsfilen til introduktionen. Indholdsfilen består af sider, fælles grupper, der kan inkluderes på flere sider, og udvidelser til ankerpunkter, der er defineret i andre konfigurationer.



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>

Dette element bruges til at beskrive en side, der skal vises. Introduktionen kan vise både dynamiske og statiske sider.

Indholdet af dynamiske sider genereres ud fra underelementerne på den side, der beskrives nedenfor. Typografien eller den alternative typografi anvendes afhængigt af præsentationen. Typografierne kan forbedres yderligere ved at referere til id'en eller klasse-id'en.

Statiske sider giver mulighed for genbrug af eksisterende HTML-dokumenter i introduktionen, og alle statiske eller dynamiske sider kan kædes sammen med dem. Statiske sider er ikke defineret i et sideelement. Det er simpelthen html-filer, som kan kædes sammen med andre sider.

Hjemmesiden, hvis id er angivet i præsentationselementet for udvidelsespunktet til introduktionen, kan have en URL, der angiver, at det er en statisk side. Hvis der ikke er angivet en URL, antages det, at hjemmesiden er dynamisk. Alle andre sider, som er beskrevet vha. sideelementet, er dynamiske.
Bemærk også, at når SWT-præsentationen bruges, og der skal vises en dynamisk side, startes en ekstern browser, og den aktuelle side forbliver synlig.

De underelementer, der anvendes på en dynamisk side, er som følger: Et group-underelement bruges til at gruppere relateret indhold og anvende typografi på tværs af det grupperede indhold. Et link-underelement definerer et link, som kan bruges til sammenkædning med en statisk eller dynamisk side og udføre en introduktionsfunktion/-kommando. Et link defineres normalt på sideniveau til at navigere mellem hovedsider i modsætning til link på en side. Et text-underelement definerer tekstindholdet på sideniveau. Et head-underelement er kun tilgængeligt for den webbaserede præsentation og giver mulighed for at tilføje yderligere html til HTML-afsnittet head. Dette er nyttigt, når du vil tilføje Java-scripts eller ekstra typografiark. Et img-underelement definerer billedindhold til sideniveauet. Et include-underelement giver mulighed for at genbruge ethvert element på en anden side. Et html-underelement er kun tilgængeligt for den webbaserede præsentation og giver mulighed for at indbygge eller inkludere html i sidens indhold. Ved indbygning kan en fuldt defineret html-fil indbygges i et HTML-object ved at referere til html-filen. Ved inkludering kan html-kode inkluderes direkte fra en html-fil. Et title-underelement definerer titlen på siden. Et anchor-underelement definerer et punkt, hvor eksterne bidrag kan tilføres vha. et <extensionContent>-element.


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) >

Bruges til at gruppere relateret indhold - indhold, der skal anvende en ensartet typografi, eller indhold, der skal inkluderes samlet på andre sider.


link


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

<!ATTLIST link

id           CDATA #IMPLIED

label        CDATA #IMPLIED

url          CDATA #REQUIRED

style-id     CDATA #IMPLIED

filteredFrom (swt|html) >

Kan sammenkædes til en statisk HTML-fil eller et eksternt websted, eller kan udføre en URL-funktion for en introduktion.




De foruddefinerede funktioner beskrives vha. dette format:

action name - beskrivelse af funktionen
action parameter1 - beskrivelse af parameter.
action parameter2 (valgfri) - beskrivelse af parameter.
action parameter3 (valgfri) = ("true" | "false") "false" - beskrivelse af parameteren, valg mellem enten true eller false, og false er standard.


Følgende foruddefinerede funktioner er inkluderet i introduktionsstrukturen:

close - lukker introduktionsdelen.
Der kræves ingen parametre.

execute - udfører den angivne kommando. Se metoden serialize()org.eclipse.core.command.ParameterizedCommand for at få oplysninger om kommandoens serialiseringsformat. Fra 3.2.
command - en serialiseret ParameterizedCommand
standby (optional) = ("true" | "false") "false" - angiver, om intro skal angives i standby-tilstand efter udførelse af kommandoen.

navigate - navigér gennem introduktionssiderne i en bestemt retning, eller vend tilbage til hjemmesiden.
direction = ("backward" | "forward" | "home") - angiver den retning, der navigeres i

openBrowser - åbner url i en ekstern browser. Siden 3.1 udnytter denne funktion browserunderstøttelsen på arbejdsbænken. Det betyder, at brugerindstillinger, angivet for browseren, overholdes.
url - en gyldig URL til et eksternt websted eller en statisk HTML-fil.
pluginId (optional) - kræves kun, hvis der er angivet en statisk HTML-fil. Det er id'en for den plugin, som indeholder filen.

openURL - åbn den URL, der er indbygget på velkomstsiden. Hvis det er en SWT-præsentation, vises URL'en i en ekstern browser (svarende til funktionen openBrowser ovenfor). Fra 3.1.
url - en gyldig URL til et eksternt websted eller en lokal HTML-fil.
pluginId (valgfrit) - hvis URL'en er relativ, angiver dette id'en til den plugin, der indeholder filen.

runAction - udfører den angivne funktion.
class - det fuldstændige klassenavn på den klasse, der implementerer org.eclipse.ui.intro.config.IIntroAction, org.eclipse.jface.action.IAction eller org.eclipse.ui.IActionDelegate
pluginId - id'en til den plugin, der indeholder klassen.
standby (optional) = ("true" | "false") "false" - angiver, om intro skal angives i standby-tilstand, efter funktionen er udført.
ekstra parametre - eventuelle ekstra parametre overføres til funktioner, der implementerer org.eclipse.ui.intro.config.IIntroAction.

setStandbyMode - angiver tilstanden af introduktionsdelen
standby = ("true" | "false") - true, hvis intro-delen skal være delvis synlig i standby-tilstand, og false, hvis den skal være fuldt synlig.

showHelp - åbn hjælpen.
Der kræves ingen parametre.

showHelpTopic - åbn et emne i hjælpen.
id - URL'en til hjælperessourcen. (Se Javadoc til org.eclipse.ui.help.WorkbenchHelp.displayHelpResource
embed (valgfri) = ("true" | "false") "true" - angiver, at hjælperessourcen skal vises indbygget som en del af velkomstsiderne. Standardværdien er false. Dette flag ignoreres, hvis der er tale om SWT-præsentationen. Siden 3.1
embedTarget (valgfri) - stien til en div i den aktuelle velkomstside, som indeholder hjælpeemnets indhold. Hvis det er angivet, er embed som standard true, og den indbyggede URL indsættes inde i div med den angivne sti. Stien er relativ i forhold til siden og skal derfor ikke starte med side-id'en. De underordnede til div'en placeres af indholdet af URL'en. Kun én div pr. side kan bruges som indbygningsmål. Dette flag ignoreres, hvis der er tale om SWT-præsentationen. Det understøttes heller ikke, når XHTML anvendes som introduktionsindhold. Fra 3.1.


showMessage - viser en meddelelse til brugeren vha. en standardoplysningsdialogboks.
message - den meddelelse, der skal vises for brugeren.

showStandby - indstiller introduktionsdelen til standby-tilstand og viser standbyContentPart med det angivne input.
partId - id'en for den standbyContentPart, der skal vises.
input - det input, der skal angives for standbyContentPart.

showPage - vis introduktionssiden med den angivne id.
id - id'en for den introduktionsside, der skal vises.
standby (valgfri) = ("true" | "false") "false" - angiver, om intro skal sættes i standby-tilstand, når siden er vist.

Hvis de parametre, der overføres til disse funktioner, indeholder specialtegn (dvs. tegn, der er ulovlige i en URL), skal de kodes vha. UTF-8-kodning. For at modtage disse parametre i afkodet tilstand kan der bruges en særlig parameter decode = ("true" "false") for at gennemtvinge en afkodning af disse parametre, når Intro-strukturen behandler dem.
Eksempelvis vil følgende introduktions-URL:
http://org.eclipse.ui.intro/showMessage?message=This+is+a+message
behandler meddelelsesparameteren som "This+is+a+message",
hvorimod
http://org.eclipse.ui.intro/showMessage?message=Dette+er+en+meddelelse&amp;decode=true
behandler meddelelsesparameteren som "This is a message".


  • style-id - en måde at klassificere dette link i en given kategori, så der kan anvendes en fælles typografi.
  • filteredFrom - en valgfri attribut, som giver mulighed for at bortfiltrere et bestemt element fra en specifik implementering. Hvis en gruppe f.eks. har filteredFrom = swt, betyder det, at denne gruppe ikke bliver vist som indhold i swt-implementering.
  • 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

    Direkte HTML, der skal inkluderes på siden, enten ved at indbygge hele dokumentet eller ved at anbringe et inline HTML-kodestykke lokalt. Et reservebillede eller en reservetekst skal defineres til gengivelse af alternativ swt-præsentation. Hvis indholdet indeholder erstatningssegmenter af formen $plugin:plugin_id$, erstattes de med den absolutte sti til plugin'en med id'en plugin_id.
    Ved indbygning kan en fuldt defineret html-fil indbygges i den dynamiske sides indhold. Der oprettes et HTML-baseret object-element, som refererer til html-filen.
    Ved inkludering kan html-kode inkluderes direkte fra en fil til den dynamiske html-side.


    hr


    <!ELEMENT hr EMPTY>

    <!ATTLIST hr

    id           CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    En vandret regel.


    title


    <!ELEMENT title EMPTY>

    <!ATTLIST title

    id           CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    Et tekststykke, der kan indeholde HTML-koder med Escape-tegn. Det bruges kun som sidetitel, så derfor kan en side kun have ét titelelement.


    text


    <!ELEMENT text EMPTY>

    <!ATTLIST text

    id           CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    Et tekststykke, der kan indeholde HTML-koder med Escape-tegn. Det kan indeholde b- og li-koder. Det kan også indeholde ankre til URL'er. Hvis du har brug for flere afsnit, kan teksten opdeles i flere afsnit, der hver begynder og slutter med p-koden.


    include


    <!ELEMENT include EMPTY>

    <!ATTLIST include

    configId    CDATA #IMPLIED

    path        CDATA #REQUIRED

    merge-style (true | false) >

    Udvider et element, som den angivne sti og de valgfrie configId-attributter har som mål. Stien skal entydigt adressere et element i den angivne konfiguration. Den kan pege på en delt gruppe, der er defineret på konfigurationsniveau eller et element på en side.


    head


    <!ELEMENT head EMPTY>

    <!ATTLIST head

    src CDATA #REQUIRED>

    encoding     CDATA #IMPLIED

    Direkte HTML, der skal inkluderes i en sides HEAD-indholdsområde. Det giver mulighed for at tilføje yderligere html i HTML-afsnittet HEAD. Det er nyttigt, når det skal tilføjes java-kommandofiler eller ekstra typografiark. Hvis indholdet indeholder erstatningssegmenter af formen $plugin:plugin_id$, erstattes de med den absolutte sti til plugin'en med id'en plugin_id. Denne kode skal kun bruges med en HTML-baseret implementering af en introduktionsdel. Den ignoreres, hvis der er tale om en UI Forms-implementering. En side kan have mere end ét head-element. En implementering kan have ét og kun ét head-element (eftersom det deles af alle sider).


    img


    <!ELEMENT img EMPTY>

    <!ATTLIST img

    id           CDATA #REQUIRED

    src          CDATA #REQUIRED

    alt          CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    Et billede, der repræsenterer introduktionsindhold og ikke præsentation (i modsætning til dekorationsbilleder, der er defineret i typografier).


    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>

    Det indhold, der skal tilføjes til målankeret. Der må kun være én extensionContent i en given configExtension, fordi hvis denne udvidelse ikke kan opløses (hvis config ikke er fundet, eller målankerelementet ikke er fundet), skal siderne og/eller grupperne i udvidelsen ignoreres.


    anchor


    <!ELEMENT anchor EMPTY>

    <!ATTLIST anchor

    id CDATA #REQUIRED>

    Et anker er det element, der bruges til at erklære udvidelsesmuligheder. Det er en placering i konfigurationen, som gør eksterne bidrag muligt. Kun ankre er gyldige målværdier for stiattributten i en extensionContent.


    contentProvider

     

    <!ELEMENT contentProvider (text)>

    <!ATTLIST contentProvider

    id       CDATA #REQUIRED

    pluginId CDATA #IMPLIED

    class    CDATA #REQUIRED>

     

    En proxy til en udbyder af introduktionsindhold, som giver mulighed for, at introduktionssiden dynamisk kan hente data fra forskellige kilder (f.eks. internettet, eclipse osv.) og levere indhold ved runtime, der er baseret på disse dynamiske data. Hvis den IIntroContentProvider-klasse, der er angivet i klasseattributten, ikke kan indlæses, bliver indholdet af tekstelementet i stedet gengivet. Dette er en dynamisk version af den html-baserede introduktionskode. Mens html-koden giver mulighed for at indbygge statisk html-indhold eller anbringe det inline på den genererede html-introduktionsside, giver koden contentProvider mulighed for dynamisk oprettelse af dette indhold ved runtime. En anden forskel mellem koderne er, at html-koden kun understøttes for HTML-præsentationen, mens denne contentProvider-kode understøttes for både HTML- og SWT-præsentationer. Siden 3.0.1