Kontextbezogene Hilfe wird beschrieben, indem der im Code der Benutzerschnittstelle deklarierten Kontext-ID eine Beschreibung sowie eine Liste von Links zu verwandten Themen in der Onlinehilfefunktion zugeordnet wird. Diese Zuordnungen werden innerhalb einer XML-Datei durchgeführt. Für jedes Plug-in können Sie eine beliebige Anzahl von XML-Dateien mit Zuordnungen für Kontexthilfen erstellen. Beschreibung und Links jeder Kontext-ID werden innerhalb der <Kontext>elemente der XML-Datei bereitgestellt. Jedes Kontextelement kann über ein optionales <Beschreibungs>element verfügen, in dem das Benutzerschnittstellenobjekt beschrieben wird, sowie über <Themen>elemente, die Links zur Onlinedokumentation bereitstellen.
Ab Version 3.1 können Kontextelemente optional den zur Darstellung der Informationen der Kontexthilfe in der Hilfesicht verwendeten Standardtitel überschreiben.
<contexts> <context id="panic_button" title="Panic Button Title"> <description>This is the panic button.</description> <topic href="tasks/pushing_the_panic_button.htm" label="Pushing the panic button"/> <topic href="reference/panic_button.htm" label="Panic Button Reference"/> </context> ... </contexts>
Sobald die Kontexte in der XML-Datei (oder den XML-Dateien) beschrieben wurden, können Sie in Ihrem Plug-in-Manifest auf die Kontextdateien verweisen. Beachten Sie, dass im obigen Beispiel die Kontext-ID nicht vollständig qualifiziert ist. Dies ist zulässig, solange die Kontextdatei in dem Manifest des Plug-ins, das die Kontext-ID definiert hat, ergänzt wird. In anderen Worten: die Kontext-ID wird zur ID des Plug-ins aufgelöst, das die XML-Datei ergänzt hat.
Zur Ergänzung von Kontextdateien verwendet ein Plug-in den Erweiterungspunkt org.eclipse.help.contexts.
<extension point="org.eclipse.help.contexts"> <contexts name="myContextHelp.xml" /> </extension>
Sie können auch aus anderen Plug-ins auf Kontextdateien verweisen, indem Sie das Attribut plugin aufnehmen. Hierdurch können Sie die gesamte Dokumentation (einschließlich der kontextbezogenen Hilfe) in einem gemeinsamen Plug-in zusammenfassen und dann aus dem Plug-in für den Benutzerschnittstellencode oder einem anderen zugehörigen Plug-in auf dieses Plug-in verweisen.
<extension point="org.eclipse.help.contexts"> <contexts name="myContextHelp.xml" plugin="com.example.helpExample" /> </extension>
Wie Sie sehen, haben Sie einen großen Spielraum, wenn es darum geht, Ihre Kontexte in eine oder mehrere Dateien in einem oder mehreren Plug-ins zu organisieren. Wesentlich ist nur, dass die Kontext-IDs der Dateien korrekt aufgelöst werden. Wenn Sie eine Kontext-ID nicht vollständig qualifizieren, müssen Sie die Kontext-XML-Dateien in dem Plug-in ergänzen, das die Kontext-IDs deklariert hat. Wenn Sie vollständig qualifizierte Kontext-IDs verwenden, haben Sie völlige Freiheit, was die Position Ihrer XML-Dateien und die Wahl des Plug-ins, das die Kontext ergänzt, angeht.
Eine weitere Flexibilitätsstufe ergibt sich dadurch, dass die kontextbezogene Hilfe für dieselbe Kontext-ID aus unterschiedlichen Plug-ins ergänzt werden kann. Dies ist beispielsweise dann hilfreich, wenn es Plug-ins für verschiedene Dokumentationsgruppen gibt, die in der Konfiguration eines Benutzers installiert werden können, jedoch nicht installiert werden müssen. Auf diese Weise kann jedes Dokumentations-Plug-in seine Kontexte unabhängig deklarieren. Für den Endbenutzer wird der zusammengeführte Inhalt der kontextbezogenen Hilfe aller Plug-ins angezeigt, die Kontexte für die ID des Fensterobjekts ergänzen.
Bitte beachten Sie, dass die vollständig qualifizierte Kontext-ID für das Fensterobjekt verwendet werden muss, da keines der Dokumentations-Plug-ins die Kontext-ID deklariert hat. Wenn mehrere Plug-ins kontextbezogene Hilfe für dieselbe Kontext-ID bereitstellen, wird zunächst der Inhalt angezeigt, der in dem Plug-in definiert ist, das den Kontext deklariert hat (das Plug-in für die Benutzerschnittstelle). Die Reihenfolge, in der zusätzliche Beschreibungen und Links angehängt werden, kann nicht garantiert werden.
Dynamischer Inhalt
Dynamischer Inhalt ist für die Kontexthilfe in Form von Filtern für Links zu Kontexthilfethemen verfügbar. Er kann beispielsweise dann eingesetzt werden, wenn Sie einen Themalink in der Kontexthilfe nur bei der Ausführung unter einem bestimmten Betriebssystem anzeigen wollen.