ODTCreatorUnit
|
Gruppe |
|
|
Funktion |
Die Unit dient der Erstellung von Textdokumenten im OpenDocument-Format. |
Beschreibung
Die ODTCreatorUnit dient der Erstellung von Textdokumenten im OpenDocument-Format. Dieses wird von mehreren Office-Paketen und Textverarbeitungen unterstützt, unter anderem von OpenOffice 2.0.
Das Format der zu erzeugenden Office-Dokumente wird dabei durch eine Vorlage definiert, die z.B. einfach in OpenOffice als Textdokument erstellt wird. Diese ist wirklich als Textdokument zu speichern, nicht etwa als Vorlage im Sinne von OpenOffice.
Beschreibung der Parameter
|
Parametername |
Erlaubte Werte |
Default-Wert |
Beschreibung |
|
create multiple files |
true, false |
false |
Auf true setzen, wenn mehrere Dokumente generiert werden sollen anstatt eines einzigen. |
|
directory |
|
|
Gibt das Verzeichnis an in das die Dateien geschrieben werden. |
|
file pattern |
|
|
Muster für die Namen der generierten Dokumente, wenn die Unit selbst sie wegschreibt (save files ist true). Das file pattern kann Platzhalter enthalten. Erlaubte Vorlagen dazu sind y, M, d, h, m, s, S und n. |
|
keep linebreaks within text |
true, false |
false |
Bei true werden Zeilenumbrüche von Werten ins Template übernommen, ansonsten werden sie als Leerzeichen dargestellt. |
|
root node for multiple files |
|
|
Für jedes Vorkommen dieses Knotens wird ein einzelnes Dokument generiert (falls create multiple files den Wert true hat). Alle über diesem Knoten liegenden Knoten des Zielbaumes sind nicht erreichbar. Die Vorlage muss den äußersten Block immer auf den Knoten beziehen, der als root node gesetzt wurde. |
|
save files |
true, false |
false |
Auf true setzen, wenn die Unit selbst schon die generierte(n) Datei(en) wegschreiben soll (Pflichtwert). |
|
template-file |
|
|
Die Textdatei, die als Vorlage für die generierten Dokumente dient. |
|
unknown tags replacement |
|
? |
Marken für unbekannte Felder werden mit der angegebenen Zeichenkette ersetzt. |
Beispiel zum Parameter "file pattern"
Für Rechnung<yyyy><MM><dd>_<HH><mm>
wird am 24.02.2006, um 12:30 Uhr entweder eine Datei erzeugt mit dem Namen:
Rechnung20060224_1230.odt
Oder, wenn create multiple files gewählt wurde, Dateien mit den Namen:
Rechnung20060224_1230_Part1.odt,
Rechnung20060224_1230_Part2.odt,
Rechnung20060224_1230_Part3.odt
...
Format der Vorlage
Die Vorlage ist eine ganz normale Text-Datei im OpenDocument-Format (ODF). Die übliche Endung einer solchen Datei ist .odt. Im Folgenden wird angenommen, diese Datei wurde mit OpenOffice 2.0 erstellt. Innerhalb dieser Vorlage können sowohl im Text als auch in den Kopf- und Fußzeilen bestimmte Platzhalter gesetzt werden, die die Arbeit der ODTCreatorUnit steuern. Diese Marken werden entweder durch den Inhalt eines Feldes ersetzt oder sie begrenzen Blöcke, die für jedes Vorkommen eines Knotens wiederholt werden. Daneben gibt es noch spezielle Anweisungen, die die Unit sehr flexibel steuern können.
Marken:
Alle Marken werden grundsätzlich mit {-- geöffnet und mit --} geschlossen. Also so:
{--Marke--}Zwischen den Begrenzungen und dem Feldnamen, dem Knotennamen, bzw. der Anweisung dürfen keine Leerzeichen sein.
{--Richtig--}{-- Falsch --}Ist die Marke unbekannt (z. B. weil das angegebene Feld nicht existiert), wird im Standard statt des Feldwertes ein Fragezeichen ausgegeben. Über den Unit-Parameter unknown tags replacement kann eine andere Zeichenkette angegeben werden.
Blöcke:
Blöcke werden, ähnlich wie bei XML, mit einem Slash / geschlossen. Alle Marken, die Blöcke einrahmen, müssen immer am Anfang einer Zeile stehen, die auch nur diese Marke zum Inhalt hat. Diese Zeilen werden bei der Verarbeitung gelöscht.
Also das {--Block--} wäre völligfalsch. {--/Block--}{--Block--}Aber so geht das.{--/Block--}Blöcke müssen sich auf Knoten in der Datenstruktur beziehen. Der Inhalt von Blöcken wird so oft wiederholt, wie der jeweilige Knoten vorkommt (also pro Datensatz dieses Knotens).
Ein Knoten oder Feld kann immer nur innerhalb eines Blocks angesprochen werden, der sich auf den direkt darüberliegenden Knoten bezieht. Im nachfolgenden Beispiel kann der Knoten PosKopf also nur im Block Position angesprochen werden, nicht im umgebenden Block Rechnung. Ist ein Block unbekannt (z. B. weil der angegebene Knoten nicht existiert), wird der komplette Block nicht dargestellt.
Die Vorlage muss den äußersten Block immer auf den Knoten beziehen, der als root node gesetzt ist (bei Verwendung der Option create multiple files). Das muss nicht der oberste Knoten sein. Werden root node und create multiple files nicht verwendet, dann muss der äußerste Block sich auf das oberste Element des Baumes beziehen. Liegen mehrere Knoten in der obersten Ebene, können sie alle so angesprochen werden.
Anweisungen:
Anweisungen beginnen immer mit der Kennung odtcreator, gefolgt von einem Doppelpunkt und der Anweisung. Darauf können, durch Doppelpunkte getrennt, Parameter für die Anweisung folgen. Anweisungen können auch Blöcke bilden. In diesem Falle reicht als schließende Marke der Teil /odtcreator:<Anweisung>. Weitere Angaben danach werden ignoriert.
Zum Beispiel:
{--odtcreator:if:equal:Anrede:Herr--}Inhalt des Blocks{--/odtcreator:if:das wird ignoriert:das auch:das auch--}Zum einfacheren Verständnis folgt ein praktisches Beispiel. Es sollen die Daten mehrerer Rechnungen in einzelne Rechnungs-Dokumente umgesetzt werden.
Beispiel-Datenstruktur und -Daten
Beispiel-Datenstruktur
Wie man sieht, besteht jede Rechnung aus Kopfdaten, der Empfängeradresse und einer oder mehrerer Positionen. Jede Position wiederum hat einen Satz Kopfdaten und kann mehrere Detail- und Zusatzinformationen enthalten. Im Knoten Summen wird eine Summe über alle Positionspreise berechnet, um die Gesamt-Rechnungssumme auszugeben.
|
|
|
|
|
|
Gesamte Struktur, oberstes Level. |
Aufgeklappte Knoten Kopf und Adresse. |
Aufgeklappte Knoten PosKopf, PosDetail und PosZusatz. |
Aufgeklappter Knoten Summen. |
Die Beispieldaten
RK;R2006-100;C0815;20.02.2006;A2006-98;23.02.2006;L2006-98AD;Meier;Hans;Hauptstraße 10;12345;Musterstadt;HerrRP;1;4711;1;"Festplatte Turbo 300";149.99;149.99PD;"Interne Festplatte Turbo 300, EIDE, 300 GB"RP;2;4712;1;"DVD-Brenner";89.99;89.99PD;"Externer DVD-Brenner, USB2"RP;3;4713;5;"DVD Rohlinge";2.99;14.95PD;"DVD-RW Rohlinge"RP;4;4714;2;"Toner";129.99;259.89PD;"Tonerkartusche fuer Laserdrucker"PD;"Passend fuer HP Laserjet"RK;R2006-101;C0300;21.02.2006;A2006-102;23.02.2006;L2006-102AD;Mueller;Trude;Nebenstraße 77;23456;Trabantenstadt;FrauRP;1;8810;1;"Komplettsystem";499.99;499.99PD;"Komplettsystem Desktop-PC"PD;"Prozessor: Athlon 3,2 GHz"PD;"1 GB RAM"PZ;"Aktionspreis"RP;2;8820;1;"USB Stick";49.98;49.98PD;"USB-Stick, 1 GB, USB2"RP;3;8830;1;"SUSE";39.95;39.95PD;"SUSE Linux Professional"PD;"Version 10.0"Beispiel-Vorlagen
Eine erste Vorlage
Wie man an den Beispieldaten sehen kann, sollten zwei Rechnungen generiert werden, eine für Herrn Hans Meier und eine für Frau Trude Mueller. Daher wird in der Konfiguration der Unit festgelegt, dass mehrere Dokumente generiert werden sollen. Und zwar eines pro Vorkommen des Knotens Rechnung. Wir setzen daher den Parameter create multiple files auf true und geben als root node for multiple files den Knoten Rechnung an. Für den Anfang wollen wir nur die Kopfdaten und die Adresse ausgeben. Unsere Vorlage ist also erst mal eine ODT-Datei mit folgendem Inhalt.
Daran kann man schon mal die wichtigsten Elemente einer solchen Vorlage erkennen: Blöcke und Feld-Platzhalter. Alles zwischen den Elementen {--Rechnung--} und {--/Rechnung--} ist zum Beispiel ein Block. Dies bedeutet, dass alle Felder und weiteren Blöcke, die zwischen den beiden Anfangs- und Endmarken stehen, sich auf den Knoten Rechnung beziehen. Hätten wir create multiple files auf false gesetzt, würde ein Dokument erzeugt, in dem für jede Rechnung die Kopf- und Adressdaten stehen.
Innerhalb des Blocks Rechnung werden zwei weitere Blöcke aufgemacht. Einer für die Kopfdaten und einer für die Adressdaten. Die Marken für diese Blöcke heißen genau so wie die Knoten, in denen sich die jeweiligen Felder befinden: Kopf und Adresse. Innerhalb dieser Blöcke wiederum werden die Werte der Felder, die sich unter den entsprechenden Knoten befinden, an den durch die Platzhalter vorgegebenen Stellen eingefügt. Die Platzhalter haben wiederum exakt die Namen, die die Felder im Baum haben. Also z. B. {--Lieferschein_Nummer--} oder {--Anrede--}. Sie sehen übrigens an der Zeile mit PLZ und Ort, dass auch beliebige Textformatierungen möglich sind. Die anstelle der Platzhalter eingesetzten Werte sind dann ebenfalls so formatiert.
Unsere Rechnung für Herrn Meier sieht bis dahin so aus:
Template_2_DE.odt (Dies ist kein Template, sondern das Ergebnis eines verarbeiteten Templates.)
Erweiterungen der Vorlage
Nun brauchen wir eine Anrede. Natürlich könnten wir innerhalb des Adress-Blocks einfach folgendes schreiben:
Aber so ein "Sehr geehrte(r)" sieht doch nicht gerade schön aus. Also machen wir diese Zeile abhängig von der Anrede:
Dies ist ein Beispiel für einen Block, der mit Anweisungen für die Unit arbeitet. In diesem Fall soll der jeweilige Block nur dann ausgeführt werden, wenn das Feld Anrede den Wert Herr, bzw. Frau hat. Das Ende eines solchen Blocks muss nur die Kennung odtcreator und die Anweisung selbst enthalten, in diesem Falle also /odtcreator:if. Den Rest aus der öffnenden Marke können Sie gerne dazuschreiben, um sich z. B. besser orientieren zu können, welchen if-Block Sie da gerade schließen. Ausgewertet wird das aber nicht mehr.
Als nächstes wollen wir nun die einzelnen Rechnungspositionen aufführen. Dies soll in einer Tabelle geschehen. Erst mal die einfache Variante:
Die Unit wiederholt so für jede Position die Inhalts-Zeile der Tabelle (die Kopfzeile wird nicht wiederholt) und füllt sie mit den Feldwerten aus dem jeweiligen Unterknoten PosKopf. Wie man sieht, können Blöcke auch innerhalb einer Tabellenzelle stehen. Aber auch hier müssen öffnende und schließende Marke wieder am Anfang einer ansonsten leeren Zeile stehen. Allerdings sieht das doch sehr unleserlich aus. Also warum beziehen wir die Tabelle nicht direkt auf den Knoten PosKopf? Weil der leider nicht direkt unter Rechnung liegt, sondern unter Position und wie vorhin schon erwähnt wurde, kann ein Knoten, oder Feld immer nur innerhalb eines Blocks angesprochen werden, der sich auf den direkt darüberliegenden Knoten bezieht.
Aber dafür gibt es eine Lösung. Statt der Anweisung table wird die Anweisung tabledeep benutzt:
Bei dieser Variante wird auch tief unten in den Unterknoten von Rechnung nach Vorkommen des Knotens PosKopf gesucht und die Tabelleninhalte für diese Knoten wiederholt.
Dann fehlt uns noch die Summe über alle Positionen:
Liste aller Anweisungen
Im folgenden eine Liste aller Anweisungen, die zur Steuerung der ODTCreatorUnit eingesetzt werden können. Wenn diese Anweisungen Blöcke einschließen, nennen wir sie Blockmarken, wenn sie durch Werte ersetzt werden, Wertmarken. Daneben gibt es noch Aktionsmarken, die sich nicht sofort auf das erzeugte Dokument auswirken, sondern nur eine Aktion innerhalb der Unit auslösen.
table
Typ: Blockmarke
Format: odtcreator:table:<Knotenname>
Ein table-Block schließt immer eine Tabelle ein. Die Inhalts-Zeilen dieser Tabelle werden für jeden Datensatz des angegebenen Knotens wiederholt, während die Überschrifts-Zeile gleich bleibt. Diese Überschriftszeile wird normalerweise beim Anlegen einer Tabelle (in OpenOffice) automatisch als erste Zeile generiert. Soll eine Tabelle mehrere Überschriften enthalten, die pro Datensatz wiederholt werden sollen, darf keine "echte" Überschrifts-Zeile verwendet werden, sondern es muss eine normale Inhalts-Zeile verwendet werden, in der die Texte eben als Überschrift formatiert sind. Dies erreicht man, indem man nach Anlage der Tabelle die Überschriftszeile löscht und dann stattdessen eine normale Zeile einfügt.
Der Knoten, auf den sich die Tabelle bezieht, muss im aktuellen Block liegen. Innerhalb des table-Blocks befindet man sich dann in dem angegebenen Knoten, kann also direkt auf seine Felder und Unterknoten zugreifen.
tabledeep
Typ: Blockmarke
Format: odtcreator:tabledeep:<Knotenname>
Die tabledeep-Anweisung arbeitet im Prinzip wie die table-Anweisung. Allerdings müssen hier die Knoten, auf die sich die Anweisung bezieht, nicht direkt unter dem Knoten des aktuellen Blocks liegen. So kann man sich unter Umständen einige Blöcke sparen, wenn man diese nur benötigen würde, um zu den Tabellen-Knoten zu kommen.
deep
Typ: Blockmarke
Format: odtcreator:deep:<Knotenname>
Ähnlich wie tabledeep kann auch deep mehrere Blöcke einsparen, wenn man nur schnell in einen Knoten mehrere Ebenen unter dem aktuellen Knoten gehen will. Im Rechnungs-Beispiel könnte man also z. B. direkt aus dem Block Rechnung in den Block PosKopf gelangen. Mit "normalen" Blöcken müsste man erst noch den Knoten Position betreten, bevor man in PosKopf gelangt.
Beispiel ohne deep:
{--Rechnung--}...{--Position--}{--PosKopf--}Position {--Pos-Nr--}: Artikelnr. {--Artikelnummer--}, {--Kurzbeschreibung--}{--/PosKopf--}{--/Position--}...{--/Rechnung--}Beispiel mit deep (dort geht das in einem Schritt):
{--Rechnung--}...{--odtcreator:deep:PosKopf--}Position {--Pos-Nr--}: Artikelnr. {--Artikelnummer--}, {--Kurzbeschreibung--}{--/odtcreator:deep--}...{--/Rechnung--}parent
Typ: Blockmarke
Format: odtcreator:parent
Mit dieser Anweisung kann man in der Baumstruktur wieder ein Element nach oben gehen. Der Inhalt des parent-Blocks wird auf den aktuellen Datensatz des übergeordneten Knotens angewandt. Das heißt, man könnte von dort aus auch wieder in andere Knoten dieses Vaterknotens gelangen.
Beispiel:
{--Rechnung--}...{--odtcreator:deep:PosKopf--}Position {--Pos-Nr--}: Artikelnr. {--Artikelnummer--}, {--Kurzbeschreibung--}{--odtcreator:parent--}Detailinformationen:{--PosDetail--}{--Detailtext--}{--/PosDetail--}Zusätze:{--PosZusatz--}{--Zusatzinfo--}{--/PosZusatz--}{--/odtcreator:parent--}{--/odtcreator:deep--}...{--/Rechnung--}if
Typ: Blockmarke
Format: odtcreator:if:equal:<Feld>:<Wert>
oder: odtcreator:if:notequal:<Feld>:<Wert>
oder: odtcreator:if:textis:<Wert>
oder: odtcreator:if:textisnot:<Wert>
oder: odtcreator:if:inelement:<Elementname>
Bedingungen equal und notequal:
Der Block wird nur ausgewertet, wenn das angegebene Feld den gewünschten Wert hat (equal), bzw. nicht hat (notequal).
Bedingungen textis und textisnot:
Wenn man sich in einem Block direkt auf Felder bezieht, kann so der Inhalt des Feldes überprüft werden.
Bedingung inelement:
Diese Bedingung ist nur in einem Block der Anweisung in sinnvoll. Der Block der if-Anweisung wird dann nur ausgewertet, wenn man sich im Element (Knoten oder Feld) des angegebenen Namens befindet. Ein Beispiel hierzu finden Sie bei der Beschreibung der in-Anweisung (Beispiel 2).
Beispiel 1: equal
{--Rechnung--}...{--Adresse--}...{--odtcreator:if:equal:Anrede:Herr--}Sehr geehrter Herr {--Nachname--},{--/odtcreator:if--}{--odtcreator:if:equal:Anrede:Frau--}Sehr geehrte Frau {--Nachname--},{--/odtcreator:if--}{--/Adresse--}...{--/Rechnung--}Die Bedingung notequal wird entsprechend ausgewertet.
Beispiel 2: textis
{--Rechnung--}...Aktionspreise erhalten Sie bei folgenden Positionen:{--odtcreator:deep:Zusatzinfo--}{--odtcreator:if:textis:Aktionspreis--}{--odtcreator:parent--}{--odtcreator:parent--}{--PosKopf--}Position {--Pos-Nr--}: Artikelnr. {--Artikelnummer--}, {--Kurzbeschreibung--}{--/PosKopf--}{--/odtcreator:parent--}{--/odtcreator:parent--}{--/odtcreator:if--}{--/odtcreator:deep--}...{--/Rechnung--}In diesem Beispiel werden sämtliche Zusatzinformationen daraufhin überprüft, ob sie den Wert Aktionspreis haben. Wenn ja, werden die Kopfdaten der jeweiligen Position ausgegeben. Dazu muss man sich erst im Baum hocharbeiten, von der Zusatzinfo über PosZusatz (1. parent) zur Position (2. parent) und dann den Knoten PosKopf betreten. Die Bedingung textisnot wird analog ausgewertet.
in
Typ: Blockmarke
Format: odtcreator:in:[Liste von Knotennamen] oder odtcreator:in:*
Mit dieser Anweisung können alle Unterknoten und Felder des aktuellen Knotens angesprochen werden. Man gibt entweder die gewünschten Knoten- und Feldnamen (durch : getrennt) an, oder setzt einen Stern (*) für alle Unterelemente dieses Knotens.
Beispiel 1: Die Namen und Werte aller Felder von PosKopf ausgeben
{--Rechnung--}...{--odtcreator:deep:PosKopf--}Position {--Pos-Nr--} hat folgende Inhalte:{--odtcreator:in:*--}{--odtcreator:elementname--} = {--odtcreator:elementtext--}{--/odtcreator:in--}{--/odtcreator:deep--}...{--/Rechnung--}Zu den Anweisungen elementname und elementtext siehe dort.
Beispiel 2: Kombination mit if:inelement
{--Rechnung--}...{--Position--}{--odtcreator:in:PosKopf:PosZusatz--}{--odtcreator:if:inelement:PosKopf--}Position {--Pos-Nr--}: Artikelnr. {--Artikelnummer--}, {--Kurzbeschreibung--}{--/odtcreator:if--}{--odtcreator:if:inelement:PosZusatz--}Zusatz: {--Zusatzinfo--}{--/odtcreator:if--}{--/odtcreator:in--}{--/Position--}...{--/Rechnung--}Im Block zum Knoten Position werden die beiden Knoten PosKopf und PosZusatz durch die in-Anweisung durchlaufen. Je nach dem, in welchem Unterknoten man sich befindet, wird die entsprechende Zeile ausgegeben. Das ist natürlich in diesem Fall etwas sinnlos, da man gleich direkt die Blöcke angeben kann. Aber es zeigt das Prinzip.
elementname und elementtext
Typ: Wertmarken
Format: odtcreator:elementname oder odtcreator:elementtext
Diese beiden Marken werden durch den Namen des aktuellen Elements (Knoten oder Feld) ersetzt, bzw. durch den Text (also Wert), falls es sich um ein Feld handelt. Ein Beispiel zur Anwendung finden Sie bei der in-Anweisung (Beispiel 1).
define und undefine
Typ: Aktionsmarken
Format: odtcreator:define:<BeliebigerName> oder odtcreator:undefine:<BeliebigerName>
Diese beiden Marken haben keine direkte Auswirkung im Text und werden einfach durch einen Leerstring ersetzt. Allerdings merkt sich die ODTCreatorUnit die angegebenen Namen als definiert, bzw. löscht diese Definition wieder. So kann z.B. an anderer Stelle darauf reagiert werden, ob davor mal eine bestimmte Bedingung erfüllt war.
Im folgenden Beispiel erweitern wir die Ausgabe der Positionen mit Aktionspreis (Beispiel 2 der if-Anweisung) um eine Zeile, die nur dann ausgegeben wird, wenn keine Position mit Aktionspreis gefunden wurde. Dazu nutzen wir die Anweisung ifundef, die weiter unten beschrieben wird.
Beispiel: Zeile ausgeben, wenn keine Aktionspreise existieren
{--Rechnung--}...Aktionspreise erhalten Sie bei folgenden Positionen:{--odtcreator:deep:Zusatzinfo--}{--odtcreator:if:textis:Aktionspreis--}{--odtcreator:parent--}{--odtcreator:parent--}{--PosKopf--}Position {--Pos-Nr--}: Artikelnr. {--Artikelnummer--}, {--Kurzbeschreibung--}{--odtcreator:define:Aktionspreis gefunden--}{--/PosKopf--}{--/odtcreator:parent--}{--/odtcreator:parent--}{--/odtcreator:if--}{--/odtcreator:deep--}{--odtcreator:ifundef:Aktionspreis gefunden--}Leider kommen Sie nicht in den Genuss von Aktionspreisen.{--/odtcreator:ifundef--}...{--/Rechnung--}Will man eine ähnliche Überprüfung später noch mal machen, kann man die Definition von "Aktionspreis gefunden" hinterher wieder löschen: {–odtcreator:undefine:Aktionspreis gefunden–}.
ifdef und ifundef
Typ: Blockmarken
Format: odtcreator:ifdef:<BeliebigerName> oder odtcreator:ifundef:<BeliebigerName>
Der mit ifdef definierte Block wird nur ausgewertet, wenn der angegebene Name vorher mittels der define-Anweisung definiert wurde.
Der mit ifundef definierte Block dagegen wird nur ausgewertet, wenn der Name nicht definiert, oder die Definition mittels der undefine-Anweisung wieder gelöscht wurde. Ein Beispiel zur Verwendung von ifundef finden Sie oben bei der Beschreibung der Anweisungen define und undefine (ifdef wird analog benutzt).