medamind

Contao-Formulare: Fehlermeldungen individuell

Ergänzend zu meinem Artikel über die in Contao deklarierte CSS-Klasse “error” geht es in diesem Beitrag darum, das für Formulare verwendete Template hinsichtlich der Gestaltung von Fehlermeldungen individuell zu gestalten.

Wie sieht eigentlich eine Fehlermeldung aus? Wie wird sie erzeugt? Und wie kann man Formulare noch benutzerfreundlicher gestalten, indem man die vorgegebene Standard-Ausgabe individualisiert? Eine Anleitung für alle, die nicht so gerne in den Code schauen.

Fehlermeldungen in Contao Formularen

Die Fehlermeldung, die nach dem Abschicken eines fehlerhaft ausgefüllten Formulars angezeigt wird, ist mehrstufig und hat etwas mit den Validierungsregeln zu tun, die man für einzelne Formularfelder vorgegeben hat. Die Fehlermeldungen werden der Reihe nach in einem Array verwaltet und können mehrstufig sein:

• Zunächst geht es darum, ob ein Feld Pflichtfeld ist. Dies ist immer die erste ausgegebene Fehlermeldung.
• Im Weiteren geht es darum, ob die Benutzereingaben den vorgegebenen Regeln entspricht, beispielsweise ob es sich wirklich um eine E-Mail Adresse handelt oder ob wirklich nur Zahlen eingeben wurden usw.

Das Template

Das Template form_widget ist verantwortlich für die Anzeige einzelner Formularfelder,  von Textfeldern oder Drop Down Menüs und anderen. Folgende Beispiele kann man also genau mit diesem Template durchspielen. <?php echo $this->generateWithError(); ?> ist die Standardvorgabe erzeugt das Eingabefeld so, dass bei fehlerhaft ausgefüllten Formularen die erste zutreffende Fehlermeldung erzeugt und oberhalb des Formularfelds angezeigt wird.

Änderung der Positionierung der Fehlermeldung Die Positionierung der Fehlermeldung unterhalb des Formularfelds erzeugt man durch die simple Änderung <?php echo $this->generateWithError(true); ?>

Es geht aber noch einiges mehr…

Aufgabe: Alle Fehlermeldungen auf einmal ausgeben

Um alle Fehlermeldungen auf einmal ausgeben zu lassen, empfiehlt es sich, die Vorgabe generateWithError() zu ersetzen und die Ausgabe des Formularfelds und die einer potenziellen Fehlermeldung voneinander zu trennen.

Ausgabe des Formularfelds

Das Formularfeld an sich erzeugt man durch ein schlichtes generate(). Man ersetzt also
<?php echo $this->generateWithError(); ?> durch
<?php echo $this->generate(); ?>

Nun muss man sich natürlich noch um die Fehlermeldung kümmern:

Die Fehlermeldung

Zunächst prüft man mit Hilfe von hasErrors(), ob es überhaupt eine Fehleingabe gibt (denn nur dann soll ja die Fehlermeldung angezeigt werden). Dann werden über die Funktion getErrorsAsString() alle Fehlermeldungen ausgegeben.

<?php if($this->hasErrors()):?>
<p><?php echo $this->getErrorsAsString(); ?></p>
<?php endif; ?>

Hinweis: um eine HTML Formatierung muss man sich selbst kümmern, daher habe ich die Fehlermeldungen hier in einen Paragraph gepackt.

Der komplette Code (Fehlermeldung über dem Eingabefeld) im Template form_widget könnte dann beispielsweise so aussehen:

<?php echo $this->generateLabel(); ?>
<?php if($this->hasErrors()):?>
<p class="error"><?php echo $this->getErrorsAsString(); ?></p>
<?php endif; ?>
<?php echo $this->generate(); ?><br />

Formatierungsvarianten

Wer es gerne etwas übersichtlicher möchte, kann durch getErrorsAsString(’mein x-beliebiges Trennzeichen’) noch gestalten, wie die einzelnen Fehlermeldungen voneinander getrennt dargestellt werden.

Aufgabe: eine eigene Fehlermeldung integrieren

Die Benutzerfreundlichkeit kann natürlich enorm gesteigert werden, indem man abseits der von Contao standardmäßig definierten Fehlermeldungen für Pflichtfelder und Muster-Verletzungen die Fehlermeldungen je nach Feld individualisiert und damit vielleicht noch deutlicher erklärt. Interessant abseits typischer Formularfelder wie Name oder E-Mail.

(Für alle Felder) eine eigene Fehlermeldung ergänzen

Die Funktion addError() ergänzt das Array der Fehlermeldungen um eine eigene Meldung - die letzte im Array, sie wird also hinten angestellt:

<?php this->addError('Es ist ein Fehler aufgetreten'); ?>

Nun ist das leider etwas ungenau, denn diese Meldung wird ohne weitere Instruktionen allen Feldern hintenangestellt, sobald ein Fehler auftritt und man beispielsweise nach obigem Muster Fehlermeldungen ausgibt.

Ein spezielles Feld um eine eigene Fehlermeldung ergänzen

Ein spezielles Feld um eine eigene Fehlermeldung ergänzen, ist der mögliche nächste Schritt: Nehmen wir also an, das (und nur das!) Formularfeld mit dem Namen “meinSpeziellesFeld” bedarf besonderer Behandlung, könnte man das folgendermaßen realisieren:

<?php if($this->name=='meinSpeziellesFeld‘):?>
<?php  $this->addError(’Es ist ein Fehler aufgetreten’); ?>
<?php endif; ?>

Der Wert von this->name, in diesem Fall ‘meinSpeziellesFeld’ muss dabei dem Namen des gewünschten Formularfelds entsprechen wie im Formulargenerator definiert. (Alternativ kann man dies übrigens auch über die ID (also die eindeutige Nummer des Formularelements) als auch das (weniger eindeutige?) Label steuern).

name = eindeutiger Bezeichner eines Formularfelds
id = eindeutige Id eines Formularfelds
label = Label zum Formularfeld

Diese spezielle Fehlermeldung gesondert ausgeben

Möchte man bei der Ausgabe der Fehler nun auf die Standardausgabe verzichten, kann man auch das steuern:

<?php if($this->name=='Email'):?>
<?php  $this->addError('meinSpeziellesFeld‘); ?>
<?php echo $this->getErrorAsString(x); ?> //x entspricht der Array Position
<?php else: ?>
<?php echo $this->getErrorsAsString(’/'); ?>
<?php endif; ?>

Wird also bei einem bestimmten Feld ein Fehler erzeugt, so wird die eigene Fehlermeldung, bei allen anderen ein String aus allen Fehlermeldungen getrennt durch einen Slash ausgegeben.
Eleganter (?) ist hier auch eine Mixtura mit generateWithError() denkbar.

Überlegungen zur Ausgabe und zum Layout

getErrorsAsString() und getErrorAsString() geben alle oder einen Fehler als Zeichenkette aus.
Oben ist beschrieben, wie man diese Fehlermeldung in ein HTML-Element packt und damit noch mehr Möglichkeiten hat, die Ausgabe per CSS zu stylen.

Die Funktion getErrorAsHTML() gibt die erste oder bei Angabe der Position x die x+1ste Fehlermeldung HTML-formatiert aus. Das ist recht simpel, die Ausgabe kommt einem auch sofort bekannt vor: <p class=”error…

Der Phantasie sind also kaum Grenzen gesetzt, - ich persönlich denke, die reine Textausgabe in Kombination mit dem Template bietet die meiste Flexibilität.

Insgesamt

Die Erzeugung und Darstellung von Formularen wie auch ihr Handling im täglichen Gebrauch sind in Contao wirklich gelungen gelöst - es funktioniert durchdacht und problemlos. Manchmal braucht man es allerdings etwas individueller. Nicht jedes Formular ist von Natur aus selbsterklärend und manche Information braucht vielleicht mehr Erklärung als andere. Die Contao API bietet mit etwas Blick hinter die Kulissen gewaltige Möglichkeiten zur Individualisierung. Und weil das alles gar nicht so schwer ist, hoffe ich, dem ein oder anderen Mut gemacht zu haben, sich nach den ersten Schritten an die Anpassung von Templates zu wagen.

Mehr Infos zum technischen Hintergrund findet man sowohl auf in der und natürlich auch in .