Erweiterte Office-Berichte

Produktlinien: Standard, Expert
Module: Leistung & CRM
Erstellt: 01.03.2018, Änderung:
Einfügen von Textbausteinen beschrieben.
Mehr ansehen

Mit den erweiterten Office-Berichten stellt Vertec einen office-basierten, cloud-fähigen Reportgenerator zur Verfügung.

Erweiterte Office-Berichte bestehen aus der Kombination einer Word- oder Excel-Vorlage für die Layout-Struktur sowie einer Bericht-Definition in Form von Python Code für die Generierung des Inhalts.

Registrierung erweiterte Office-Berichte

Um einen erweiterten Office-Bericht zu erstellen, muss er registriert werden. Dabei wird die Word- oder Excel-Vorlage hinterlegt und als Bericht-Definition der dazugehörige Python Code eingefügt.

Das Vorgehen ist im Artikel Reports registrieren detailliert beschrieben.

Python-Code

Der Dateninhalt des Berichts wird berechnet durch Python-Code, welcher als Berichts-Definition hinterlegt wird.

 

Wie dieser Code genau aufgebaut wird, ist im Artikel Python-Code für erweiterte Office-Berichte detailliert beschrieben.

Aufbau der Word-Vorlagen

Die erweiterten Office-Berichte verwenden Word-Dokumente (.docx) als Vorlagen.

Bands

Alles, was gedruckt wird, befindet sich in sogenannten Bands.

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, worum 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 hat mindestens ein Haupt-Band, welches über alles geht. Sie können also, nachdem Sie die Vorlage erstellt haben, alles markieren und mit einer Textmarke umschliessen.Ein Band wird bei der Ausführung eines Reports ein- oder mehrmals gedruckt, je nachdem, ob es sich um ein einzelnes Objekt oder um eine Liste handelt. In diesem Fall wird das Band so viel mal gedruckt, wie sich Elemente in der Liste befinden.

Band Expressions

Die einzelnen Bands werden durch Band-Expressions gesteuert, welche sich in einer durch einen Kommentar markierte Textstelle befinden.Die Syntax ist dabei wie folgt:

  • Der markierte Text beginnt mit dem Namen des Bands, auf welches sich die Expression bezieht, gefolgt von Exp, Cond oder Locale, je nachdem, um welche Art von Expression es sich handelt (siehe unten).
  • Die Referenz auf den Code wird mit :name angegeben.

Als Band-Expression wird also zum Beispiel bndSpesenExp:spesen geschrieben, dieser Text markiert und mit einem leeren Kommentar versehen:

Im Code enthält das Schlüsselwort spesen dann die gewünschten Objekte, welche im Band dargestellt werden sollen.Es sind folgende Band Expressions möglich (bndXXX bedeutet dabei der Name des Bandes):

  1. 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.
  2. 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. Ein Band kann nicht gleichzeitig Exp- und eine Cond-Expression haben. Falls beides gewünscht ist, müssen zwei Bands gemacht werden, wobei das Cond-Band das Exp-Band umschliesst.
    Als Cond-Expression kann auch eine Context-Expression angegeben werden (ab Version 6.2.0.5). Die Syntax ist wie folgt: bndXXXCond:context:name.
  3. bndXXXLocale: Zahlenwerte werden nach den lokalen Regionaleinstellungen formatiert. Mit Locale-Expressions können alle Zahlenwerte innerhalb des Bands nach anderen Ländereinstellung formatiert werden. Für die Steuerung gibt es dabei zwei Möglichkeiten:
    1. Es wird eine Referenz auf den Code angegeben, welcher als Ergebnis einen Ländercode enthält. Im Code wird dafür im entsprechenden Frame ein OclTextField mit dem angegebenen Namen (hier im Beispiel locale) eingefügt:
      Resultat der angegebenen OCL-Expression muss ein Ländercode sein. Dieser kann entweder direkt angegeben werden wie hier oben im Beispiel ('de-DE'), oder z.B. aus einem Feld ausgelesen werden: OclTextField("locale", "projekt.zusatzfeldasstring('locale')").
    2. Der Ländercode wird direkt angegeben, z.B.  bndSpesenLocale:de-DE

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

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. Der markierte Text enthält dabei die Referenz auf die im Python-Code definierten Felder. Der Kommentar selbst ist oder enthält das Schlüsselwort translation, um die Übersetzung für dieses Feld zu aktivieren.

Um ein solches Feld zu erstellen, fügen Sie an der Stelle, wo später die Daten aus Vertec eingefügt werden sollen, das Schlüsselwort ein, und klicken Sie auf Überprüfen - Neuer Kommentar.

Felder summieren

Mit dem Präfix sum: können Feldwerte summiert werden. Im folgenden Beispiel werden die Werte des Feldes wertext des Frames leistungen summiert:

sum:leistungen.wertext

Summenfelder können auch Summen über mehrere Frame-Hierarchien darstellen:

Als Beispiel gibt es auf einem Spesen-Bericht ein Frame, welches eine Gruppierung nach Spesentypen macht (Name des Frames: spesentypen) und darauf ein Sub-Frame mit der Liste der Spesen für diesen Typ (Name des Sub-Frames: spesen).

Möchte man nun ausserhalb des Spesentypen-Bands die Summe aller Spesen ausgeben, geht das mit folgender Expression:

sum:spesentypen.spesen.wertext

Dieses Feld muss sich ausserhalb des ersten durch die Summe referenzierten Frames befinden, an einem Ort, wo auch die Frame Expression erlaubt wäre und das Frame liefern würde.

Context-Expressions

Mittels sogenannten Context-Expressions können Variablen direkt auf dem Report-Context ausgegeben werden, ohne dass dafür extra ein Feld auf einer Frame-Definition eingeführt werden muss.

Eine Context-Expression ist durch den Präfix context: gekennzeichnet und referenziert eine Context-Variable des Reports. Beispiel:

context:stichdatum

Der Datentyp des Feldes richtet sich nach dem Wert der Context-Variable. Falls es sich bei der Context-Variable um eine Objekt-Referenz oder eine Liste handelt, gibt die Context-Expression als Wert einen String (String-Representation) zurück.

Möchte man also beispielsweise im Titel einen Report-Parameter angeben, z.B. das Stichdatum einer Auswertung, muss dafür nicht extra ein separates Rahmenframe mit berechnetem FrameField eingeführt werden, sondern es kann direkt die Context-Expression angegeben werden.

Übersetzungen

Um ein Feld zu übersetzen, wird als Kommentar das Schlüsselwort translation eingetragen. Der Übersetzungsmechanismus schaut dann in der Übersetzungsdatei nach dem Begriff und setzt, falls vorhanden, die entsprechende Übersetzung ein.

Das setzt voraus, dass Begriffe, die ausschliesslich im Report verwendet werden (zum Beispiel der Report-Titel) in die Übersetzungsdatei eingefügt werden. Wie das geht, finden Sie im Artikel Sprachen / Begrifflichkeit.

Übersetzungen in Kopf- und Fusszeilen

In Kopf- und Fusszeilen von erweiterten Office-Berichten können Translations in doppelten Anführungszeichen geschrieben werden, z.B.

{{Translation:Page}} X {{Translation:of}} XX

Feldformatierungen

Datumswerte sowie Zahlen (Currency, Integer) können nach Visual Basic Formatierungsregeln formatiert werden. Die Formatierung wird dabei in den Kommentar des Feldes eingefügt, welches formatiert werden soll:

Für die Formatierung werden die lokalen Regionaleinstellungen verwendet. Um andere Regionaleinstellungen zu verwenden, kann eine Locale-Expression auf dem Band eingefügt werden (siehe dazu Abschnitt über die Bands).

Weitere Informationen zur Formatierung von Nummern und Datumsformaten finden Sie im Artikel Formatierung von Nummern und Datumsformaten.

Bilder

Bilder aus der Datenbank (wie ImageData bei Word-Berichten) werden im Python Code als ImageField bzw. OclImageField deklariert. Im Report-Dokument können sie als normale Datenfelder (kommentierter Text) eingefügt werden.

Die Angabe eines Bilder-Pfades (wie ImagePath bei Word-Berichten) ist in erweiterten Office-Berichten nicht implementiert.

Textbausteine (HTML)

Als HTML-formatierter Text z.B. aus Textbausteinen wird im Python Code als TextField bzw. OclTextField deklariert. Im Report-Dokument wird er mit dem Präfix html: eingefügt.

Beispiel Felddeklaration:

 OclTextField('textbaustein', "zusatzfeldobj('textbaustein').oclAsType(Textbaustein).text"),

In der Vorlage:

Der Wert wird als formatierter HTML-Text interpretiert und das Ergebnis in den Report geschrieben.

Es werden alle im Artikel Textbausteine beschriebenen Elemente unterstützt, auch innerhalb des HTML berechnete OCL-Expressions.

Expressions in Kopf- und Fusszeilen

In Kopf- und Fusszeilen können Context-Expressions verwendet werden.

Da in Kopf- und Fusszeilen Kommentare nicht verfügbar sind, werden die Variablen hier in doppelt geschweifte Klammern geschrieben, z.B.:

{{context:projekt}}

Aufbau der Excel-Vorlagen

Erweiterte Office-Berichte können ab Vertec 6.3 auch im Excel-Format ausgegeben werden. Der zugrunde liegende Python-Code ist dabei derselbe wie bei Word-Berichten; die beiden Formate unterscheiden sich nur durch die Vorlage.

Bänder

Um ein Band zu setzen, markieren Sie die entsprechenden Zellen und fügen im Feld oben links den Bandnamen ein.

Es gibt immer ein Main-Band, welches alles umfasst und sich auf das Hauptobjekt bezieht, also das Main-Frame enthält.

Die anderen Bänder und Sub-Bänder werden gleich gesetzt: Zellen markieren und oben links den Namen einfügen:

Wichtiger Hinweis: Achten Sie beim Setzen der Bänder darauf, dass nicht die gesamten Zeilen (hinten rechts bis unendlich) markiert sind, sondern nur die Zellen, die tatsächlich benötigt werden. Sonst dauert der Aufbau des Berichts länger, da Vertec durch alle Zellen iterieren muss, um herauszufinden, ob irgendwo ein Wert gesetzt ist.

Band-Expressions

Es gibt zwei Arten von Band-Expressions: Cond- und Exp-Bands.

  • Der Text beginnt mit dem Namen des Bands, auf welches sich die Expression bezieht, gefolgt von Exp oder Cond, je nachdem, um welche Art von Expression es sich handelt (siehe unten).
  • Die Expression (Referenz auf die Daten) wird mit :name angegeben

Als Band-Expression wird also zum Beispiel bndProjekteExp:projekte geschrieben, dieser Text markiert und mit einem leeren Kommentar versehen.

Excel fügt beim Anlegen eines Kommentars den Autor automatisch ein. Es ist wichtig, dass Sie diesen lassen und nicht rauslöschen. Mit "leerem" Kommentar ist also kein gänzlich leerer Kommentar gemeint, sondern einer, bei dem nur der Autor drin steht:

Notiz oder Kommentar?

In Excel-Versionen ab Office 365 gibt es "Notes", welche die "Comments" ablösen. Comments gibt es nach wie vor, sind aber neu eine Art Thread, wo sich mehrere User darüber unterhalten können.

 

Steht beides zur Verfügung, sollte man für die Vertec-Vorlagen die "Notes" verwenden.

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. Der markierte Text enthält dabei die Referenz auf die im Python-Code definierten Felder. Der Kommentar selbst ist leer (siehe oben) oder enthält das Schlüsselwort translation, um die Übersetzung für dieses Feld zu aktivieren.

Pro Zelle kann jeweils nur ein Begriff gesetzt werden. Es können also nicht in einer Zelle gleichzeitig ein Feld und eine Band-Expression gesetzt werden. Im Beispielreport in Abbildung 3 wurde das so gelöst, dass in der Zelle am Ende der Zeile die Band-Expression eingefügt und das Band um eine Spalte breiter gemacht wurde.

Context-Variablen

Auch die Context-Variablen werden unterstützt. Statt einem Python-Feld enthält die Zelle den Text context:, gefolgt von der entsprechenden Variable:

Datentypen in Excel

Im Gegensatz zu Word gibt es in Excel verschieden Datentypen. Die automatische Erkennung von Excel ist dabei nicht immer sinnvoll. Deshalb kann in der Excel-Vorlage die entsprechende Zelle mit der gewünschten Formatierung versehen werden. Beim Einfügen der Daten bzw. Kopieren der Zellen nach unten wird die Formatierung mitkopiert.

Summierung

Summierung in Excel funktioniert mit der gewohnten Excel Formel =Summe(<Band>).

Zeilensummen werden wie üblich mit den Zell-Bezügen gemacht:

Bei den Summen in den Spalten gelten folgende Richtlinien:

  • Es werden sämtliche Excel-Operatoren akzeptiert. Das Format muss aber =Operator(<Band>) lauten
  • Die Formel muss sich ausserhalb des durch die Summe referenzierten Bands befinden, aber innerhalb des dieses einschliessenden Bands, also eine Ebene tiefer.
  • Summiert wird die Spalte, in der sich die Formel befindet.
  • Zwischensummen sind möglich, aber nur innerhalb desselben Datensatzes.
  • Summierung aller Teilsummen in derselben Spalte wird nicht unterstützt.

Aufgrund der Formatierung der Datentypen (siehe den Abschnitt Datentypen in Excel) kann es bei den Zellbezügen zum Hinweis kommen "Ein in der Formel verwendeter Wert ist vom falschen Datentyp."

Dies ist deshalb so, weil in den Feldern z.B. leistwertint, leistwertext etc. steht, was ja nicht summiert werden kann. Nach der Generierung des Reports funktioniert die Summierung, da dann die Zahlenwerte drin stehen.