Aquarius MMX

h1. Ablauf der Reporterzeugung

h2. Prinzipieller Ablauf

Reports werden grundsätzlich aus den Ergebnissen einer oder mehrerer Datenbankabfragen generiert. Die Ergebnisse werden in einer XML-Datei gespeichert. Aus dieser Rohdatendatei können mit Hilfe von _Backends_ verschiedene Ausgaben generiert werden. Zur Zeit sind dies bspw. PDF-Dateien, CSV-Dateien oder die direkte Ausgabe an den Drucker. Nicht für alle Reports werden alle Ausgabeformate unterstützt. 

Die Einstellungen für die Reporterzeugung und einzelnen Reports erfolgt über eine Vielzahl von Dateien, die sich unter dem Verzeichnis @Reporting@ befinden.

h2. Definition von Reports

Die Definition der Reports erfolgt über die Konfigurationsdatei unterhalb des @Reporting@-Verzeichnis. In der XML-Datei @config.xml@ wird für einen Report ein @Report@-Element angelegt werden. Hier sind die Attribute @Code@ und @Scope@ verpflichtend, wobei ersterer eindeutig für einen bestimmten Report sein muss. Das @Scope@-Attribut gibt den Gültigkeitsbereich des Reports an. Für einen Report ist weiterhin ein @Title@-Element verpflichtend. Unter dem Element @Queries@ werden schließlich die Datenbankabfragen angegeben, die für den Report ausgeführt werden sollen. Pro Abfrage ist ein @Query@-Element anzugeben. Dessen Wert referenziert eine SQL-Datei im Verzeichnis @Reporting\Queries@. Die Dateierweiterung (.sql) entfällt hierbei. Das Attribut @TableName@ gibt den Namen des Eltern-Elements für alle pro Datensatz der Abfrage erzeugten Elemente im Rohdaten-XML-Dokument an.

Zusätzlich zu den Datenbankabfragen wird automatisch ein Datensatz @ReportInfo@ in das Rohdaten-XML-Dokument eingefügt, der Informationen über den erzeugten Report enthält.

In den Query-Dateien können Parameter aus dem Gültigkeitsbereich des zu erstellenden Reports verwendet werden. Diese müssen in @%@-Zeichen eingeschlossen werden. Die folgenden Parameter stehen zur Verfügung:

* event - ID des Events des erzeugten Reports

* day - Tag (als Datumsstring) des Laufs

* race - ID des gewählten Rennens

* round - Runde des ausgewählten Laufs (Integer)

* comp - ID Lauf des gewählten Laufs

Die über die Queries erzeugten Rohdaten werden in XML-Dateien im Verzeichnis @Reports\RAW\XML@ abgespeichert. Die sich daran anschließende XSLT-Transformation verwendet die Stylesheet-Dateien aus dem Order @Reporting\XSL@ und dem jeweiligen Backend. Der Name des Stylesheets ergibt sich aus dem @Code-Attribut eines Reports. Das Stylesheet kann auch über das @Name@-Attribut des @Stylesheet@-Element unterhalb des @Report@-Elements in der Konfigurationsdatei angegeben werden. Damit können Stylesheets mehrfach genutzt werden. Über Kind-Elemente mit dem Namen @Param@ können Parameter der XSL-Transformation angegeben werden, um das verwendete Stylesheet an die Bedürfnisse des Reports anpassen zu können.

h2. Umwandlung in Ausgabeformate

Die Umwandlung in andere Formate geschieht grundsätzlich mit XML-Stylesheets (XSL-Dateien). Diese Dateien befinden sich im Verzeichnis @XSL@ und Unterverzeichnissen, die nach dem jeweiligen _Backend_ benannt sind (@FP@ ist das Backend für den Direktdruck, @INC@ enthält allgemeine, wiederverwendbare Dateien). Soll ein Backend einen Report unterstützen, muss eine XSL-Datei im Verzeichnis des Backends mit dem Kürzel des Reports existieren (bspw. M_ME.xsl für das Meldeergebnis). Die XSL-Datei wird schließlich auf die XML-Datei, die die Rohdaten enthält, angewendet ("XSL Transformation":http://de.wikipedia.org/wiki/XSL_Transformation).

Zur Generierung von PDFs wird durch die XSL-Transformation eine XSL-FO-Datei erzeugt. Diese wird anschließend durch "Apache FOP":http://xmlgraphics.apache.org/fop/ in eine PDF-Datei umgewandelt. Da Apache FOP eine Java-Anwendung ist, ist für das Erzeugen von PDFs eine [[Aquarius_installieren#Systemvoraussetzungen|Java-Installation notwendig]].

Im Falle von CSV erfolgt nach der XSL-Transformation keine weitere Umwandlung. 

Für die direkte Druckausgabe wird eine Seitenbeschreibung generiert und anschließend an den Drucker gesendet. 

h2. Zusätzliche Backends

Um einen neuen Dateityp unterstützen zu können, das auf einer Umwandlung von XML-Daten in ein anderes Dateiformat basiert, muss ein zusätzliches Backend angelegt werden. Hierfür sind Schritte notwendig:

1. Unterhalb des Verzeichnis @Reporting\XSL@ muss ein neuer Ordner mit dem Namen des Backends angelegt werden. Üblicherweise entspricht dieser Name der Dateinamenserweiterung des erzeugten Dateien in Großbuchstaben. Für ein Backend, das Text-Dateien erzeugt, wäre also ein Verzeichnis @Reporting\XSL\TXT@ anzulegen

2. Im Verzeichnis aus Schritt 1 muss eine Datei @config.ini@ angelegt werden. Diese enthält bspw. folgenden Inhalt <pre>

[ReportingXslt]

MimeType=text/plain

Extension=csv

Enabled=True

</pre>Hierbei entspricht der @MimeType@ einem eindeutigen Bezeichner des Ausgabetyps, unabhängig von der Dateierweiterung, die über den Schlüssel @Extension@ definiert wird. Über den Schlüssel @Enabled@ können Backends ein- und ausgeschaltet werden.

Die Backends können auch in Verzeichnissen unterhalb des @Plugins@-Verzeichnis angelegt werden. Für das beispielhafte TXT-Backend könnte dies unter @Plugins\MeinPlugin\Reporting\XSL\TXT@ erfolgen.