Befehlsreferenz CIB jsMerge

Transcription

> Technical Support & Services
Anwender-Handbuch
Erzeugung von dynamischen Dokumenten im ODTFormat
> Stand: 28. Oktober 2014
Version 1.0
CIB software GmbH > Technical Support & Services > Befehlsreferenz CIB jsMerge >
DOKUMENT
BefehlsreferenzCIBjsmerge.rtf vom 28.10.14 11:26
Autor:
CIB software GmbH
Thema:
Befehlsreferenz CIB jsMerge – Anwender-Handbuch
Erzeugung von dynamischen Dokumenten im ODT-Format
Copyright:
CIB software GmbH, Elektrastraße 6a, 81925 München
Status:
gültig
2 | 42
INHALT
1
ALLGEMEIN
5
1.1
HINWEIS
5
1.2
SUPPORT
6
1.3
VERSIONSHISTORIE
6
1.4
LITERATURVERWEIS
6
1.5
LIEFERUMFANG
6
1.6
LIZENZIERUNG
7
1.7
ABKÜRZUNGEN
7
2
EINFÜHRUNG
8
2.1
ANSTEUERUNG DER CIBJSMERGE DLL
9
2.1.1
Aufruf über CIB runshell
10
2.1.2
Aufruf über CIB job
11
2.2
CIB PLUG-IN FÜR LIBREOFFICE / APACHE OPENOFFICE
12
3
SYNTAXGRUNDLAGEN
13
3.1
ZEICHENERKLÄRUNG
13
3.2
VERWENDUNG VON FELDERN
13
3.2.1
Skriptfelder
14
3.2.2
Inhaltsfelder
14
3.3
GEMISCHTE SKRIPT- UND INHALTSFELDER
16
4
BESCHREIBUNG DER CIB-FUNKTIONEN
17
4.1
KURZREFERENZ
17
4.2
FUNKTIONEN IM DETAIL
18
4.2.1
text(text)
18
4.2.2
fref(name, {formfieldAttributes})
18
4.2.3
include(name, { includeAttributes })
19
4.2.4
ref(variableName) und getData(variableName)
20
4.2.5
isEmptyRef(variableName)
20
4.2.6
existsRef(variableName)
21
4.2.7
setData(variableName, value)
21
4.2.8
formatDate(formatString, date)
21
4.2.9
Verarbeitung von Eingabedaten in Tabellenform
22
4.2.9.1
resetRec(tablealias)
23
4.2.9.2
hasRec(tablealias)
23
4.2.9.3
nextRec(tablealias)
23
4.2.9.4
mergeRec(tablealias)
23
3 | 42
4.2.9.5
Besonderheiten bei den erstellten dynamischen Tabellen
24
4.3
RESERVIERTE VARIABLEN UND FUNKTIONEN
25
5
JAVASCRIPT KONTROLLSTRUKTUREN
26
5.1
BEDINGTE ANWEISUNGEN
26
5.2
SCHLEIFENANWEISUNGEN
27
5.3
VERGLEICHSOPERATOREN
27
6
JAVASCRIPT FUNKTIONEN
28
6.1
GLOBALE FUNKTIONEN
28
6.2
LOKALE FUNKTIONEN
28
6.3
EXPORT VON LOKALEN FUNKTIONEN
29
6.4
SUPPORT DER JAVASCRIPT-FUNKTIONEN
29
7
UNTERSTÜTZTE INHALTE UND EIGENSCHAFTEN
30
8
FÜR RTF-UMSTEIGER: GEGENÜBERSTELLUNG DER FUNKTIONEN
32
8.0.1
Abbildung von RTF-Feld-Befehlen auf die Skriptlogik
32
9
ANWENDUNGSBEISPIEL
38
4 | 42
1
ALLGEMEIN
1.1 HINWEIS
© Copyright 2014 CIB software GmbH. Alle Rechte vorbehalten.
Die CIB software GmbH behält sich sämtliche Eigentumsrechte an der angebotenen Software und
der dazugehörigen Dokumentation vor. Die Benutzung der Software und des dazugehörigen
Benutzerhandbuches unterliegen dem der Software zugrundeliegenden Lizenzvertrag. Die
Bereitstellung und der Download dieses Dokuments und der Software allein bewirken keine
Übertragung von Nutzungs- und Vervielfältigungsrechten.
Kein Teil dieses Handbuchs darf ohne schriftliche Genehmigung der CIB software GmbH in
irgendeiner Form reproduziert oder weiterverwertet werden. Auch eine Bearbeitung, insbesondere
eine Übersetzung der Dokumentation, ist ohne Genehmigung der CIB software GmbH nicht
gestattet. Der Inhalt dieses Handbuches ist auch urheberrechtlich geschützt, wenn es nicht mit der
Software geliefert wird, die eine Endbenutzerlizenzvereinbarung enthält.
CIB Produktbezeichnungen wie CIB coSys, CIB workbench, CIB jsMerge, CIB merge, CIB format, CIB
pdf toolbox sind entweder eingetragene Marken oder Marken der CIB software GmbH.
Windows ist eine eingetragene Marke der Microsoft Corporation.
Solaris und Java sind Marken bzw. eingetragene Marken der Sun Microsystems, Inc.
Alle anderen Marken- und Produktnamen sind Marken oder eingetragene Marken der jeweiligen
Rechteinhaber.
Der Inhalt dieses Handbuchs wurde mit größter Sorgfalt erarbeitet. Die Angaben in diesem
Handbuch gelten jedoch nicht als Zusicherung von Eigenschaften des Produktes. Die CIB software
GmbH haftet nur im Umfang ihrer Verkaufs- und Lieferbedingungen und übernimmt keine Gewähr
für technische Ungenauigkeiten und oder Auslassungen.
Die CIB software GmbH haftet weder für technische oder typographische Fehler und Mängel in
diesem Handbuch, noch für Schäden, die direkt oder indirekt auf die Lieferung, Leistung und
Nutzung dieses Materials zurückzuführen sind.
Die Informationen in diesem Handbuch können ohne Ankündigung geändert werden.
Sollten während des Einsatzes Unstimmigkeiten in Zusammenhang mit den Ausführungen in dieser
Übersicht auftreten, sind wir Ihnen für entsprechende Hinweise sehr dankbar:
CIB software GmbH
Elektrastraße 6a
81925 München
E-Mail:
[email protected]
5 | 42
Tel.:
49 (0)89 / 1 43 60 - 111
Fax.:
49 (0)89 / 1 43 60 - 100
1.2 SUPPORT
E-Mail:
[email protected]
Tel.:
49 (0)89 / 1 43 60 - 111
Fax.:
49 (0)89 / 1 43 60 – 100
1.3 VERSIONSHISTORIE
Version
Beschreibung
Datum
1/0
Erstausgabe
28.10.2014
1.4 LITERATURVERWEIS
Dokumentationsart
Titel
Technischer Leitfaden
Technischer Leitfaden CIB merge (für RTF-Dokumente)
Technischer Leitfaden
Technischer Leitfaden CIB jsMerge
Schulung
Textprogrammierung im RTF-Format:
Dynamische Dokumente - Band 1 – Grundlagen
Dynamische Dokumente - Band 2 - fortgeschrittene Optionen
1.5 LIEFERUMFANG
Versionshistorie
CibJSMerge.h
6 | 42
Win32:
CibDataCsv.dll
CibDataXml.dll
CibJSMerge32.dll
Xalan-C_1_5_0.dll
Xerces-c_2_2_0.dll
Linux:
libcibdatacsv.so
libcibdataxml.so
libcibjsmrgux.so
libxerces-c.so.22
libxalan-c1_5_0.so
1.6 LIZENZIERUNG
Dieses Dokument gibt keine Hinweise zur Lizenzierung. Detaillierte Informationen zu Lizenzierung
und den Lizenzmodellen erhalten Sie von den Mitarbeitern des CIB Vertriebs.
1.7 ABKÜRZUNGEN
In diesem Dokument werden folgende Abkürzungen benutzt:
−
CSV
comma separated values, Standardformat zur Datenübergabe
−
DOCX doc eXtended, an die alte Dateiendung (doc) von Word-Dateien bis Word 2007 hat
wegen dem danach erweiterten Dateiformat (eXtended, XML-basiert) ein X angehängt
bekommen.
−
ODF
Open Document Format (XML basiert, ISO zertifiziert)
−
ODT
OpenDocument Text
−
RTF
Rich Text Format, leistungsfähiges, standardisiertes Dateiformat zur
Beschreibung von Dokumenten
−
XML
eXtended Markup Language, Standardformat zur Datenübergabe
7 | 42
2
EINFÜHRUNG
CIB jsMerge ist eine zentrale Komponente innerhalb der CIB office Module (CoMod) zur Erzeugung
von dynamischen Dokumenten unter Verwendung von ODT-Formaten und JavaScript basierten
Feldanweisungen.
XML basierte offene Dokumentenformate wie Open Document und Office Open XML finden immer
größere Verbreitung. Vor allem da sich auch Microsoft entschieden hat, das Office Open XML
Format als Standardformat in den aktuellen Versionen von Microsoft Office zu verwenden.
XML basierte offene Dokumentenformate werden dadurch zunehmend eine Alternative zum bis
Dato für die Textprogrammierung verwendeten RTF (Rich Text)-Format. Einige CIB Module
verarbeiten bisher das RTF-Format und mit dem Modul CIB jsMerge wird die Palette erweitert auf
die zusätzliche Verarbeitung von ODT- und DOCX-Formaten.
CIB jsMerge interpretiert die Feldanweisungen, die sich in den Dokumentbausteinen (sogenannten
Templates) befinden und mischt in diese optional variable Daten ein. Das Ergebnis ist ein
Zieldokument, in dem die Feldanweisungen aufgelöst und die aktuell zugesteuerten Daten direkt
enthalten sind. Die variablen Daten können aus CSV-Dateien und XML-Dateien eingemischt werden.
Für die Dokumentbausteine wird aktuell das ODT-Format unterstützt. Die Verwendung des DOCXFormates ist möglich, ist derzeit jedoch noch nicht voll implementiert.
8 | 42
2.1 ANSTEUERUNG DER CIBJSMERGE DLL
CIB jsMerge kann als CibJSMerge32.dll über die CIB runshell oder CIB job angesteuert werden.
Folgende Parameter können dabei übergeben werden:
inputfile:
Als Eingabedatei kann hier eine .odt-Datei angegeben werden. Diese Datei stellt das
Wurzeldokument dar. Im Wurzeldokument können weitere Dokumente eingebunden werden.
outputfile:
Hier wird der gewünschte Dateiname des Ergebnisdokuments angegeben. Das Ergebnisdokument
enthält alle aus den Bausteinen und der Datenversorgung eingemischten Informationen.
scriptfile:
In der Skriptdatei können globale Funktionen in der Skriptsprache JavaScript definiert werden, die
dann in allen Templates zur Verfügung stehen.
licenseCompany:
Mit dieser Property wird der Lizenznehmer aus den Lizenzdaten an CIB jsMerge gesetzt. Diese
Property muss bei einem Aufruf gesetzt sein.
licenseKey:
Mit dieser Property wird der Lizenzschlüssel aus den Lizenzdaten an CIB jsMerge gesetzt. Diese
Property muss bei einem Aufruf gesetzt sein.
datafile:
Als Datenversorgung kann eine CSV-Datei oder eine XML-Datei dienen. Diese Dateien enthalten die
Daten, die später im Wurzeldokument oder dessen eingebundenen Vorlagen verwendet werden.
multidatafile:
Handelt es sich bei der verwendeten CSV- oder XML-Datei um eine Multi-Datenversorgung, muss
diese Property mit dem Wert „1“ gesetzt werden.
headerfile:
Dieser Parameter wird bei der Datenversorgung mit XML eingesetzt. Er zeigt auf die gesetzte
Datendatei. Wird „headerfile“ in Kombination mit dem Parameter „multidatafile“ verwendet, so
gibt „datafile“ den XPath zu den Multiknoten an.
ignoreInvalidXMLCharacters:
Wird dieser boolesche Parameter mit dem Wert „1“ gesetzt, werden nicht gültige XML-Zeichen in
der Datenversorgung herausgefiltert. Ist dieser Parameter auf „0“ gesetzt, gibt CIB jsMerge im
Falle von nicht-validen Zeichen einen Fehler aus.
logfile:
Der Parameter setzt den Dateinamen (und Pfad) für die Fehlerprotokoll-Datei. Dieser Parameter
kann nicht in der Skriptdatei gesetzt werden.
9 | 42
loglevel:
Über den Parameter „loglevel“ kann man die Menge/Art der Fehlermeldungen im Logfile
bestimmen. Es gibt die folgenden Levels: FATAL | ERROR | WARN | INFO | DEBUG | TRACE | ALL
Je allgemeiner das Level gewählt wird, desto größer wird die Datei. Der Default Wert ist „INFO“.
Dieser Parameter kann nicht in der Skriptdatei gesetzt werden.
Hinweis:
Alle oben genannten Parameter bis auf „logfile“ und „loglevel“ können auch innerhalb der
Skriptdatei übergeben werden.
Beispiel Skriptdatei:
setProperty("inputfile", "./Dateiname.odt");
setProperty("outputfile", "Dateiname_out.odt");
setProperty("datafile", "testordner/steuer.csv");
setProperty("multidatafile", "1");
2.1.1 Aufruf über CIB runshell
Über die CIB runshell kann CIB jsMerge wie folgt angesteuert werden:
Cibrsh.exe <property1>=<value1> <property2>=<value2> -js [<inputfile name><outputfile name>]
Beispiel:
Cibrsh.exe scriptfile=meinSkript.js licenseCompany=Lizenznehmer licenseKey=xxxx-xxxxx-xxxxxxxx
datafile=Daten.csv inputfile=Eingabe.odt outputfile=Ausgabe.odt –js
Beim Aufruf über die CIB runshell ist es auch möglich, die Ein- und Ausgabedateien ohne Angabe
der Parameter-Bezeichnungen „inputfile“ und „outputfile“ zu setzen.
Beispiel:
Cibrsh.exe scriptfile=meinSkript.js licenseCompany=Lizenznehmer licenseKey=xxxx-xxxxx-xxxxxxxx
datafile=Daten.csv Eingabe.odt Ausgabe.odt –js
Hinweise:
Die Properties licenseCompany und licenseKey müssen bei jedem Aufruf gesetzt werden.
Properties können grundsätzlich sowohl direkt im Aufruf über die CIB runshell als auch in der
Skriptdatei gesetzt werden. Dabei gilt:
Sind Properties im CIB runshell-Aufruf gesetzt, haben diese Properties standardmäßig Vorrang vor
Properties, die in der Skriptdatei angegeben wurden.
Sollen die in der Skriptdatei angegebenen Properties gelten, so muss in der Skriptdatei der
Override-Parameter innerhalb des setProperty()-Befehls auf „true“ gesetzt werden.
10 | 42
Beispiel:
Für den oben bereits dargestellten CIB runshell-Aufruf
Cibrsh.exe scriptfile=meinSkript.js licenseCompany=Lizenznehmer licenseKey=xxxx-xxxxxxxxxxxxx datafile=Daten.csv inputfile=Eingabe.odt outputfile=Ausgabe.odt –js
wird Folgendes in der Skriptdatei „meinSkript.js“ gesetzt:
setProperty("inputfile", "./AndereEingabe.odt", true);
setProperty("outputfile", "AndereAusgabe.odt", false);
setProperty("datafile", "testordner/AndereDaten.csv");
In diesem Beispiel wird an CIB jsMerge die Eingabedatei „AndereEingabe.odt“ aus dem Skript
„meinSkript.js“ übergeben, da der Override-Parameter für „inputfile“ auf „true“ gesetzt wurde. Der
über den CIB runshell-Aufruf direkt angegebene Parameter „inputfile“ wird in diesem Fall
ignoriert.
Für die Ausgabedatei und die Datenversorgung werden die im CIB runshell-Aufruf genannten
Dateien „Daten.csv“ und „Ausgabe.odt“ übergeben.
Für diese beiden Properties „outputfile“ und „datafile“ wurde in der Skriptdatei der OverrideParameter nicht oder auf „false“ gesetzt, somit gilt das Standardverhalten.
2.1.2 Aufruf über CIB job
Für die Ansteuerung über CIB job wurde ein neuer Jobstep: „jsmerge“ eingeführt. In diesem
Jobstep können die Eigenschaften wie gewohnt an CIB jsMerge gesetzt werden.
<step name="jsmerge" command="jsmerge">
<properties>
<property name="inputfile">FirstScriptField.odt</property>
<property name="outputfile">out.odt</property>
<property name="licenseCompany">Lizenznehmer</property>
<property name="licenseKey">xxxx-xxxx-xxxxxxx</property>
</properties>
</step>
11 | 42
2.2 CIB PLUG-IN FÜR LIBREOFFICE / APACHE OPENOFFICE
Die CIB software GmbH hat ein Plug-In als Extension für LibreOffice / Apache OpenOffice
entwickelt, welches Zusatzfunktionalitäten für das Einfügen und Arbeiten mit Feldern bietet. Das
Plug-In kann über den „Extension Manager“ hinzugefügt werden und ist dann über eine neue
Symbolleiste in LibreOffice / Apache OpenOffice ansprechbar.
Dieses Plug-In überträgt die aus Microsoft Word bekannte Funktion zum Einfügen neuer Felder
über die Tastenkombination STRG-F9 nach LibreOffice / Apache OpenOffice. So können neue Felder
entweder per Klick auf die Schaltfläche „Neuer Block“ (in der Symbolleiste) oder über die
Tastenkombination STRG-F9 eingefügt werden. Ein Feld besteht aus zwei Feldmarkierungen – einer
öffnenden und einer schließenden Klammer – die untrennbar zusammen gehören.
Neben der Vereinfachung beim Einfügen von Feldern unterstützt die Extension auch dabei, die
Integrität der eingefügten Feldmarkierungen bei gängigen Editier-Aktionen zu wahren: Das
ungewollte Löschen einzelner Feldmarkierungen mittels der Tasten Rück / Backspace oder ENTF /
DEL wird verhindert. Beim Ausschneiden (Cut), Einfügen (Paste) oder Kopieren (Copy) von
selektierten Feldern oder Feldteilen wird darauf geachtet, dass bestehende Felder vollständig
ausgeschnitten, überschrieben oder kopiert werden. Eine ungültige Selektion, wenn z.B. ein Teil
eines Feldes mit nur einer Feldmarkierung ausgewählt ist, wird dabei zunächst so ausgeweitet,
dass das vollständige Feld in der Auswahl liegt. Anschließend kann das Ausschneiden, Einfügen
oder Kopieren ohne Integritätsverlust wiederholt werden.
Anmerkungen:
·
Im Unterschied Microsoft Office wird aus Performance-Gründen nicht bereits während der
Selektion von Text darauf geachtet, dass Felder nur vollständig erfasst werden können. Die
Konsistenzprüfung findet nur bei den o.g. gängigen Editier-Aktionen statt.
·
Die Extension kann den Vorlagenersteller nicht vor allen möglichen Fehlersituationen
bewahren. Bei weniger gängigen Editier-Aktionen, wie z.B. dem Einfügen bestimmter
Inhalte über das Menü „Einfügen“, findet keine Integritätsprüfung statt. Beim Einfügen
dieser Inhalte wird die tatsächliche aktuelle Selektion durch den neuen Inhalt ersetzt, ggf.
ungeachtet enthaltener Feldmarkierungen.
·
Bei der Nutzung von Redo- und Undo-Funktionen (STRG+Y, STRG+Z) kann es ebenfalls zu
Inkonsistenzen kommen.
Nähere Informationen zur Verwendung von Feldern finden sich in Kapitel 3.2 und 3.3 in diesem
Dokument. Bei Interesse an der LibreOffice / Apache OpenOffice Plug-In Extension wenden Sie sich
bitte an den CIB Vertrieb.
12 | 42
3
SYNTAXGRUNDLAGEN
In diesem Kapitel erfolgt die Beschreibung von Grundlagen, die für das Verständnis und damit für
die Eingabe der Funktionen bei der Textprogrammierung benötigt werden. Es handelt sich dabei
sowohl um die Verwendung reservierter Zeichen als auch um die Klärung von Grundbegriffen.
3.1 ZEICHENERKLÄRUNG
Bei den in nachfolgender Tabelle erläuterten Zeichen handelt es sich um reservierte Zeichen, die in
der Textprogrammierung eine feste Bedeutung besitzen.
Hinweis:
Auf die Bedeutung der in den Beschreibungen verwendeten Begriffe (z.B. Skriptfeld) wird in den
folgenden Kapiteln genauer eingegangen.
Zeichen
Bedeutung
Beschreibung
{
Feldmarkierung
Per STRG-F9 in MS Word oder über das CIB
officeControlBlocks Plug-In in LibreOffice eingefügtes
Zeichen. Es handelt sich um ein Klammerzeichen, das
immer paarweise vorkommt.
Geschweifte Klammer
Normale textuelle Klammer, kommt in Skriptfeldern immer
paarweise vor.
#
Startzeichen Skriptfeld
Zeichnet ein Feld als Skriptfeld aus, dessen Inhalt von CIB
jsMerge ausgewertet wird.
‘
Escape-Zeichen
(Maskierungszeichen)
LibreOffice
Mit dem Apostroph als Maskierungszeichen können
andere geschützte Zeichen als Beginn eines Feldes
verwendet werden, z.B. das #.
‘
Escape-Zeichen
(Maskierungszeichen) MS
Word
In MS Word muss ein Inhaltsfeld mit dem Apostroph
eingeleitet werden, um das Feld von MS Word
Standardfeldern unterscheiden zu können.
|
Pipe-Zeichen
Das Fieldresult wird intern von LibreOffice getrennt durch
„|“ an den Feldbefehl angehängt.
}
{
}
3.2 VERWENDUNG VON FELDERN
Felder sind definierte Elemente, die für die Textprogrammierung in dynamischen Dokumenten
benötigt werden. Die in einem Dokument verwendeten Felder werden bei einem Mischvorgang
direkt durch den CIB jsMerge interpretiert und dynamisch in die Ausgabedatei umgesetzt.
13 | 42
Sie sind in ihrer Handhabung und Struktur ähnlich den aus MS Word bekannten Feldern.
Unterschieden wird hier jedoch zwischen sogenannten Skriptfeldern und Inhaltsfeldern. Details zu
deren Verwendung befinden sich in den nachfolgenden Kapiteln.
Ein Feld ist eine spezielle Komponente innerhalb eines Dokuments und hat folgenden Aufbau:
{ Feldinhalt }
Felder werden mit geschweiften Klammern {
} als Feldmarkierung umschlossen. Dabei ist zu
beachten, dass öffnende und schließende Klammer untrennbar zusammengehören.
Wichtig:
Felder können nur über die entsprechenden Befehle des Texteditors hinzugefügt werden. In MS
Word z.B. über die Tastenkombination STRG-F9, in LibreOffice über die Schaltfläche „Neuer Block“
des CIB officeControlBlocks Plug-In.
Manuell eingefügte geschweifte Klammern (ALT GR – 7 bzw. ALT GR - 0) werden nicht als
Feldmarkierungen gewertet.
3.2.1 Skriptfelder
Skriptfelder enthalten eine oder mehrere Anweisungen eines Skripts sowie zusätzliche Metadaten.
Eingeleitet werden Skriptfelder mit dem Nummernzeichen „#“ und haben folgende Struktur:
{#SkriptInhalt }
Der Text, der als „SkriptInhalt“ im Feld steht, wird von einem Skriptinterpreter ausgewertet. Dieser
„SkriptInhalt“ kann auch aus einem oder mehreren eingebetteten Feldern bestehen.
Beispiele:
{# text(ref(“Vorname”)) }
{# if(ref(“Vorname”)!=””) text(ref(“Vorname”)) }
3.2.2 Inhaltsfelder
Inhaltsfelder dienen dazu, Textinhalte, die innerhalb eines Skriptfeldes nicht ausgewertet werden
sollen, entsprechend zu kennzeichnen. So ist es möglich, den Quellcode des Skripts mit normalem
Textinhalt zu kombinieren. Das Skript entscheidet dann, welche Inhaltsfelder in das
Ergebnisdokument geschrieben werden und welche nicht. Inhaltsfelder haben den folgenden
Aufbau:
{‘NichtAuszuwertenderTextinhalt }
oder
14 | 42
{NichtAuszuwertenderTextinhalt } (Nur in ODT möglich)
„NichtAuszuwertenderTextinhalt“ kann jeglicher Textinhalt sein, der vom Texteditor unterstützt
wird, d.h. in allen Formaten (z.B. Rich Text) und Formatierungsmöglichkeiten (z.B. Tabellen).
Achtung:
Das Inhaltsfeld darf nicht mit einem Nummernzeichen „#“ beginnen, da es sonst als Skriptfeld
gewertet würde. Um trotzdem das Nummernzeichen als erstes sichtbares Zeichen im Inhaltsfeld zu
verwenden, wurde als Escape-Zeichen das Apostroph (‘) eingeführt. Nach dem Apostroph darf
jeglicher Textinhalt stehen, auch ein weiteres Apostroph.
Beispiel:
{#1 } dieses Feld wird als Skriptfeld ausgewertet
{‘#1 } das Nummernzeichen ist korrekt maskiert
Weitere Beispiele für Inhaltsfelder:
{‘Das ist der Textinhalt dieses Inhaltsfelds}
{‘Der Inhalt kann auch Tabellen enthalten:
Tabelle innerhalb
des Inhaltsfelds
und vieles mehr
}
Nur in ODT Vorlagen funktioniert auch dieses Inhaltsfeld: { Inhaltsfeld ohne Apostroph}
Hinweis zu MS Word:
In MS Word möchte man auch auf die von jeher in MS Word bekannten Felder wie { DATE }
zurückgreifen können. Diese MS Word Felder werden von CIB jsMerge aber nicht ausgewertet. Um
die drei verschiedenen Feldarten Skriptfelder, Inhaltsfelder und MS Word Felder entsprechend zu
unterscheiden wurde festgelegt, dass CIB jsMerge Inhaltsfelder nur erkennt, wenn das Feld mit
einem ‘ eingeleitet entsprechend maskiert ist.
Beispiele:
{ DATE }
Wird von CIB jsMerge nicht ausgewertet
{‘ein Inhalt }
Dies ist ein Inhaltsfeld. Der String „ein Inhalt“ wird in das Ergebnisdokument
geschrieben
{‘DATE }
Dies ist ein Inhaltsfeld. Der Inhalt „DATE“ wird in das Ergebnisdokument
geschrieben
15 | 42
3.3 GEMISCHTE SKRIPT- UND INHALTSFELDER
Die nachfolgenden Beispiele zeigen, wie Skript- und Inhaltsfelder zu einer sinnvollen Struktur
kombiniert werden können.
{# if(ref(“Vorname“)== “Bob“) {‘Hallo Bob!} else {‘Hallo zusammen!} }
Abhängig vom Inhalt der Variable “Vorname“ wird in das Ergebnisdokument entweder der Inhalt
des ersten Inhaltsfelds (“Hallo Bob“) oder der Inhalt des zweiten Inhaltsfelds (“Hallo zusammen“)
geschrieben.
Im nächsten Beispiel wird eine switch-Anweisung verwendet um 3 verschiedene, alternative
Textbausteine auszugeben, abhängig vom Inhalt der Variable “Vorname“.
{#switch(ref(“Vorname“)) {
case “Bob“: {‘Hallo Bob!} break;
case “Alice” {‘Hallo Alice!} break;
default: {‘Hallo zusammen!}
}}
16 | 42
4
BESCHREIBUNG DER CIB-FUNKTIONEN
4.1 KURZREFERENZ
Als Überblick eine Liste der Funktionen mit kurzer Beschreibung und deren Rückgabewerten:
Funktion
Beschreibung
Funktion ist eine Erweiterung von “text(ref(name))“. Es
können zusätzliche optionale Parameter angegeben werden.
„{formfieldAttributes}“: Dienen der Beschreibung von
Dialogfeldern, sie werden aktuell noch nicht ausgewertet.
text(text)
Kopiert den Wert des angegebenen Parameters „text“ in das
Zieldokument
ref(variableName) oder
getData(variableName)
Gibt den Wert der Variablen „variableName” zurück
include(name,
{includeAttributes})
Fügt die Vorlage “name” in das Ergebnisdokument
ein.“name” kann dabei mit relativem Pfad zum aktuellen
Verzeichnis angegeben werden, oder mit absolutem Pfad.
„{includeAttributes}“: Können optional angegeben werden
und steuern, wie die Vorlage einzufügen ist.
picture(name)
Funktion ist noch nicht implementiert.
Fügt die Grafikdatei „name” in das Ergebnisdokument ein.
„name” kann dabei mit relativem Pfad zum aktuellen
Verzeichnis angegeben werden, oder mit absolutem Pfad.
isEmptyRef(variableName)
Diese Funktion liefert „True“, wenn „variableName” eine
Länge von 0 hat oder die Variable nicht definiert ist;
andernfalls liefert sie „False“ zurück.
Liefert „True“, wenn die Variable „variableName” definiert
ist, andern falls „False“.
Belegt den Wert der Variablen „variableName” mit dem
angegebenen Wert „value“.
formatDate(formatString, date)
Liefert die in „formatString“ definierte Formatierung des
Datums „date“ zurück.
deDate()
Die Funktion erwartet ein Datum im Format
„dd.MM.yyyy“
17 | 42
Funktion
Beschreibung
Positioniert auf den ersten Datensatz der Tabelle
„tablealias“.
hasRec(tablealias)
Liefert den Wert “wahr” zurück, wenn es den aktuell
positionierten Datensatz der Tabelle „tablealias“ gibt,
ansonsten „False“.
nextRec(tablealias)
Positioniert auf den nächsten Datensatz in der Tabelle
„tablealias“.
mergeRec(tablealias)
Gibt die Nummer des gerade gelesenen Datensatzes in der
Tabelle „tablealias“ zurück.
4.2 FUNKTIONEN IM DETAIL
4.2.1 text(text)
Die text(text)-Funktion kopiert den aus dem Parameter „text“ ermittelten Text in das
Ergebnisdokument. Der Parameter kann dabei auch ein von einer Funktion zurückgelieferter Wert
sein.
Der Text wird mit denselben Formatierungsoptionen eingefügt, mit der das Startzeichen ({) des
zugehörigen Skriptfelds formatiert ist.
Beispiele:
{# text(“Hallo Welt”)}
{# text(ref(“MeineVariable”))}
Hinweis:
In mehrzeiligem Text kann durch „\n“ ein neuer Paragraph erzeugt werden.
4.2.2 fref(name, {formfieldAttributes})
Die Funktion kopiert den Inhalt der als Parameter „name“ übergebenen Variablen in das
Ergebnisdokument. Das Verhalten dieser Funktion unterscheidet sich vom Aufruf „text(ref(name))“
durch die Möglichkeit, zusätzliche optionale Parameter angeben zu können. Er ist damit dem
„text(ref(name))“ vorzuziehen.
Der Parameter „{formfieldAttributes}“ wird zukünftig der Beschreibung von Dialogfeldern für eine
18 | 42
Restdatenerfassung dienen. Er wird allerdings aktuell noch nicht ausgewertet und kann damit
derzeit weggelassen werden.
4.2.3 include(name, { includeAttributes })
Mit der include()-Funktion wird die Vorlage mit dem angegebenen Dateinamen „name“ in das
Ergebnisdokument eingebunden. Der Dateiname kann dabei entweder den absoluten Dateipfad
enthalten, oder einen zum aktuellen Arbeitsverzeichnis relativen Dateipfad.
Die Dateiendung (z.B. .docx, .odt, .ott) kann auch weggelassen werden. In diesem Fall bestimmt
das Format der aufrufenden Vorlage, nach welchen Namensendungen gesucht wird. Ist die
aufrufende Vorlage ein ODT-Dokument, wird nach *.odt, *.ott, *.ODT und *.OTT gesucht. Ist die
aufrufende Vorlage ein DOCX-Dokument, wird nach *.docx, *.docm, *.DOCX und *.DOCM gesucht.
Als optionaler Parameter { includeAttributes } wird eine Hash-Tabelle erwartet. Folgende Optionen
werden innerhalb der Hash-Tabelle unterstützt:
Die Option „importPageSettings“ bestimmt, welche Seiten/Abschnittseigenschaften im aktuellen
Abschnitt des Ergebnisdokuments angewandt werden sollen. Folgende Werte sind für
importPageSettings möglich:
·
„autoHeaderFooter“: Wenn in der importierten Vorlage Kopf- oder Fußzeilen definiert sind,
so werden sie in das Ergebnisdokument übernommen. Sind keine Kopf- oder Fußzeilen
definiert, greifen die Kopf- und Fußzeilen Definitionen aus der aufrufenden Vorlage (falls
dort welche definiert sind). Andere Abschnitts- und Seiteneigenschaften werden nicht aus
der importierten Vorlage übernommen.
·
„all“: Neben den Kopf- und Fußzeilen werden alle Abschnitts- und Seiteneigenschaften aus
der importierten Vorlage übernommen. Dieser Wert kann damit z.B. genutzt werden, wenn
mehrere unabhängige Teildokumente mit allen ihren Eigenschaften hintereinander
verkettet werden sollen.
·
„none“: Weder Kopf- und Fußzeilen noch andere Abschnitts- und Seiteneigenschaften
werden aus der importierten Vorlage übernommen. Es wird nur der eigentliche Textinhalt
eingefügt.
Wird „importPageSettings“ nicht angegeben, greift der Standard Wert „autoHeaderFooter“.
Beispiele:
{# include(“abaustGruss2.odt”)}
{# include(“belehrungstext.odt”)}
{# include(“belehrungstext.odt”, {importPageSettings:”none”})}
19 | 42
4.2.4 ref(variableName) und getData(variableName)
Diese Funktionen sind identisch und liefern den Wert der Variable „variableName“ zurück. Um eine
Variable in diesen Funktionen verwenden zu können, muss sie in der Datenversorgung vorkommen
oder vorher mit „setData“ belegt worden sein. Ist das nicht der Fall, wird ein Fehler ausgegeben.
Beispiele:
{# ref(“meineVariable”)}
{# ref(“institut.EL_KIN_BEZ”)}
{# var i=1; ref(“institute.EL_KIN_BEZ” + i)}
Wenn der „variableName“ ein spezielles Trennzeichen enthält (Standardmäßig ist das der “.”),
dann wird die Variable als eine Tabellenvariable gewertet. Dabei beschreibt der erste Teil vor dem
Trennzeichen den Tabellen-Alias, der zweite Teil beschreibt den Namen des Knotens, der
ausgewählt werden muss.
Wenn die Variable nicht aufgelöst werden kann, bewirkt diese Funktion, dass die umliegende
Funktion mit einem Fehler beendet.
Achtung:
Soll der Rückgabewert im Kontext einer Nummernverarbeitung / als Zahl weiterverarbeitet werden,
so muss das ref mit der JavaScript-Standardfunktion Number() umgeben werden. Ansonsten wird
der Inhalt der Variable als String ausgewertet.
Beispiel:
{# setData(“meinBetrag”, 50)}
{# text(Number(ref(“meinBetrag”)) + 10)}
4.2.5 isEmptyRef(variableName)
Diese boolesche Funktion gibt „Wahr“ zurück, wenn die Variable „variableName“ eine Länge von 0
hat oder die Variable nicht aufgelöst werden kann. Andernfalls gibt sie „Falsch“ zurück.
20 | 42
4.2.6 existsRef(variableName)
Diese boolesche Funktion gibt „Wahr“ zurück, wenn die Variable „variableName“ aufgelöst werden
kann, d.h. in der Datenversorgung existiert. Andernfalls gibt die Funktion „Falsch“ zurück.
4.2.7 setData(variableName, value)
Die setData()-Funktion setzt den Wert der Variable „variableName“ auf den angegebenen Wert
„value“.
{# setdata(“meineVariable”, “Hallo”)}
{# var i=42; set(“meineVariable” + i, “Hallo”)}
Trennzeichen den Tabellen-Alias, der zweite Teil beschreibt den Namen des Knoten, der innerhalb
dieser Tabelle ausgewählt werden muss.
Es ist möglich, den Wert einer Tabellenvariablen zu überschreiben.
4.2.8 formatDate(formatString, date)
Die Funktion „formatDate(formatString, date)“ liefert die in „formatString“ definierte Formatierung
des Datums „date“ zurück.
Für „date“ werden die folgenden Varianten unterstützt:
deDate()
Funktion erwartet Datum im Format
„dd.MM.yyyy“ (dd und MM können auch ohne führende 0 geschrieben werden) oder
„dd.MM.“ (in diesem Fall wird das aktuelle Jahr ergänzt).
Bei Fehlern im String (z.B. keine 2 Punkte, keine Zahl, nicht existentes Datum wie
30.2.12) erfolgt eine JavaScript-Exception
new Date() Funktion liefert das aktuelle Datum und Uhrzeit, genau: Jahr, Monat, Tag, Stunde,
Minute, Sekunde, Millisekunde
Derzeit werden für „formatString“ die folgenden Formate unterstützt:
"t", "d", "tt", "dd", "MM", "M", "jjjj", "yyyy", "jj", "yy", "HH", "H", "mm", "m", "ss", "s"
21 | 42
Beispiele:
{# text(formatDate(“jjjj”,deDate(“28.08.2012”)))}
Mischt „2012“ in das Ausgabedokument ein
{# text(formatDate(“tt.MM.jj”, new Date()))}
Mischt das aktuelle Datum in der
angegebenen Formatierung ein, z.B.
„01.09.14“
{# text(formatDate(“jjjj”, enDate(“2012.08.10”)))}
Mischt „2012“ in das Ausgabedokument ein
4.2.9 Verarbeitung von Eingabedaten in Tabellenform
CIB jsMerge bietet die Möglichkeit einen oder mehrere gleichartige Eingabe-Datensätze (DatenTabelle) in einer Schleife einzulesen und deren Inhalte in das Ausgabedokument einzumischen. Im
Ausgabedokument wird damit eine dynamische Tabelle erzeugt. Die Eingabe-Datensätze können
sowohl aus CSV- als auch aus XML-Datenquellen kommen.
Für die Erzeugung von dynamischen Tabellen aus diesen Eingabedaten wurden spezielle
Funktionen implementiert. Die dynamische Tabelle wird über einen Aliasnamen angesprochen.
Dieser Aliasname wird definiert entweder über
·
Multi-Knoten in einer XML-Datenquelle oder
·
Name der CSV-Datenquelle (bei Single-CSV) oder
·
Eintrag in der Steuerdatei einer Multi-CSV-Datenquelle
Die Variable wird über den Namen angesprochen, unter dem sie in der Datenquelle definiert ist
(„variableName“). Um eine Variable aus einer Multi-Datenquelle eindeutig anzusprechen, muss der
Aliasname der Tabelle als Präfix vor den Variablennamen gesetzt werden.
Beispiel
{# ref(“<tablealias>.<variableName>”)}
Zur Veranschaulichung folgt ein Beispiel, in dem einige der für die Tabellenverarbeitung
eingeführten Funktionen enthalten sind:
{#while(hasRec(“Personen”)) {‘x
{#fref(“Personen.Anrede”))}
{#fref(“Personen.Name”))}
{#nextRec(“Personen”)}}}
Hinweis
Die Funktionen „resetRec()“, „hasRec()“, „nextRec()“ und „mergeRec()“ können auch ohne
„tablealias“ (oder mit „tablealias“=null) verwendet werden. In diesem Fall wirken diese
22 | 42
Funktionen auf sämtliche im Vorlagen-Projekt verwendeten dynamischen Tabellen.
Anwendungsbeispiele dafür wären das Erstellen von Serienbriefen oder Ausfertigungen.
4.2.9.1 resetRec(tablealias)
Die Funktion „resetRec(tablealias)“ positioniert auf den ersten Datensatz der Tabelle „tablealias“.
Wird diese Funktion ohne den Parameter „tablealias“ oder mit „tablealias“=null verwendet,
werden alle vorhandenen Tabellen auf den ersten Datensatz positioniert. Damit stehen auch alle
Datensatz-Zähler (=Rückgabewert der Funktion „mergeRec(…)“) auf 1.
4.2.9.2 hasRec(tablealias)
Die Funktion „hasRec(tablealias)“ liefert den Wert “wahr” zurück, wenn es den aktuell
positionierten Datensatz der Tabelle „tablealias“ gibt. Ist die Tabelle leer oder das Tabellenende
erreicht, (z.B. nach „nextRec(…)“), gibt die Funktion „falsch“ zurück.
Wird diese Funktion ohne den Parameter „tablealias“ oder mit „tablealias“=null verwendet, liefert
die Funktion „hasRec()“ nur dann den Wert “falsch” zurück, wenn das Ende aller Tabellen erreicht
ist. Ansonsten ist das Ergebnis „wahr“.
4.2.9.3 nextRec(tablealias)
Die Funktion „nextRec(tablealias)“ liest den nächsten Datensatz in der Tabelle „tablealias“.
Die Funktion verhält sich wie „{ next tablealias }“ mit dem Unterschied, dass die Angabe des
Aliasnamens obligatorisch ist. D. h. Variablen müssen immer mit Präfix angesprochen werden:
{#ref("<tablealias>.<variableName>"))}
Beispiel:
{# text(ref(“Person.CustomerID”));
nextRec(“Person”);
text(ref(“Person.CustomerID”));}
In diesem Beispiel wird die „customerID“ des ersten und zweiten Datensatzes in das
Ausgabedokument eingemischt.
Wenn die Funktion „nextRec(tablealias)“ das Ende der Tabelle „tablealias“ erreicht, setzt sie alle
Variablen dieser Tabelle auf leer (d.h. “”) und die Funktion „hasRec(tablealias)“ wird beim
nächsten Aufruf “falsch” zurückliefern, der Zähler „mergeRec(tablealias)“ auf „0“ gesetzt. Weitere
Aufrufe der Funktion „nextRec(tablealias)“ ändern nichts an diesem Zustand.
Wenn die Funktion „nextRec()“ ohne den Parameter „tablealias“ oder mit „tablealias“=null
23 | 42
verwendet wird, wird für alle vorhandenen Tabellen auf den nächsten Datensatz weitergeschaltet.
In diesem Fall gibt es einen globalen internen Zähler, der alle Aufrufe der Funktion „nextRec()“
zählt. Dieser Zähler beginnt bei 1 und wird durch die Funktion „resetRec()“ auf 1 zurückgesetzt. Er
zählt nicht mehr weiter, wenn das Ende aller Tabellen erreicht ist.
4.2.9.4 mergeRec(tablealias)
Die Funktion „mergeRec(tablealias)“ gibt die Nummer des gerade gelesenen Datensatzes in der
Tabelle „tablealias“ zurück (beginnend bei 1 für den ersten gelesenen Datensatz).
Beispiel:
{#while(hasRec(“Personen”)) { if((Number(mergeRec(“Personen”)) % 2) == 0) {‘x
{#fref(“Personen.Anrede”)}
{#fref(“Personen.Vorname” +
fref(“Personen.Nachname”)}
{#fref(“Personen.Anrede”)}
{#fref(“Personen.Vorname” +
ref(“Personen.Nachname”)}
} else {‘x
} nextRec(“Personen”);}}
Wird das Beispiel ohne den Parameter „tablealias“ oder mit „tablealias“=null ausgeführt, gibt die
Funktion den Stand des internen globalen Zählers zurück, wie er durch die Funktion „nextRec()“
verwendet wird.
Bei Tabellenüberlauf wird „mergeRec(tablealias)“ auf „0“ gesetzt.
4.2.9.5 Besonderheiten bei den erstellten dynamischen Tabellen
Die folgenden Besonderheiten im Zusammenhang mit dynamischen Tabellen in LibreOffice, wie in
den Beispielen in diesem Dokument zu sehen, gilt es zu beachten:
Um ausgeblendete Absätze in LibreOffice zu realisieren, muss in einem auszublendenden Absatz
mindestens ein Zeichen (in unseren Beispielen: „x“) vorkommen. Dieses Zeichen muss dann
„ausgeblendet“ formatiert werden. Absatzmarken können, anders als in MS Word, nicht als
„ausgeblendet“ gekennzeichnet werden.
Hinweis:
Im Ausgabedokument entsteht für jeden Datensatz eine einzeilige Tabelle. Im Eingabedokument
müssen die Absätze vor der Tabelle „ausgeblendet“ formatiert sein, damit die Einzelzeilen im
Ausgabedokument optisch wie eine große Tabelle wirken:
24 | 42
{#while(hasRec(“Personen”)) {‘x
(siehe auch das Beispiel in Kapitel 4.2.9.4)
Im Gegensatz zu MS Word interpretiert LibreOffice diese Tabellenzeilen nicht als eine einzige
Tabelle.
Damit wird auch eine vorher definierte Tabellenüberschrift nicht auf die Gesamtheit der einzelnen
Tabellenzeilen angewendet, d.h. sie erscheint nur einmalig, aber nicht auf den Folgeseiten.
4.3 RESERVIERTE VARIABLEN UND FUNKTIONEN
Die folgenden Variablennamen sind aktuell in CIB jsMerge nicht belegt. Ihre Umsetzung ist aber für
spätere Versionen geplant:
Funktion oder Variable
Beschreibung
data
Name reserviert; Noch nicht implementiert.
ERROR
OUTPUTMODE
25 | 42
5
JAVASCRIPT KONTROLLSTRUKTUREN
JavaScript Anweisungen stellen den größten Anteil der Textprogrammierung dar. Eine umfassende
Beschreibung der Syntax und Anwendung von JavaScript wird hier nicht behandelt. Einen
detaillierten Überblick liefern einschlägige online-Dokumentationen wie beispielsweise:
http://www.w3schools.com.
https://developer.mozilla.org/de/docs/JavaScript
Im Folgenden soll kurz auf die im Kontext dieser Befehlsreferenz relevantesten JavaScript
Kontrollstrukturen eingegangen werden. Diese Strukturen sind auch in der RTF-Programmierung
entsprechend abgebildet.
5.1 BEDINGTE ANWEISUNGEN
Bedingte Anweisungen werden nur dann ausgeführt, wenn die festgelegte Bedingung erfüllt ist. Am
Beispiel der if-Anweisung lautet die Syntax grundsätzlich:
if (Bedingung) {
Anweisung
}
Um das Verhalten bei nicht-Erfüllen der Bedingung ebenfalls zu steuern, kann die if-Anweisung mit
einer else-Anweisung kombiniert werden:
if (Bedingung) {
Anweisung1
}
else {
Anweisung2
}
Zur Veranschaulichung wird das Beispiel aus Kapitel 3.3 wiederholt:
{# if(ref(“Vorname“)== “Bob“) {‘Hallo Bob!} else {‘Hallo zusammen!} }
Ist der Wert der Variablen „Vorname“ Bob, so wird „Hallo Bob!“ ausgegeben, andernfalls wird
„Hallo zusammen!“ ausgegeben.
26 | 42
5.2 SCHLEIFENANWEISUNGEN
Schleifenanweisungen werden solange ausgeführt, wie eine festgelegte Bedingung wahr ist. Am
Beispiel der while-Schleife lautet die Syntax:
while (Bedingung) {
Anweisung
}
Zur Veranschaulichung das Beispiel aus Kapitel 4.2.9:
{#while(hasRec(“Personen”)) {‘
Solange Datensätze in der Datenversorgung „Personen“ vorhanden sind, werden die in der Tabelle
angegebenen fref()-Funktionen ausgeführt und mit der nextRec()-Funktion auf den nächsten
Datensatz in der Datenversorgung weitergeschaltet.
Die Kombination von while-Schleife und if-Anweisung ist in Kapitel 4.2.9.4 Und im
Anwendungsbeispiel im Kapitel 8 exemplarisch dargestellt.
5.3 VERGLEICHSOPERATOREN
Es können alle in JavaScript erlaubten Vergleichsoperatoren (z.B. ==,!=, >, <,) verwendet werden.
Eine detaillierte Auflistung und Erklärung ist in einschlägiger, online verfügbarer JavaScript
Dokumentation zu finden.
Beispiele:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Comparison_Opera
tors
27 | 42
6
JAVASCRIPT FUNKTIONEN
Innerhalb der Vorlagen bzw. in der Skriptdatei besteht die Möglichkeit, in der Skriptsprache
JavaScript eigene Funktionen zu schreiben. Auf die Konventionen der Skriptsprache JavaScript geht
diese Befehlsreferenz nicht ein. Dazu verweisen wir auf einschlägige, verfügbare onlineDokumentationen wie beispielsweise:
Eigene Funktionen können direkt in der Vorlage (=lokale Funktion) definiert werden oder in
(genau) einer Skriptdatei, die im Aufruf an CIB jsMerge übergeben werden kann (=globale
Funktion).
Dazu werden die benötigten Funktionen in einem Skriptblock definiert, z.B.:
{# myGlobalFunc = function(){ … } }
6.1 GLOBALE FUNKTIONEN
In der Skriptdatei können globale Funktionen und Variablen über folgende Syntax definiert
werden:
myGlobalFunc = function() { ... }
oder
function myGlobalFunc() { ... }
oder
i=42
Globale Funktionen und Variablen haben im gesamten Dokumentenprojekt Gültigkeit. Sie können
allerdings durch gleichnamige Funktionen/Variablen überschrieben werden. Damit ist die globale
Funktion/Variable in dem Template, in dem die lokale Funktion/Variable definiert wurde, nicht
mehr gültig (aber in allen anderen Bausteinen).
Die Funktion wird referenziert über myGlobalFunc(…). Z.B. text(myGlobalFunc(…))
6.2 LOKALE FUNKTIONEN
Innerhalb der Vorlage können lokale Funktionen und Variablen über folgende Syntax definiert
werden:
{# this.myFunc = function() { ... }}
28 | 42
{# this.i = 42}
Der Vorteil lokaler Funktionen ist, dass sie nur in dem Template gelten, in dem sie definiert wurden
und hier geschützt sind. Sie können nicht durch Funktionen anderer Templates überschrieben
werden. Andere Templates “sehen” diese Funktionen nicht und können damit gleichnamige
Funktionen und Variablen verwenden sich gegenseitig zu beeinflussen.
Die Funktion wird referenziert über this.myFunc(…), z.B. text(this.myFunc(…))
6.3 EXPORT VON LOKALEN FUNKTIONEN
Im Template können lokale Funktionen und Variablen über folgende Syntax exportiert werden:
{# this.exports.myFunc = function() { ... }}
{# this.exports.i = 42}
Hierbei handelt es sich ebenfalls um eine lokale Funktion/Variable innerhalb eines Templates, die
aber durch den Export auch allen inkludierten Templates bekannt gemacht wird.
Die Funktion/Variable ist für dieses Template geschützt, könnte aber in einem inkludierten
Template überschrieben werden. Die überschriebene Funktion ist dann aber nur in dem UnterTemplate überschrieben (durch Vererbung) und ein Überschreiben überträgt sich nicht auf das
Haupttemplate, das die Funktion ursprünglich definiert hat.
So sind solche Funktionen besser gegen ungewolltes Überschreiben geschützt.
Die Funktion wird ebenfalls referenziert über this.myFunc(…), z.B. text(this.myFunc(…))
6.4 SUPPORT DER JAVASCRIPT-FUNKTIONEN
Die Möglichkeit, das Gesamtprojekt bzw. einzelne Vorlagen durch eigene JavaScript-Funktionen zu
erweitern, bietet dem Anwender ein hohes Maß an Flexibilität. Allerdings impliziert diese
Flexibilität beim Anwender eine erhöhte Eigenverantwortung für seine Dokumentenprojekte.
Bei der Inanspruchnahme des CIB Supports ist die aktuelle Vertragslage des jeweiligen Kunden zu
beachten.
Achtung:
Es ist dem Anwender auch möglich, die Standard-CIB-Funktionen (wie z.B. fref) durch eigene
JavaScript-Skripte zu überlagern. Damit verliert die in dieser Befehlsreferenz enthaltene
Funktionsbeschreibung ihre Gültigkeit. Die Pflege und Wartung der Dokumentenprojekte wird
damit erheblich aufwändiger.
Wir empfehlen dringend, auf eine Überlagerung der Standard-Funktionen zu verzichten und eigene
JavaScript-Skripte auch mit einem eigenen Namen zu kennzeichnen.
29 | 42
7
UNTERSTÜTZTE INHALTE UND EIGENSCHAFTEN
Sowohl ODF als auch Office Open XML beschreiben eine enorme Vielzahl an Inhaltselementen und
möglichen Eigenschaften. Nicht alle dieser Elemente und Eigenschaften sind für die Standard
Korrespondenzerstellung nötig. Die folgende Auflistung gibt eine Übersicht über die Unterstützung
von Elementen:
Element oder Eigenschaft
ODT-Unterstützung
DOCX-Unterstützung
Text und Zeichenformatierung
Ja
Ja
Zeichenformatvorlagen
Ja
Ja
Absatz und
Absatzformatierung
Ja
Ja
Tabelle und
Tabellenformatierung
Grundsätzlich ja.
Eine dynamisch erzeugte
Tabelle wird derzeit nicht als
eine physikalische Tabelle
erzeugt.
Grundsätzlich ja.
Eine dynamisch erzeugte
Tabelle wird derzeit nicht als
eine physikalische Tabelle
erzeugt.
Seiten- und
Abschnittsformatierung
Ja
Ja
Kopf- und Fußzeilen
Ja
Noch nicht freigegeben
Grafiken, Text- oder
Grafikrahmen,
Ja
Ja
Listen und
Listeneigenschaften/Zähler
Nicht freigegeben
Nicht freigegeben
Felder
Standardfelder werden nicht
ausgewertet
MS Office Felder werden nicht
ausgewertet
Ausgewertet werden:
Skriptfelder
Ausgewertet werden:
Skriptfelder
Inhaltsfelder
Inhaltsfelder
30 | 42
Element oder Eigenschaft
ODT-Unterstützung
DOCX-Unterstützung
Anpassen von Element-IDs /
Namen:
Einige Elemente besitzen IDs
oder Namen, die beim Mischen
oder bei Wiederholungen
eindeutig gemacht werden
müssen.
Für folgende Elemente wird eine
Umbenennung aktuell
vorgenommen:
Für folgende Elemente wird eine
Umbenennung aktuell
vorgenommen:
Formatvorlagen (Styles)
Formatvorlagen (Styles)
Keine Anpassung erfolgt derzeit
für:
Keine Anpassung erfolgt derzeit
für:
Tabellen
Tabellen
Grafiken
Grafiken
Listen
Listen
Lesezeichen
Lesezeichen
An der Seite verankerte
Elemente
Grundsätzlich nicht umsetzbar.
Empfehlung:
Elemente vermeiden
Grundsätzlich nicht umsetzbar.
Empfehlung:
Elemente vermeiden
Inhalts-, Abbildungs- und
Literaturverzeichnisse
Nicht freigegebenen
Nicht freigegeben
Eingebettete Fonts
Nein
Nein
31 | 42
8
FÜR RTF-UMSTEIGER: GEGENÜBERSTELLUNG DER
FUNKTIONEN
Für Anwender, die aus dem Umfeld MS Word und RTF kommen, ist es hilfreich zu sehen, wie die
bereits bekannten Feldbefehle im ODT-Umfeld umgesetzt werden.
8.0.1 Abbildung von RTF-Feld-Befehlen auf die Skriptlogik
In diesem Abschnitt wird gezeigt, wie die Logik der RTF-Feldbefehle mit der neuen Skriptlogik
abgebildet werden kann. In der nachstehenden Tabelle finden Sie eine Liste aller RTF-Felder, wie
sie von CIB merge verarbeitet werden und die dazugehörige Abbildung in Skriptlogik:
Feldbefehl ( engl. / dt.)
Beschreibung (aus dem Leitfaden
CIB merge)
Entsprechung in ODT bzw.
Skriptlogik (Beispiele in
JavaScript)
COMPARE / VERGLEICH
Vergleicht zwei Werte und gibt den JavaScript: Boolscher Vergleich
numerischen Wert 1 zurück, wenn
Beispiel: (a==b)
der Vergleich wahr ist, und 0
(Null), wenn der Vergleich falsch
ist.
DATE / AKTUALDAT
Fügt das aktuelle Datum ein.
Siehe:
formatDate(formatString, date).
IF / WENN
Vergleicht Argumente unter
Berücksichtigung bestimmter
Bedingungen.
Kann optional zu einem
Schleifenbefehl erweitert werden
(SOLANGE).
JavaScript: IF Befehl.
Fügt einen Text aus einer Datei
ein.
Siehe:
include(name,
INCLUDETEXT /
EINFÜGENTEXT
Beispiel: if(a==b){
… }else{ … }
while(a==b) { … }
(für
SOLANGE)
{includeAttributes})
Beispiel:
include(„mydoc.odt“)
32 | 42
MERGEFIELD /
SERIENDRUCKFELD
CIB merge)
Legt einen Platzhalter mit Namen
fest, der später durch einen
angelieferten variablen Inhalt
ersetzt wird.
JavaScript)
Siehe:
oder
text(ref(name))
Beispiel:
text(ref(“institute.EL_KIN_BEZ”
))
MERGEREC / DATENSATZ
Fügt die Nummer des aktuellen
Seriendruck-Datensatzes ein.
Siehe:
mergeRec()
Beispiel:
mergeRec()
MERGEREC ?
MERGEREC „tablealias“
Liefert den bool’schen Wert ‚1‘,
wenn noch ein Datensatz des
Seriendrucks vorhanden ist.
Standardmäßig ist der Wert ‚0‘
eingestellt.
Siehe:
hasRec()
Fügt die Nummer des aktuellen
Datensatzes einer Tabelle ein.
Siehe:
mergeRec(tablealias
Beispiel:
hasRec()
Beispiel:
mergeRec(„Personen“)
MERGEREC "?tablealias"
Liefert 0 zurück, wenn keine
weiteren Datensätze in dieser
Tabelle vorhanden sind.
Siehe:
hasRec(tablealias)
Beispiel:
while(hasRec(„Personen“)) …
NEXT / NÄCHSTER
Geht zum nächsten Datensatz oder
Knoten in der Datenversorgung.
Siehe:
nextRec()
Beispiel:
nextRec()
NEXT -
Das Zurücksetzen (reset) aller
Siehe:
Steuerdateien auf den "nullten"
resetRec()
Datensatz. Die Variableninhalte
Beispiel:
werden gelöscht. Die Werte des
resetRec()
ersten Datensatzes werden erst mit
{NEXT} wieder eingelesen.
33 | 42
NEXT aliasname
CIB merge)
Knoten in der durch aliasnamen
beschriebenen Datenliste
JavaScript)
Siehe:
nextRec(tablealias)
Beispiel:
nextRec(„Personen“)
NEXT –aliasname
NEXT aliasname
Diese beiden Kommandos setzten
die Datenliste zurück auf den 1.
Datensatz
Siehe:
Beispiel:
resetRec(„Personen“)
NEXTIF / NWENN
Knoten in der Datenversorgung,
wenn eine bestimmte Bedingung
erfüllt ist.
Gültig beim Seriendruck und beim
Iterieren von Listen
QUOTE / ANGEBEN
Fügt einen Text in das Dokument
ein.
JavaScript:
if(<condition>) nextRec()
oder
if(<condition>)
nextRec(tablealias)
Siehe:
text(text)
Beispiel:
text(„Hallo world“)
REF / REF
Legt einen Platzhalter mit Namen
fest, der später durch einen
angelieferten variablen Inhalt
ersetzt wird.
Siehe:
oder
text(ref(name))
Beispiel:
text(ref(“institute.EL_KIN_BEZ”
))
REF "?variable"
Liefert 0 zurück, wenn die Variable Siehe:
nicht vorhanden ist, ansonsten 1.
Beispiel:
existsRef(„<variable>“)
SET / BESTIMMEN
Weist einer Textmarke einen neuen Siehe:
Text zu.
Beispiel:
setData(„myVar“, 1)
34 | 42
SKIPIF / ÜBERSPRINGEN
CIB merge)
Überspringt einen Datensatz oder
Knoten in der Datenversorgung
entsprechend einer Bedingung.
Und erzeugt für diesen Datensatz
auch kein Ausgabedokument im
Seriendruck.
JavaScript)
JavaScript:
if(<condition>) skip()
Nur beim Seriendruck gültig. Nicht
auf Listen anwendbar.
Fügt die aktuelle Uhrzeit ein.
TIME / ZEIT
TIME wird durch CIB merge immer
ausgewertet. In manchen Fällen ist
es erwünscht, dass CIB format die
Ersetzung macht. Dann verwendet
man den \* keep-Schalter.
= Ausdruck / Expression
Berechnet das Ergebnis eines
Ausdruckes (=Formeln)
Siehe:
formatDate(formatString, date).
JavaScript Rechenausdrucke
Beispiele:
(3-1) oder
(5*10) oder
(10%2) oder
(Number(ref(“myNumber”)) + 10)
Achtung:
In JavaScript wird der “+”Operator per Default für die String
Konkatenation benutzt. Die
Operatoren müssen mit Number()angegeben werden um eine
Addition zu erzwingen.
Es folgen einige Beispiele dafür, wie RTF-Ausdrücke in Skript-Felder umgesetzt werden.
MS-Office Feldbefehle
Skript Logik (Beispiele in JavaScript)
Einfaches REF:
{#
text(ref(“myVariable))
{#
setData(“myVar”, “Hallo”)
{
REF “institute.EL_KIN_BEZ”
Einfaches SET:
{
SET myVar “Hallo”
}
}
}
}
35 | 42
REF mit Datum-Formatschalter:
{#
text(formatDate(“tt.mm.jjjj”, ref(“myDate”)))
{#
if(ref(“myVariable)==””)
{
REF myDate \@ “tt.mm.jjjj”
}
Einfaches “IF-then”-Konstrukt:
{
IF
{
REF “myVariable”
variable is empty”
}
}
= “” “My
{My
variable is
empty}}
Hier würde die Funktion mit Fehler beenden, wenn
“myVariable“ nicht aufgelöst werden kann.
}
oder
{#
if(isEmptyRef(“myVariable))
{My
variable is
empty}}
Hier würde die Funktion nicht mit Fehler beenden,
wenn “myVariable“ nicht aufgelöst werden kann
Abfrage auf leere Variable:
{
IF
{
REF “myVariable”
REF myVariable”}”
{#
}
!= “” “{
IF <condition> “then-part” “else-
part”
text(ref(“myVariable”)}
}
Einfaches “IF-then-else”-Konstrukt:
{
if(!isEmptyRef(“myVariable”))
{#
}
if(<condition>)
{‘then-part}
else
{‘else-part}
}
Abfrage auf Existenz einer Variablen
(und Definieren, falls sie nicht existiert):
Mehrere dieser Konstrukte können in einem Scriptfeld
abgehandelt werden:
{
{#if(!existsRef(„myVar“))
IF myVar = “myVar”
“Hallo”
{SET
myVar
set(„myVar“, „Hallo“);
if(!existsRef(„myVarXXX“))
}}
oder:
{
IF
set(„myVarXXX“, „Hallo“);}
{
REF ?myVarXXX
myVarXXX “Hallo”
}
= 0
{
SET
}}
Einfacher Rechenausdruck:
{
SET myVar
{
= 1 +2 + 3
SET myVar
+ 3
{
=
{
REF myNumber
}}
String-Konkatenation:
{
REF “var{ REF myNumber
set(“myVar”, 1 + 2 + 3)
}
{#
set(“myVar”, Number(ref(“myNumber”)) + 2 + 3)
}}
Rechenausdruck mit Variable:
{
{#
}
+ 2
}
In JavaScript müssen Zahlenvariablen mit “Number()”
angegeben werden um sie von Stringvariablen zu
unterscheiden. Default für “+” ist eine StringKonkatenation.
{#
text(ref(“var” + ref(myNumber)))
}
}” }
36 | 42
SET-IF:
{#
{
SET “myVar”
“Er”
{
IF <condition> “Sie”
}}
setData(“myVar”, (<condition>)? “Sie” : “Er”)
oder
{#
if(<condition>) setData(“myVar”, “Sie”);
else setData(“myVar, “Er”);
Compare:
{
{#
{ ={ COMPARE { REF
= 1} && { COMPARE { REF b } = 2}
{ COMPARE { REF c } = 3}}}
set “valid”
SOLANGE-Schleife:
{
{
if <condition> “…content…
next …
}”
\* SOLANGE
a
}
}
}
setData(“valid”, (ref(“a”)==1) && (ref(“b”)==2)
}
&& (ref(“c”)==3))
&&
{#
{#
while(<condition>)
{#
resetRec(“aliasname”)
{#
include(“template.odt”)
nextRec(…)
{…content…
}}}
}
Next –aliasname:
}
{ next –aliasname }
Einfacher INCLUDETEXT:
{
INCLUDETEXT “template.rtf”
}
}
37 | 42
9
ANWENDUNGSBEISPIEL
Im Folgenden wird ein komplettes, kurz gehaltenes Beispiel dargestellt. Die beteiligten Dateien
sind dabei vollständig abgebildet.
Startpunkt ist hier das Wurzeldokument inputDoc.odt . Daten werden aus einer CSV-Datei
(Personen.csv) eingemischt und zusätzlich wird ein weiterer Textbaustein, die Datei Baustein.odt,
eingebunden.
CIB jsMerge wird in diesem Beispiel über die CIB runshell auf Kommandozeilenebene aufgerufen.
Hier werden die Übergabeparameter in der Skriptdatei script.js angegeben:
Aufruf:
Cibrsh.exe –js scriptfile=script.js
script.js:
In der Skriptdatei werden für dieses Beispiel nur die benötigten Übergabeparameter angegeben. In
diesem Fall sind das Name des Wurzeldokuments, Name der Ausgabedatei und Name der CSVDatei.
setProperty("licenseCompany", "Lizenznehmer", true);
setProperty("licenseKey", "xxxx-xxxxx-xxxxxxxx", true);
setProperty("inputfile", "./inputDoc.odt", true);
setProperty("outputfile", "./outputDoc.odt", true);
setProperty("datafile", "Personen.csv", true);
38 | 42
inputDoc.odt:
Zu Beginn des Wurzeldokuments wird die lokale Funktion „upperCase“ definiert. Diese wird später
innerhalb einer „while“-Schleife aufgerufen, um in der dritten Tabellenspalte die Namen der aus
der „Personen.csv“ eingemischten Personen in Großbuchstaben abzubilden.
Die nächste Feldanweisung mischt das aktuelle Datum über die Funktion „formatDate()“ ein.
Dann wird mit der „include()“ Feldanweisung der zusätzliche Baustein „Baustein.odt“
eingebunden.
Das nun folgende Konstrukt erzeugt mit Hilfe der „while“-Schleife dynamisch eine Tabelle und füllt
diese mit den Personendaten aus der Datenversorgung „Personen.csv“. Dabei werden so oft neue
Tabellenzeilen angelegt, wie Einträge in der Datei „Personen.csv“ vorhanden sind. Realisiert wird
dies über die Funktionen „hasRec()“ und „nextRec()“.
Die erste Tabellenspalte im Wurzeldokument zeigt die Verwendung einer „if“-Bedingung zur
Auswahl der passenden Anrede. Die zweite Spalte demonstriert die reine Anzeige des Wertes der
Variable „Personen“ über die „fref()“-Funktion, während in der dritten Spalte mittels der „ref()“Funktion der Wert der Variable „Nachname“ an die Funktion „upperCase“ übergeben wird.
Das Dokument inputDoc.odt ist auf der folgenden Seite abgebildet.
39 | 42
inputDoc.odt
{ # this.upperCase = function(name) { text(name.toUpperCase());} }
Ausgabe des Aktuellen Datums:
München, den { #text(formatDate(„tt.MM.jj“, new Date() )) }
Text aus einem weiteren Baustein einfügen:
{ # include(„Baustein.odt“) }
Die nachfolgende Tabelle wird dynamisch über eine while-Schleife erzeugt. Dabei werden
die Daten aus der CSV Datei Personen.csv verwendet und so viele Tabellenzeilen erzeugt,
wie Einträge in der CSV vorhanden sind.
{ #while(hasRec(„Personen“)){ '
{#if(ref(„Geschlecht“)==“m“) { #fref(„Vorname“) }
{ 'Herr } else{ 'Frau } }
{ # this.upperCase
(ref(„Nachname“)) }
{ #nextRec(„Personen“) } } }
40 | 42
Baustein.odt:
Der Inhalt der Datei „Baustein.odt“ wird an der im Wurzeldokument mithilfe der „include()“Anweisung angegebenen Stelle eingefügt:
Dies ist ein Hinweistext, der im Textbaustein „Baustein.odt“ definiert ist und mit dem
include-Befehl ins Ausgabedokument eingebaut wird.
Personen.csv
Diese Datei dient als Datenversorgung. In der ersten Zeile werden die Variablennamen definiert,
die folgenden Zeilen enthalten dann jeweils die Datensätze.
Hinweis:
Die CSV-Datei muss UTF-8 codiert sein, damit eventuelle Umlaute und Sonderzeichen korrekt
gelesen werden.
Vorname;Nachname;Geschlecht
Peter;Meier;m
Hans;Müller;m
Anne;Kurz;f
Tim; Berg;m
outputDoc.odt:
Nach dem Aufruf von CIB jsMerge wird das auf der nächsten Seite dargestellte Dokument erzeugt,
in dem alle Daten wie oben beschrieben eingemischt wurden:
41 | 42
outputDoc.odt
Ausgabe des Aktuellen Datums:
München, den 01.09.14
Text aus einem weiteren Baustein einfügen:
Dies ist ein Hinweistext, der im Textbaustein „Baustein.odt“ definiert ist und mit dem
include-Befehl ins Ausgabedokument eingebaut wird.
Die nachfolgende Tabelle wird dynamisch über eine whileSchleife erzeugt. Dabei werden
die Daten aus der CSV Datei Personen.csv verwendet und so viele Tabellenzeilen erzeugt,
wie Einträge in der CSV vorhanden sind.
Herr
Peter
MEIER
Herr
Hans
MÜLLER
Frau
Anne
KURZ
Herr
Tim
BERG
42 | 42

Befehlsreferenz CIB jsMerge

Transcription

Similar documents

CIB PDF BREWER INSTALLATIONSANLEITUNG

pdf, 269 KB

Foto Quick Labor: Fotolabor Service - Fotostudio

Finden, was man sucht!

tutorial zu scratch 2.0

Papyrus Document System 7

6. Programmieren in VoiceXML