Neues Berichtsvalidierungssystem in FastReport VCL

Im technischen Support wurde uns oft der Wunsch nach einer automatischen Berichtsprüfung mitgeteilt – und mit dem Release 2026.2.0 haben wir dies umgesetzt. Im Menü „Datei“ des Berichtsdesigners sind nun die Punkte „Validate“ und „Einstellungen für Validierungsregeln“ (Validation Rule Settings) verfügbar. Damit können Berichte nicht nur geprüft, sondern auch der Satz an Regeln – einschließlich eigener Regeln – verwaltet werden.

In diesem Artikel erklären wir, wie die Berichtsprüfung funktioniert, wie sie konfiguriert wird, wie Sie eigene Regeln anhand von Beispielen erstellen und geben Einblicke in interessante Neuerungen.

Begriffe

Wir beschränken uns auf drei grundlegende Begriffe, die in diesem Artikel mehrfach verwendet werden.

Validierung ist die Prüfung der korrekten Berichtserstellung und der Einhaltung festgelegter Regeln, ohne den Bericht selbst zu generieren. Die Validierung erfolgt durch die sequenzielle Anwendung eines vordefinierten Regelsatzes auf den Bericht.

Regel ist eine einzelne Prüffunktion, die während der Berichtsvalidierung ausgeführt wird. Der Validierer speichert einen Satz von Regeln. Eine Regel kann ein- oder ausgeschaltet sein. Bei der Validierung werden nur die eingeschalteten Regeln ausgeführt. Während der Ausführung kann eine Regel mehrere Nachrichten senden.

Nachricht ist ein Eintrag, den eine Regel während der Berichtsprüfung erzeugt. Eine Nachricht enthält Informationen über ein erkanntes Problem, einschließlich Kritikalitätsstufe, Textbeschreibung und Reaktion auf einen Doppelklick.

Durchführen einer Berichtsprüfung im Designer

Die Berichtsvalidierung wird über den Menüpunkt „Validieren“ (Validate) oder durch Drücken der Tastenkombination Umschalt+F9 ausgeführt. Die Validierung kann auch an das Speichern oder Erstellen des Berichts gekoppelt werden. Dies kann im Menü „Ansicht → Einstellungen…“ (View → Options) auf dem Reiter „Validierung“ (Validation) konfiguriert werden.

Das Kontrollkästchen „Automatische Validierung“ (Automatic validation) aktiviert den automatischen Start der Berichtsprüfung beim Erstellen oder Speichern des Berichts.

Die Einstellung „Validierung fehlgeschlagen ab Kritikalitätsstufe“ (Validation fails if severity is at least) legt fest, ab welcher Kritikalitätsstufe die Validierung als fehlgeschlagen gilt. Mögliche Werte: „Hinweis“ (Hint), „Warnung“ (Warning), „Fehler“ (Error).

Wenn Sie „Warnung“ auswählen, gilt die Validierung bereits dann als fehlgeschlagen, wenn während der Prüfung mindestens eine Warnung oder ein Fehler auftritt. Standardmäßig ist „Fehler“ eingestellt.

Die letzten beiden Einstellungen steuern die Aktionen bei Berichten, die die Validierung beim Speichern oder Erstellen nicht bestehen. Sie können die Aktion erlauben, den Benutzer benachrichtigen oder die Aktion untersagen.

Konfiguration der Regelliste

Im Menü „Einstellungen für Validierungsregeln“ (Validation rule settings) kann der Satz an Regeln konfiguriert werden, der auf den Bericht angewendet wird. Dieses Fenster sieht wie folgt aus:

In der linken Liste „Standardregeln“ (Default rules) befinden sich die integrierten Regeln. Die rechte Liste „Benutzerdefinierte Regeln“ (Custom rules) ist für Regeln vorgesehen, die der Benutzer für spezifische Anforderungen erstellt hat. Diese Trennung ist jedoch bedingt: Der Benutzer kann seine eigenen Regeln auch in die Liste der Standardregeln einfügen.

Die Kontrollkästchen unter den Listen ermöglichen es, alle Elemente einer Liste auf einmal zu aktivieren oder zu deaktivieren. Das Kontrollkästchen „Validierung beim Speichern ausführen“ (Run validation on save) startet die Validierung beim Schließen des Regel-Einstellungsfensters durch Klicken auf die Schaltfläche „OK“.

Bei nachfolgenden Validierungen werden nur die aktivierten Regeln verwendet. Die Listen der angewendeten Regeln bleiben auch nach Beenden des Berichtsdesigners erhalten.

Liste der Standardregeln

Standardmäßig sind die folgenden Regeln verfügbar:

1. IntersectingTest erkennt Überlappungen von Berichtskomponenten. In einigen Fällen kann dies absichtlich geschehen sein, aber für tabellarische Exporte können solche Überlappungen Probleme verursachen. Daher empfehlen wir, diese Regel bei Verwendung tabellarischer Exporte aktiviert zu lassen.
2. PrepareScript prüft das Berichtsskript. Derzeit beschränkt sich die Prüfung auf die Kompilierung des Skripts.
3. ComponentValidation_IsEmpty findet leere Komponenten, die nicht mit Datenquellen verbunden sind. Manchmal werden solche Komponenten über das Skript befüllt, daher ist ihr Vorhandensein nicht immer ein Fehler.
4. ComponentValidation_Properties prüft die korrekte Einstellung von Komponenteneigenschaften. Beispielsweise prüft die Regel, ob nicht angebundene Child Bands vorhanden sind, sowie die Syntax von Ausdrücken in Eigenschaften.
5. ComponentValidation_Expressions prüft die Korrektheit von Ausdrücken in Komponenten, indem deren Werte ausgewertet werden. Standardmäßig deaktiviert.
6. DatasetsValidation prüft die korrekte Konfiguration der Berichts-Datasets. Standardmäßig deaktiviert.

Bitte beachten Sie, dass die Regelliste in Zukunft erweitert werden kann.

Berichtsvalidierung im DemoCenter

Versuchen wir, eine Berichtsvalidierung zu starten. Beachten Sie: Die Validierung gilt als fehlgeschlagen, wenn Warnungen oder schwerwiegendere Fehler auftreten (falls Sie vergessen haben, wie das funktioniert, lesen Sie bitte im Abschnitt „Durchführen einer Berichtsprüfung im Designer“ nach).

Nehmen wir den Bericht 1.fr3 aus dem DemoCenter und starten die Validierung:

Die Berichtsvalidierung ist fehlgeschlagen. Die Regel IntersectingTest hat fünf Warnungen erkannt. Dies war zu erwarten, da eine leere MemoView zur Hintergrundfüllung der geraden Zeilen verwendet wird.

Um die Liste der Warnungen anzuzeigen, kann der Knoten mit der Regel aufgeklappt werden. Durch einen Doppelklick auf die Zeile mit der Warnung wird die Komponente im Designer hervorgehoben, auf die die Regel das Problem gemeldet hat. Es ist wichtig zu beachten, dass nicht nur die Berichtsseiten, sondern auch das Skript sowie die Dialoge geprüft werden können. Für die Validierung steht der gesamte Bericht zur Verfügung.

Debug-Ausgabe mit DebugLn

Beachten Sie das Fenster zur Ausgabe der Validierungsmeldungen. Wir haben uns entschieden, es auch für andere Zwecke zu nutzen, beispielsweise für Debug-Meldungen und die Anzeige der Berichtserstellungszeit.

Wie kann dies genutzt werden? Verwenden Sie im Berichtsskript die neue Funktion DebugLn. Rufen Sie sie mit einem Parameter vom Typ String auf. Der Wert des Parameters erscheint bei der Berichtsausführung im Fenster „Messages“ zusammen mit einem Zeitstempel. Sehen wir uns das an einem Beispiel an.

Öffnen Sie im „FastReport Demo“ einen beliebigen Bericht, z. B. 1.fr3. Erstellen Sie einige Ereignisse bei Komponenten und rufen Sie im Ereignisbehandlungscode DebugLn() mit dem Ereignisnamen auf. Starten Sie den Bericht – im Fenster Messages sehen Sie dann die folgende Information:

Wir hoffen, dass diese Funktion Ihnen hilft, Berichte effizienter zu debuggen.

Erstellen einer eigenen Regel

Weiter oben wurde erwähnt, dass Sie eigene Regeln zur Berichtsprüfung erstellen können. Sehen wir uns im Detail an, wie das geht. Jede Validierungsregel muss ein Nachfahre einer der folgenden Klassen sein:

TfrxValidationRule ist Basisklasse für Berichtsregeln. Um mit dieser Klasse zu arbeiten, muss die abstrakte Methode Validate(AReport: TfrxReport) überschrieben werden.

TfrxValidationPageRule ist eine Klasse für die seitenweise Validierung eines Berichts. In Nachfahren muss die Methode ValidatePage überschrieben werden. Diese Methode wird für jede Berichtsseite aufgerufen.

TfrxValidationComponentRule ist eine Klasse für die komponentenweise Validierung eines Berichts. In dieser Klasse muss die Methode ValidateComponent überschrieben werden. Diese Methode wird für jede Berichtskomponente aufgerufen.

Zur Meldung eines Validierungsfehlers ist in der Basisklasse TfrxValidationRule die folgende Methode vorgesehen:

procedure DoMessage(ASeverity: TfrxValidationSeverity; 
const AText: string; 
ADoubleClickData: TObject = nil);

Diese Methode sendet eine Fehlermeldung an die registrierten Empfänger. Sehen wir uns die Parameter im Detail an:

1. ASeverity: TfrxValidationSeverity. Dieser Parameter bestimmt den Typ der Fehlermeldung und kann die Werte vsHint, vsWarning oder vsError annehmen.
2. const AText: string; Zeichenkette mit der Fehlermeldung.
3. ADoubleClickData: TObject = nil. Parameter, der die Aktion bei Doppelklick festlegt.

Betrachten wir den dritten Parameter ADoubleClickData etwas genauer. Derzeit kann hier nur eine Instanz der Klasse TfrxDoubleClickSetSelectionData übergeben werden. Dies kann in Zukunft erweitert werden.

Diese Klasse hat die folgenden Felder:

• ComponentName: string; Name der Komponente, bei deren Prüfung der Validierungsfehler aufgetreten ist.
• PropName: string; Name der Komponenteneigenschaft, bei deren Prüfung der Validierungsfehler aufgetreten ist.
• SelStart: TPoint. Startposition des fehlerhaften Codes im Code-Editor.
• SelEnd: TPoint. Endposition des fehlerhaften Codes im Code-Editor.

Für die korrekte Verarbeitung gibt es drei Möglichkeiten, dieses Objekt zu füllen:

• Nur ComponentName. Bei Doppelklick wird zur Komponente navigiert.
• ComponentName + PropName. Die Eigenschaft wird im Objektinspektor hervorgehoben. Auch die Aktivierung von verschachtelten Eigenschaften ist möglich – dies wird im folgenden Beispiel zu sehen sein.
• SelStart + SelEnd. Bei Doppelklick auf die Meldung wird in den Code-Editor gewechselt und der entsprechende Text markiert.

Nach dem Senden der Validierungsfehlermeldung muss das Objekt, das für den Doppelklick verantwortlich ist, gelöscht werden. Um eine Regel zu verwenden, muss die geschriebene Klasse registriert werden. Dies geschieht durch den Aufruf des folgenden Codes:

frxValidationSettings.RegisterRule(ABucket: TfrxRuleBucket; 
ARuleClass: TfrxValidationRuleClass; AActive: Boolean = True);

Das Objekt frxValidationSettings ist im Modul TfrxValidator definiert. Es handelt sich um ein Singleton zur Speicherung der Validierungsregeln.

Die Aufrufparameter im Einzelnen:

1. ABucket: TfrxRuleBucket legt fest, ob es sich um eine systemeigene oder benutzerdefinierte Regel handelt. Mögliche Werte: rbCustom, rbDefault.
2. ARuleClass: TfrxValidationRuleClass ist die Klasse der erstellten Regel.
3. AActive: Boolean legt fest, ob die Regel standardmäßig aktiv ist (dies kann später im Dialog der Regeln geändert werden).

Basierend auf dem oben Gesagten versuchen wir, eine eigene Berichtsvalidierungsregel zu formulieren. Angenommen, wir erstellen Berichte für eine Firma, in der alle Texte in den Firmenfarben Schwarz und Rot gehalten sein müssen. Die Verwendung anderer Farben gilt als Fehler. Auch die Rahmen von Beschriftungen müssen schwarz oder rot sein, der Hintergrund weiß. Da wir einzelne Komponenten prüfen, bietet sich für die Vererbung die Klasse TfrxValidationComponentRule an.

Die Deklaration unserer Regelklasse sieht wie folgt aus:

type
 TCorporateRule = class(TfrxValidationComponentRule)
 private
 procedure SendMessage(AComponent: TFrxComponent; APropertyName, AText:string);
 public
 procedure ValidateComponent(AComponent: TfrxComponent); override;
 class function GetName: string; override;
 end;

Auch die Methode GetName muss überschrieben werden, um den Namen der Regel zurückzugeben. Die Implementierung der Methoden:

class function TCorporateRule.GetName: string;
begin
 Result := 'Corporate_Colors';
end;
 
 
procedure TCorporateRule.SendMessage(AComponent: TFrxComponent;
 APropertyName: string);
var
 LSelData: TfrxDoubleClickSetSelectionData;
begin
 LSelData := TfrxDoubleClickSetSelectionData.Create;
 try
 LSelData.ComponentName := AComponent.Name;
 LSelData.PropName := APropertyName;
 DoMessage(vsError, AComponent.Name + ': Invalid color of property ' + APropertyName, LSelData);
 finally
 LSelData.Free;
 end;
end;
 
 
procedure TCorporateRule.ValidateComponent(AComponent: TfrxComponent);
var LMemo: TfrxMemoView;
 function CheckColors(AValue: TColor): Boolean;
 begin
 Result := (AValue = clBlack) or (AValue = clRed) or (AValue = clWhite) or (AValue = clNone) ;
 end;
begin
 if not (AComponent is TfrxMemoView) then Exit;
 LMemo := TfrxMemoView(AComponent);
 if not CheckColors(LMemo.Font.Color) then
 SendMessage(LMemo, 'Font.Color');
 if (not CheckColors(LMemo.Frame.TopLine.Color)) and (ftTop in LMemo.Frame.Typ) then
 SendMessage(LMemo, 'Frame.TopLine.Color');
 if not CheckColors(LMemo.Frame.BottomLine.Color) and (ftBottom in LMemo.Frame.Typ) then
 SendMessage(LMemo, 'Frame.BottomLine.Color');
 if not CheckColors(LMemo.Frame.LeftLine.Color) and (ftLeft in LMemo.Frame.Typ) then
 SendMessage(LMemo, 'Frame.LeftLine.Color');
 if not CheckColors(LMemo.Frame.RightLine.Color) and (ftRight in LMemo.Frame.Typ) then
 SendMessage(LMemo, 'Frame.RightLine.Color');
 if not CheckColors(LMemo.Color) then
 SendMessage(LMemo, 'Color');
end;

Registrierung der Regel:

initialization
 frxValidationSettings.RegisterRule(rbCustom, TCorporateRule);

Starten Sie nun die Anwendung, öffnen Sie den Berichtsdesigner und überprüfen Sie die Regelliste.

Testen wir nun unsere Regel mit einem Bericht, z. B. mit dem Bericht 1.fr3 aus dem DemoCenter.

Im Prüflog ist zu sehen, dass die Regel anschlägt. Bei einem Doppelklick auf den Fehler wird sofort zur Komponente mit der falschen Farbe navigiert. Im Objektinspektor ist die betreffende Eigenschaft hervorgehoben.

Validierung außerhalb des Designers

Mit FastReport wird die Berichtsprüfung nur im Designer selbst durchgeführt. Falls solche Prüfungen auch in anderen Fällen benötigt werden, kann der Benutzer sie selbst implementieren. So können beispielsweise Hunderte von Berichten auf Knopfdruck validiert werden. Dies kann wie folgt realisiert werden:

1. Zuerst muss eine Validator-Klasse TfrxValidator erstellt werden.
2. Dann wird die Liste der Regeln mit der Methode frxValidationSettings.ApplySettings(AValidator: TfrxValidator) übernommen.
3. Wenn nicht alle verfügbaren Regeln verwendet werden sollen, sondern nur bestimmte, müssen die Listen DefaultRules und CustomRules des Validator-Objekts manuell mit Regel-Objekten gefüllt werden (ein Implementierungsbeispiel findet sich in frxValidationSettings.ApplySettings).
4. Mit der Methode TfrxValidator.AddListener(const AListener: IfrxValidationListener) werden Empfänger für die Validierungsfehlermeldungen hinzugefügt.
5. Anschließend wird die Methode TfrxValidator.Validate(AReport: TfrxReport) zur Prüfung des Berichts gestartet.

Dies ist eine recht allgemeine Anleitung. Ein fertiges Implementierungsbeispiel finden Sie im Demo-Projekt ConsoleValidate.

Wie wir sehen, ist die Berichtsvalidierung unkompliziert und sehr nützlich. Wir freuen uns über Vorschläge zur Erstellung neuer Regeln.