Aufbau des Dokuments

Im Kapitel Problemstellung werden die Aufgaben, die an die HTML Manipulationssoftware erfüllt werden müssen, umrissen.

Im Kapitel Lösungsansatz wird die Funktionsweise der HTML Manipulationssoftware beschrieben.

Das Kapitel Klassendiagramm beschreibt das Zusammenspiel und die Eigenschaften der eingesetzten Klassen.

Problemstellung

Die Dokumentation von VirtL besteht aus einigen kleineren HTML Dokumenten die den eigentlichen Inhalt der Seiten darstellen. Diese Seiten werden im folgenden Content genannt. Die Darstellung, und die Position der einzelnen Dokumente in der Navigationsleiste, stehen unter ständigem Wandel und müssen daher dynamisch erzeugt werden können.
Die Präsentation besteht, wie im VirtL Homepage Architekturdokument bei Homepage Bereiche beschrieben, aus drei Bereichen.

Navigationsleiste Eigenschaften

Die Navigationsleiste hat beim ersten Aufruf von VirtL zum Beispiel folgendes Aussehen:

VirtL

Anwendungsfälle

Administration

Architektur

Allgemeines

Glossar

Hilfe

VirtL

Referenz auf die Datei index.HTML

Hiermit wird auf die Startseite der VirtL Homepage verwiesen. Auf dieser Startseite finden sich erste Informationen wie die Homepage aufgebaut ist und welche Personengruppen die jeweiligen Dokumente lesen sollten.

Anwendungsfälle

Referenz auf die Datei index.html im Unterordner usecases.

Verweis auf die Untergruppe Anwendungsfälle. Wenn diese Seite aufgerufen wird soll sich die Navigationsleiste wie folgt verändern:

VirtL

Anwendungsfälle

Mobile

Stammdaten Mgmt

System Admin

User Management

Administration

Architektur

Allgemeines

Glossar

Hilfe

Der Inhalt ist wiederum eine index.html Seite die allgemeine Informationen zu den Anwendungsfällen bereithält.

Die tiefste Ebene

Bei der Auswahl einer Anwendungsfallgruppe wird auf eine index.html verwiesen bei der die Gemeinsamkeiten der Anwendungsfälle beschrieben wird. Der Navigationsbaum verändert sich wie folgt:

VirtL

Anwendungsfälle

Mobile

Stammdaten Mgmt

Allg. Stammdaten

Anbieter

Autor

Buch

CD

DVD

Genre

Interpret

Magazin

Regisseur

Schauspieler

Wunschliste

System Admin

User Management

Administration

Architektur

Allgemeines

Glossar

Hilfe

Die Navigationsleiste verändert sich bei jedem Klick und muss pro Seite angepasst werden. Es wird jeweils der selektierte Link in einer anderen Form dargestellt. Da mit mehr als achtzig Seiten zu rechnen ist, soll die Navigationsleiste einfach veränderbar sein. Weiterhin kann passieren, dass von einer liste auf Buttons umgestellt wird. Die Navigationsleiste soll daher nicht in der Content HTML Seite gepflegt werden.

Lösungsansatz

Der HTML Generator besteht aus der Ressource navigation.xml, der Property-Datei Properties.properties und den Klassen die im Kapitel HTML Generator Klassen beschrieben sind.

Für die Anwender ist vor allem die Ressource navigation.xml interessant. Hier wird der Aufbau der Navigationsleiste und die Position der einzelnen Contents hinterlegt. Der folgende Auszug zeigt den Aufbau dieser Ressource:

Der Aufbau von navigation.xml

<!-- $Id: HTMLGenerator.html,v 1.3 2006/02/25 07:13:41 rbaldenhofer Exp $ -->
<navigation project="VirtL">
	<!--The german entries which creates the /de subfolders.-->  
  	<language lang="de" text="deutsch">
		<!-- In the german root the entry name is VirtL.-->
		<directory text="VirtL" file="/de/index.html" type="static">
    			<entry text="Interpret" file="/jsp/interpret.jsp" type="dynamic"/>
		</directory>
		<!-- The howto pages. -->
   		<directory text="Howtos" file="/de/howto/index.html" type="static">
			<entry text="Dokumentationsplan" file="/de/howto/Dokumentationsplan.html" type="static"/>
			<entry text="Glossar" file="/de/howto/Glossar.html" type="static"/>
			<entry text="FAQ" file="/de/howto/FAQ.html" type="static"/> 
			<entry text="Allgemeine Infos" file="/de/howto/Infos.html" type="static"/>
			<entry text="Lizenzinfos" file="/de/howto/lizenz.html" type="static"/>
			<entry text="Kontakt" file="/de/howto/kontakt.html" type="static" manipulate="no"/>   
		</directory>
	</language>
</navigation>

Folgende Elemente beinhaltet die Ressource navigation.xml:

• navigation
  Der Root Node der Navigation.
• language
  Die Navigation kann für mehrere Sprachen erstellt werden. Die einzelnen Sprachen können unterschiedliche Navigationsleisten beinhalten. So kann es sein, dass die englische Version mehr oder weniger Content besitzt als die Deutsche.
• directory
  Mit diesem Tag wird auf eine weitere Ebene im Navigationsbaum verwiesen. Bei diesem Eintrag wird normalerweise auf eine index.html Seite in einem speziellen Verzeichnis verwiesen. Wenn der Navigationspunkt ausgewählt wird, wird diese index.html Seite angezeigt.
• entry
  Dieses Element beinhaltet einen Eintrag im Navigationsbaum der auf eine Content Seite verweist.

Die Elemente haben folgende Attribute:

naviation

• project
  Angabe zu welchem Projekt diese Navigationsleiste erzeugt werden soll. Je nachdem können unterschiedliche Verhaltensweisen und HTML Tags generiert werden. (TODO Ist im Moment noch nicht auscodiert)

language

• lang
  Angabe der zu generierenden Sprache. Der HTML Generator erzeugt pro Sprache einen eigenen Navigationsbaum.
• text
  Ein Text, der für diese Sprache angezeigt werden kann.

directory

• text
  Der Text der in der Navigationsleiste erscheinen soll.
• file
  Angabe des relativen Pfades und des Dateinamens zu der Seite, die angezeigt werden soll wenn dieser Navigationseintrag ausgewählt wird.
• type
  Angabe ob es sich um static oder um dynamic handelt. Die HTML Seiten werden statisch erzeugt und mit der Navigation versehen. Bei den jsp Seiten wird die Navigation zur Laufzeit hinzugefügt. Auf Webservern bei denen nur die HTML Präsentation dargestellt wird, wie beispielsweise Sourceforge, werden nur die statischen HTML Seiten berücksichtigt und die jsp Seiten ignoriert.
• manipulate
  Optionale Angabe. Mit no wird angegeben das dieser Eintrag nicht verändert werden soll. Hiermit kann erreicht werden, dass eine HTML Seite in mehreren Navigationsleisten vorhanden und angezeigt werden kann, die HTML Seite jedoch immer nur einer Sprache zugeordnet wird. Dieser Eintrag wird bei der Language independent benötigt um die englische und deutsche index.html Seite aufrufen zu können und diese index.html im Sprachunabhängigen Teil abbilden zu können.

entry

• text
  Der Text der in der Navigationsleiste erscheinen soll.
• file
  Angabe des relativen Pfades und des Dateinamens zu der Seite, die angezeigt werden soll wenn dieser Navigationseintrag ausgewählt wird.
• type
  Angabe ob es sich um static oder um dynamic handelt. Die HTML Seiten werden statisch erzeugt und mit der Navigation versehen. Bei den jsp Seiten wird die Navigation zur Laufzeit hinzugefügt. Auf Webservern bei denen nur die HTML Präsentation dargestellt wird, wie beispielsweise Sourceforge, werden nur die statischen HTML Seiten berücksichtigt und die jsp Seiten ignoriert.
• manipulate
  Optionale Angabe. Mit no wird angegeben das dieser Eintrag nicht verändert werden soll. Hiermit kann erreicht werden, dass eine HTML Seite in mehreren Navigationsleisten vorhanden und angezeigt werden kann, die HTML Seite jedoch immer nur einer Sprache zugeordnet wird. Dieser Eintrag wird bei der Language independent benötigt um die englische und deutsche index.html Seite aufrufen zu können und diese index.html im Sprachunabhängigen Teil abbilden zu können.

Die Eintragungen in der Content Seite

Die einzelnen Inhalte der Seiten müssen im Body in ein <div class=”content”> eingeschrieben werden. Beispiel:

<body>
<div class=”content”>
</div>
</body>

Weiterhin erwartet der Generator einen title Eintrag, um die css Referenz an dieser Stelle einzufügen.

Die Datei Properties.properties

Die Datei Properties.properties, welche sich im /src/java/ressources/ Verzeichnis befindet, beinhaltet folgende Einträge:

Property Einträge

Eintrag	Beschreibung	Beispiel
rootPath	Gibt den absoluten Pfad an, an dem der HTML Generator die Sourcen von VirtL (HTML und Java) finden kann.	rootPath=/home/roland/workspace/org.virtl
destinationPath	Relativer Pfad, der zum rootPath hinzugefügt wird um die HTML Daten auszugeben. Hier werden die Ergebnisse der HTML Generation abgelegt. Der Pfad ist standardmässig wie im Beispiel angegeben konfiguriert und sollte nicht verändert werden da die Ant Scripts diesen Pfad für das Deployment erwarten.	destinationPath=/bin/out/html
navigationXML	Relativer Pfad ab dem rootPath in dem die Ressource navigation.xml gefunden werden kann. Standardmäßig ist sie bei den Java Ressourcen abgelegt.	navigationXML=/src/java/ressources/navigation.xml
htmlPath	Relativer Pfad ab dem rootPath an dem die zu bearbeitende HTML Dokumente abgelegt sind.	htmlPath=/docs/html
language0	Die nullte Sprache muss auf independent gesetzt werden, wenn man eine sprachunabhängige Einstiegsseite mit einer speziellen Navigation erreichen will. Häufig haben die verschiedenen Sprachen verschiedene Dokumente zum Darstellen. Aus diesem Grund wurden mehrere Navigationsbäume erstellt. Die Sprachauswahl beinhaltet im Normalfall nur Verweise auf die jeweilige Sprache.	language0=independent
language1 - languageN	Die einzelnen Sprachen werden hochgezählt und mit den Kürzeln der Sprache versehen.	language1=de language2=en

Klassendiagramm

Die folgende Skizze zeigt die beteiligten HTML Generator Klassen.

Sowohl die Erstellung der statischen HTML Seiten als auch die dynamischen Seiten, die von den UseCases her generiert werden, verwenden die gleichen Schnittstellen.
Um eine Navigationsleiste herzustellen wird mit einem Factory Pattern die Erzeugung der jeweiligen Navigationsleisten generiert:

Im oberen Bereich sind die jeweiligen Klienten, wie die JSPUseCases, StaticHTMLGenerator oder die Erstellung für ein weiteres Projekt schematisch dargestellte AnotherProjectHTMLGenerator dargestellt.
Diese Klienten holen sich über die AbstractNavigationFactory eine NavigationFactory für die jeweiligen Bedürfnisse.
Die eigentlichen Navigation Generator Klassen werden von den NavigationFactories initialisiert und stehen den Klienten über die AbstractNavigation Schnittstelle zur Verfügung.

Die Navigation Factory Klassen und deren Methoden sind in folgender Grafik dargestellt. Im oberen Bereich kann der Factory Teil erkannt werden. Das Instantiieren der einzelnen Navigationsklassen wird von den Factory Klassen übernommen.
Im unteren Bereich sind die von AbstractNavigation abgeleiteten Navigationsklassen abgebildet.

Beim Erstellen der CSS Einträge wird auf die selbe Technologie gebaut. Für die Entwicklungs-, Abnahme- und Produktionsumgebung müssen unterschiedliche CSS Einträge erzeugt werden. Damit hier kein manueller Eingriff benötigt wird, werden die einzelnen statischen oder dynamischen Seiten in verschiedenen Unterordnern erzeugt und mit den jeweilig korrekten CSS-Einträgen versorgt. Hierfür müssen drei verschiedene Klassen wie VirtLSourceforgeCSS für die statische HTML Präsentation, VirtLAcceptanceCSS für die Abnahmetestumgebung und VirtLDevelopmentCSS für die Entwicklungsumgebung erstellt werden. Der Vorteil dieser Dreiteilung ist, dass völlig unterschiedliche Generierungsarten für die CSS Einträge verwendet werden, jedoch die Benutzung dieser Generierungsarten für alle Umgebungen identisch sind.

Code Beautifier

Der Code Beautifier wird dazu verwendet, die HTML Seiten um die Navigation und CSS Einträge zu erweitern sowie um die Umlaute des Contents in HTML Tags zu ersetzten. Da es für verschiedene Projekte verschiedene Navigationsleisten, CSS Einträge usw. gibt, wird der Code Beautifier ebenfalls mit einem Factory Pattern erstellt.

Klassenbeschreibung

Hier werden die Aufgaben der einzelnen verwendeten Klassen aufgelistet um das Verständnis für diese Klassen zu festigen.

Klassenbeschreibung

Klasse	Beschreibung / Aufgaben
CodeBeautifierFactory	Erzeugt die CodeBeautifier Klasse, die für das jeweilige Projekt benötigt wird.
VirtLCodeBeautifier	Die Implementation von AbstractCodeBeautifier für VirtL. Hier wird die VirtL Navigation, für die jeweilige Umgebung die CSS Einträge und die Umlaute behandelt.
AbstractCodeBeautifier	Schnittstelle um die Eigenschaften der jeweiligen CodeBeautifier normiert verwenden zu können.
SomeOtherProjectBeautifier	Dies ist keine Klasse sondern ein Platzhalter um zu beschreiben, wie die Erweiterung für weitere Projekte stattfinden soll.
CSSFactory	Erzeugt und verwaltet die jeweilige Instanz der CSS Klassen.
VirtLStaticCSS	Generiert statische CSS Einträge, bei denen als Server der Sourceforge Server eingetragen wird. Falls die statische HTML Präsentation von VirtL auf einen anderen Server umgezogen wird, kann die Position des neuen Servers in der Property Datei eingetragen werden.
VirtLAcceptanceCSS	Generiert statische CSS Einträge, bei denen der Servername der Acceptance Umgebung eingetragen wird. Diese wird beim Build jeweils in den Property Dateien eingetragen.
VirtLDevelopmentCSS	Generiert statische CSS Einträge, bei denen der Localhost als Servername eingetragen wird.
OtherProjectCSS	Platzhalter für andere Projekte. Die Grundfunktionalität der CSS Erstellung erlaubt auch relative Pfade und dies kann bei anderen Projekten auscodiert werden.
AbstractCSS	Die einheitliche Schnittstelle für alle CSS Erstellungsklassen.
AbstractNavigationFactory	Verwaltet die Factory Klassen für die dynamischen und statischen VirtL Navigationen
VirtLStaticNavigationFactory	Factory für die jeweiligen Navigationsklassen.
VirtLDynamicNavigationFactory	Factory für die jeweiligen dynamischen Navigationsklassen.
VirtLLeftStaticNavigation	Erzeugt die statische Navigationsleiste auf der linken Seite.
VirtLBottomStaticNavigation	Erzeugt die statische Navigationsleiste im unteren Bereich der Seite.
VirtLBottomDynamicNavigation	Erzeugt die dynamische Navigationsleiste im unteren Bereich der Seite.
VirtLLeftDynamicNavigation	Erzeugt die dynamische Navigationsleiste auf der linken Seite.
AbstractNavigation	Schnittstelle über die die einzelnen Navigationsleisten Erzeuger standardmäßig aufgerufen werden können.
AnotherProjectStaticNavigation	Platzhalter für weitere Navigationsleisten in anderen Projekten.
AnotherProjectHTMLGenerator	Platzhalter für weitere HTML Generatoren in anderen Projekten.
StaticHTMLGenerator	Hauptklasse um die statischen HTML Seiten zu erzeugen.
JSPUseCase	Platzhalter für die einzelnen JSP Use Case Klassen die Navigationsleisten erzeugen müssen.
VirtLBasics	Beinhaltet die Basismethoden, wie den Loggingmechanismus und die Property Verwaltung von VirtL.
NavigationBean	Beinhaltet die Datensätze um eine Navigation aufzubauen.