Word-Berichte

Der Word-Report-Mechanismus von Vertec ermöglicht es, benutzerdefinierte Berichte in MS Word zu entwerfen und direkt aus Vertec auszuführen. Die Möglichkeiten gehen dabei weit über die in Word eingebauten Serienbrief-Funktionalitäten heraus.

Word-Reports basieren auf einem speziellen VisualBasic Makro in der Word Standard-Vorlage, welches bestimmte Elemente in einer Berichtvorlage interpretiert und via COM bzw. ActiveX auf das Vertec Objektsystem zugreift.

Installieren der Word-Report-Makrovorlage

Zum Ausführen von Vertec Word-Berichten wird in Word spezieller Makrocode benötigt. Diese Makros befinden sich im Vorlagendokument VertecReport.dot.

Dieses Vorlagendokument wird standardmässig im Vertec Installationsverzeichnis abgelegt. Vertec lädt diese Makrodatei bei Bedarf explizit als Word Add-in, daher ist auch keine Signatur notwendig.

Falls Ihre Vertec Installation mit lokalen Programmfiles auf den Clients arbeitet und kein Netzwerkzugriff auf das Serververzeichnis besteht, kann VertecReport.dot auch im Vorlagenverzeichnis für Word-Berichte abgelegt werden. Den korrekten Pfad finden Sie in Vertec unter Optionen > Systemeinstellungen Allgemein; Vorlagenpfad für Word-Berichte.

Registrierung von Word-Reports in Vertec

Damit ein Word-Report in Vertec ausgeführt werden kann, muss er registriert werden. Das Vorgehen ist im Artikel Reports registrieren detailliert beschrieben.

Aufbau von Word Report-Vorlagen

Ein Word-Report basiert immer auf einer Dokumentvorlage in Word. Diese Report-Vorlage enthält neben normalem Text spezielle Elemente, die vom Makro DoReport ausgewertet werden. Diese werden hier nachfolgend beschrieben:

Bänder

Bänder sind die Grundlagen von Word-Reports. Alles, was gedruckt wird, befindet sich in einem Band.

Ein Band wird in der Report-Vorlage durch eine Textmarke dargestellt. Der Name der Textmarke ist der Band-Name.

Erstellen Sie dort, wo Sie ein Band erstellen möchten, einen Beispiel-Text im gewünschten Layout (z.B. eine Tabelle, Zeilen mit Tab etc.). Markieren Sie dann diesen Text und klicken Sie auf "Einfügen - Textmarke...". Es öffnet sich das Fenster, in dem Sie den Namen der Textmarke angeben können. Es empfiehlt sich, dabei einen Namen zu wählen, bei dem erkennbar ist, um was es sich handelt (also nicht Band1, Band2 etc.). Das erleichtert später das Anpassen der Bänder und der Ausdrücke in den Expressions.

Die Bänder können frei verschachtelt werden. Jede Report-Vorlage muss aber ein Standard-Band enthalten. Das ist ein Band, das alles andere einschliesst. Sie können also, nachdem Sie die Vorlage erstellt haben, alles markieren und mit einer weiteren Textmarke umschliessen. Der Namen dieser Textmarke spielt keine Rolle.

Ein Band kann bei der Ausführung eines Reports ein- oder mehrmals gedruckt werden. Wird also ein Band auf einer Liste ausgeführt, wird das Band so viel mal gedruckt, wie sich Elemente in der Liste befinden.

Textmarken, die nicht gelöscht werden

Textmarken, deren Name mit trg oder src beginnt, werden vom Vertec Report-Mechanismus nicht gelöscht. Wenn Sie also in Ihrem Dokument Textmarken benötigen, die auch nach dem Ausführen bestehen bleiben, nennen sie diese trg.. oder src...

Felder

Ein Feld ist ein durch einen Kommentar markierter Text innerhalb eines Bandes, der beim Ausführen des Reports durch Daten aus Vertec ersetzt wird.

Um ein solches Feld zu erstellen, markieren Sie einen beliebigen Text, an dessen Stelle später die Daten aus Vertec eingefügt werden sollen, und klicken Sie auf "Überprüfen - Neuer Kommentar". Der dazugehörige Kommentar muss eine an der entsprechenden Stelle gültige OCL-Expression enthalten.

Um ein Feld zu bearbeiten, klicken Sie mit der rechten Maustaste darauf und wählen Sie Kommentar bearbeiten.

Beispiel von Feldern mit zugehörigem Kommentar in Word:

Band Expressions

Band Expressions sind ebenfalls durch Kommentare markierte Textstellen innerhalb eines Bandes. Sie unterscheiden sich von Feldern dadurch, dass der markierte Text immer mit dem Namen des Bandes beginnt, auf das sich die Expression bezieht. Es sind folgende Band Expressions möglich (bndXXX bedeutet dabei der Name des Bandes):

  • bndXXXExp: Band Hauptexpression. Falls angegeben, wird der Wert des Bandes aufgrund dieser Expression berechnet. Die Expression bezieht sich auf das Root-Objekt des Reports oder auf den Wert des nächst äusseren Bandes.

    Falls das Ergebnis dieser Expression einer Liste entspricht, wird das Band für jeden Eintrag der Liste dupliziert.

  • bndXXXCond: Band Conditional Expression. Falls angegeben, wird diese Expression bei jedem Auftreten des Bandes ausgewertet (d.h. falls das Band innerhalb einer Liste dupliziert wird, für jedes Objekt). Das Ergebnis der Expression muss ein boolescher Wert sein (Wahr/Falsch). In Abhängigkeit dieses Ergebnisses wird das Band gedruckt oder nicht.

Regionsspezifische Zahlenformatierung

Mit der Version 6.1 implementiert Vertec eine eigene Formatierungsfunktion, welche einen Teil der VBA Format Funktion umsetzt und die angegebenen Regionaleinstellungen berücksichtigt. Damit kann im Word-Report angegeben werden, welche Regionaleinstellungen (Locale) für Zahlen- und Datumsformatierung verwendet werden sollen.

Zum Setzen der Regionaleinstellungen kann folgende Band-Expression verwendet werden:

  • bndXXXLocale: Ein Kommentar auf <band-name>Locale gibt die Regionaleinstellung als OCL Expression an.

Beispiel

Ein Kommentar auf rchMasterLocale mit Inhalt de-DE setzt die Regionaleinstellung für das gesamte Master-Band auf Deutsch, Deutschland.

Innerhalb dieses Bands werden alle Zahlen und Datumswerte in formatierten Kommentaren (Texte mit einem \ beginnend), als Formatstring angesehen und der Wert in der entsprechenden Regionaldarstellung dargestellt.

Eine Tabelle mit den Ländercodes finden Sie unter: https://msdn.microsoft.com/de-de/library/ee825488(v=cs.20).aspx.

Bilder in Word-Reports einfügen

Ab Vertec 6.0 können in Word-Reports Bilder eingefügt werden. Diese können entweder aus Vertec (z.B. Belegbilder auf Spesen) oder aus dem Filesystem kommen.

Dafür gibt es spezielle Felder, welche beim Ausführen des Reports nicht durch Text, sondern durch andere Daten ersetzt werden. Um ein solches Feld zu erstellen muss der durch einen Kommentar markierte Text mit einer bestimmten Zeichenfolge beginnen. Diese speziellen Felder werden im Folgenden erklärt.

ImageData

Solche Felder werden verwendet, um in Vertec gespeicherte Bilder in Word-Reports einzufügen.

Der durch einen Kommentar markierte Text muss mit der Zeichenkette ImageData beginnen. Die im Kommentar enthaltene OCL-Expression muss den Inhalt eines Bildfeldes in Vertec liefern.

ImagePath

Solche Felder werden verwendet, um auf dem Dateisystem abgelegte Bilder in Word-Reports einzufügen. Der durch einen Kommentar markierte Text muss mit der Zeichenkette ImagePath beginnen.

Die OCL-Expression muss einen absoluten Pfad zu einer im Dateisystem abgelegten Bilddatei liefern. In Word eingefügt wird dann direkt die Bilddatei, die sich an diesem Ort befindet.

Als OCL-Expression kann der Pfad auch direkt angegeben werden, in einfachen Anführungszeichen:

Ist das Resultat der OCL-Expression ein Leerstring, wird einfach der Kommentar im Word gelöscht und nichts angezeigt. Falls das Bild am angegebenen Ort nicht existiert, wird eine Fehlermeldung anstelle des Bildes in den Wordreport eingefügt.

Skalierung von eingefügten Bildern

Um die dargestellte Grösse der eingefügten Bilder in Word zu steuern, empfiehlt es sich, diese in einer Tabelle anzuzeigen wie in den gezeigten Beispielen. Die Skalierung in der Tabelle verhält sich wie folgt:

Die eingefügten Bilder werden nicht hochskaliert, weder horizontal noch vertikal. Die Bilder werden aber bei Bedarf runterskaliert:

  • Ist ein Bild breiter als die Tabellenzelle, wird es runterskaliert, wenn die automatische Grössenanpassung der Tabelle ausgeschaltet ist.
  • Wenn ein Bild höher als die Tabellenzeile ist, wird die Zeile vergrössert, ausser für die Zeilenhöhe wurde in den Tabelleneigenschaften ein genauer Wert gesetzt. Ist für die Zeilenhöhe ein genauer Wert gesetzt und die automatische Grössenanpassung ausgeschaltet, so wird das Bild runterskaliert, damit es in die Zelle passt.

Hier nachfolgend eine Übersicht über die Skalierungen:

Zeilenhöhe fixGrössenanpas­­sung zulassenAuswirkungen auf das Bild
Nein Nein Skaliert: ja. Verändert die Zeilenhöhe der Tabelle. Die Zeilenbreite bleibt.
Nein Ja Skaliert: nein. Verändert Zeilenhöhe und Zeilenbreite (das Bild wird skaliert auf maximalbreite der Tabelle - Seitenbreite)
Ja Nein Skaliert: ja. Verändert weder Zeilenhöhe noch Zeilenbreite.
Ja Ja Skaliert: nein. Verändert die Zeilenbreite. Die Zeilenhöhe bleibt, das Bild überlappt.

Textbausteine (HTML) in Word-Reports einfügen

Auf die gleiche Art wie die Bilder (siehe oben) kann ab Version 6.0 auch HTML-formatierter Text z.B. aus Textbausteinen in Word-Reports eingefügt werden.

HtmlTextBlock

Dieses Feld wird verwendet, um HTML formatierten Text in Word-Reports einzufügen. Dieser kann zum Beispiel aus einem Vertec Textbaustein kommen, aber es kann auch ein beliebiges Textfeld angegeben werden, welches formatierten Text enthält. In Word können Sie diesen Text wie folgt einfügen:

Der durch einen Kommentar markierte Text muss mit der Zeichenkette HtmlTextBlock beginnen. Die im Kommentar enthaltene OCL-Expression muss als Resultat einen HTML-Formatierten Text ergeben. Hier im Beispiel das Feld text eines Textbausteines:

Der Wert, der aus der Auswertung des OCL (Kommentar) resultiert, wird als formatierter HTML-Text interpretiert und das Ergebnis in den Report geschrieben.

Der formatierte Text unterstützt den folgenden Teilumfang von HTML:

  • Absätze mit <p/>
  • Nummerierte Listen <ol><li/>…</ol>
  • Unnummerierte Listen <ul><li/>…</ul>
  • Fette Schrift <b>text</b>
  • Kursive Schrift <i>text</i>
  • Inline Text <span>text</span> (nur nützlich zum Einsetzen von OCL Expressions ohne sonstige Formatierung)
  • <p> Elemente können zur Formatierung folgende Wert im class Attribute haben:

    • h1, h2, h3 für Überschrift 1-3

    • indent für eingerückten Absatz.

      Beispiel <p class=“h1“>Ein Titel</p>.

  • Falls ein Element class=“ocl“ gesetzt hat, dann wird sein Inhalt (Text) als OCL Expression ausgewertet und eingesetzt. Sinnvoll ist das bei inline Elementen wie <b>, <i> oder <span>.
    Beispiel: <span class="ocl">projekt.code</span>

Event Makros

Im Word Report Mechanismus gibt es die Möglichkeit, VB Makros, die vor und nach dem eigentlichen Report aufgerufen werden, zu erstellen. Makros mit folgenden Namen werden berücksichtigt:

BeforeReport2

Wird vom Report Mechanismus aufgerufen, bevor die Daten aus Vertec im Report eingesetzt werden. Das bietet zum Beispiel die Möglichkeit, einen Dialog anzuzeigen, der eine bestimmte Vorauswahl trifft.

Die Deklaration ist wie folgt:

sub BeforeReport2(vertec As Object, dok As Object)
end sub

Der Zugriff auf Vertec wird mit der Variable vertec übergeben. Es kann auf Vertec also direkt zugegriffen werden. Beispiel:

sub BeforeReport2(vertec As Object, dok As Object)
dim projektliste as IVtcObjectList

set projektliste = Vertec.eval("projekt->select(aktiv)")

end sub

Der Word-Report wird mit der Variable dok übergeben.

AfterReport2

Dieses Makro wird aufgerufen, nachdem die Daten aus Vertec im Report eingesetzt worden sind.

Die Deklaration ist wie folgt:

sub AfterReport2(vertec As Object, dok As Object)

end sub

Der Zugriff auf Vertec wird mit der Variable vertec übergeben.

Der Word-Report wird mit der Variable dok übergeben.

AfterReport3

Ab Version 5.5. Dieses Word-Report Eventmakro ermöglicht den Zugriff auf die dazugehörige Aktivität. Dabei handelt es sich um die Aktivität, die erzeugt wird, um den Report mit dem Objekt in Vertec zu verknüpfen.

Dieses Makro wird aufgerufen, nachdem die Daten aus Vertec im Report eingesetzt worden sind.

Die Deklaration ist wie folgt:

sub AfterReport3(vertec as Object, dok as Object, root as Object, optarg as Object, akt as Object)

end sub

Argumente:

  • vertec: Zugriff auf Vertec
  • dok: das erstellte Word Dokument
  • root: das Vertec Objekt, auf dem der Report ausgeführt wurde
  • optarg: das optionale Vertec objekt (Adresse)
  • akt: die erstellte Aktivität

optarg und akt können auch leer sein, in VB entspricht das "nothing". Das Makro wird aufgerufen, nachdem die Daten aus Vertec im Report eingesetzt worden sind.

Die übergebene Aktivität hat bereits den vorgesehenen Pfad gesetzt. Wird der Pfad der Aktivität im Eventmakro verändert, wirkt sich das auf den Speicherpfad des Dokuments aus.

Die Aktivität wird dafür vor dem Ausführen des Reports bereits erstellt. Tritt dabei irgendwo ein Fehler auf, wird die Aktivität wieder gelöscht.

OCL Variablen für Office-Reports

Vor dem Ausführen eines Office-Reports werden folgende OCL Variablen angelegt:

  • rootObj: Das Objekt auf dem der Report ausgeführt wird
  • optArg: Das optionale Zusatzargument (z.B. Adresseintrag)
  • betreff: Der Betreff aus dem Report Dialog
  • kommentar: Der Kommentar aus dem Report Dialog

Diese Variablen sind in OCL definiert und nur innerhalb einer OCL Expression zugänglich (rootObj und optArg können auch aus den Methodenparametern evaluiert werden (AfterReport3)).

Die Variablen würden für obiges Beispiel folgende Rückgabewerte liefern:

ExpressionResultat

Vertec.eval("rootObj")

Liefert die Rechnung (16070001, COMINSTALL) zurück.

Vertec.eval("optArg")

Liefert die optional eingegebene Adresse (Eliwag AG) zurück.

Wird in diesem Dialog keine Adresse optional eingegeben, liefert diese Variable die Standardadresse zurück (Comtelsat AG).

Vertec.eval("betreff") Liefert den String Rechnung Juni 2016 zurück.
Vertec.eval("kommentar") Liefert den String Diese Rechnung geht einmalig an die Firma Eliwag AG zurück.

Lokale OCL Variablen in Wordreports

Ab Version 5.3.0.29 können in Wordreports lokale OCL Variablen verwendet werden. Mittels einer Var-Expression kann eine Variable erstellt und später im Report wieder verwendet werden. Das verhindert vor allem das erneute Berechnen von Werten, die mehrmals verwendet werden.

Var-Expressions sind Kommentare auf Texten der Form

<bandname><varname>

wobei varname mit "var" beginnen muss.

Beispiel

In einem Rechnungsreport sollen Leistungen nach Tätigkeit gruppiert werden. Dafür werden zuerst die Tätigkeiten eruiert und dann pro Tätigkeit eine Liste der Leistungen ausgegeben. Das heisst, die Leistungen müssen mit einer Expression in der Art bndMaster.leistungen->select(typ=self) gefiltert werden. Bei den Stunden und Honoraren musste dann pro Zeile jeweils wieder die ganze Liste aufgerufen werden (z.B. bndMaster.leistungen->select(typ=self).wertext->sum). Neu kann man die Liste in die Variable laden und dann mit dieser weiterarbeiten (z.B. varLeistList.wertext->sum).

bandvariablen.gif

Zugriff via COM

Die entsprechende Methode auf IvtcSession heisst

EvalToVariable(root as IVtcObject, expression as String, varname as String)

Damit können auch im Code, zum Beispiel in einem Excel-Report, Werte in Variablen geladen werden, die später in OCL-Expressions verwendet werden können. Insbesondere können auch Ergebnisse von Expressions, welche nur durch die Expression entstehen und nicht in Vertec vorhanden sind, in eine Variable geschrieben werden (beispielsweise das Ergebnis einer Summierung, ein Datumswert mittels encodedate etc.)

Zum Beispiel sollen in einem Excel-Report die Leistungen ab einem bestimmten Zeitpunkt angezeigt werden. Statt nun die Leistungen in der Art "offeneLeistungen->select(datum >=" & encodeDate(2012, 08, 01) & ") " zusammenzusuchen, kann zuerst eine Variable gesetzt und dann verwendet werden:

Vertec.EvalToVariable(Vertec.argobject, "encodeDate(2012,08,01)", "varVon")

und dann in der Expression:

offeneLeistungen->select(datum >= varVon)

Datenfelder in Kopf- und Fusszeilen einfügen

Ab Vertec 6.1 werden Datenfelder in Word-Berichten unterstützt, um das Einfügen von Daten in Kopf- und Fusszeilen zu ermöglichen.

Feld Definition

Die Felder werden in den erweiterten Eigenschaften im Word Dokument geführt, Menü Datei > Informationen > Eigenschaften > Erweiterte Eigenschaften > Anpassen:

Der Feldname muss mit var beginnen. Der Feldwert beinhaltet die OCL Expression. Typ ist immer Text.

Integration in Kopf- und Fusszeile

Im Editiermodus der Kopf- oder Fusszeile kann mittels Einfügen > Schnellbausteine > Feld im Feld DocProperty die gewünschte Variable als Feld übernommen werden:

Die Expressions der Dokumenteigenschaften werden beim Erstellen einmalig auf dem aktuellen Vertec-Objekt (argobject) ausgewertet. Die OCL Expression wird durch deren Ergebnis ersetzt, wobei mehrzeilige Texte ebenfalls übernommen werden.

Grössenbeschränkung

Der Inhalt von Feldern in Word kann maximal 255 Zeichen lang sein. Längere Texte werden beim Auswerten der Feldexpression deshalb auf 255 Zeichen abgeschnitten.

Dokument von der Vorlage trennen

Ab und zu tritt das Problem auf, dass Word 2010 beim Öffnen einer Word-Datei, die aus einer Word-Vorlagen-Datei erstellt wurde, sehr lange braucht beim Öffnen (ca. 15-30 Sekunden). Dabei erscheint die Meldung Kontaktaufnahme: Pfad zur ursprünglichen Vorlagendatei. Dies geschieht dann, wenn das Word-Dokument auf einem Rechner geöffnet wird, vom dem aus nicht auf die Vorlagendatei zugegriffen werden kann.

Grundsätzlich bräuchte das Dokument nicht mehr auf die ursprüngliche Vorlage zuzugreifen, ausser es sind darin Makros vorhanden, welche auch später noch gebraucht werden. Bei normalen Vertec-Dokumenten ist dies aber nicht der Fall.

Dafür kann man in der Vorlage ein Document Property (Eigenschaft) erstellen mit Namen VertecDetachTemplate. Über Datei > Informationen > Eigenschaften > Erweiterte Eigenschaften gelangen Sie in den folgenden Dialog:

Geben Sie unter Namen VertecDetachTemplate an und wählen Sie beim Typ Ja oder Nein aus. Dann klicken Sie auf Hinzufügen.

  • Ja: Vertec entfernt die Vorlage beim Erzeugen des Dokuments. Da ein Dokument immer eine Vorlage braucht, wird stattdessen die Standardvorlage angehängt.
  • Nein: Die Verbindung zur Vorlage bleibt bestehen.

26.06.2003 | 09.11.2016: Regionsspezifische Zahlenformatierung sowie Datenfelder in Kopf- und Fusszeilen eingefügt.
Produktlinien: Standard, Expert
Module: Leistung & CRM