Format XML pliku treści wprowadzenia

Wersja 3.1.0

W tym dokumencie opisano strukturę pliku treści wprowadzenia w postaci zbioru fragmentów definicji DTD.

introContent


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

Element introContent definiuje treść pliku treści wprowadzenia. Plik treści składa się ze stron, współużytkowanych grup, które mogą być umieszczane na wielu stronach, oraz rozszerzeń do punktów zakotwiczenia zdefiniowanych w innych konfiguracjach.



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>

Ten element służy do opisania wyświetlanej strony. We wprowadzeniu mogą być wyświetlane zarówno strony dynamiczne, jak i statyczne.

Treść stron dynamicznych jest generowana na podstawie podelementów strony, które zostaną opisane poniżej. Zależnie od prezentacji stosowany jest styl z elementu style lub alt-style. Style można rozszerzać, odwołując się do elementu id lub class-id.

Strony statyczne umożliwiają ponowne wykorzystanie we wprowadzeniu istniejących dokumentów HTML. Odsyłacze do stron statycznych można umieszczać na dowolnej stronie statycznej lub dynamicznej. Strony statyczne nie są definiowane w elemencie page. Są to po prostu pliki HTML, które mogą być połączone z innymi stronami.

Strona główna, której identyfikator jest określony w elemencie prezentacji punktu rozszerzenia konfiguracji wprowadzenia, może mieć adres URL wskazujący, że jest to strona statyczna. W przypadku braku takiego adresu URL zakłada się, że strona główna jest stroną dynamiczną. Wszystkie inne strony opisane za pomocą elementu page są dynamiczne.
Jeśli używana jest prezentacja SWT i konieczne jest wyświetlenie strony statycznej, uruchamiana jest zewnętrzna przeglądarka, a bieżąca strona pozostaje widoczna.

Na stronie dynamicznej używane są następujące podelementy: Podelement group służy do grupowania powiązanej treści i stosowania stylu dla całej zgrupowanej treści. Podelement link definiuje odsyłacz, który może zostać użyty do połączenia ze stroną statyczną lub dynamiczną, a także do wykonania akcji lub komendy wprowadzenia. Odsyłacz jest zwykle definiowany na poziomie strony w celu przechodzenia między stronami głównymi (w odróżnieniu od odsyłaczy na stronie). Podelement text definiuje treść tekstową na poziomie strony. Podelement head odnosi się tylko do prezentacji WWW i umożliwia dołączenie dodatkowego kodu HTML do sekcji head dokumentu HTML. Pozwala to dodawać skrypty Java lub arkusze stylów. Podelement img definiuje treść obrazu na poziomie strony. Podelement include umożliwia ponowne wykorzystanie każdego elementu innego niż strona. Podelement html odnosi się tylko do prezentacji WWW i umożliwia osadzenie lub dołączenie kodu HTML do treści strony. Osadzanie oznacza tu osadzenie w znaczniku HTML object w pełni zdefiniowanego pliku HTML poprzez odwołanie się do tego pliku. Możliwe jest także dołączenie fragmentu kodu HTML bezpośrednio z pliku HTML. Podelement title definiuje tytuł strony. Podelement anchor definiuje punkt, w którym można utworzyć zewnętrzne elementy przy użyciu elementu <extensionContent>.


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

Stosowany do grupowania pokrewnej treści, treści, dla której należy zastosować podobny styl, bądź treści umieszczanej wspólnie na innych stronach.


link


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

<!ATTLIST link

id           CDATA #IMPLIED

label        CDATA #IMPLIED

url          CDATA #REQUIRED

style-id     CDATA #IMPLIED

filteredFrom (swt|html) >

Umożliwia połączenie ze statycznym plikiem HTML lub zewnętrznym serwisem WWW, bądź wykonanie akcji URL wprowadzenia.




Predefiniowane akcje zostaną opisane za pomocą następującego formatu:

nazwa akcji - opis akcji.
parametr akcji 1 - opis parametru.
parametr akcji 2 (opcjonalnie) - opis parametru.
parametr akcji 3 (opcjonalnie) = ("true" | "false") "false" - opis parametru; dostępne wartości to true (prawda) lub false (fałsz), gdzie false jest wartością domyślną.


Struktura wprowadzenia zawiera następujące predefiniowane akcje:

close - zamyka część wprowadzenia.
Brak wymaganych parametrów.

navigate - nawigacja po stronach wprowadzenia w określonym kierunku lub powrót do strony głównej.
direction = ("backward" | "forward" | "home") - określa kierunek nawigacji.

openBrowser - otwiera adres URL w zewnętrznej przeglądarce. Począwszy od wersji 3.1 ta akcja jest zależna od funkcji obsługi przeglądarki środowiska roboczego. Oznacza to, że wszystkie preferencje użytkownika ustawione dla przeglądarki będą akceptowane.
url - poprawny adres URL zewnętrznego serwisu WWW lub statycznego pliku HTML.
pluginId (opcjonalnie) - wymagany tylko w przypadku określenia statycznego pliku HTML. Jest to identyfikator modułu dodatkowego zawierającego ten plik.

openURL - otwiera adres URL osadzony na stronie powitania. W przypadku prezentacji SWT adres URL jest wyświetlany w przeglądarce zewnętrznej (podobnie jak w akcji openBrowser powyżej). Dostępny od wersji 3.1.
url - poprawny adres URL zewnętrznego serwisu WWW lub lokalnego pliku HTML.
pluginId (opcjonalnie) - określa identyfikator modułu dodatkowego zawierającego plik, jeśli adres URL jest względny.

runAction - uruchamia określoną akcję.
class - pełna nazwa klasy implementującej interfejs org.eclipse.ui.intro.config.IIntroAction, org.eclipse.jface.action.IAction lub org.eclipse.ui.IActionDelegate.
pluginId - identyfikator modułu dodatkowego zawierającego klasę.
standby (opcjonalnie) = ("true" | "false") "false" - wskazuje, czy po wykonaniu akcji należy ustawić wprowadzenie w trybie gotowości.
Dodatkowe parametry - dodatkowe parametry są przekazywane do akcji implementujących interfejs org.eclipse.ui.intro.config.IIntroAction.

setStandbyMode - ustawia stan części wprowadzenia.
standby = ("true" | "false") - wartość "true" powoduje ustawienie części wprowadzenia w częściowo widocznym trybie gotowości, natomiast wartość "false" powoduje, że wprowadzenie jest w pełni widoczne.

showHelp - otwiera system pomocy.
Brak wymaganych parametrów.

showHelpTopic - otwiera temat pomocy.
id - adres URL zasobu pomocy. Więcej informacji zawiera dokumentacja Javadoc dla interfejsu org.eclipse.ui.help.WorkbenchHelp.displayHelpResource.
embed (opcjonalnie) = ("true" | "false") "true" - wskazuje, że konieczne jest wyświetlenie systemu pomocy jako osadzonej części na stronie powitania. Wartość domyślna to false. Znacznik jest ignorowany w przypadku prezentacji SWT. Dostępny od wersji 3.1.
embedTarget (opcjonalnie) - ścieżka do znacznika na bieżącej stronie powitania, który zawiera treść tematu pomocy. Jeśli jest określony, atrybut embed przyjmuje domyślnie wartość true, a osadzony adres URL jest wstawiany wewnątrz znacznika div z określoną ścieżką. Ścieżka jest określana względem strony i dlatego nie powinna rozpoczynać się od identyfikatora strony. Elementy potomne znacznika div są zastępowane treścią spod danego adresu URL. Znacznik div może zostać użyty tylko raz na danej stronie jako osadzony element docelowy. Znacznik jest ignorowany w przypadku prezentacji SWT. Znacznik nie jest również obsługiwany, jeśli jako treść wprowadzenia używany jest kod XHTML. Dostępny od wersji 3.1.


showMessage - wyświetla komunikat dla użytkownika za pomocą standardowego informacyjnego okna dialogowego.
message - komunikat wyświetlany użytkownikowi.

showStandby - ustawia część wprowadzenia w tryb gotowości i wyświetla część standbyContentPart z podanymi danymi wejściowymi.
partId - identyfikator części standbyContentPart do wyświetlenia.
input - dane wejściowe do ustawienia w części standbyContentPart.

showPage - wyświetla stronę wprowadzenia o podanym identyfikatorze.
id - identyfikator strony wprowadzenia do wyświetlenia.
standby (opcjonalnie) = ("true" | "false") "false" - wskazuje, czy po wyświetleniu strony należy ustawić wprowadzenie w trybie gotowości.

Jeśli jeden z parametrów przekazanych do tych akcji zawiera znaki specjalne (tzn. nieprawidłowe znaki w adresie URL), należy zakodować je w adresie URL za pomocą kodowania adresu UTF-8. Aby odebrać te parametry w ich zdekodowanym stanie, możliwe jest użycie specjalnego parametru decode = ("true" "false") w celu wymuszenia dekodowania tych parametrów w czasie ich przetwarzania przez strukturę wprowadzenia.
Na przykład następujący adres URL wprowadzenia:
http://org.eclipse.ui.intro/showMessage?message=To+jest+komunikat
przetworzy parametr komunikatu jako "To+jest+komunikat"
natomiast adres URL
http://org.eclipse.ui.intro/showMessage?message=To+jest+komunikat&amp;decode=true
przetworzy parametr komunikatu jako "To jest komunikat".


  • style-id - sposób zaklasyfikowania tego odsyłacza do określonej kategorii, dzięki czemu możliwe jest zastosowanie wspólnego stylu.
  • filteredFrom - opcjonalny atrybut umożliwiający odfiltrowanie danego elementu z konkretnej implementacji. Na przykład jeśli grupa ma atrybut filteredFrom = swt, nie będzie ona wyświetlana jako treść w implementacji SWT.
  • 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

    Bezpośredni kod HTML do uwzględnienia na stronie poprzez osadzenie całego dokumentu lub wstawienie fragmentu kodu HTML. Należy zdefiniować obraz lub tekst awaryjny na potrzeby renderowania alternatywnej prezentacji SWT.
    Osadzanie umożliwia uwzględnienie w pełni zdefiniowanego pliku HTML w treści strony dynamicznej. Tworzony jest w tym celu element HTML object, który odwołuje się do danego pliku HTML.
    Możliwe jest także dołączenie do dynamicznej strony HTML fragmentu kodu HTML bezpośrednio z pliku.


    title


    <!ELEMENT title EMPTY>

    <!ATTLIST title

    id           CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    Fragment kodu, który opcjonalnie może zawierać specjalne znaczniki HTML. Jest on używany tylko jako tytuł strony, więc dana strona może zawierać maksymalnie jeden element title.


    text


    <!ELEMENT text EMPTY>

    <!ATTLIST text

    id           CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    Fragment kodu, który opcjonalnie może zawierać specjalne znaczniki HTML. W kodzie mogą znajdować się znaczniki b i li, a także zakotwiczenia adresów URL. Jeśli konieczne jest użycie wielu akapitów, można podzielić tekst na wiele sekcji rozpoczynających się i kończących znacznikiem p.


    include


    <!ELEMENT include EMPTY>

    <!ATTLIST include

    configId    CDATA #IMPLIED

    path        CDATA #REQUIRED

    merge-style (true | false) >

    Rozwija element wskazywany przez daną ścieżkę i opcjonalne atrybuty configId. Ścieżka powinna jednoznacznie adresować element w określonej konfiguracji. Ścieżka może wskazywać współużytkowaną grupę zdefiniowaną na poziomie konfiguracji bądź dowolny element na stronie.


    head


    <!ELEMENT head EMPTY>

    <!ATTLIST head

    src CDATA #REQUIRED>

    encoding     CDATA #IMPLIED

    Jest to bezpośredni kod HTML, który zostanie dołączony do obszaru treści HEAD na stronie. Umożliwia to dołączenie dodatkowego kodu HTML do sekcji HTML HEAD. Pozwala to dodawać skrypty Java lub arkusze stylów. Ten znacznik jest używany tylko w przypadku implementacji części wprowadzenia opartego na kodzie HTML. Znacznik jest ignorowany w przypadku implementacji w postaci formularzy interfejsu użytkownika. Strona może zawierać więcej niż jeden element head. W implementacji może znajdować się tylko jeden element head, ponieważ jest ona współużytkowana przez wszystkie strony.


    img


    <!ELEMENT img EMPTY>

    <!ATTLIST img

    id           CDATA #REQUIRED

    src          CDATA #REQUIRED

    alt          CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    Obraz reprezentujący treść wprowadzenia, a nie prezentację (w przeciwieństwie do obrazów dekoracji definiowanych w stylach).


    extensionContent


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

    <!ATTLIST extensionContent

    style     CDATA #IMPLIED

    alt-style CDATA #IMPLIED

    path      CDATA #REQUIRED>

    Treść, którą należy dodać do docelowego zakotwiczenia. Tylko jeden element extensionContent jest dozwolony w danym rozszerzeniu configExtension, ponieważ gdy nie można rozpoznać tego rozszerzenia (jeśli nie znaleziono konfiguracji lub docelowego elementu zakotwiczenia), konieczne jest zignorowanie stron i/lub grup w rozszerzeniu.


    anchor


    <!ELEMENT anchor EMPTY>

    <!ATTLIST anchor

    id CDATA #REQUIRED>

    Element anchor służy do definiowania rozszerzalności. Jest to miejsce w konfiguracji umożliwiające dołączenie zewnętrznych elementów dodatkowych. Zakotwiczenia są jedynymi poprawnymi wartościami docelowymi atrybutu path w elemencie extensionContent.


    contentProvider

     

    <!ELEMENT contentProvider (text)>

    <!ATTLIST contentProvider

    id       CDATA #REQUIRED

    pluginId CDATA #IMPLIED

    class    CDATA #REQUIRED>

     

    Serwer proxy dostawcy treści wprowadzenia, który umożliwia stronie wprowadzenia dynamiczne pobieranie danych z różnych źródeł (np. z sieci WWW lub platformy Eclipse) oraz udostępnianie treści w czasie wykonywania w zależności od tych danych dynamicznych. Jeśli nie można załadować klasy IIntroContentProvider, którą określono w atrybucie class, wyrenderowana zostanie treść elementu text. Jest to dynamiczna wersja znacznika wprowadzenia HTML. Znacznik HTML umożliwia osadzanie lub wstawianie statycznej treści HTML do wygenerowanej strony HTML wprowadzenia, natomiast znacznik contentProvider umożliwia dynamiczne tworzenie takiej treści w czasie wykonywania. Kolejną różnicą między tymi znacznikami jest fakt, że znacznik HTML jest obsługiwany tylko przez prezentacje HTML, podczas gdy znacznik contentProvider jest obsługiwany przez prezentacje HTML i SWT. Dostępne od wersji 3.0.1.