BIRT-Ereignishandler für das Berichtslayout

Jeder Ereignishandler für das Berichtslayout ermöglicht den Zugriff auf ein BIRT-Berichtselement, das im Bericht angezeigt wird. Dieser Elementtyp wird als Berichtslayoutelement bezeichnet, um ihn von einem Element, das eine Datenquelle oder ein Dataset darstellt, zu unterscheiden.

Die charakteristischen Merkmale der Ereignishandler für das Berichtslayout sind nachfolgend aufgeführt:
Der nachfolgend dargestellte Ereignishandler akzeptiert ein Bezeichnungselement mit dem Namen 'remark_label' und aktualisiert eine BIRT-Berichtstabelle, die über einen gebundenen Ausdruck mit dem Namen 'account_balance' verfügt.
function myLabelFunction( theLabel LabelInstance, theContext ReportContext ) 
   { eventType = onCreate, elementName = "remark_label" }
   balance float = theLabel.getRowData().getColumnValue("account_balance");
   if( balance > 0 )
      theLabel.text = "Balance Due";
      theLabel.getStyle().color = "red";
   end
end

In diesem Beispiel wird kein Berichtsparameter verwendet, jedoch der Ereignishandlerparameter theLabel zum Referenzieren eines gebundenen Ausdrucks mit dem Namen 'account_balance' und zum Aktualisieren der Bezeichnung 'remark_label'. Die Namen 'account_balance' und 'remark_label' stammen aus der Berichtsdesigndatei.

Der Inhalt eines Datenelements (wie z. B. 'account_balance') kann in einem Ereignishandler für das Berichtslayout nicht aktualisiert werden; es ist jedoch möglich, eine Bezeichnung zu aktualisieren, wie im vorherigen Beispiel gezeigt; auf einer allgemeineren Ebene kann ein Ereignishandler für das Berichtslayout den Stil für ein oder mehrere Berichtslayoutelemente festlegen.

Jeder der Ereignishandlerparameter (z. B. theLabel) basiert auf einem externen EGL-Typ, der eine Java™-Schnittstelle darstellt. Die folgende Tabelle enthält den Typ und den Zweck jedes Parameters in einem Ereignishandler für das Berichtslayout sowie den nicht qualifizierten Namen der zugehörigen Java-Schnittstelle. Die dritte Spalte der Tabelle gibt an, ob Eigenschaften (mit Ausnahme von eventType und elementName) angegeben werden können.

Externe EGL-Typen Zweck Eigenschaften (Beschreibung folgt zu einem späteren Zeitpunkt) mit Ausnahme von 'eventType' und 'elementName' Java-Schnittstelle
CellInstance Zugriff auf eine Zelle in einem Berichtsraster oder einer Berichtstabelle. Wenn 'CellInstance' für ein Raster verwendet wird, sind die Eigenschaften columnNumber und rowNumber verfügbar (beide optional). Wenn 'CellInstance' für eine Tabelle verwendet wird, sind die Eigenschaften rowType (erforderlich), columnNumber und rowNumber (beide optional) sowie groupName (erforderlich, wenn der Wert von rowType 'groupHeader' oder 'groupFooter' lautet) verfügbar. ICellInstance
DataInstance Zugriff auf ein Feld, das Daten aus einer Datenquelle oder einer Berechnung enthält.   IDataItemInstance
DynamicTextInstance Zugriff auf ein Feld, das CLOB-Daten (CLOB = großes Zeichenobjekt) enthält, zum Beispiel der Inhalt eines Memos.   IDynamicTextInstance
GridInstance Zugriff auf ein Feld in einem Raster, d. h. einer einfachen tabellenartigen Struktur.   IGridInstance
ImageInstance Zugriff auf ein Image, das sich in einem Datasetfeld, in einem lokalen Dateisystem oder an einer fernen Position befinden kann oder das in eine Berichtsdesigndatei eingebettet sein kann.   IImageInstance
LabelInstance Zugriff auf eine Bezeichnung, die keine HTML-Formatierung aufweist und keinen berechneten Wert darstellt.   ILabelInstance
ListInstance Zugriff auf eine Liste.   IListInstance
ReportContext Abrufen oder Festlegen von Berichtsparameterwerten.   IReportContext
RowInstance Zugriff auf eine bestimmte Zeile in einem Berichtsraster oder einer Berichtstabelle. Wenn 'RowInstance' für ein Raster verwendet wird, ist die optionale Eigenschaft rowNumber verfügbar. Wenn 'RowInstance' für eine Tabelle verwendet wird, sind die Eigenschaften rowType (erforderlich), rowNumber (optional) und groupName (erforderlich, wenn der Wert von rowType 'groupHeader' oder 'groupFooter' lautet) verfügbar. IRowInstance
TableInstance Zugriff auf eine Tabelle.   ITableInstance
TextInstance Zugriff auf Text, der eine HTML-Formatierung aufweisen oder eine berechneten Wert darstellen kann.   ITextItemInstance

Die folgende Tabelle enthält vier weitere externe Typen, die in Ereignishandlern für das Berichtslayout verwendet werden.

Externe EGL-Typen Zweck Java-Schnittstelle
ReportElementInstance Bereitstellen zusätzlicher Java-Methoden, wenn Sie mit Variablen eines der Typen arbeiten, die in der vorherigen Tabelle aufgeführt sind. IReportElementInstance (eine Java-Superklasse)
ReportItemInstance Bereitstellen zusätzlicher Java-Methoden, wenn Sie mit Variablen eines der Typen arbeiten, die in der vorherigen Tabelle aufgeführt sind (mit Ausnahme von 'CellInstance' und 'RowInstance'). IReportItemInstance (eine Java-Superklasse, die 'IReportElementInstance' untergeordnet ist)
RowData Zugriff auf die Laufzeitwerte einer Gruppe gebundener Ausdrücke; genauer: Akzeptieren des Inhalts, der von der 'ReportElementInstance'-Funktion 'getRowData()' zurückgegeben wird. IRowData
Style Zugriff auf Details der verwendeten Stile; genauer: Akzeptieren des Inhalts, der von der 'ReportElementInstance'-Funktion 'getStyle()' zurückgegeben wird. IScriptStyle

Details zu den externen Typen und ihren Funktionen finden Sie im Abschnitt 'Externe Typen in einem BIRT-Ereignishandler für Berichtslayouts'.

Möglicherweise benötigen Sie die Java-spezifischen Details nie, doch das Javadoc, in dem die einzelnen Schnittstellen beschrieben sind, ist im Dokument BIRT Report Scripting API Reference enthalten, das sich im Hilfesystem Ihres Produkts unter BIRT Programmer Reference > Reference > APIReference > BIRT Report Scripting API Reference befindet. Alle Java-Schnittstellen - mit Ausnahme von zwei Schnittstellen - befinden sich im Paket 'org.eclipse.birt.report.engine.api.script.instance'. Die Ausnahmen ('IRowData' und 'IReportContext' befinden sich in 'org.eclipse.birt.report.engine.api.script'.

Eigenschaften von Ereignishandlern

In der folgenden Tabelle werden die oben erwähnten Eigenschaften beschrieben.

Eigenschaft Typ Kommentar
columnNumber INT Identifiziert die Spalte bei der Verarbeitung einer Tabellenzelle oder Rasterzelle. Diese Eigenschaft ist optional.
elementName STRING

Für alle Layoutelementtypen mit Ausnahme von 'CellInstance' und 'RowInstance' ist 'elementName' der Name des Berichtselements selbst. Für 'CellInstance' und 'RowInstance' ist 'elementName' der Name der Tabelle oder des Rasters, in der bzw. dem sich die Zelle oder die Zeile befindet. (Die Ursache für den Unterschied ist, dass der BIRT-Designer das Benennen von Zellen oder Zeilen nicht zulässt.)

eventType 'EventTypeKind'-Auflistung: 'beforeOpen', 'openEvent' usw. Wie im Abschnitt '"EGL-BIRT-Handler' beschrieben.
groupName STRING Identifiziert die Gruppe, wenn der Wert von rowType 'GroupHeader' oder 'GroupFooter' lautet; in diesem Fall ist die Eigenschaft erforderlich.
rowNumber INT Identifiziert die Zeile bei der Verarbeitung einer Tabellenzelle oder -zeile bzw. einer Rasterzelle oder -zeile. Diese Eigenschaft ist optional.
rowType RowTypeKind-Auflistung:
  • detail
  • header
  • footer
  • groupHeader
  • groupFooter
Gibt den Zeilentyp an und ist für eine Tabellenzelle oder -zeile erforderlich. Diese Eigenschaft wird ignoriert, wenn sie für eine Rasterzelle oder -zeile angegeben wird.
Die nachfolgend aufgeführten zusätzlichen Details zu den Eigenschaften columnNumber und rowNumber sind nur für ein Zeilenelement oder ein Zellenelement von Bedeutung.
  • Die Nummerierung von Spalten und Zeilen beginnt mit 1, nicht mit 0.
  • Bei einer Rasterzeile verweist die Eigenschaft rowNumber auf eine Position innerhalb des Rasters. Bei einer Tabellenzeile verweist die Eigenschaft rowNumber auf eine Position innerhalb eines bestimmten Zeilentyps bzw. innerhalb eines bestimmten Zeilentyps mit einem bestimmten Gruppennamen. (Die Verwendung eines Gruppennamens ist nur möglich, wenn die Zeile den Typ 'groupHeader' oder 'groupFooter' aufweist.) Beispiele:
    • Wenn Sie die Zeile Nr. 3 angeben und der Wert der Eigenschaft rowType 'detail' lautet, ruft die EGL-Laufzeit den Ereignishandler immer dann auf, wenn die dritte Detailzeile erstellt wird. Beachten Sie, dass jede Detailzeile selbst einen Zeilentyp darstellt und mehrmals in einem bestimmten Bericht vorkommen kann. Wenn Ihre Datenbankabfrage zum Beispiel eine Gruppe von Datenbankzeilen abruft, von denen jede einen Mitarbeiternamen, eine Adresse und einen Titel enthält, können Sie eine Berichtsdetailzeile für den Namen, eine für die Adresse und eine für den Titel definieren. Der Ereignishandler kann z. B. die dritte Detailzeile in Fettdruck darstellen. Dies liefert die folgende Ausgabe:
      Sales:
      
         Mr. A
         100 Main Street, Someplace, NY
         Sales Manager
      
         Mr. B
         101 Main Street, Someplace, NY
         Sales Rep
      
      Marketing:
      
         Ms. X
         102 Main Street, Someplace, NY
         Marketing Manager
    • Wenn Sie die Zeile Nr. 2 angeben, für die Eigenschaft rowType den Wert 'groupHeader' und für das 'groupName'-Element den Wert 'Division', findet der Aufruf während der Erstellung der zweiten 'groupHeader'-Zeile immer dann statt, wenn 'groupName' den Wert 'Division' aufweist. Sie können hier für die zweite Zeile ebenfalls Fettdruck festlegen. Dies liefert die folgende Ausgabe:
      Division A
      contains 2 departments:
      
         Sales
         Marketing
      
      Division B
      contains 3 departments:
      
         Sales
         Marketing
         Operations		
  • Für einen Ereignishandler, der ein Element des Typs 'RowInstance' akzeptiert, gelten die folgenden Regeln:
    • Wenn Sie 'rowNumber' angeben, ruft die EGL-Laufzeit den Ereignishandler auf, wenn die angegebene Zeile erstellt wird. Siehe hierzu die oben angeführten Beispiele.
    • Wenn Sie 'rowNumber' nicht angeben, findet der Aufruf entweder statt, wenn eine beliebige Zeile des angegebenen Typs erstellt wird oder - falls der Wert für RowType 'groupHeader' oder 'groupFooter' lautet - wenn eine beliebige Zeile des angegebenen Typs ('groupHeader' oder 'groupFooter') für die angegebene Gruppe erstellt wird.
  • Für einen Ereignishandler, der ein Element des Typs 'CellInstance' akzeptiert, gelten die folgenden Regeln:
    • Wenn Sie sowohl 'columnNumber' als auch 'rowNumber' angeben, ruft die EGL-Laufzeit den Ereignishandler auf, wenn die angegebene Zelle in der angegebenen Zeile erstellt wird.
    • Wenn Sie 'rowNumber' angeben, nicht jedoch 'columnNumber', findet der Aufruf statt, wenn eine beliebige Zelle in der angegebenen Zeile erstellt wird.
    • Wenn Sie 'columnNumber' angeben, nicht jedoch 'rowNumber', findet der Aufruf statt, wenn eine beliebige Zelle in der angegebenen Spalte erstellt wird. Wenn Sie z. B. die Spalte Nr. 2 angeben und der Wert für die Eigenschaft rowType 'detail' lautet, findet der Aufruf statt, wenn die zweite Spalte in einer beliebigen Detailzeile erstellt wird. Entsprechend findet, wenn Sie die Spalte Nr. 2 angeben, für die Eigenschaft rowType den Wert 'groupHeader' und für das Element 'groupName' den Wert 'Division', der Aufruf während der Erstellung der zweiten Spalte in jeder 'groupHeader'-Zeile statt, für die 'groupName' den Wert 'Division' aufweist.
    • Wenn Sie weder 'columnNumber' noch 'rowNumber' angeben, findet der Aufruf entweder statt, wenn eine beliebige Zelle für einen angegebenen Zeilentyp erstellt wird, oder - beim Wert 'groupHeader' bzw. 'groupFooter' für RowType - der Aufruf findet statt, wenn eine beliebige Zelle im angegebenen Zeilentyp ('groupHeader' bzw. 'groupFooter') für die angegebene Gruppe erstellt wird.

Die Auswirkung der Reihenfolge bei Ereignishandlern für 'onCreate'

Wenn für die Eigenschaft eventType der Wert onCreate festgelegt ist, ist die Reihenfolge der Ereignishandler für das Berichtslayout von Bedeutung. Immer dann, wenn mehrere Ereignishandler für die Erstellung eines bestimmten Berichtslayoutelements Anwendung finden könnten, nimmt ein späterer Ereignishandler eine Vorrangstellung gegenüber früheren ein. Betrachten Sie z. B. die folgenden Funktionen in der aufgeführten Reihenfolge:
function myEventHandler01( r RowInstance, theContext ReportContext )
{eventType = onCreate, elementName = "myReportTable", rowType = detail}
  r.getStyle().color = "red";
end

function myEventHandler02( r RowInstance, theContext ReportContext )
{eventType = onCreate, elementName = "myReportTable", rowType = detail, rowNumber = 2}
  r.getStyle().color = "green";
end
Wenn die Tabelle 'myReportTable' über 3 Detailzeilen verfügt, wirkt sich dies zur Laufzeit wie folgt aus:
  • 'myEventHandler01' wird bei der Erstellung von Zeile 1 aufgerufen, die rot hervorgehoben wird.
  • 'myEventHandler02' wird bei der Erstellung von Zeile 2 aufgerufen, die grün hervorgehoben wird.
  • 'myEventHandler01' wird bei der Erstellung von Zeile 3 aufgerufen, die rot hervorgehoben wird.

Bei der Erstellung von Zeile 2 könnten beide Funktionen Anwendung finden, 'myEventHandler02' hat jedoch Vorrang und 'myEventHandler01' wird für diese Zeile nicht aufgerufen.

Betrachten Sie dieselben Funktionen in umgekehrter Reihenfolge:
function myEventHandler02( r RowInstance, theContext ReportContext )
{eventType = onCreate, elementName = "myReportTable", rowType = detail, rowNumber = 2}
  r.getStyle().color = "green";
end

function myEventHandler01( r RowInstance, theContext ReportContext )
{eventType = onCreate, elementName = "myReportTable", rowType = detail}
  r.getStyle().color = "red";
end

Bei der Erstellung jeder Zeile hat 'myEventHandler01' Vorrang und 'myEventHandler02' wird nicht aufgerufen. Jede Zeile wird rot hervorgehoben.


Feedback