Erstellen einer Online Hilfe: Unterschied zwischen den Versionen

Aus Eclipse
Wechseln zu: Navigation, Suche
Zeile 288: Zeile 288:
  
 
= Weiterführende Artikel =
 
= Weiterführende Artikel =
[[]]
+
[[Integration von Hilfe in Eclipse]]
[[Dokumentation und Hilfe|Hauptartikel zu Dokumentation und Hilfe]]
+
[[Dokumentation und Hilfe]]
  
 
[[Kategorie:Hilfe]]
 
[[Kategorie:Hilfe]]

Version vom 11. Juli 2010, 12:59 Uhr

Erstellen des Help Plug-Ins

Im Folgenden werden wir das Erstellen einer rudimentären Hilfe-Dokumentation, Ihre Gliederung im Filesystem sowie die Verlinkung mit den Controls der Anwendung behandeln. Da das Helpwindow nur eine andere Aufbereitung der Informationen des Helpviews ist werden wir im Folgenden die Erstellung eines Hilfe-Plug-Ins mit Inhalten für den Helpview, bzw. die Infopops und damit natürlich dann auch für das Helpwindow behandeln.

Wenn man die in Eclipse angebotene Hilfe erweitern möchte, muss man dazu ein weiteres Plug-In erstellen. Eclipse bietet dazu fertige Vorlagen an, die einem einen gewissen Grundstock bereitstellen. Wir werden also zunächst das Grundgerüst für unser Hilfe-Plug-In erstellen.

1. Dazu erstellen wir zunächst ein neues Plug-In.

Auswählen des Plug-in Project Wizards

2. Danach benennen wir das Plug-In. Wir nennen es de.test.HelloWorldHelpPlugin.

Benennen des Plug-Ins

3. Als Template wählen wir uns das Plug-in with sample help content, so bekommen wir die benötigte Infrastruktur gleich aufbereitet.

Auswählen des Plug-In-Templates

4. Nun müssen wir festlegen, welche Art TOC (Table of Contents) wir generiert bekommen wollen. Wir haben die Wahl zwischen einem einfachen TOC-File mit einer Unterhierarchie-Ebene,

Einfache Hierarchie

oder einer komplexeren Struktur, die uns schon die in der Eclipse Hilfe verwendeten Unterkategorien erzeugt.

Einfache Hierarchie mit mehr Kategorien

Wir entscheiden uns aus Gründen der Übersichtlichkeit für die einfachere Variante.

5. Nach einem Klick auf Finish ist das Hilfe-Plug-In-Projekt generiert und zur Anpassung nach unseren Vorstellungen bereit. An den Extensions lässt sich schön erkennen, dass sich unser Hilfe-Projekt auf den Extension-Point org.eclipse.help.toc stützt.

Die Extensions eines Hilfe-Plug-Ins

6. Auch die Hilfe können wir wieder, wie ein normales Plug-In testen, indem wir Run As, sowie Eclipse Application aus dem Kontextmenü des Plug-Ins wählen. In der geöffneten neuen Eclipse Plattform finden wir in der Hilfe die Topics unseres Plug-Ins.

Test des Hilfe-Plug-Ins

Dateien des Hilfe-Plug-Ins

Nach Erstellen des Plug-Ins finden wir folgende Struktur im Package-Explorer vor (wenn wir die Vorarbeiten ausgeführt haben):

Die Struktur des Help-Plug-Ins


plugin.xml

In der generierten plugin.xml finden wir als genutzten Extension-Point wie bereits angesprochen den Punkt org.eclipse.help.toc. Dieser Extension-Point wird parametrisiert mit den xml-files, welche die TOC (Table of Contents) bilden, in unserem Beispiel toc.xml und testToc.xml.

<?xml version="1.0" encoding="UTF-8"?>
<?Eclipse version="3.4"?>
<plugin>
 
   <extension
         point="org.Eclipse.help.toc">
      <toc
            file="toc.xml">
      </toc>
      <toc
            file="testToc.xml"
            primary="true">
      </toc>
   </extension>
 
</plugin>

Das Elements <toc> stellt die Attribute File und primary bereit. File nimmt den Filenamen eines toc-xml files auf. Primary zeigt an, ob diese table of contents auf oberster Ebene im Eclipse Hilfe-Baum angezeigt werden soll, oder nicht. Wenn ein TOC file weder primary gesetzt, noch von einem anderen referenziert wird, erscheint es nicht im Eclipse Hilfe-Baum.

Beachte: Alle toc-files, die benutzt werden sollen müssen hier deklariert werden.

In der generierten plugin.xml werden also die Punkte aus testToc.xml auf oberster Ebene angezeigt. Laut obigem Bild müssten wir also "Test TOC" als Label in diesem xml File finden.

<tocname>.xml

Ein Beispiel für ein TOC file:

<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.Eclipse.help.toc"?>
 
<toc label="Test TOC" topic="html/toc.html">
	<link toc="toc.xml" />
</toc>

Wir erkennen am Label des ersten toc-elements, dass wir mit unserer vorherigen Vermutung richtig lagen.

Wie ist nun also ein toc-xml-file aufgebaut.

Das Element <toc> beschreibt einen Eintrag im Inhaltsverzeichnis der Eclipse Hilfe. Das Attribut label enthält seinen Namen und das Attribut topic das Dokument, das bei der Aktivierung des Eintrags visualisiert werden soll. In unserem Beispiel nimmt das Element <toc> noch ein Subelement <link> auf. Das Element <link> beschreibt, welche weitere toc-xml hierarchisch unter der aktuellen eingeordnet wird. In unserem Beispiel ist das die datei toc.xml:

<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.Eclipse.help.toc"?>
 
<toc label="Sample Table of Contents">
	<topic label="Main Topic"  href="html/maintopic.html"> 
		<topic label="Sub Topic" href="html/subtopic.html"/> 
	</topic>
	<topic label="Main Topic 2"/>
</toc>

Hier wird <topic> als Element eingeführt (beim Element <toc> war es als Attribut definiert). Während <toc> mit seinem Attribut topic einen Text (und nähere Erläuterungen) spezifiziert, der im Inhaltsverzeichnis der Eclipse-Hilfe erscheinen soll, spezifiziert das Element <topic> einen konkreten Artikel in der Eclipse-Hilfe. Wie man aus obigem Beispiel erkennt, können auch <topic> Elemente verschachtelt werden. Ein <topic> Element wird nur dann im Hilfe-Baum visualisiert, wenn es ein href Attribut mit anzuzeigendem Dokument beinhaltet. Das Element <topic label="MainTopic 2"/> erscheint folglich nicht im Baum.


html - Dateien

Sie enthalten die eigentlichen Hilfe-Dokumente, die angezeigt werden, wenn der entsprechende Eintrag in der Hilfe aktiviert wird. Auch die Verwendung von aktiven Inhalten ist mittlerweile möglich, darauf wird im Rahmen dieses Artikels nicht näher eingegangen, sondern auf Eclipse.org verwiesen. Die Organisation der Hilfe-Dokumente innerhalb des Plug-Ins ist einfach. Die html-Dateien werden in den Projekt-Unterordner html abgelegt. Eine hierarchische Struktur ist hier möglich, sie muss aber in den href-Attributen berücksichtigt werden.


Bis hier haben wir nun eine statische Hilfe-Struktur erzeugt, die in der Eclipse-Hilfe angezeigt werden kann. Der nächste Abschnitt wird sich nun mit der kontextsensitiven Hilfe zu Eclipse beschäftigen.

Kontextsensitive Hilfe

Kontextsensitive Hilfe ermöglicht dem User quasi "zur Laufzeit" Hilfe zum aktuell aktivierten UI-Element anzufordern. In der Regel werden die jeweiligen Controls dazu mit einem sog. Anker versehen, der wiederum auf einen Topic in der Hilfe verweist. Wie dieses "Anker-Prinzip" in Eclipse umgesetzt wurde soll der folgende Abschnitt des Artikels erläutern.

Das Anker-Prinzip in Eclipse - Context IDs

Eclipse nutzt sogenannte context IDs, um Hilfe-Inhalte zu referenzieren.

Aufbau einer context ID:
<plug-in-id>.<local-context-id>
<plug-in-id>: In der Regel der Packagename des Plug-Ins. In unserem Fall also de.test.HelloWorldPlugin
<local-context-id>: Name des Kontextes (also Kommandos), der assoziiert werden soll. Für unseren Button 
                  in der Toolbar bspw. sampleCommand. Die <local-context-id> darf  KEINEN Punkt 
                  enthalten, nur alphanummerische Zeichen und den Underscore.
Die Id unseres Toolbar-Buttons wäre also bspw. de.test.HelloWorldPlugin.sampleCommand.

Assoziieren von Context IDs mit UI-Controls

Nachdem nun klar ist, wie wir die context ID bilden muss jetzt noch geklärt werden, wie wir den Zusammenhang zwischen einer Context ID, einem UI-Control und einer Hilfe-Sektion festlegen.

Der einfachste Weg ist, in der plugin.xml Definition des Controls die helpContextId gleich mit zu vergeben.


In der plugin.xml unseres Beispiels sähe das dann wie folgt aus:

<?xml version="1.0" encoding="UTF-8"?>
<?Eclipse version="3.4"?>
<plugin>
   ...
   <extension
         point="org.Eclipse.ui.menus">
      <menuContribution
            locationURI="menu:org.Eclipse.ui.main.menu?after=additions">
         <menu
               label="Sample Menu"
               mnemonic="M"
               id="de.test.HelloWorldPlugin.menus.sampleMenu">
            <command
                  commandId="de.test.HelloWorldPlugin.commands.sampleCommand"
                  mnemonic="S"
                  id="de.test.HelloWorldPlugin.menus.sampleCommand"
                  helpContextId="de.test.HelloWorldPlugin.sampleCommand">
            </command>
         </menu>
      </menuContribution>
      ...
   </extension>
 
</plugin>

Für UI-Controls, die nicht in der plugin.xml aufscheinen muss auf die IWorkbenchHelpSystem API zurückgegriffen werden. Dazu muss man folgende Schritte gehen:

/* Referenz auf das Hilfesystem besorgen */
IWorkbenchHelpSystem helpSystem = de.test.helloworldplugin.Activator.getDefault().getWorkbench().getHelpSystem();
/* Hilfe ID mit dem gewünschten Control verheiraten (exitButton ist in diesem Fall ein Control des Typs
   org.Eclipse.swt.widgets.Button */
helpSystem.setHelp(exitButton, "de.test.HelloWorldPlugin.toolbars.sampleCommand");

Diese Initialisierung macht man am besten an der Stelle, an der das Control definiert wird, also üblicherweise bei der Initialisierung des entsprechenden views, bzw. Dialogs.

Ein "schlechtes" Beispiel, in dem wir einfach in unserem Sample-Command-Handler ein neues Control erzeugen und ihm einen Hilfe-Kontext zuweisen verdeutlicht die Anwendung der API:

public Object execute(ExecutionEvent event) throws ExecutionException {
		IWorkbenchWindow window = HandlerUtil.getActiveWorkbenchWindowChecked(event);
		MessageDialog.openInformation(
				window.getShell(),
				"HelloWorldPlugin",
				"Hello, Eclipse world");
 
 
                /* Wir besorgen uns eine neue Shell mit dem aktuellen Display-Kontext */
                Shell shell = new Shell(de.test.helloworldplugin.Activator.getDefault().getWorkbench().getDisplay());
		shell.setText("Hello World");
		shell.setBounds(100,100,100,100);
		shell.setLayout(new FillLayout());
 
                /* und pflanzen einen Button hinein */
		Button exitButton = new Button(shell,0);
		exitButton.setText("SampleText");
		shell.open();
 
                /* Dieser Button wird nun mit unserem Hilfe-System verknüpft. Ein Klick auf den Button und Druck auf F1 öffnet die Hilfe */
		IWorkbenchHelpSystem helpSystem = de.test.helloworldplugin.Activator.getDefault().getWorkbench().getHelpSystem();
		helpSystem.setHelp(exitButton, "de.test.HelloWorldPlugin.sampleCommand");
 
		while(!shell.isDisposed()){
			if(!de.test.helloworldplugin.Activator.getDefault().getWorkbench().getDisplay().readAndDispatch()){
				de.test.helloworldplugin.Activator.getDefault().getWorkbench().getDisplay().sleep();
			}
		}
		return null;
	}

Assoziieren von Context IDs mit Help Content

Um nun noch die korrekte Hilfe-Information anzeigen zu lassen ist es noch notwendig, dem Hilfe Plug-In zu sagen, welcher Abschnitt der Hilfe-Dateien mit welcher context ID zusammengehört.

Dazu erstellen wir ein File im root-Verzeichnis des HelloWorldHelpPlugins und nennen es context.xml

<contexts>
  <context id="sampleCommand">
    <description>Dies ist die Hilfe unseres Toolbar Buttons</description>
    <topic href="html/maintopic.html"
           label="Toolbar->MainTopic!"/>
    <topic href="html/subtopic"
           label="Oder Toolbar->Subtopic"/>
  </context>
</contexts>
Aufbau einer contexts.xml:
<contexts>: Elternelement für alle vergebenen Context IDs
<context>: enthält als Attribut id die oben erwähnte <local_context_id>  
<description>: "Überschrift" des angezeigten Infopops 
<topic>: linkt über das href-Attribut die Hilfe-html-Dokumente wie in den toc-files angegeben. Das label Attribut enthält 
               den als Link anzuzeigenden Text.


Bekanntmachen der contexts.xml als Extension

Abschließend muss man im Hilfe Plug-In die Datei contexts.xml noch als Extension-Parameter bekannt machen. Dies trägt man in unserem Beispiel einfach in die plugin.xml des Projektes HelloWorldHelpPlugin ein. Sie sollte dann wie folgt aussehen:

<?xml version="1.0" encoding="UTF-8"?>
<?Eclipse version="3.4"?>
<plugin>
   <extension
         point="org.Eclipse.help.toc">
      <toc
            file="toc.xml">
      </toc>
      <toc
            file="testToc.xml"
            primary="true">
      </toc>
   </extension>
   <extension
         point="org.Eclipse.help.contexts">
      <contexts
            file="contexts.xml"
            plugin="de.test.HelloWorldPlugin">
      </contexts>
   </extension>
 
</plugin>
Die zu definierende Extension heißt org.Eclipse.help.contexts. Sie verlangt als Parameter:
<contexts> mit den Attributen:
file: enthält den Filenamen unserer contexts.xml
plugin: für welches Plug-In soll die Kontext-Definition gelten. In unserem Fall für das HelloWorldPlugin.

Ergebnis

Wurde die Hilfe nach diesem Tutorial innerhalb des Beispielworkspaces erstellt, sollte das Ergebnis wie folgt aussehen:

Wenn der User Hilfe zu unserem Menüpunkt anfordert, wird er gleich mit einem Infopop bedacht:

Hilfe zum SampleMenu

Nun kann er auswählen, ob er lieber in der dynamischen Hilfe stöbern möchte:

Nach einem Klick auf Dynamic Help

Oder, ob er einen speziellen Punkt in der Hilfe direkt anspringen möchte:

Klick auf einen der Topics

Unsere für den Button programmierte Hilfe funktioniert natürlich auch. Allerdings haben wir, da wir eine neue Shell generiert haben natürlich keinen Zugriff auf die dynamische Hilfe in Eclipse. Aber Eclipse ist so schlau und bietet diese Option gar nicht erst an.

Hilfe zum neuen Button


Infopops werden also automatisch aus den Einträgen der contexts.xml generiert.

Marker Hilfe

Auch für die Eclipse Marker kann zusätzlich eine Hilfe angeboten werden. Dazu muss der Extension-Point org.Eclipse.ui.ide.markerHelp erweitert werden. Je nach markertyp kann man eine helpContextId zuweisen.

Ein Beispiel:

<extension point="org.Eclipse.ui.ide.markerHelp">
  <markerHelp markerType="de.test.auditmarker" helpContextId="de.test.HelloWorldPlugin.SampleCommand">
    <attribute name="violation" value="1"/>
  </markerHelp>
</extension>

Weiterführende Artikel

Integration von Hilfe in Eclipse Dokumentation und Hilfe