Eine Einführung in die WebTML-Formularvalidierung
Wir haben ein simples WebTML-Formular um ein Benutzerprofil zu befüllen. Es besitzt vier Felder: Ein Textfeld, ein numerisches Feld sowie zwei Datumsfelder:
Bevor die Daten dieses Formulars irgendwo gespeichert werden möchten wir einige Bedingungen für die Daten sicherstellen:
Nun stellt sich die Frage der Realisierung. Natürlich können wir diese Validierungen manuell in TMLScript programmieren, und zwar bevor wir ebenfalls per TMLScript die Formulardaten speichern. WebTML-Formulare verfügen jedoch über eigene, dedizierte Validierungsfunktionen die in vielen Belangen praktischer sind als der manuelle Weg.
<tml:form id="theForm" source="profile">
Name: <tml:input type="text" name="name"/><br>
Personal-Nr.: <tml:input type="number" name="persnr" format="0"/><br>
Dienstantritt: <tml:input type="date" name="start" format="dd.MM.yyyy"/><br>
Dienstende: <tml:input type="date" name="end" format="dd.MM.yyyy"/><br>
<tml:button clickaction="$store">Speichern</tml:button>
</tml:form>
Name: <tml:input type="text" name="name"/><br>
Personal-Nr.: <tml:input type="number" name="persnr" format="0"/><br>
Dienstantritt: <tml:input type="date" name="start" format="dd.MM.yyyy"/><br>
Dienstende: <tml:input type="date" name="end" format="dd.MM.yyyy"/><br>
<tml:button clickaction="$store">Speichern</tml:button>
</tml:form>
Bevor die Daten dieses Formulars irgendwo gespeichert werden möchten wir einige Bedingungen für die Daten sicherstellen:
- Wir möchten dass immer ein Name eingegeben wurde.
- Dasselbe wollen wir auch für die Personalnummer, die darüber hinaus natürlich numerisch sein soll
- Wir möchten naturgemäß dass ein Dienstantritts-Datum vor dem Dienstende-Datum liegt
Nun stellt sich die Frage der Realisierung. Natürlich können wir diese Validierungen manuell in TMLScript programmieren, und zwar bevor wir ebenfalls per TMLScript die Formulardaten speichern. WebTML-Formulare verfügen jedoch über eigene, dedizierte Validierungsfunktionen die in vielen Belangen praktischer sind als der manuelle Weg.
Ein Vorteil der WebTML-Validierung gegenüber einer manuellen Methode ist, dass die Validierungsfunktionen direkt am Feld hinterlegt werden können. So können sämtliche Verhaltensweisen eines WebTML-Feldes direkt an seiner Definition gesammelt werden was sich positiv auf die Verstehbarkeit des Codes auswirkt.
Eine WebTML-Validierungs-Definition besteht im wesentlichen aus zwei zusätzlichen Attributen des <tml:input>-Tags: validation und message.
Das Attribut validation empfängt einen TMLScript-Ausdruck welcher den gewünschten Zustand des Feldes beschreibt. Dies bedeutet z.B. für das Feld "name" das es nicht leer sein darf:
Das Attribut message hingegen muss die Meldung beinhalten welche ausgegeben werden soll, wenn der Validierungsausdruck nicht erfüllt ist.
Wo aber werden diese Meldungen ausgegeben? Dies können wir über verschiedene Wege bestimmen, von welchen der trivialste die Verwendung des Tags <tml:formmessages/> ist:
Dieser Tag gibt die gesammelten Validierungsmeldungen des Formulars - im Beispiel jeweils getrennt durch einen HTML-Umbruchstag <br> - als Liste aus.
Wann passiert nun die Validierung? Sie wird automatisch vorgenommen sobald irgendeine Funktionalität versucht die WebTML-Formulardaten über eine der dafür vorgesehenen Methoden zu speichern. Dazu gehören die Methoden "storeInContent()", "storeInProfile()" etc. am TMLScript-Objekt "tmlform", aber auch die Default-Aktion "$store" wie sie im Beispiel verwendet wird.
Schlägt die Validierung fehl so wird die Speicherung abgebrochen, das Formular erneut angezeigt und die Validierungsmeldungen über Tag <tml:formmessages> ausgegeben.
Eine WebTML-Validierungs-Definition besteht im wesentlichen aus zwei zusätzlichen Attributen des <tml:input>-Tags: validation und message.
Das Attribut validation empfängt einen TMLScript-Ausdruck welcher den gewünschten Zustand des Feldes beschreibt. Dies bedeutet z.B. für das Feld "name" das es nicht leer sein darf:
<tml:input type="text" name="name"
validation="!isEmptyValue(tmlform.name)"/>
validation="!isEmptyValue(tmlform.name)"/>
Das Attribut message hingegen muss die Meldung beinhalten welche ausgegeben werden soll, wenn der Validierungsausdruck nicht erfüllt ist.
<tml:input type="text" name="name"
validation="!isEmptyValue(tmlform.name)"
message="Bitte geben sie einen Namen ein!"/>
validation="!isEmptyValue(tmlform.name)"
message="Bitte geben sie einen Namen ein!"/>
Wo aber werden diese Meldungen ausgegeben? Dies können wir über verschiedene Wege bestimmen, von welchen der trivialste die Verwendung des Tags <tml:formmessages/> ist:
p>
<tml:formmessages divider="<br>"/>
</p>
<tml:formmessages divider="<br>"/>
</p>
Dieser Tag gibt die gesammelten Validierungsmeldungen des Formulars - im Beispiel jeweils getrennt durch einen HTML-Umbruchstag <br> - als Liste aus.
Wann passiert nun die Validierung? Sie wird automatisch vorgenommen sobald irgendeine Funktionalität versucht die WebTML-Formulardaten über eine der dafür vorgesehenen Methoden zu speichern. Dazu gehören die Methoden "storeInContent()", "storeInProfile()" etc. am TMLScript-Objekt "tmlform", aber auch die Default-Aktion "$store" wie sie im Beispiel verwendet wird.
Schlägt die Validierung fehl so wird die Speicherung abgebrochen, das Formular erneut angezeigt und die Validierungsmeldungen über Tag <tml:formmessages> ausgegeben.
Weiter zur nächsten Seite ...