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.
- Der Wert der Eigenschaft eventType lautet onCreate (da der Handler aufgerufen wird, wenn ein Berichtslayoutelement erstellt wird) oder onPageBreak (da der Handler aufgerufen wird, wenn ein Seitenumbruch nach der Verwendung eines Berichtslayoutelements an einer beliebigen Stelle auf der vorherigen Seite stattfindet).
- Der Wert des ersten Parameters basiert auf einem bestimmten Berichtslayoutelementtyp. Wenn der erste Parameter zum Beispiel den Typ 'LabelInstance' aufweist, enthält das Berichtslayoutelement, das an den Ereignishandler übergeben wird, Details, die für eine Bezeichnung - d. h. für Berichtstext ohne HTML-Formatierung - spezifisch sind. Darüber hinaus wird mithilfe des Typs des ersten Parameters bestimmt, welche Eigenschaften (zusätzlich zu den erforderlichen Eigenschaften eventType und elementName) im Handler gültig sind.
- Beachten Sie die folgenden Punkte hinsichtlich Ereignishandlern,
die onPageBreak referenzieren:
- Wenn eine Berichtstabelle oder ein Berichtsraster auf mehreren Seiten angezeigt wird, wird bei jedem Seitenumbruch ein Ereignishandler für diese Tabelle bzw. dieses Raster aufgerufen.
- Wenn sich ein Berichtslayoutelement (z. B. eine Bezeichnung) in einer Tabelle oder einem Raster befindet, wird ein Ereignishandler für dieses Berichtselement einmal pro Seite aufgerufen, auch wenn das Element mehrmals pro Seite wiederholt wird.
- Die Reihenfolge beim Aufrufen der Ereignishandler entspricht der Reihenfolge, in der die Berichtslayoutelemente angezeigt werden.
- Der Handler enthält stets einen Parameter des Typs 'ReportContext', mit dem Sie Berichtsparameterwerte zum Zeitpunkt des Aufrufs des Ereignishandlers abrufen oder festlegen können. Sie können beispielsweise für einen Berichtsparameter einen bestimmten Wert festlegen, der in einem Ausdruck verwendet wird, dessen Laufzeitwert im Bericht angezeigt wird.
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:
|
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 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
- 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:
- 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'
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
- '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.
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.