DotPlot-Architektur

Aus THM-Wiki
Wechseln zu: Navigation, Suche

Preferences

Hier sollen die Änderungen erläutert werden, die im SS 2006 im Rahmen des Schwerpunktpraktikums Dotplot eingeführt wurden.

Das neue Erscheinungsbild des Dotplot-Architektur

Das Startfenster des Plugins wurde den Bedürfnissen eines Endbenutzer angepasst. Am Anfang ist das Fenster auf das nötigste reduziert worden. Die Dateiauswahl an der linken Seite wurde durch den Konfiguartions-Wizard ersetzt. Das Startbild ist geändert worden. Die zugehörigkeit zu Elipse ist jetzt auch visuell sichtbar. Außerdem wurde aus dem neuen Startbild auch die Icons für Windows Fenster geändert. Zusätzlich ist ein Hilfesystem dazugekommen das dem Benutzer die Bedienung des Plugins noch einfacher machen soll.

Das neue Erscheinungsbild

Start.jpg

Dateien Änderungen

Alle neuen Icons, sowie auch Startbilder sind im /icons Ordner mit einer fortlaufender Versionsnummer gespeichert worden. Z.b. das neue Fenster icon dp_v08.gif

Das neue Startbild ist komplett ersetzt worden. Die alte Datei wurde überschrieben.

Anpassen der Grafischen Oberfläche

Änderungen an der GUI sind durch anpassen folgender Datein möglich:

  • dotplot.product Das FensterIcon wird unter dem Tab "Branding" -> "Window Images" gesetzt.
  • plugin.xml Anpassen der MenuItems. Neue Anlegen, vorhandene verwalten.

Konfigurations-Wizard

Der alte Dialog zur Konfiguration eines Dotplots wurde durch einen Wizard-Dialog ersetzt, um so die Konfiguration zu vereinfachen. Die Dateiauswahl aus dem Hauptfenster wurde entfernt. Die Auswahl der Plotquellen findet jetzt im ersten Schritt des Wizards statt. Vorher diente ein Teil des Hauptfensters der Dateiauswahl.

Das alte Erscheinungsbild=

Der alte Konfigurationsdialog

Typischer Ablauf eines Dotplots

Die Konfiguration eines Dotplots erfolgt in verschiedenen Schritten. Nicht alle Schritte sind notwendig, nach dem ersten Schritt kann der Plot bereits konfiguriert werden.

  1. Öffnen des Wizards und Wahl der Quellen
    1. Quellenwahl
  2. Wahl des Tokenizers und Konverterwahl
    2. Tokenizerwahl
  3. Konfiguration des Konverters
    Tokenizerkonfiguration
  4. Konfiguration des Bildes
    QImage-Konfiguration
  5. Grid-Konfiguration
    Grid-Konfiguration
  6. Finish erzeugt den Plot im Hauptfenster
    Der fertige Dotplot

Paketstruktur

Die Klassen Preferences-GUI sind in der kompletten Anwendung verteilt. Hier folgt die Übersicht der wichtigsten Pakete, die für die Arbeit mit der GUI der Einstellungen wichtig sind.

  • org.dotplot.ui: Das wichtigste Paket für die Arbeit an der Wizard-UI. Enthält alle Klassen, die den Wizard realisieren und auch View und Controller für die Plotquellenauswahl.
  • org.tokenizer.service.ui: Enthält View und Controller, die zur Auswahl eines Tokenizers dienen.
  • org.tokenizer.filter.ui: Enthält View und Controller, die zur Konfiguration eines gewählten Tokenizers dienen.
  • org.tokenizer.image.ui: Enthält View und Controller der QImage Komponente.
  • org.tokenizer.grid.ui: Enthält View und Controller der Grid-Konfiguration.
  • org.tokenizer.fmatrix.ui: Enthält View und Controller der FMatrix. Für die FMatrix-Konfiguration wurde ein eigenständiger Dialog geschaffen, der nach dem erfolgen Plot aufgerufen wird.
  • org.dotplot.eclipse.actions: Die Action-Klassen, von denen zwei für den Aufruf des Plot-Wizards und der FMatrix-Konfiguration dienen.

Klassendokumentation

Es wurden verschiedene neue Klassen erstellt, mit denen der Wizard realisiert wurde.

  • ConfigurationViewWizardDialog: Diese Klasse dient dazu, einen Wizard innerhalb eines eigenen Fensters darzustellen.
  • ConfigurationViewWizard: Repräsentiert den kompletten Wizard inklusive dem Satz an Wizardseiten, den Buttons und der Logik zum Wechseln der Seiten.
  • ConfigurationViewWizardPage: Dient der Repräsentation einer einzelnen Seite des Wizards. Eine solche Seite ist ein Wrapper/Umschlag für ein ConfigurationView-Objekt, dient also zur Anbindung der bisherigen ConfigurationView-Struktur in die durch JFaces vorgegebenen Wizardstruktur.
  • SelectPlotSourceView: Die View, die zur Auswahl der Plotquellen dient. Enthält eine Liste von Plotquellen, die bislang nur durch wählbare Dateien zu füllen ist.
  • SelectPlotSourceController: Der Controller, der die Anwendungslogik der Quellenwahl kapselt. Die gewählten Plotquellen werden in die anwendungsweite Liste von Plotquellen geschrieben.

Anlegen einer neuen Seite

Hier soll anhand eines Beispiels beschrieben werden, wie eine neue Wizardseite angelegt werden kann. Als Anschauung wird die Seite SelectPlotSource verwendet.

  • Anlegen der benötigten Klassen: Zuerst müssen die für das MVC Model benötigten Klassen angelegt werden, die am besten in einem eigenen Paket abgelegt werden sollten. In diesem Falle sind das die Klassen SelectPlotSourceView und SelectPlotSourceController im Paket org.dotplot.ui.
  • Anpassen der Doplot-Konfiguration:

Die Dotplotkonfiguration befindet sich in der Datei std/dotplotplugin.xml. Diese muss angepasst werden, damit die neue Seite beim Start der Anwendung verfügbar ist.

    <Extention hotspot="org.dotplot.standard.EclipseUI.View" class="org.dotplot.ui.SelectPlotSourceView">
    	<Parameter name="id" value="01_PlotSource"/>	    		   
    </Extention>
  • Hinzufügen der Seite zum Wizardsystem: Hierzu muss die Klasse org.dotplot.eclipse.actions.ConfigAction angepasst werden. In der Methode run() muss die neue Seite hinzugefügt werden:
	views.put("01_PlotSource", ((EclipseUIService) ContextFactory
		.getContext().getGuiService()).getConfigurationViews().get("01_PlotSource"));

Es muss darauf geachtet werden, die neue View an die richtige Position in der Liste zu setzen, da dies die Seitenposition im Wizard festlegt.

Die neue Seite erscheint nun im Wizard.

Die FMatrix Konfiguration

Die FMatrix Konfiguration, um die Übersichtlichkeit der Bedienung im Dotplot Plugin einen eigenes Konifugurationsfenster bekommen. Dieses wurde auf der Basis des neuen Wizards implementiert. Alle alten Einstellungsmöglichkeiten wurden dabei übernommen.

Die Konfuguration der FMatrix kann erst nach einem neuen Plot gemacht werden. Die neue Konfiguration wird dann geplottet.


Die FMatrix Konfiguration im Wizard-Fenster


FMatrix.jpg


Um die Änderungen zu plotten wird die Konfiguration mit Finish abgeschlossen.

Neue Menupunkte mit neuen Icons

Der Konfigurations-Wizard und die FMatrix Konfiguration werden über Menupunkte gestartet. Die Icons der Ithems wurden dem neuen Gesamtbild des Dotplot-Projektes angepasst.


Neue Menupunkte mit Icons


Menu.jpg


Die FMatrix Konfiguartion ist zusätzlich auch über das Context-Menu der rechten Maustaste möglich. Unter "configure" können die Anpassungen an die FMatrix nochmals angepasst werden.


ContextMenu FMatrix


Contex.JPG

Neue Menupunkte anlegen

Um einen neuen Menupunkt anzulegen muss die plugin.xml angepasst werden. Dies geht über die GUI unter dem Tab "Extension". Dort lässt sich unter org.eclipse.ui.actionSets mit der rechten Maustaste im Context Menu "new" -> "action" eine neue Action anlegen. Folgende Parameter müssen gesetzt werden:


Ext.jpg


  • Das Feld für die "class" muss gesetzt werden. Hier wird die Klasse aufgerufen die gestartet werden soll. Im Fall der FMatrix Konfiguration steht hier die Klasse: org.dotplot.eclipse.actions.ConfigActionFMatrix
  • Es muss eine "id" und ein "label" vergeben werden.
  • Ein icon wird unter "icon" gesetzt.


Das Hilfesystem

Ein Hilfesystem wurde implementiert um dem Nutzer den Einstieg und die Handhabung der Anwendung zu erleichtern. Auch wurde für die nächsten Generationen von Dotplot Entwicklern ein Sytem eingeführt, welches die Einstellung weitere Hilfeseiten erleichtert.


Grundlagen

Da das Eclipse Help System intern eine Client-Server-Architektur verwendet, die die Hilfeseiten und zusätzliche Dienste (Suche, Indizierung etc.) bereitstellt, wurden einige Plugins benötigt. Konkret müssen dem Plugin-Manifest folgende Einträge hinzugefügt werden:

  • org.eclipse.help.base
  • org.eclipse.help.ui
  • org.eclipse.help.webapp
  • org.eclipse.help.appserver
  • org.eclipse.tomcat
  • org.apache.lucene


Das Inhaltsverzeichnis

Grundsätzlich bietet Eclipse zwei Arten der Hilfe an: zum einen strukturiert über ein Inhaltsverzeichnis (erreichbar über Help>Help Contents), zum anderen gekoppelt an GUI Elemente in Form kontextsensitiver Hilfe(aufgerufen über F1). Sowohl das Inhaltsverzeichnis als auch die Zuordnung von Hilfe Seiten zu GUI Elementen wird in separaten XML-Dateien definiert. Anhand eines kleinen Beispiels folgt nun eine Erläuterung zum Aufbau eines Inhaltsverzeichnisses:


 <?xml version="1.0" encoding="UTF-8" ?> 

   <toc label="Matrix4.plot" topic="help/index/dotplot/html/index.html">

     <topic label="Arbeiten mit Dotplot">

       <link toc="help/index/dotplot/toc_dotplot.xml" />
 
     </topic>
 
</toc>

Erläuterung zu den einzelnen Tags
Tag/Attribute Bedeutung
<toc> Wurzelement des XML Files
<topic> Unterkapitel (dürfen auch geschachtelt werden)
<label> Spezifiziert Anzeigetext für das Inhaltsverzeichnis
link Verweis auf Untergeordnetes Toc File


Index Beispiel

Damit das Verzeichnis vom Hilfesystem auch gefunden wird, muss es noch im Plugin-Manifest bekannt gemacht werden. Hierzu fügt man dem Manifest die Extension org.eclipse.help.toc hinzu und erweitert diese um einen Verweis auf das gewünschte Inhaltsverzeichnis.


Die Kontext Sensitive Hilfe

Die Erstellung einer Hilfe Kontext-Zuordnung erfolgt analog zur Erstellung eines Inhaltsverzeichnisses über eine XML Datei:

<?xml version="1.0" encoding="UTF-8"?>

<?NLS TYPE="org.eclipse.help.contexts"?>

<contexts>
	
      <context id ="conHelpTokenizer">
		
          <description>Help for Tokenizer Settings</description>
		
          <topic href="help/context/settings/tokenizer.html" label ="Tokenizer Settings Help"/>
	
       </context>

</contexts>
Erläuterung zu den einzelnen Tags
Tag/Attribute Bedeutung
<contexts> Wurzelement des XML Files
<context> Eigentliches Context Element das einem Hilfefenster entspricht, wenn die F1 Taste gedrückt wird
id GUI Element für welches das Context Element zuständig ist
<topic> Verweist im href Attribut auf die Zugeordnete Html Seite
<label> Spezifiziert Anzeigetext
href Verweist auf Hilfeseite

Im Eclipse Hilfesystem müssen die in der Kontextdatei deklarierten IDs GUI-Elementen zugeordnet werden. Wird im Wizzard auf der Tokenizer Settings Seite F1 gedrückt, baut sich neben dem Wizzard eine Hilfeseite auf mit den Inhalten, die definiert wurden:

Context example.jpg

In der ConfigurationViewWizzardPage muss die PerformHelpMethode wie folgt implementiert werden.




public void performHelp() {
    	
     PlatformUI.getWorkbench().getHelpSystem().
               displayHelp(“org.dotplot.plugin.conHelpTokenizer”)
}


Auch hier muss dem Plugin-Manifest die erstellte XML Datei natürlich noch bekannt gemacht werden. Dies geschieht wieder über den Extension Manager durch Hinzufügen der Extension org.eclipse.help.contexts und dem Eintragen der entsprechenden Datei.

Die Aktive Hilfe

Die Aktive hilfe bietet die Möglichkeit, Hyperlinks in Hilfetexte einzubetten, die bei Betätigung Programmfunktionen ausführen.


Cheat Sheets

Cheat Sheets führen den Benutzer Schritt für Schritt durch eine Reihe von Arbeitsschritten. Als Beispiel kann man sich die mit dem Eclipse-SDK ausgelieferten Cheats Sheets betrachten (z.B das Hello World Beispiel). Da im Dotplot Projetkt onehin ein Wizzard implementiert wurde, der den Nutzer Schritt für Schritt durch die einzelnen Views zur Erstellung eines Plots führt, wurde auf eine Implementierung von Cheat Sheets verzichtet.


Die Einbinung in das Dotplot Projekt

Anbei eine kleine Hilfestellung für die Erstellung eigener Hilfeseiten für das Dotplot Projekt.


Seiten für das Inhaltsverzeichnis

Zu Beginn sei zu erwähnen, dass man sich an die vorgegebene Dokumententstruktur der Hilfeseiten halten sollte, da die TOC Files, durch die der interne Tomcat Server von Eclipse auf die erstellten Seiten zugreift, wenig Spielraum für Änderungen lässt. Um die Seiten zu erstellen sollte immer nach dem folgenden Schema vorgegangen werden:


1. Erstellen/Bearbeiten der XML Seite

Die Inhalte der der Hilfeseiten werden in XML Files abgelegt und später mittels eines XSL Files in die passende Form gebracht. Ob das XML File die richtige Struktur hat, wird mittels einer vorhandenen dtd Datei geprüft. Um Fehler zu vermeiden ist es das Beste, man nimmt sich die example.xml aus dem Template Ordner und passt sie den eigenen Anforderungen an und speichert sie im passenden Dotplot Ordner ab.

Folgendes Listing soll der Demonstration dienen:

  <Document Heading = "Die Überschrift des Dokumentes">
	
     <Paragraph Heading = "Die Überschrift des Absatztes (Optional)">

        <Text>Der Text kann auch Links enthalten. Diese werden so
              dargestellt: 

                <Link Linktext ="Der Text">http://sourceforge.net/projects/dotplot/</Link>
              Natürlich sind auch Aufzählungen möglich:

        </Text>

        <Numbering>

 	   <Topic Heading=" Überschrift zu Punkt 1:">

 		<Description> Text zu Punkt 1 </Description></Topic>

 	   <Topic Heading="Überschrift zu Punkt 2">

 		<Description>Text zu Punkt 2 </Description></Topic>
           
        </Numbering>
		
        <Image>../images/Bilder_gibt_ es_auch.jpg</Image>

       </Paragraph>

<Document>


2. Abspeichern des Dokumentes in das richtige Verzeichnis.

Wie zu Beginn schon erläutert ist es wichtig, die Dateistruktur einzuhalten. Auch sollten Bilder nur in den dafür vorgesehenen Ordner abgelegt werden, der wie oben im Beispiel Code zwischen den Image Tags angegeben wird. Die XML Dateien für das Inhaltsverzeichnis sind im Index Verzeichnis abzuspeichern. Hier entscheidet man sich je nach Themenschwerpunkt entweder für das Configuration, das Dotplot oder das Examples Verzeichnis und legt die erstellte XML Datei im XML Ordner ab.

Filesytem example.jpg


Die einelzen Themenschwerpunkten und die zugehörigen Ordner:

Configurations:

Hier sind alle Dateien abzuspeichern, die sich mit dem Erstellen eines Plots beschäftigen. Dazu zählen besonders :Hinweise zu den Einstellungsmöglichkeiten am Wizzard.

Dotplot:

Allgemeine Informationen zu Dotplot

Examples:

Beispiele für Plots und wie diese zu Interpretieren sind.


3. Die Transformation in Html und das Einklinken in das Hilfesystem

Wurde die XML Datei erstellt und im passenden Ordner abgespeichert, kann man die Html Seite generieren. Hierzu legt man einfach in den Eclipse Einstellungen HelpFileGenerator.java als Startobjekt fest, übergibt Ihr die passenden Parameter und startet die Anwendung. Die neue Html Seite wurde im passenden html-Ordner erstellt. Gleichzeitig wurde ein neuer Eintrag im im entsprechenden toc File gesetzt.

Anmerkungen zum Aufruf des HelpFileGenerators

Als erster Paramerter ist eine XML Datei oder, sollten es mehrere Dateien sein, ein ganzes Verzeichnis anzugeben. :Der Zweite Parameter ist das XSL Stlyesheet. Dieses ist im Template Ordner des Index Verzeichnisses zu finden.


Einbinden der Kontext Sensitive Hilfe

Die Kontext Sensitive Hilfe bezieht sich immer auf die einzelnen Views des Configuration Wizzards bzw. der FMatrix Einstellungen.


1. Die Erstellung der Hilfeseiten

Die Gestaltung der Context Sensitiven Hilfe Seiten erfolgt mittels Html und einem einfachen CSS Stylesheet. Auch hier sollte darauf geachtet werden, dass die Seite am richtigen Ort abgespeichert ist. (Hier ist es help->context)


2. Eintrag in die context.xml


3. Zuweisung einer ID and das jeweilige Elemet

Im Konstruktor der View, der eine Kontext Sensitive Hilfe zugeordnet werden soll, wird dem Hilfesystem durch this.setHelpContextID("org.dotplot.conHelpExample"); eine ID zugeordnet.