Konfiguracja części wprowadzenia

org.eclipse.ui.intro.config

3.0

Ten punkt rozszerzenia umożliwia rejestrowanie konfiguracji wprowadzenia. Konfiguracja ta udostępnia implementacje prezentacji i treść dla określonego wprowadzenia dodatkowego. Wprowadzenie jest wyświetlane po pierwszym uruchomieniu środowiska roboczego oraz jako opcja w menu Pomoc. Wprowadzenie służy zwykle do przedstawienia użytkownikowi produktu utworzonego na platformie Eclipse.

Wprowadzenia są zorganizowane w postaci stron, które zwykle odpowiadają konkretnej kategorii materiałów wprowadzających. Na przykład strona Co nowego może przedstawiać nowe pojęcia lub funkcje dodane w stosunku do poprzednich wersji. Do treści zdefiniowanej przez jedną konfigurację rozszerzenia można odwoływać się i rozszerzać ją z poziomu innych modułów dodatkowych przy użyciu punktu rozszerzenia org.eclipse.ui.intro.configExtension.

<!ELEMENT extension (handle? , config+)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT config (presentation)>

<!ATTLIST config

introId CDATA #REQUIRED

id      CDATA #REQUIRED

content CDATA #REQUIRED>

Za pomocą elementu config można skonfigurować dostosowywalną część wprowadzenia. W elemencie config musi być określony identyfikator konfiguracji, identyfikator wprowadzenia oraz plik treści. Plik treści wprowadzenia jest plikiem XML opisującym strony, grupy i odsyłacze.



<!ELEMENT presentation (implementation+ , launchBar?)>

<!ATTLIST presentation

home-page-id    CDATA #REQUIRED

standby-page-id CDATA #IMPLIED>

Element prezentacji, który definiuje wszystkie możliwe implementacje prezentacji danej części wprowadzenia. Może być w nim zdefiniowana jedna implementacja lub większa ich liczba. Podczas uruchamiania, na podstawie atrybutów os/ws wszystkich implementacji, zostanie wybrana tylko jedna implementacja. W przeciwnym razie zostanie wybrana pierwsza implementacja bez zdefiniowanych atrybutów os/ws.



<!ELEMENT implementation (head?)>

<!ATTLIST implementation

kind  (swt|html)

style CDATA #IMPLIED

os    CDATA #IMPLIED

ws    CDATA #IMPLIED>

Prezentacja standardowych elementów interfejsu użytkownika platformy ma dwie implementacje. Jedna z nich bazuje na przeglądarce SWT, a druga na formularzach interfejsu użytkownika. Dostosowywalną część wprowadzenia można skonfigurować w taki sposób, aby wybierana była jedna z tych implementacji w oparciu o bieżące atrybuty OS i WS. Implementacja może być typu swt lub html.



<!ELEMENT launchBar (handle? , shortcut*)>

<!ATTLIST launchBar

location (left|bottom|right|fastview) "fastview"

bg       CDATA #IMPLIED

fg       CDATA #IMPLIED>

Pasek uruchamiania działa w połączeniu z komendą switchToLaunchBar. Podczas wykonywania komendy zamyka ona wprowadzenie i tworzy pasek uruchamiania w jednym z obszarów marginesu okna głównego. Pasek uruchamiania będzie zawierać co najmniej jeden przycisk umożliwiający użytkownikom powrót do ostatniej strony wprowadzenia. Opcjonalnie może zawierać dodatkowe przyciski zdefiniowane przy użyciu elementów shortcut. Te przyciski mogą służyć do szybkiego przechodzenia do określonej strony wprowadzenia. Dostępny od wersji 3.1.



<!ELEMENT shortcut EMPTY>

<!ATTLIST shortcut

tooltip CDATA #IMPLIED

icon    CDATA #REQUIRED

url     CDATA #REQUIRED>

Dla każdego elementu shortcut utworzony zostanie przycisk na pasku uruchamiania wprowadzenia. Po naciśnięciu takiego przycisku nastąpi przejście do adresu URL zdefiniowanego w elemencie shortcut. Dostępny od wersji 3.1.



<!ELEMENT handle EMPTY>

<!ATTLIST handle

close (true | false) "true"

image CDATA #IMPLIED>

Element opcjonalny kontrolujący sposób renderowania uchwytu paska uruchamiania. Dostępny od wersji 3.1.



<!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.



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

shared-style (true | false) >

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



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

<!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.



<!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.



<!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.



<!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.



<!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.



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



<!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.



<!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.



<!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.



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

<!ATTLIST extensionContent

style     CDATA #IMPLIED

alt-style CDATA #IMPLIED

path      CDATA #REQUIRED

content   CDATA #IMPLIED>

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.



<!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.



Poniżej przedstawiono przykładowe zastosowanie punktu rozszerzenia konfiguracji.

<extension id=

"intro"

point=

"org.eclipse.ui.intro.config"

>

<config introId=

"com.org.xyz.intro"

id=

"com.org.xyz.introConfig"

content=

"introContent.xml"

>

<presentation home-page-id=

"root"

title=

"%intro.title"

>

<implementation ws=

"win32"

style=

"css/shared.css"

kind=

"html"

os=

"win32"

>

</implementation>

<implementation style=

"css/shared_swt.properties"

kind=

"swt"

>

</implementation>

</presentation>

</config>

</extension>

Bardziej szczegółowe informacje zawiera specyfikacja pakietu interfejsu API org.eclipse.ui.intro.config.

Wprowadzenie dołączone w ramach modułu dodatkowego org.eclipse.platform jest jedyną implementacją na platformie Eclipse.