Einführungsinhaltsdatei im XML-Format

Version 3.1.0

Dieses Dokument beschreibt die Struktur der Einführungsinhaltsdatei als Serie von DTD-Fragmenten.

introContent


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

Das Element introContent definiert den Hauptteil der Einführungsinhaltsdatei. Die Inhaltsdatei besteht aus Seiten, gemeinsam benutzten Gruppen, die in mehrere Seiten aufgenommen werden können und Erweiterungen für Ankerpunkte, die in anderen Konfigurationen definiert sind.



page


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

<!ATTLIST page

url           CDATA #IMPLIED

id           CDATA #REQUIRED

style        CDATA #IMPLIED

alt-style     CDATA #IMPLIED

filteredFrom (swt|html)

content      CDATA #IMPLIED

style-id     CDATA #IMPLIED>

Dieses Element beschreibt eine Seite, die angezeigt werden soll. Die Einführung kann sowohl dynamische als auch statische Seiten anzeigen.

Der Inhalt für dynamische Seiten wird aus den Unterelementen der Seite generiert, die im Folgenden beschrieben sind. Abhängig von der Darstellung kommt entweder das Attribut style oder das Attribut alt-style zur Anwendung. Die Darstellungen können weiter erweitert werden, indem auf das Attribut id oder class-id verwiesen wird.

Bei statischen Seite können vorhandene HTML-Dokumente innerhalb einer Einführung wiederverwendet werden. Außerdem kann jede beliebige statische oder dynamische Seite Links zu statischen Seiten enthalten. Statische Seiten werden nicht in einem Element page definiert. Es handelt sich um einfache HTML-Dateien, zu denen andere Seiten Links enthalten können.

Die Homepage, deren ID im Darstellungselement des Erweiterungspunktes für die Einführungskonfiguration angegeben ist, kann über eine URL verfügen, mit der angegeben wird, dass es sich um eine statische Seite handelt. Falls keine URL angegeben ist, wird davon ausgegangen, dass die Homepage eine dynamische Seite ist. Alle anderen Seiten, die mit dem Element 'page' beschrieben werden, sind dynamische Seiten.
Außerdem ist bei Verwendung der SWT-Darstellung und dem Anzeigen einer statischen Seite zu beachten, dass ein externer Browser gestartet wird und die aktuelle Seite sichtbar bleibt.

In einer dynamischen Seite werden die folgenden Unterelemente verwendet: Mit einem Unterelelement group wird zusammengehörender Inhalt gruppiert und eine bestimmte Darstellung auf den gruppierten Inhalt angewendet. Das Unterelement link definiert einen Link, mit dem ein Link zu einer statischen oder zu einer dynamischen Seite hergestellt und eine Aktion oder ein Befehl für die Einführung ausgeführt wird. Normalerweise wird ein Link auf der Seitenebene definiert, damit zwischen den Hauptseiten (gegenüber den Links auf einer Seite) navigiert werden kann. Ein text Ein Unterelementtext definiert Textinhalt auf Seitenebene. Ein Unterelement head kann nur bei der webbasierten Darstellung angewendet werden und ermöglicht das Hinzufügen weiterer html-Daten zum HTML-Abschnitt head. Dies ist für das Hinzufügen von Java-Scripts oder zusätzlicher Style-Sheets nützlich. Ein Unterelement img definiert Imageinhalt für die Seitenebene. Mit einem Unterelement include kann ein beliebiges anderes Element (mit Ausnahme einer Seite) wiederverwendet werden. Ein Unterelement html kann nur bei der webbasierten Darstellung angewendet werden und ermöglicht das Einbetten oder Aufnehmen von html-Daten in den Inhalt der Seite. Beim Einbetten kann eine vollständig definierte HTML-Datei in ein HTML-Element object eingebettet werden, indem auf die HTML-Datei verwiesen wird. Mit einem Einschluss kann ein HTML-Ausschnitt direkt aus einer HTML-Datei integriert werden. Ein Unterelement title definiert den Titel der Seite. Ein Unterelement anchor definiert einen Punkt, an dem externe Ergänzungen durch ein Element <extensionContent> bereitgestellt werden können.


group


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

<!ATTLIST group

id           CDATA #REQUIRED

label        CDATA #IMPLIED

style-id     CDATA #IMPLIED

filteredFrom (swt|html) >

Mit diesem Element wird zusammengehörender Inhalt gruppiert sowie Inhalt, auf den eine ähnliche Darstellung angewendet werden soll, oder Inhalt, der zusammen in andere Seiten integriert werden soll.


link


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

<!ATTLIST link

id           CDATA #IMPLIED

label        CDATA #IMPLIED

url          CDATA #REQUIRED

style-id     CDATA #IMPLIED

filteredFrom (swt|html) >

Dieses Element kann einen Link zu einer statischen HTML-Datei oder einer externen Website herstellen oder aber eine Aktion für die Einführungs-URL ausführenn.




Die vordefinierten Aktionen werden unter Verwendung des folgenden Formats beschrieben:

action name - Beschreibung der Aktion
action parameter1 - Beschreibung des Parameters
action parameter2 (optional) - Beschreibung des Parameters
action parameter3 (optional) = ("true" | "false") "false" - Beschreibung des Parameters. Zur Auswahl stehen "true" und "false"; "false" ist der Standardwert


Die folgenden vordefinierten Aktionen sind in das Einführungsgerüst integriert:

close - Schließt die Einführungskomponente
Es sind keine Parameter erforderlich

navigate - Navigiert in einer bestimmten Richtung durch die Einführungsseiten oder kehrt zur Homepage zurück
direction = ("backward" | "forward" | "home") - Gibt die Richtung für die Navigation

openBrowser - Öffnet die URL in einem externen Browser. Ab Version 3.1 stützt sich diese Aktion auf die Browserunterstützung der Workbench. Das bedeutet, dass alle durch den Benutzer eingestellten Vorgaben für den Browser berücksichtigt werden.
url - Eine gültige URL zu einer externen Webseite oder einer statischen HTML-Datei
pluginId (optional) - Ist nur dann erforderlich, wenn eine statische HTML-Datei angegeben wird. Gibt die ID des Plug-ins an, das die Datei enthält.

openURL - Öffnet die URL eingebettet in der Startseite 'Willkommen'. Im falle der SWT-Darstellung wird die URL in einem externen Browser angezeigt (ähnlich der oben beschriebenen Aktion 'openBrowser'). Ab 3.1
url - Eine gültige URL zu einer externen Webseite oder einer lokalen HTML-Datei
pluginId (optional) - Wenn die URL relativ ist, wird hier die ID eines Plug-ins angegeben, das die Datei enthält.

runAction - Führt die angegebene Aktion aus
class - Der vollständig qualifizierte Klassenname der Klasse, die org.eclipse.ui.intro.config.IIntroAction, org.eclipse.jface.action.IAction oder org.eclipse.ui.IActionDelegate implementiert.
pluginId - Die ID des Plug-ins, das die Klasse enthält.
standby (optional) = ("true" | "false") "false" - Gibt an, ob die Einführung nach der Ausführung der Aktion in den Bereitschaftsmodus gesetzt werden soll
additional parameters - Alle zusätzlichen Parameter werden an Aktionen übergeben, die org.eclipse.ui.intro.config.IIntroActionimplementieren.

setStandbyMode - Legt den Status der Einführungskomponente fest
standby = ("true" | "false") - Bei "true" wird die Einführungskomponente in den teilweise sichtbaren Bereitschaftsmodus versetzt. Bei "false" ist die Komponente komplett sichtbar.

showHelp - Öffnet die Hilfefunktion.
Es sind keine Parameter erforderlich

showHelpTopic - Öffnet ein Hilfethema.
id - Die URL der Hilferessource. (siehe das Javadoc für org.eclipse.ui.help.WorkbenchHelp.displayHelpResource
embed (optional) = ("true" | "false") "true" - Gibt an, dass die Hilferessource eingebettet als Teil der Startseite 'Willkommen' angezeigt werden muss. Der Standardwert ist "false". Im Falle der SWT-Darstellung wird dieses Attribut einfach ignoriert. Ab 3.1
embedTarget (optional) - Der Pfad zu einer div in der aktuellen Startseite 'Willkommen', die den Inhalt des Hilfethemas enthalten wird. Wenn angegeben, ist einbetten standardmäßig 'true' und die eingebettete URL wird mit dem angegebenen Pfad innerhalb der div eingefügt. Der Pfad ist relativ zu der Seite und sollte daher mit der Seiten-ID nicht starten. Die untergeordneten Elemente der div werden durch den Inhalt der URL ersetzt. Pro Seite kann nur eine div als eingebettetes Ziel verwendet werden. Im Falle der SWT-Darstellung wird dieses Attribut einfach ignoriert. Es wird ebenfalls nicht unterstützt, wenn XHTML als Inhalt der Einführung verwendet wird. Ab 3.1


showMessage - Zeigt unter Verwendung eines Standardinformationsdialogs eine Nachricht für den Benutzer an.
message - Die Nachricht, die für den Benutzer angezeigt werden soll.

showStandby - Setzt die Einführungskomponente in den Bereitschaftsmodus und zeigt 'standbyContentPart' mit der angegebenen Eingabe an
partId - Die ID des anzuzeigenden 'standbyContentPart'
input - Die Eingabe, die für 'standbyContentPart' festgelegt werden soll

showPage - Zeigt die Einführungsseite mit der angegebenen ID an
id - Die ID der anzuzeigenden Einführungsseite
standby (optional) = ("true" | "false") "false" - Gibt an, ob die Einführung nach dem Anzeigen der Seite in den Bereitschaftsmodus gesetzt werden soll.

Wenn die an diese Aktion übergebene Parameter Sonderzeichen enthalten (d.h. Zeichen, die für eine URL nicht zulässig sind), so sollten sie anhand der Codierung 'UTF-8' codiert werden. Für den Empfang dieser Parameter in ihrem decodierten Zustand kann ein Sonderparameter decode = ("true" "false") verwendet werden, um eine Decodierung dieser Parameter zu erzwingen, wenn das Intro-Gerüst diese verarbeitet.
Die folgende Intro-URL:
http://org.eclipse.ui.intro/showMessage?message=Dies+ist+eine+Nachricht
verarbeitet beispielsweise den Nachrichtenparameter als "Dies+ist+eine+Nachricht"
während
http://org.eclipse.ui.intro/showMessage?message=Dies+ist+eine+Nachricht&amp;decode=true
den Nachrichtenparameter als "Dies ist eine Nachricht" verarbeitet.


  • style-id - Hiermit wird dieser Link in einer bestimmten Kategorie klassifiziert, damit eine allgemeine Darstellung angewendet werden kann.
  • filteredFrom - Mit diesem optionalen Attribut kann ein bestimmtes Element aus einer spezifischen Implementierung herausgefiltert werden. Hat beispielsweise eine Gruppe die Angabe 'filteredFrom = swt', bedeutet dies, dass diese Gruppe in der SWT-Implementierung nicht als Inhalt erscheint.
  • 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

    Dieses Element weist HTML an, die Seite entweder durch Einbettung des gesamten Dokuments oder durch die Integration eines vorhandenen HTML-Ausschnitts aufzunehmen. Es muss ein Image oder Text für das Zurücksetzen definiert werden, damit eine alternative SWT-Darstellung wiedergegeben werden kann.
    Beim Einbetten kann eine vollständig definierte HTML-Datei in den Inhalt einer dynamischen Seite eingebettet werden. Es wird ein HTML-Element object erstellt, das auf die HTML-Datei verweist.
    Mit einem Einschluss kann ein HTML-Ausschnitt direkt aus einer HTML-Datei integriert werden. Ein Unterelement title definiert den Titel der Seite.


    title


    <!ELEMENT title EMPTY>

    <!ATTLIST title

    id           CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    Dieses Element ist ein Textausschnitt, der optional verlassene HTML-Tags enthalten kann. Es wird als Titel der Seite verwendet. Daher kann jede Seite maximal nur ein Element title enthalten.


    text


    <!ELEMENT text EMPTY>

    <!ATTLIST text

    id           CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    Dieses Element ist ein Textausschnitt, der optional verlassene HTML-Tags enthalten kann. Es kann die Tags "b" und "li" enthalten. Außerdem kann es Anker für URLs enthalten. Falls mehrere Absätze benötigt werden, kann der Text in mehrere Abschnitte unterteil werden, die jeweils mit dem Tag 'p' beginnen und enden.


    include


    <!ELEMENT include EMPTY>

    <!ATTLIST include

    configId    CDATA #IMPLIED

    path        CDATA #REQUIRED

    merge-style (true | false) >

    Ein Element include erweitert ein Element, das ein Ziel des angegebenen Pfades und einem optionalen Attribut configID ist. Der Pfad sollte ein Element in der angegebenen Konfiguration eindeutig adressieren. Er könnte auf eine gemeinsam benutzte Gruppe zeigen, die auf der Konfigurationsebene definiert ist, oder auf ein beliebiges Element in einer Seite.


    head


    <!ELEMENT head EMPTY>

    <!ATTLIST head

    src CDATA #REQUIRED>

    encoding     CDATA #IMPLIED

    Dieses Element weist HTML an, Daten in den Inhaltsbereich HEAD einer Seite aufzunehmen. Auf diese Weise kann zusätzliches HTML zum HTML-Abschnitt HEAD hinzugefügt werden. Dies ist für das Hinzufügen von Java-Scripts oder zusätzlicher Style-Sheets nützlich. Diese Angabe kann nur bei einer HTML-basierten Implementierung der Einführungskomponente verwendet werden. Bei einer Implementierung mit Benutzerschnittstellenformularen wird sie einfach ignoriert. Eine Seite kann mehrere Elemente 'head' enthalten. Eine Implementierung kann lediglich ein Element head enthalten (weil sie von allen Seiten gemeinsam benutzt wird).


    img


    <!ELEMENT img EMPTY>

    <!ATTLIST img

    id           CDATA #REQUIRED

    src          CDATA #REQUIRED

    alt          CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    Dieses Element gibt ein Image an, das Einführungsinhalt und (im Gegensatz zu den in Darstellungen definierten Dekorationsimages) keine Darstellung angibt.


    extensionContent


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

    <!ATTLIST extensionContent

    style     CDATA #IMPLIED

    alt-style  CDATA #IMPLIED

    path      CDATA #REQUIRED>

    Dieses Element gibt den Inhalt an, der zum Zielanker hinzugefügt werden soll. In einem gegebenen Objekt 'configExtension' ist jeweils nur ein Element 'extensionContent' zulässig. Dies liegt daran, dass bei einer nicht erfolgreichen Auflösung der Erweiterung (falls die Konfiguration oder aber das Zielelement nicht gefunden werden kann) die Seiten und/oder Gruppen in der Erweiterung ignoriert werden müssen.


    anchor


    <!ELEMENT anchor EMPTY>

    <!ATTLIST anchor

    id CDATA #REQUIRED>

    Mit dem Element anchor wird die Erweiterungsfähigkeit deklariert. Es handelt sich um eine Position in der Konfiguration, an der externe Ergänzungen zulässig sind. Nur Elemente anchor sind gültige Zielwerte für das Attribut 'path' in einem Objekt extensionContent


    contentProvider

     

    <!ELEMENT contentProvider (text)>

    <!ATTLIST contentProvider

    id       CDATA #REQUIRED

    pluginId CDATA #IMPLIED

    class    CDATA #REQUIRED>

     

    Ein Proxy für einen Einführungsinhalt-Provider, der ermöglicht, dass Einführungsseiten dynamisch Daten von verschiedenen Quellen (z.B. dem Web, Eclipse, usw.) extrahieren und, basierend auf diesen dynamischen Daten zur Laufzeit Inhalt zur Verfügung stellen. Wenn die Klasse 'IIntroContentProvider', die in dem Klassenattribut angegeben worden ist, nicht geladen werden kann, wird statt dessen der Inhalt des Texteleme nts übergeben. Dies ist eine dynamische Version des HTML-Einführungstags. Während das HTML-tag ermöglicht, dass ein statischer HTML-Inhalt in die generierte HTML-Einführungsseite eingebettet oder integriert wird, ermöglicht das Tag 'contentProvider' die dynamische Erstellung dieses Inhalts zur Laufzeit. Ein weiterer Unterschied zwischen den Tags ist, dass das HTML-Tag nur für die HTML-darstellung unterstützt wird, während das Tag 'contentProvider' sowohl für H TML- als auch für SWT-Darstellung unterstützt wird. Ab 3.0.1