Untertitel: Hilfesysteme entwickeln
Einleitung:
Kaum ein Softwareprojekt kann heute auf die Erstellung eines Hilfesystems (Online-Help) verzichten. Dazu muss man sich in ein Autorensystem einarbeiten. Dies bedeutet ein enormer Zeit- und Kostenaufwand für das Projekt. Mit Java Help stellt die Firma Sun diverse Tools zur Vereinfachung des Entwicklungsprozessess bereit. Mittels Java Help kann ein Entwickler sehr schnell ein Hilfesystem umsetzen.
Einführung:
Mittels eines Hilfesystems kann ein Anwender sich schnellstmöglich in ein Softwaresystem einarbeiten. Dessen Realisierung läßt sich mit Java Help vereinfachen.
Der Aufbau eines Hilfesystems ist fast immer der gleiche, dadurch ist der Entwicklungsprozess automatisierbar. Standardmäßig verfügt jedes Hilfesystem über einen einzelnen Anzeigebereich und diverse Navigationsbereiche. Nach Auswahl wird der jeweilige Hilfetext
im Anzeigebereich dargestellt. Über die einzelnen Navigationsbereiche werden dem Anwender möglichst schnelle Zugriffe auf bestimmte Hilfeinformationen angeboten. Im Navigationsbereich wird je nach Situation das Inhaltsverzeichnis, der Index oder eine Suchmaschine eingeblendet. Das Inhaltsverzeichnis listet die einzelnen Kapitel auf. Natürlich hat jedes Kapitel seinen eigenen Kapitelaufbau, der über eine Baumstruktur dargestellt wird. Über den Index findet man alle wichtigen Schlagwörter aller Hilfedokumente. Mittels der Volltextsuche kann der Anwender nach bestimmten Begriffen suchen.
Java Help
Java Help kennt laut Definition zwei Arten von Architekturen, indem ein Hilfesystem ablaufen kann. Entweder ist das Hilfesystem direkt in der Anwendung integriert oder läuft vollständig unabhängig von der Anwendung. Jedes Hilfeprogramm (JavaHelpSystem) besteht aus einer Vielzahl von Komponenten (Anzeige- und Navigationskomponenten). Diese sind als Java Klasse (HelpViewer, JHelp, Navigators) innerhalb der Java Help API realisiert. Dabei ist Java Help so konzipiert, dass es sich flexibel erweitern läßt. Besonders flexibel läßt sich ein Java Help System im Netzwerkbereich einsetzen. Dabei kann das Hilfesystem beisielsweise lokal ablaufen, während es seine Daten aus dem
Netzwerk bezieht. Java Help stellt bereits eine Referenzimplementierung zur Demonstration zur Verfügung. Ein Entwickler kann dieses Implementierung als Schablone nutzen und so schnellstmöglich seine Applikationen mit einem Online Hilfesystem ausstatten. Java Help bietet eine 100% Javalösung. Diese ist auf jede Plattform lauffähig, wo eine JRE (Java Runtime Environment) verfügbar ist.
Die Java Help Software
Leider lässt sich Java Help nicht sofort nutzen, da es sich um eine Standarderweiterung handelt. Es kann von der Website: www.javasoft.com herunterladen werden. Dort ist auch die komplette Dokumentation zu Java Help vorhanden. Um die Erweiterung nutzen zu können, ist sie in das jeweilige Entwicklungssystem zu importieren. Nun stehen die neuen Java Help Klassen zur Programmierung bereit. Mittels der JavaHelp-API lassen sich Hilfesysteme für Java Applikationen, Java Applets und Java Beans realisieren. Zusätzlich liefert Java Help zur Vereinfachung der Entwicklung eine Reihe von Tools mit. Das Tool “HSViewer” ist in der Lage, mit Hilfe aller Hilfebeschreibungsdateien das Hilfesystem darzustellen. Es ist also nicht nötig, ein Java Programm zu schreiben.
Die ersten Schritte
Bevor das Hilfesystem umgesetzt werden kann, muß man sich zuerst Gedanken über den Aufbau der Hilfetexte machen. Jede Hilfe verfügt über eine Reihe von Kapiteln, die sich unterschiedliche Thematiken widmen. Deren Aufbau muß einen logischen und abgeschlossenen Zusammenhang letzlich ergeben. Jedes Kapitel ist dabei als gewöhnliches HTML Dokumentenformat abgelegt. Im Java Help Termini wird jedes Kapitel als Topic bezeichnet. Damit das Java Help System jedes Hilfedokument einwandfrei identifizieren kann, existiert eine sogenannte Topic-Kennung. Alle Topics sind in der MAP – Datei zentral erfaßt. Dort ist jedem HTML Hilfedokument eine eindeutige Topic zugeordnet. Der Aufbau solch einer Datei ist in Listing #1 zu sehen.
Listing #1: Datei: "MAP.jhm"
<?xml version='1.0' encoding='ISO-8859-1' standalone='yes' ?>
<!DOCTYPE map
PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 1.0//EN"
"http://java.sun.com/products/javahelp/map_1_0.dtd">
<map version="1.0">
<mapID target="help.Einführung" url="Einführung.html" />
<mapID target="help.Detail" url="Detail.html" />
<mapID target="help.Einleitung " url="Einleitung.html" />
<mapID target="help.Grundlagen" url="Grundlagen.html" />
<mapID target="help.Aufbau" url="Aufbau_eines_Hilfesystems.html" />
<mapID target="help.Software" url="Die_Java_Help_Software.html" />
<mapID target="help.Überblick" url="Überblick_über_Java_Help.html" />
<mapID target="help.API" url="Die_Java_Help_API.html" />
</map>
<tocitem text="Einführung in JavaHelp" target="javahelp.intro"/>
Aufbau eines Java Help – Hilfe
Java Help führt eine Standisierung ein, wie die einzelnen Hilfedokumente organisiert sein müssen, um ein Hilfesystem zu realisieren. Durch eine Vielzahl von Dokumenten bzw. Beschreibungsdateien wird der Aufbau des Hilfesystems im Detail beschrieben. Hier wird festgelegt, welche Hilfetexte das
Hilfesystem einsetzt, welche Komponenten im Hilfesystem verwendet werden und von welchen Komponenten die Darstellung der Hilftexte übernommen wird. Natürlich erschwert die Vielzahl der Beschreibungsdateien die Verwaltung enorm. Zur Verwaltung wurde deshalb die zentrale Hilfesatzdatei (HelpSet) eingeführt. Dort sind der Reihe nach die Dateien für das Inhaltsverzeichnis und den Index angegeben und über welche Anzeigekomponenten (verschiedene Java-Klassen) die Darstellung erfolgt. Zusätzlich ist die MAP-Datei angegeben, wo alle Hilfedokumente der Hilfe zusammengefaßt abgelegt sind. Um die HelpSet-Datei möglichst einfach aufzubauen, wird zur Beschreibung die Sprache XML (Extension Markup Language) verwendet. Dem Entwickler wird die Arbeit so enorm vereinfacht. Der exemplarische Aufbau solch einer HelpSet-Datei ist in Listing #2 zu sehen.
#Datei: HelpSet.hs#
<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE helpset
<helpset version="1.0">
<!-- title -->
<title>Java Help im Detail</title>
<!-- maps -->
<maps>
<homeID>top</heimatsID>
<mapref location="MAP.jhm"/>
</maps>
<!-- views -->
<view>
<name>Das Inhaltsverzeichnis</name>
<label>Inhaltsverzeichnis </label>
<type>javax.help.TOCView</type>
<data>Inhalt.xml</data>
</view>
<view>
<name>Das Indexverzeichnis</name>
<label>Indexverzeichnis</label>
<type>javax.help.IndexView</type>
<data>Index.xml</data>
</view>
</helpset>
Das Inhaltsverzeichnis
Nun ist das Inhaltsverzeichnis noch zu definieren. Es wird ebenfalls in der XML
Beschreibungssprache definiert. Mittels des Tags <TOC> ist angegeben, daß es sich um
eine Inhaltsdatei (table of content) handelt. Über den Tag <tocitem> werden die
einzelnen Kapiteleinträge aufgenommen.
Über den Tag <image> läßt sich angegeben, daß ein konkreter Eintrag über ein
Bildsymbol verfügen soll. Mit dem Tag <target> läßt sich angeben, welche Seite
anzuzeigen ist, wenn der Eintrag ausgewählt wird. Mittels weniger Tags ist das
Inhaltsverzeichnis somit definiert.
#Datei: Inhalt.xml#
<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE toc
PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp TOC Version 1.0//EN"
"http://java.sun.com/products/javahelp/toc_1_0.dtd">
<toc version="1.0">
<tocitem text="Java Help" image="toplevelfolder">
<tocitem text="Einführung in JavaHelp" target="help.Einführung"/>
<tocitem text="JavaHelp im Detail" target="help.Detail">
<tocitem text="Einleitung" target="help.Einleitung"/>
<tocitem text="Grundlegendes zu Hilfesystemen" target="help.Grundlagen"/>
<tocitem text="Aufbau eines Hilfesystems" target="help.Aufbau"/>
<tocitem text="Die JavaHelp Software" target="help.Software"/>
<tocitem text="Überblick über JavaHelp" target="help.Überblick"/>
<tocitem text="Die JavaHelp API" target="help.api "/>
</tocitem>
</toc>>
Die Java Help API
Damit eine Applikation die einzelnen notwendigen Hilfedateien möglichst leicht ansteuern kann, stellt die Java Help API die zentrale Klasse HelpSet hier bereit. Diese Klasse kapselt alle Informationen aus der HelpSet Datei. Innerhalb der HelpSet Datei sind alle notwendigen Daten für das Hilfesystem zusammengefaßt. Beim Aufruf einer Applikation wird zuerst mit Hilfe der Klasse HelpSet die Datei HelpSet geladen. Das Objekt HelpSet wird wie immer über den Konstruktor new() erzeugt. Als Argument kann eine URL Adresse angegeben werden, wo sich die HelpSet Datei befindet. Alternativ kann über die Funktion findHelpSet() im gesamten Dateisystem nach einer HelpSet Datei gesucht werden. Bei Erfolg wird eine die URL Adresse zurückgeliefert. Eine Applikation kann mehrere HelpSets einsetzen. Über die Funktion add() lassen sich weitere HelpSets hinzufügen und über die Funktion remove() bei Bedarf wieder entfernen. An alle aktuellen HelpSets gelangt die Applikation über die Funktion getHelpSets(). Diese liefert ein Objekt vom Typ Enumeration zurück und erlaubt so einen Zugriff auf die einzelnen HelpSets. Jedes HelpSet verfügt über einen Titel. Dieser kann über die Funktion getTitle() abgerufen und über die Funktion setTitle()
gesetzt werden. Standardmäßig verfügt jedes Hilfeprogramm über eine Schaltfläche, worüber man wieder zum Heimatverzeichnis gelangt. Diese Schaltfläche verfügt über eine eindeutige ID-Kennung. Mittels der Funktion getHomeID() läßt sich die Kennung abfragen und über die Funktion setHomeID() setzen. Um ein Hilfedokument intern im Hilfesystem einwandfrei identifizieren zu können, besitzt jedes Hilfedokument eine eindeutige MAP-ID-Kennung. Diese ist innerhalb der zentralen MAP Datei hinterlegt. Welcher Map Datei sich ein HelpSet bedient, kann über die Funktion getLocalMap() erfragt werden. Jedes Hilfesystem setzt bestimmte Navigatoren zur Darstellung ein. Welche Navigatoren das HelpSet verwendet, läßt sich über die Funktion getNavigatorViews() ermitteln.
Die Darstellungsebene
Nun müssen die Hilfetexte für den Endanwender dargestellt werden. Diese Aufgabe übernimmt die Klasse HelpBroker in der Java Help API. Sie zeigt die Hilfetexte an und übernimmt auch deren Verwaltung. Zur Darstellung verwendet die Klasse HelpBroker intern verschiedene Hilfebrowser - Programme (TOCView, IndexView, SearchView). Die einzelnen Browser - Programme erlauben die Navigation durch das Inhaltsverzeichnis, den Index oder die Volltextsuche zu starten. Bevor eine Anzeige erfolgen kann, muß dem HelpBroker zuerst mitgeteilt werden, auf
welcher Datenbasis die Darstellung erfolgen soll. Hier kommt die zentrale Klasse HelpSet
wie gerufen. Nur über ein HelpSet Objekt kann eine Instanz von HelpBroker erzeugt
werden. Die komplette Darstellung läuft über die HelpBroker Klasse ab. Der Entwickler wird nicht gezwungen diese Klasse zu verwenden. Er kann hier eine neue Klasse einführen. Jedoch muß der Entwickler sich dann selbst um die Ansteuerung von HelpViewer, JHelp und die Navigatoren kümmern. Diesen Aufwand wollen wir hier nicht betreiben! Welches HelpSet Objekt der HelpBroker zur Darstellung verwenden soll, läßt sich über die Funktion setHelpSet() vorgeben. Die Sprache die von der Anzeigekomponente verwendet wird, kann über die Funktion getLocale() erfragt werden. Auch die Darstellung im Hilfebrowser Programm kann beeinflusst werden. Dazu gibt es die Funktion setFont(), worüber der Zeichensatz gesetzt wird. Ebenso können verschiedene Ansichtsarten im Hilfesystem eingestellt werden. Hierzu ist setCurrentView() zuständig, worüber eine spezielle Navigationsansicht eingeblendet wird. Die Darstellung der Inhalte läßt sich gezielt über die Funktion setDisplayed() steuern. Was gerade angezeigt wird, kann über die Funktion isDisplayed() erfragt werden. Bestimmte Hilfeinhalte lassen sich gezielt einblenden. Über setCurrentID() wird der Hilfetext mit der betreffenden ID-Kennung angezeigt. Ob eine Hilfe für eine Komponente gerade zur Verfügung steht, kann über enableHelp() erfragt werden. Je nach Kontext der Anwendung ist es sinnvoll gewisse Funktionen zu deaktivieren.
Hilfe realisieren
Zur Demonstration wird eine Java Applikation "JavaHelpAnwendung" entwickelt, welches ein Hilfesystem aufruft bzw. integriert hat. Es verfügt über ein Menü, worüber das Hilfesystem aufgerufen wird. Als Erstes sind die JavaHelp Erweiterungsklassen mittels der Anweisung Import zu importieren. Nun muß die Applikation dafür sorgen, daß sie einen Zugriff auf die zahlreichen Beschreibungsdateien für das Hilfesystem erhält. Also wird mittels der Funktion findHelpSet() der Klasse HelpSet im gesamten Dateisystem nach einer konkreten HelpSet-Datei gesucht. Kann diese nicht lokalisiert werden, wird eine Exception ausgelöst und eine Fehlermeldung ausgegeben. Diese kritischen Operationen sind unbedingt in einem try-catch-Block unterzubringen, um bei Ausnahmen entsprechend reagieren zu können. Eventuelle Syntaxfehler innerhalb des HelpSets bzw. XML-Dokumentes werden erkannt. Ist der Parse Vorgang erfolgreich beendet, lassen sich weitere Operationen vornehmen. Auf der Basis der zurückgelieferten URL-Adresse zur HelpSet-Datei kann über das Schlüsselwort new() das HelpSet Objekt angelegt werden.
Mit Hilfe des HelpSet Objekts wird nun das HelpBroker Objekt erzeugt. Hierzu
wird die Funktion createHelpBroker() auf das HelpSet-Objekt angewendet und erzeugt
so den HelpBroker. Jetzt besteht eine direkte Verbindung zwischen HelpSet und dem
HelpBroker. Damit aus dem Programm heraus die Hilfe aufgerufen werden kann, wird noch ein
Hilfemenü erzeugt. Hierzu nutzen wir die Komponente JMenu aus der Swing Bibliothek.
Mittels des Schlüsselworts new() wird das JMenu (Hilfe) angelegt. Als Übergabeparameter
läßt sich der Titel des Menü vorgeben. Das Menü wird einer Menüleiste (menuBar) über die
Funktion add() hinzugefügt. Jetzt muß das Menü noch mit einem Menüeintrag
ausgestattet werden. Hierzu existiert die Komponente JMenuItem. Damit diese Komponente
auf Ereignisse reagieren kann, ist diese beim ActionListener zu registrieren.
Hiermit sind die Grundfunktionalität der Applikation beschrieben.
#Quellcode:#
import javax.help.*;
public class JavaHelpAnwendung extends JPanel implements ActionListener {
HelpSet helpset = null;
HelpBroker helpbroker;
JavaHelpAnwendung() {
try {
URL url = HelpSet.findHelpSet(null, „../HelpSet.hs“);
helpset = new HelpSet(null, url);
} catch (Exception ee) {
System.out.println ("HelpSet: "+helpsetName+" not found!");
return; }
helpbroker = helpset.createHelpBroker();
Jmenu help = new JMenu('Hilfe');
menuBar.add(help);
menu_help = new JMenuItem(helpsetLabel);
menu_help.addActionListener(new CSH.DisplayHelpFromSource(mainHB);
}
Schluss:
JavaHelp stellt eine einfache Möglichkeit zur Umsetzung eines Hilfesystems dar. Der Aufwand wird für den Entwickler über die JavaHelp API minimiert. Da diese auf Swing basiert, können verschiedene Look & Feels verwendet werden. Meist fehlt innerhalb eines Projektes die Zeit ein eigenes Hilfesystem aufzubauen. Da kommt die JavaHelp API wie gerufen. Da diese offene Standards verwendet, wird diese sich künftig wohl weiter verbreiten. Einige Dokumentationsprodukte wie RoboHelp unterstützen JavaHelp bereits.
#Bilder:#
Pic1.tif: Unser selbst entwickeltes Hilfesystem als Beispiel. Die einzelnen Kapitel werden hier im Hilfebrowser dargestellt.
Pic2.tif: Hier von der Website www.javasoft.com kann die JavaHelp API heruntergeladen werden.
Pic3.tif: Mittels dieses Programms kann auf Basis der HelpSet Datei Das komplette Hilfesystem dargestellt werden.
Pic4.tif: Die API Dokumentation von JavaHelp im Überblick.
Pic5.tif: Das Hilfebrowser Programm zeigt die komplette JavaHelp API an. Hier sind die Funktionen der Klasse HelpBroker aufgelistet.
Pic6.tif: Ein Hilfesystem mit JavaHelp kann auch in einer verteilten Umgebung ablaufen. Hier werden die Hilfedaten aus dem Netz geholt.