Element validieren
Verhalten - Kurzfassung
Das Verhalten Element validieren löst die Validierung eines bestimmten Elements (inkl. ggf. enthaltener weiterer Elemente) oder des gesamten Formulars aus und liefert dabei die Elementdaten an die Aktionen zurück.
Siehe auch: Element validieren und Profil aufrufen
Ist (wie im Bild oben) kein Element verknüpft, dann wird das Formular inklusive aller enthaltenen Elemente insgesamt validiert, so dass z. B. auch die Auslöser Formular ist gültig und Formular ist ungültig ansprechen.
Ist dagegen ein Element verknüpft (Technik dazu s. Verhalten) wird dieses Element validiert. Betrifft die Verknüpfung ein Element, das andere Elemente enthält (z. B. einen Element Container), werden auch diese Elemente validiert.
Unabhängig davon ob die Validierung ein gesamtes Formular, eine Teilstruktur oder ein individuelles Element betrifft, hängen die anwendbaren Prüfkriterien je Element von folgenden Umständen (s. a. Formularelemente) ab:
Ein Element, das als aktiv gilt und als Pflichtfeld qualifiziert ist, muss mit einem Wert "gefüllt" (ungleich $null) sein, um als valide zu gelten. Ob es zum Zeitpunkt der Validierung sichtbar ist oder nicht, hat dagegen keinen Einfluss.
Sind für ein Element individuelle Gültigkeitsregeln über Validierer konfiguriert (z. B. ein regulärer Ausdruck), dann werden diese nur dann geprüft, wenn das Element zum Zeitpunkt der Validierung aktiv und sichtbar ist.
Inaktive Elemente und diesen untergeordnete Elemente gelten grundsätzlich auch ohne Prüfung als valide.
Nur wenn jedes zu prüfende Element sämtliche anwendbaren Prüfkriterien erfüllt, werden die Aktionen bei "wahr" ausgeführt.
Sobald mindestens ein anwendbares Prüfkriterium eines zu prüfenden Elements nicht erfüllt ist, werden stattdessen die Aktionen bei "falsch" ausgeführt.
Unabhängig vom Ergebnis der Validierung übergibt das Verhalten in beiden Fällen dieselben Daten an die auszuführenden Aktionen. Welche das sind, hängt von der nachfolgenden Fallunterscheidung ab:
Ohne die Option Liefere übergeordnete Daten werden die Daten für den Einstiegspunkt der Validierung zurückgegeben.
Ist kein Element verknüpft, werden die gesamten Formulardaten zurückgegeben.
Ist ein Element mit Datenfeld verknüpft, werden dessen Daten und die aus allen ggf. direkt und indirekt enthaltenen Elementen zurückgegeben.
Ist ein Element ohne Datenfeld verknüpft, wird dessen übergeordnete Element-Hierarchie (ggf. bis zur Formularebene) aufsteigend durchlaufen bis ein Element mit Datenfeld gefunden wird, dessen Daten zurückgegeben werden.
Ist die Option Liefere übergeordnete Daten gesetzt, greift für den zweiten Fall aus der obigen Liste die folgende abweichende Regel, während die anderen unverändert gelten:
Ist ein Element mit Datenfeld verknüpft, wird der unvalidierte Stand für das in der Datenhierarchie unmittelbar übergeordnete Datenobjekt zurückgegeben, was das die Daten des verknüpften Elements und der ggf. darin enthaltenen Elemente einschließt.
Die Option Liefere übergeordnete Daten kann damit das Arbeiten mit komplexen Strukturen erleichtern, da dasselbe Verhalten einerseits die Validierung auf einen spezifischen Teilbereich aus einem Datenobjekt begrenzen kann, während für die Aktionen trotzdem ein erweiterter Informationsumfang zur Verfügung steht. Die Verwendung der Option wird in einem eigenen Beispiel (unten) demonstriert.
Der optionale Parameter Validierungsergebnis speichern in Variable legt den Namen einer Formularvariablen fest, in der im Zuge der Validierung Hinweistexte aus allen "invalide"-geprüften Elementen als Liste gesammelt werden. Sind für dasselbe Element mehrere anwendbare Prüfkriterien nicht erfüllt, wird nur der Hinweis mit der höchsten Priorität berücksichtigt. Per Hinweis setzen zugewiesene Hinweistexte werden auch dann ignoriert, wenn sie im Formular effektiv den Hinweis aus der Validierung überschreiben.
Die angegebene Variable wird vor der Validierung zurückgesetzt, so dass ihr Wert nach einer erfolgreichen Validierung leer ($null) ist.
Schlägt die Validierung fehl, stellt die Variable im Kontext des Formulars die gesammelten Hinweistexte auch nach Abschluss der aktuellen Verhaltensausführung bereit. Sie können sofort oder später über die Berechnungsfunktion var (Formularvariable auslesen) verwertet werden (s. zweites Beispiel unten).
Soweit relevant werden die einzelnen Hinweise unter Berücksichtigung der aktuellen Anzeigesprache lokalisiert (ggf. greifen Sprachverwaltung, Firmenspezifische Sprachanpassungen oder Übersetzungen auf Formularebene).
Beispiele
Beispiel zu "Liefere übergeordnete Daten"
Eine Erfassungsmaske beinhaltet ein plurales Freie-Aufzählung-Attribut (s. Freie-Aufzählung-Typ), das verwendet wird, um in den Daten eines Geschäftsobjekts ein oder mehrere "Verfügbare Luftfahrzeuge" anzugeben. Der verwendete Freie-Aufzählungs-Typ bezieht sich auf eine benutzerdefinierte Dynamische Aufzählung, die für jede Instanz des pluralen Attributs die Auswahl genau eines Luftfahrzeugtyps per Dropdown für das Feld enumValue ermöglicht. Daneben soll für jedes "verfügbare Luftfahrzeug" auch noch eine konkrete Kennung, die "Registrierung", in dem Textfeld "Text Wert"(textValue) eingetragen werden, das die Datenstruktur eines Freie-Aufzählung-Attributs als optionales Feld anbietet.
Die folgende Tabelle stellt gegenüber wie diese Datenstruktur einerseits im XML-Export für das betreffende Geschäftsobjekt (links) und andererseits in den Daten eines Detailformulars (rechts) erscheint:
|
XML-Export (Auszug) |
Anzeige von Verhaltensdaten in der Konsole (Auszug) |
|
Der folgende Auszug aus einem XML-Export zeigt die ersten beiden Einträge für das plurale Freie-Aufzählung-Attribut. XML-Export einer Sendung (Auszug)
...<attributes> ... <shp:ShipmentFreeEnum ... > <value enumValue="ACFT#A380" freeEnumType="ACFT" index="0"> <textValue>DACKL</textValue> </value> </shp:ShipmentFreeEnum> <shp:ShipmentFreeEnum ... > <value enumValue="ACFT#JU52" freeEnumType="ACFT" index="1"> <textValue>DAQUI</textValue> </value> </shp:ShipmentFreeEnum> ...</attributes>... |
Der folgende Screenshot zeigt für dieselben Daten die Ausgabe der Aktion In die Konsole loggen in einem Element validieren Verhalten, das zu diesem Zweck für jeden individuellen Eintrag des pluralen Attributs ausgeführt wurde. Dazu wurde das wiederholte Element (Spaltenlayout) des Wiederholendes Element Containers für das Attribut verknüpft, das im Formular auf das Datenfeld value verweist.
Ein Bezug zum Datenfeld value (s. value-Element im XML links) ist in der Ausgabe nicht ablesbar. Alle Merkmale der einzelnen Attribut-Instanz erscheinen allerdings deutlich erkennbar als Daten, die derselben Ebene angehören:
In der XML-Struktur links ist das weniger offensichtlich. Die Daten betreffen zwar alle dasselbe value-Element, sie werden aber in unterschiedlichen Ebenen (als XML-Attribut oder Text in einem Kind-Element) wiedergegeben. Für das Verständnis der Wirkungsweise der Option Liefere übergeordnete Daten ist die Datenhierarchie ausschlaggebend, die in der Ausgabe per Konsole direkt nachvollziehbar ist. Das Aktivieren der Option Liefere übergeordnete Daten für das oben verwendete Verhalten ergibt folgende Ausgabe für dieselben Attribut-Instanzen:
Hier tritt das Datenfeld value (das als Objekt alle oben ausgeführten Informationen beinhaltet) namentlich in Erscheinung. Es erscheint zusammen mit anderen Details für die Ebene ShipmentFreeEnum, die in der XML-Struktur ('...') weggelassen wurden. |
Im Detailformular wird das Textfeld für die Registrierung als Pflichtfeld definiert und mit einem Validierer (Typ "Regulärer Ausdruck") versehen, der formale Kriterien für die Zulässigkeit der Eingabe als "Registrierung" prüfen soll. Unter anderem muss eine Registrierung, die mit dem Buchstaben D beginnt, aus exakt fünf Großbuchstaben bestehen. Auf das Trennzeichen (Minus "-"), das die ICAO-Norm nach dem Staatszugehörigkeiten ("D" für Deutschland) vorschreibt, wird hier ausdrücklich verzichtet.
Für die Anzeige von "Verfügbaren Luftfahrzeugen" wurde im Formular die Darstellungsart "Grid" gewählt, die zahlreiche Einträge kompakt wiedergibt. Da Hinweise auf "Validierungsprobleme" bei dieser Darstellung nur für den aktuell ausgewählten Listeneintrag erkennbar sind, wird eine Prüfung aller Listeneinträge per Button "Registrierungen prüfen" angeboten, die ggf. per Aktion Hinweis anzeigen auf unzulässige Daten aufmerksam macht. Im Screenshot sind dabei zwei der angegeben Registrierungen unzulässig:
Der ausgegebene Hinweistext liefert Angaben, mit denen fehlerhafte Einträge in der Liste lokalisierbar sein sollten. Neben dem "Muster" (Feld enumValue), das in der Liste mehrfach vorkommen kann, erscheint die eindeutige Angabe der Listenzeile (automatisch befülltes Feld index mit Startwert 0).
Konfiguration:
Das entscheidende Element validieren Verhalten wird direkt für das validierende Element ("Registrierung") konfiguriert, allerdings ohne einen Auslöser festzulegen.
Trotzdem muss für das Verhalten noch ausdrücklich eine Verknüpfung zu diesem Element eingerichtet werden, da sonst das Formular insgesamt validiert wird.
Die Option Liefere übergeordnete Daten wird gesetzt, damit die Aktion Hinweis anzeigen (s. Aktionen bei "falsch") Zugriff auf die Daten des gesamten Listeneintrags und nicht nur den Wert des validierten Elements bekommt. Ohne die Option würde nur die eingegebene Registrierung, also das Literal aus dem textValue-Element (s. XML-Datenstruktur oben) zurückgegeben.
Aktionen bei "wahr" sind hier nicht vorgesehen.
Bei einem Fehlschlag der Validierung, also wenn der Wert für eine Registrierung unzulässig ist, wird die Aktion Hinweis anzeigen ausgeführt. Die Hinweisnachricht verwendet dabei Informationen aus den übergeordneten Daten des validierten Element:
{enumValue} gibt automatisch den anwendbaren Lokalisierungseintrag für das ausgewählte "Muster" für den Eintrag zurück.
{index} gibt die Zeilennummer (mit Startwert 0) für den aktuellen Listeneintrag zurück.
Für den Hinweis wird der Typ "Warnung" definiert, so dass ggf. mehrere Hinweise untereinander am rechten Bildschirmrand auftauchen.
Den Anstoß für die Validierung aller bestehenden Einträge liefert der Button, für den ein Verhalten konfiguriert wird, das auf den Auslöser "Angeklickt" reagiert.
Als Verhaltensweise wird hier zunächst Element validieren für den Wiederholendes Element Container "Verfügbare Luftfahrzeuge" (grüner Pfeil/Rahmen) ausgeführt.
Diese Validierung verläuft erfolgreich, sofern alle darin enthaltenen (aktiven) Elemente valide sind. Dann erfolgt eine globale Erfolgsmeldung per Hinweis anzeigen Aktion (im Bild nicht expandiert).
Anderenfalls wird eine Verhalten ausführen Aktion ausgeführt, die das oben beschriebene Verhalten mit dem Verhaltensnamen "check" im Element "Registrierung" Auch für Duplikate aufruft (roter Pfeil). Daraufhin erscheinen die dort definierten Hinweise für alle unzulässigen Registrierungen.
Beispiel zu "Validierungsergebnis speichern in Variable"
In einer Erfassungsmaske für Sendungen sollen bereits erfasste oder per Schnittstelle bereitgestellte Angaben per Formular validiert werden, bevor diese an ein anderes System "versendet" werden. Enthält das Formular "invalide" Angaben sollen die entsprechenden Hinweise auf Fehler als Liste in einer Hinweisbox und zusätzlich auch in einem Baum Element im Formular (eingebettetes Portal, s. Formulare einbetten (Sub-Formulare)) erscheinen. Wie im Beispiel (unten) zu sehen, besteht ein Vorteil dieser Zusammenfassung darin, dass die invaliden Daten teilweise in Aufklappbar (Expandable)-Elementen enthalten sein können und trotzdem sofort sichtbar werden.
Laufzeit-Beispiel:
Nach dem Klick auf den Button "Angaben prüfen und versenden" listet das unterhalb platzierte Baum Element alle im Formular gefundenen "Validierungsfehler" auf.
Während die Fehler-Hinweise aus den "Positionen" in dieser Situation (mit nur 2 Positionen) auch unmittelbar erkennbar wären, müsste man ohne die Zusammenfassung im Baum alle Aufklappbar (Expandable)-Elemente für Adressen öffnen um dort Fehler zu finden.
Die aufgelisteten "Validierungsfehler" kann man gezielt abarbeiten und dabei die Prüfung auch iterativ wiederholen, damit behobene Fehler verschwinden.
Konfiguration:
|
|
Für den Button "Angaben prüfen und versenden" wird ein Verhalten angelegt, das auf den Auslöser Angeklickt (nicht im Bild) reagiert und die Verhaltensweise Element validieren mit der folgenden Konfiguration verwendet:
|
