Opisywanie i pakowanie treści pomocy kontekstowej

Pomoc kontekstowa jest opisywana przez powiązanie identyfikatora kontekstu zadeklarowanego w kodzie interfejsu użytkownika z opisem oraz listą odsyłaczy do tematów pomocy elektronicznej dotyczących danego elementu. Te powiązania są zapisywane w pliku XML.  Dla każdej wtyczki można utworzyć dowolną liczbę plików XML zawierających powiązania pomocy kontekstowej. Opis i odsyłacze dla każdego identyfikatora kontekstu są tworzone wewnątrz elementów <context> w pliku XML. Każdy element kontekstu może zawierać opcjonalny element <description> używany do opisywania obiektu interfejsu użytkownika oraz dowolną liczbę elementów <topic>, które odsyłają do dokumentacji w postaci elektronicznej.

Od wersji 3.1 elementy kontekstu mogą opcjonalnie przesłaniać domyślny tytuł używany do wyświetlania pomocy kontekstowej w widoku pomocy.

<contexts>
	<context id="panic_button" title="Tytuł przycisku alarmu">
		<description>To jest przycisk alarmu.</description>
		<topic href="tasks/pushing_the_panic_button.htm" label="Naciskanie przycisku alarmu"/>
		<topic href="reference/panic_button.htm" label="Informacje o przycisku alarmu"/>
	</context>
	...
</contexts>

Gdy konteksty zostały już opisane w plikach XML można się do nich odwoływać w pliku manifestu wtyczki. Należy zwrócić uwagę, że w powyższym przykładzie identyfikator kontekstu nie był pełny. Jest to dopuszczalne w sytuacji, gdy plik kontekstu jest dostarczany w manifeście wtyczki definiującej ten identyfikator kontekstu. Inaczej mówiąc, identyfikator kontekstu jest interpretowany na identyfikator wtyczki zawierającej plik XML.  

Wtyczka dodaje pliki kontekstu przy użyciu punktu rozszerzenia org.eclipse.help.contexts.  

   <extension point="org.eclipse.help.contexts">
      <contexts name="myContextHelp.xml"  />
    </extension>

Do plików kontekstu można się odwoływać z innych wtyczek, korzystając z atrybutu plugin. Pozwala to na zgrupowanie całej dokumentacji wraz z pomocą kontekstową w jednej wtyczce, do której można się odwoływać z wtyczki kodu interfejsu użytkownika lub innej związanej z nim wtyczki.

   <extension point="org.eclipse.help.contexts">
      <contexts name="myContextHelp.xml" plugin="com.example.helpExample"  />
    </extension>

Jak widać istnieje spora elastyczność w podejściu do organizowania kontekstów, które mogą znajdować się w jednym lub wielu plikach zawartych w jednej lub wielu wtyczkach. Najważniejsze jest, aby identyfikatory kontekstu były prawidłowo interpretowane w plikach. Jeśli stosowane identyfikatory kontekstu nie są pełne, należy dodać pliki XML kontekstu do wtyczki deklarującej identyfikatory kontekstu. Jeśli w pliku XML kontekstu zawarte są pełne identyfikatory kontekstu, to nie ma znaczenia, gdzie są położone pliki XML, ani która wtyczka udostępnia konteksty.

Pomoc kontekstowa z wielu wtyczek

Kolejnym stopniem elastyczności jest możliwość wnoszenia pomocy kontekstowej dla tego samego identyfikatora kontekstu z różnych wtyczek. To może być przydatne w sytuacji, gdy istnieją różne zestawy wtyczek dokumentacji, zarówno zainstalowanych, jak i niezainstalowanych w konfiguracji użytkownika. Każda wtyczka dokumentacji może dzięki temu zadeklarować niezależnie własne konteksty.  Użytkownik końcowy zobaczy treść scalonej pomocy kontekstowej dla wszystkich wtyczek wnoszących konteksty dla danego identyfikatora widgetu.

Należy zwrócić uwagę, że dla widgetu musi być zastosowany pełny identyfikator kontekstu, ponieważ żaden z wtyczek dokumentacji nie deklarował identyfikatora kontekstu. Gdy wiele wtyczek wnosi pomoc kontekstową dla tego samego identyfikatora kontekstu, treść zdefiniowana we wtyczce deklarującej kontekst (wtyczce interfejsu użytkownika) zostanie wyświetlona jako pierwsza. Dodatkowe opisy i odsyłacze są dodawane w dowolnej kolejności.

Treść dynamiczna

W przypadku pomocy kontekstowej treść dynamiczna jest dostępna w postaci filtrów stosowanych w odniesieniu do odsyłaczy pomocy kontekstowej. Istnieje na przykład możliwość wyświetlania odsyłacza do tematu w pomocy kontekstowej wyłącznie w przypadku korzystania z określonego systemu operacyjnego.