Formulare

1. Einleitung

Auf Grund der Tatsache, dass der Page-Controller des APF einen generischen Rahmen für das Verarbeiten von beliebigen Taglibs bereitstellt, ist es auf dieser Basis möglich, Formulare mit verschiedenen Taglibs - wie z.B. Text-Felder - zu abstrahieren.

Das Release des Adventure PHP Framework beinhaltet daher einen Satz von Taglibs, mit denen HTML-Formulare vollständig abstrahiert sind und die gleichzeitig Features, wie Filterung, Validierung und Presetting out-of-the box beherrschen. Mit den in der Version 1.11 überarbeiteten Taglibs können Formular-Felder mit beliebigen Filter und Validatoren belegt und eigene Taglibs integriert werden.

Die folgenden Kapitel beschreiben den grundsätzlichen Aufbau und die Verarbeitung von Formularen, sowie die vorhandenen Tags und deren Bedeutung und Funktion. Parallel dazu ist es ratsam, die API-Dokumentation bei der Implementierung zu Hilfe nehmen. Diese zeigt - insbesondere bei der Klasse HtmlFormTag - auf, welche Möglichkeiten die APF-Formulare bieten.

Das Kapitel Verwendung von Formularen beinhaltet ausführliche Beispiele für die Verwendung und Erweiterung von Formularen.

2. Aufbau von Formularen

Wie in der Einleitung kurz beschrieben, werden Formulare im APF durch Taglibs abgebildet. Die Basis-Taglib bildet dabei <html:form />, die alle weiteren Tags kapselt und so ein Formular in einem Document-Controller als ein Objekt zur Verfügung stellt. Dieses kann weitere Tags beinhalten, die entweder konkrete Elemente wie ein Text-Feld oder einen Button repräsentieren, oder funktionale Tags wie Platzhalter, Listener oder Tags, die eigene Formular-Elemente hinzufügen.

Formulare werden - wie auch andere Elemente der GUI - in Template-Dateien definiert. Ein einfaches Formular für eine Suche mit einem Eingabe-Feld und einem Button hat folgende Gestalt:

APF-Template
<core:addtaglib class="APF\tools\form\taglib\HtmlFormTag" prefix="html" name="form" /> <html:form name="Search"> <form:text name="searchterm" /> <form:button name="search" value="GO" /> </html:form>

Um das Formular anzuzeigen, muss ein Document-Controller für das betreffende Template vorhanden sein. Dies hat den Grund, dass ein Formular - im Gegensatz zu anderen Taglibs - immer an eine Verarbeitung durch den Entwickler gebunden ist. Sei es das Auslesen des Suchwort und Ausführen der Suche oder das Speichern von Nutzerdaten.

Zur Anzeige des Formulars ist folgender Code im Controller erforderlich:

PHP-Code
class SearchController extends BaseDocumentController { public function transformContent(){ $form = &$this->getForm('Search'); $form->transformOnPlace(); } }

Die folgenden Kapitel beschreiben nun die vorhandenen Formular-Elemente und deren Einsatzgebiet.

3. Mitgelieferte Tags

Das APF beinhaltet bereits einen umfangreichen Satz and Formular-Elementen, die nach Bedarf konfiguriert werden können. Sollten diese nicht ausreichen, können jederzeit eigene Formular-Elemente hinzugefügt werden. Siehe hierzu Kapitel Verwendung von Formularen.

Da das APF einen generischen Tag-Parser beinhaltet, können Formular-Tags mit beliebigen Attributen ausgestattet werden. Zu diesen zählen insbesondere

  • id="..."
  • class="..."
  • style="..."

zur Formatierung der Elemente. Aus diesem Grund werden diese in den Beschreibungen der Taglibs nicht weiter erwähnt, sondern es wird lediglich auf die für die Funktion des Tags relevanten Attribute eingegangen.

Ein weiteres generische Attribute ist optional, das zur Kennzeichnung von optionalen Feldern hinsichtlich der Validierung genutzt wird. Details können im Kapitel Verfügbare Validatoren nachgelesen werden.
Attribute, die mit "[" und "]" geklammert dargestellt sind, haben optionalen Charakter, die übrigen müssen verpflichtend angegeben werden.

Das Formular-Tag selbst besitzt drei funktionale Attribute, die zur Definition und Konfiguration dienen:

APF-Template
<html:form name="" [method=""] [action=""] [autocomplete="true|false"]> ... </html:form>
Beschreibung der Attribute:
  • name: Name des Formulars. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
  • method: Versand-Methode des Formulars. Standardmäßig wird post verwendet. (Zeichen: [get|post])
  • action: URL, die bei Klick auf den Button aufgerufen werden soll.
  • autocomplete: Ist der Wert auf true gesetzt, wird dem Browser gestattet die Inhalte des Formulars für ein erneutes Ausfüllen zu speichern. Diese Funktion wird mit false verhindert. Letzteres wird insbesondere für Login-Formulare empfohlen.
Seit dem Release 1.13 ist es möglich, einen globalen Standard-Wert für das Attribut action über die Registry zu definieren. Dies ist in der Bootstrap-Datei durch den Aufruf von
PHP-Code
Registry::register('APF\tools', 'FormDefaultMethod','...')
möglich. Damit erhalten alle Formulare - sofern das Attribut in der Tag-Definition nicht gesetzt ist - den dort definierten Standard-Wert. Sofern auch dieser nicht gesetzt ist, wird "post" verwendet.
Bitte beachten Sie, dass Text-Felder keine Array-Notation für Namen unterstützen (Beispiel: text[de]). Grund dafür ist, dass Text-Felder skalare Werte enthalten sollen. Dieser Vereinbarung gemäß lesen die Validatoren auch nur skalare Werte aus und können nicht mit Arrays umgehen.

3.1. Button

Diese Taglib repräsentiert einen Submit-Button. APF-Formular-Elemente werden Event-basiert validiert und gefiltert. Dazu muss zwingend ein Button oder ein Image-Button definiert sein, da diese das Click-Event auslösen.

APF-Template
<form:button name="" value="" /> <form:button name=""> <button:getstring [name=""] namespace="" config="" entry="" /> </form:button>
Beschreibung der Attribute:
  • name: Name des Buttons. Über den Namen kann auf das Element zugegriffen werden. Dies ist insbesondere für die Validatoren und Filter notwendig. (Zeichen: [A-Za-z0-9-_])
  • value: Wert des Buttons. Dieser dient der Beschriftung.
Zur Beschriftung des Buttons kann der <button:getstring />-Tag eingesetzt werden. Details zur Definition der Konfigurations-Dateien können der Definition des Tags <html:getstring /> entnommen werden.

3.2. Image-Button

Der Image-Button erzeugt einen Button, der als Beschriftung ein Bild nutzt. Die Funktion ist identisch zum einfachen Button.

APF-Template
<form:imagebutton name="" src="" />
Beschreibung der Attribute:
  • name: Name des Buttons. Über den Namen kann auf das Element zugegriffen werden. Dies ist insbesondere für die Validatoren und Filter notwendig. (Zeichen: [A-Za-z0-9-_])
  • src: Bild-Quelle des Buttons.

3.3. Reset-Button

Seit dem Release 1.10 beinhalten die Formular-TagLibs einen Tag für Reset-Buttons. Diese repräsentieren einen HTML-Reset-Button und können wie "normale" Buttons im Document-Controller adressiert und konfiguriert werden.

Mit einem Reset-Button ist keine Validierung bzw. Filterung möglich!
APF-Template
<form:reset name="" value="" />
Beschreibung der Attribute:
  • value: Wert (Beschriftung) des Reset-Buttons.

3.4. Hidden-Feld

APF-Template
<form:hidden name="" value="" />
Beschreibung der Attribute:
  • name: Name des Hidden-Felds. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
  • value: Wert des Hidden-Feldes.

3.5. Text-Feld

APF-Template
<form:text name="" [value=""] />
Beschreibung der Attribute:
  • name: Name des Text-Felds. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
  • value: Wert des Text-Feldes.

3.6. Textarea

Eine APF-Text-Area existiert in zwei Ausprägungen: ohne Inhalt als selbstschließender Tag oder mit Inhalt, der im Template definiert wurde.

APF-Template
<form:area name="" /> <form:area name="">...</form:area>
Beschreibung der Attribute:
  • name: Name des Textarea. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])

3.7. Passwort-Feld

APF-Template
<form:password name="" [value=""]/>
Beschreibung der Attribute:
  • name: Name des Passwort-Felds. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
  • value: Wert des Passwort-Feldes.

3.8. Dateiupload-Feld

Das Dateiupload-Feld besitzt folgende Signatur:

APF-Template
<form:file name="" />
Beschreibung der Attribute:
  • name: Name des Dateiupload-Felds. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])

Um hochgeladene Dateien einfach verarbeiten zu können, besitzt der Tag folgende Methoden, die in einem Document-Controller genutzt werden können:

  • hasUploadedFile(): gibt true zurück, sofern eine Datei hochgeladen wurden, andernfalls false.
  • getFile(): gibt eine Instanz der Klasse FileModel zurück, die eine hochgeladene Datei repräsentiert. Wenn keine Datei hochleladen wurden, wird null zurückgegeben.

Das folgende Formular zeigt Ihnen ein Anwendungsbeispiel des Tags:

APF-Template
<@controller namespace="VENDOR\..\controller\FileUploadController" @> <core:addtaglib class="APF\tools\form\taglib\HtmlFormTag" prefix="html" name="form" /> <html:form name="upload" method="post"> <p> <label for="name">Name:</label> <form:text name="name" id="name"/> </p> <p> <label for="image">Image:</label> <form:file name="image" id="image" accepts="jpg|image/png" maxsize="269205"/> <form:addvalidator class="MimeTypeValidator" control="image" button="send" /> <form:addvalidator class="FileSizeValidator" control="image" button="send" /> </p> <p> <form:button name="send" value="GO" /> </p> </html:form>

Für die Verarbeitung des Formulars ist ein Document-Controller erforderlich. Dieser definiert, wie die hochgeladene Datei behandelt werden soll. Der nachfolgend abgebildete Quellcode gibt Ihnen eine Anregung für die Implementierung in Ihrer Applikation:

PHP-Code
namespace VENDOR\..\controller; use APF\core\pagecontroller\BaseDocumentController; use APF\tools\filesystem\FilesystemManager; use APF\tools\form\taglib\FileUploadTag; class FileUploadController extends BaseDocumentController { public function transformContent() { $form = & $this->getForm('upload'); if ($form->isSent() && $form->isValid()) { $name = & $form->getFormElementByName('name'); /* @var $image FileUploadTag */ $image = & $form->getFormElementByName('image'); $file = $image->getFile(); $fileName = $file->getName(); $tmpFile = $file->getTemporaryName(); FilesystemManager::copyFile($tmpFile, './upload/' . $fileName, true); } else { $form->transformOnPlace(); } } }

Zur Prüfung der hochgeladenen Datei lassen sich der MimeTypeValidator und der FileSizeValidator einsetzen.

Seit Release 1.16 wird seitens des APF auch ein weiteres Tool zum Erzeugen von Datei-Uploads mit Vorschau-Funktion sowie prozentualer Fortschrittanzeige angeboten: der MultiFileUpload. Ausführliche Informationen dazu entnehmen Sie bitte der Dokumentation im Wiki: MultiFileUpload im Wiki

3.9. Checkbox

Die Checkbox-Taglib implementierung nicht nur einen Wrapper für eine HTML-Checkbox, sondern inkludiert auch die Logik, die zum anhaken und abhaken einer Checkbox notwendig ist. Hierbei wird die Schwäche ausgebügelt, dass nicht angehakte Checkboxen speziell geprüft werden müssen.

APF-Template
<form:checkbox name="" value="" [checked="checked"] />
Beschreibung der Attribute:
  • name: Name der Checkbox. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
  • value: Wert der Checkbox.
  • checked: Definiert, ob die Checkbox vorselektiert ist.

3.10. Radio-Button

Die Radio-Button-Taglib implementierung nicht nur einen Wrapper für einen HTML-Radio-Button, sondern inkludiert auch die Logik, die zum anhaken und abhaken eines Radio-Buttons notwendig ist. Hierbei wird die Schwäche ausgebügelt, dass nicht selektierte Radio-Buttons speziell geprüft werden müssen.

APF-Template
<form:radio name="" value="" [checked="checked"]/>
Beschreibung der Attribute:
  • name: Name des Radio-Buttons. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
  • value: Wert des Radio-Buttons bzw. der aktuellen Option.
  • checked: Zeigt an, ob der Radio-Button vorselektiert ist.

3.11. Select-Feld

Ein Select-Feld kann auf unterschiedliche Arten definiert werden: mit statischen oder dynamisch hinzugefügten Optionen oder Gruppen oder einer Mischung aus den genannten Möglichkeiten. Dynamische Optionen und Gruppen können in einem (Document-)Controller hinzugefügt und verarbeitet werden.

Seit dem Release 1.12 sind auch Options-Gruppen verfügbar.

APF-Template
<form:select name="" /> <form:select name=""> <select:option value="" [selected="selected"]>...</select:option> [<select:group label=""> <group:option value="" [selected="selected"]>...</group:option> </select:group>] </form:select>
Beschreibung der Attribute:
  • name: Name des Select-Felds. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
  • value: Wert der Optionen. (Zeichen: [A-Za-z0-9-_])
  • selected: Soll eine Option vorausgewählt dargestellt werden, so muss das Attribut selected mit dem gleichnamigen Wert gefüllt sein.
  • label: Beinhaltet die Beschriftung einer Gruppe von Optionen.

3.12. Multiselect-Feld

Wie auch das einfache Select-Feld, so ist es auch beim Multiselect-Feld möglich, dieses auf zwei Arten zu definieren: ohne und mit statische Optionen und Gruppen.

APF-Template
<form:multiselect name="" /> <form:multiselect name=""> <select:option value="" [selected="selected"]></select:option> [<select:group label=""> <group:option value="" [selected="selected"]>...</group:option> <select:group>] </form:multiselect>
Beschreibung der Attribute:
  • name: Name des Multiselect-Felds. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
  • value: Wert der Optionen. (Zeichen: [A-Za-z0-9-_])
  • selected: Soll eine Option vorausgewählt dargestellt werden, so muss das Attribut selected mit dem gleichnamigen Wert gefüllt sein.
  • label: Beinhaltet die Beschriftung einer Gruppe von Optionen.
Der Name des Formular-Feldes darf am Schluss kein "[]" enthalten, da es sonst zu Fehlern bei der Übertragung der Optionen kommt.

3.13. Platzhalter

Der Platzhalter dieht dazu, dynamische Inhalte in das Formular einzubringen.

APF-Template
<form:placeholder name="" />
Beschreibung der Attribute:
  • name: Name des Platzhalters. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])

Um einen Platzhalter eines Formulars zu füllen, besitzt die Klasse HtmlFormTag die Methode setPlaceHolder():

PHP-Code
$form = &$this->getForm('MyForm'); $form->setPlaceHolder('NameOfThePlaceHolder','...Value...');

3.14. Datums-Control

Um die Erstellung von Datum-Auswahl-Menüs zu erleichtern, enthält das APF ein Date-Control. Dieses kann entsprechend den Anforderungen konfiguriert werden.

APF-Template
<form:date name="" [yearrange=""] [offsetnames=""] [tab-indexes=""] [prepend-empty-options="true|false"] />
Beschreibung der Attribute:
  • name: Name des Datum-Controls. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
  • yearrange: Range des Jahres-Feldes. Beispiel: 1990-2007. (Zeichen: [0-9-])
  • offsetnames: Namen der Felder für Tag, Monat und Jahr. Einzelne Felder müssen durch ";" getrennt werden. Beispiel: Tag;Monat;Jahr. (Zeichen: [A-Za-z;])
  • tab-indexes: Das Datums-Control besteht aus drei Auswahl-Feldern. Mit diesem Attribut lassen sich die tabindex-Attribute der einzelnen Felder individuell festlegen. Beispiel: 1;2;3. (Zeichen: [0-9;])
  • prepend-empty-options: Wird das Attribut mit dem Wert true gefüllt, wird das Control beim ersten Aufrufen mit leeren Optionen dargestellt. Sofern das Feld mit einem Validator belegt wird, zwingt dies den Benutzer zu einer aktiven Auswahl. (Zeichen: true|false)

3.15. Marker

Wie im Kapitel Dynamische Formulare beschrieben, kann der Tag <form:marker />-Tag zur Positionierung von dynamischen Formular-Elementen genutzt werden. Der Tag selbst erzeugt dabei keine Ausgabe.

APF-Template
<form:marker name="" />
Beschreibung der Attribute:
  • name: Name des Markers. Dieser dient zur Adressierung desselben. (Zeichen: [A-Za-z0-9_-])

3.16. Addtaglib

Die Taglib <form:addtaglib /> bildet das Pendant zur Taglib <core:addtaglib /> und bietet die Möglichkeit, die bestehende Funktionalität der Formular-Tags zu erweitern. Die Implementierung des Tags erlaubt es beliebige weitere Formular-Tags einzubinden und zu verwenden.

APF-Template
<form:addtaglib class="" prefix="" name="" />
Beschreibung der Attribute:
  • class: Der voll-qualifizierte Klassen-Name der Tag-Implementierung. (Zeichen: [A-Za-z0-9_\])
  • prefix: XML-Prefix. (Zeichen: [a-z])
  • name: XML-Tag-Name. (Zeichen: [a-z])

3.17. Getstring

Der Tag <form:getstring/gt; dient dazu einen Konfigurations-String aus einer sprachabhängigen Konfigurations-Datei auszulesen und anzuzeigen. So können auf einfache Weise mehrsprachige Formulare aufgebaut werden. Details zur Definition der Konfigurations-Dateien können der Definition des Tags <html:getstring /> entnommen werden.

APF-Template
<form:getstring [name=""] namespace="" config="" entry="" />
Beschreibung der Attribute:
  • name: Name des Platzhalters zur Referenz in der getLabel()-Methode (Zeichen: [A-Za-z0-9_-])
  • namespace: Namespace der Konfiguration des Attributes. (Zeichen: [A-Za-z0-9_-\])
  • config: Name der Konfiguration. (Zeichen: [A-Za-z0-9-_])
  • entry: Name des Konfigurations-Offsets. (Zeichen: [A-Za-z0-9-_.])

3.18. Listener

Der Listener-Tag ist Teil des Validierungs-Konzeptes. Er hört auf das Event eines Validators und zeigt seinen Inhalt an, sofern das referenzierte Formular-Element nicht erfolgreich validiert werden kann. Im Tag selbst können beliebiger Text und weitere Tags definiert werden, die zur Ausgabe-Formatierung heran gezogen werden können. Details zur Validierung, können dem Kapitel 4 entnommen werden.

APF-Template
<form:listener [name=""] control="..." [validator="..." ]> ... [<listener:getstring namespace="" config="" entry="" />] [<listener:placeholder name="" />] [<listener:addtaglib class="" prefix="" name=""/>] ... </form:listener>
Beschreibung der Attribute:
  • control: Name des Formular-Elements auf dessen fehlgeschlagene Validierung der Inhalt angezeigt werden soll. (Zeichen: [A-Za-z0-9_-])
  • name: Name des Listeners. Dient zur Adressierung des Elements innerhalb des Formulars. (Zeichen: [A-Za-z0-9_-])
  • validator: Name des Validators, der den Listener bei fehlgeschlagener Validierung aktivieren darf.

Der Platzhalter-Tag <listener:placeholder /> gleicht in seiner Funktion dem <html:placeholder />, der <listener:getstring />-Tag <html:getstring /> und der <listener:addtaglib />-Tag dem <core:addtaglib />-Tag.

Zur Befüllung eines Platzhalters in einem Document-Controller kann folgender Code verwendet werden:

Template:
APF-Template
<html:form name="name_form" method="post"> <form:listener name="name-listener" control="name"> Please fill in the <listener:placeholder name="field-name" /> field! </form:listener> <form:text name="name" /> <form:addvalidator class="APF\tools\form\validator\TextLengthValidator" control="name" button="send" /> <form:button name="send" value="Send" /> </html:form>
Controller:
PHP-Code
class FormController extends BaseDocumentController { public function transformContent(){ $form = &$this->getForm('name-form'); $listener = &$form->getFormElementByName('name-listener'); $listener->setPlaceHolder('field-name','name'); } }

Das Attribut validator kann dann verwendet werden, wenn für das relevante Formular-Feld spezielle Validator-Listener definitiert sind. Ein Anwendungs-Beispiel ist die Prüfung eines E-Mail-Feldes, für das jeweils eine eigene Meldung für eine fehlende E-Mail-Adresse und eine syntaktisch nicht korrekte Eingabe ausgegeben werden soll. Hierzu kann folgendes Template genutzt werden:

APF-Template
<html:form name="email_form" method="post"> <form:listener control="email" validator="APF\tools\form\validator\TextLengthValidator"> Please fill in the email field! </form:listener> <form:listener control="email" validator="APF\tools\form\validator\EMailValidator"> Please fill in the email field with a correct email address! </form:listener> <form:text name="email" /> <form:addvalidator class="APF\tools\form\validator\TextLengthValidator" control="name" button="send" type="special" /> <form:addvalidator class="APF\tools\form\validator\EMailValidator" control="email" button="send" type="special" /> <form:button name="send" value="Send" /> </html:form>
Bitte beachten Sie, dass Validatoren, die für das Attribut type den Wert special enthalten nur spezielle Validator-Listener benachrichtigen. Sofern die oben ausgegebenen Validator-Meldungen noch mit einer Markierung versehen werden sollen, bietet sich an, einen EMailValidator zu definieren, deren Listener als Rahmen-gebende Elemente fungieren:
APF-Template
<html:form name="email_form" method="post"> <form:listener control="email"> <div class="error-container"> </form:listener> <form:listener control="email" validator="APF\tools\form\validator\TextLengthValidator"> Please fill in the email field! </form:listener> <form:listener control="email" validator="APF\tools\form\validator\EMailValidator"> Please fill in the email field with a correct email address! </form:listener> <form:listener control="email"> </div> </form:listener> <form:text name="email" /> <form:addvalidator class="APF\tools\form\validator\TextLengthValidator" control="name" button="send" type="special" /> <form:addvalidator class="APF\tools\form\validator\EMailValidator" control="email" button="send" type="special" /> <form:addvalidator class="APF\tools\form\validator\EMailValidator" control="email" button="send" /> <form:button name="send" value="Send" /> </html:form>

3.19. Anzeige von Formular-Fehlern

Der in Kapitel 3.18 beschriebene Tag kann dazu benutzt werden, automatisiert Fehlermeldungen eines definierten Formular-Feldes zu erzeugen. Der <form:error />-Tag ist für Fehlermeldungen vorbehalten, die das gesamte Formular betreffen. Wird eines der Felder als nicht valide markiert, so wird der Inhalt des Tags - sofern in der Formular-Definition vorhanden - ausgegeben.

APF-Template
<form:error [name=""]> ... [<error:getstring namespace="" config="" entry="" />] [<error:placeholder name="" />] [<error:addtaglib class="" prefix="" name="" />] ... </form:error>

Der Platzhalter-Tag <error:placeholder /> gleicht in seiner Funktion dem <html:placeholder /> der <error:getstring />-Tag <html:getstring /> und der <error:addtaglib />-Tag dem <core:addtaglib />-Tag. Die Befüllung des Platzhalters kann identisch zur Vorgehensweise des vorangegangenen Kapitels erledigt werden.

3.20. Anzeige von Formular-Erfolgsmeldungen

Der in Kapitel 3.19 beschriebene Tag kann dazu benutzt werden, automatisiert Fehlermeldungen bezogen auf ein komplettes Formular anzugeigen. Oft ist es jedoch notwendig, auch im Erfolgsfall eine Meldung auszugeben. Der <form:success />-Tag stellt einen Inhalt dar, wenn alle Felder des Formulars als valide gekennzeichnet werden. Die Definition gestaltet sich wie folgt:

APF-Template
<form:success [name=""]> ... [<success:getstring namespace="" config="" entry="" />] [<success:placeholder name="" />] [<success:addtaglib class="" prefix="" name="" />] ... </form:success>

Der Platzhalter-Tag <success:placeholder /> gleicht in seiner Funktion dem <html:placeholder />, der <success:getstring />-Tag <html:getstring /> und der <success:addtaglib />-Tag dem <core:addtaglib />-Tag. Die Befüllung des Platzhalters kann identisch zur Vorgehensweise des vorangegangenen Kapitels erledigt werden.

3.21. TimeCaptcha

Mit dem TimeCaptcha kann ein Formular in Kombination mit dem TimeCaptchaValidator vor (Spam-)Bots geschützt werden. Hierzu speichert die Taglib den Zeitpunkt der Erstellung in der Session und macht diesen für den genannten Validator zur Auswertung verfügbar.

Die minimale Zeitspanne, die Benutzer zum Ausfüllen des Formulars brauchen sollte, kann durch Angabe des optionalen Attributs seconds beeinflusst werden. Der Wert muss eine ganzzahlige Angabe des Zeitraums beinhalten.

APF-Template
<html:form name="..."> <form:timecaptcha name="timecaptcha" [seconds="3"]/> ... </html:form>

3.22. CSRF-Schutz

Diese Taglib erzeugt ein verstecktes Feld, das einen generierten Hash enthält. Das Formular wird als ungültig gekennzeichnet, wenn sich der im Request enthaltene Hash von einem neu generiertem unterscheidet. Damit ist es möglich, ein Formular vor CSRF-Attacken zu schützen.

Der mitgelieferte CSRFHashValidator muss nicht manuell hinzugefügt werden, da dies bereits in der Taglib geschieht.

Zur Generierung des Hashs wird das Provider Pattern genutzt, wodurch der Algoritgmus leicht ausgetauscht werden kann. Die Provider-Klasse muss dafür das CSRFHashProvider-Interface implementieren, welches die Methode generateHash() vorsieht.

Die folgende Code-Box zeigt den mit dem Release mitgelieferten Provider:

PHP-Code
class EncryptedSIDHashProvider extends APFObject implements CSRFHashProvider { public function generateHash($salt) { if(!defined('SID')) { session_start(); } return md5($salt.SID); } }

Der zu verwendende Provider wird mit dem Attribut class angegeben. Ist kein Wert gesetzt, wird der Standardprovider genutzt, welcher einen MD5 Hash von der SID und dem angegebenem Salt liefert.

APF-Template
<form:csrfhash salt="" name="" [class=""] />
Beschreibung der Attribute:
  • salt: Der Salt, der zur sicheren Berechnung des Hash eingesetzt wird.
  • name: Der Name des Feldes (Zeichen: [A-Za-z0-9_]).
  • class: Der voll-qualifizierte Klassen-Name der Provider-Implementierung. (Zeichen: [A-Za-z0-9_\])

3.23. Zeit-Control

Um die Erstellung von Zeit-Auswahl-Menüs zu erleichtern, enthält das APF ein Time-Control. Dieses kann entsprechend den Anforderungen konfiguriert werden:

APF-Template
<form:time name="" [hoursrange=""] [offsetnames=""] [showseconds="true|false"] [minutesinterval=""] />
Beschreibung der Attribute:
  • name: Name des Time-Controls. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
  • hoursrange: Range des Stunden-Feldes. Beispiel: 08-21. (Zeichen: [0-9-])
  • offsetnames: Namen der Felder für Stunden, Minuten und Sekunden. Einzelne Felder müssen durch ";" getrennt werden. Beispiel: Stunde;Minute;Sekunde. (Zeichen: [A-Za-z;])
  • showseconds: Hier kann festgelegt werden ob bei der Ausgabe auch ein Sekunden-Feld angezeigt werden soll.
  • minutesinterval: Mit diesem Attribut kann definiert werden in welchem Abstand die auswählbaren Minuten vorhanden sind. Man sollte aber darauf achten, dass 60 durch den Wert sinnvoll teilbar ist. Beispiel: 5, 10 oder 15.

3.24. MultiFileUpload

Seit dem Release des APF in der Version 1.16 gibt es ein weitere nützliches Tool: den MultiFileUpload. Alle wichtigen Informationen diesbezüglich entnehmen Sie bitte dem Wiki-Beitrag: MultiFileUpload im Wiki

3.25. Label

Seit Version 1.17 ist es möglich, die Beschriftung eines Formular-Elements als APF-Tag zu definieren.

Der Label-Tag hat folgende Signatur:

APF-Template
<form:label for=""> [...] [<label:getstring [name=""] namespace="" config="" entry="" />] </form:label>
Beschreibung der Attribute:
  • for: HTML-Id des Formular-Elements auf das sich die Beschriftung bezieht. (Zeichen: [A-Za-z0-9-_])
  • Inhalt: Der Inhalt des Tags kann entweder durch einen statischen Text oder mit Hilfe eines <label:getstring />-Tags definiert werden.
Details zur Definition der für den <button:getstring />-Tag notwendigen Konfigurations-Dateien können der Dokumentation des Tags <html:getstring /> entnommen werden.

4. Validierung

In den bisherigen Versionen des APF wurde die Validierung direkt mit einem Formular-Element verknüpft und diese auch im Lifecycle einer Taglib ausgeführt. Das hat zum Nachteil, dass ein Element mit nur einem Validator belegt werden kann und sich häufig redundanter Code durch Definition der Validatoren pro Feld ergibt. Weiterhin war es nicht ohne Weiteres möglich eigene Validatoren einzuhängen.

Ab Version 1.11 wurden diese Umstände berücksichtigt und die Formular-Taglibs auf eine neue Variante der Validierung umgestellt. Ab dieser Version werden Validatoren über ein eigenes Tag, das nach dem Observer-Pattern implementiert ist, an das einzelne Element gebunden. So ist es möglich, mehrere Validatoren auf ein Feld anzusetzen, eigene Validatoren zu schreiben und mit einer Observer-Definition mehrere Felder zu gleichermaßen zu validieren.

Die Definition einer Validierung eines Formular-Feldes gestaltet sich dabei wie folgt:

APF-Template
<form:addvalidator class="" button="" control="" [type="special"] />
Beschreibung der Attribute:
  • class: Der voll-qualifizierte Klassen-Name der Tag-Implementierung. (Zeichen: [A-Za-z0-9_\])
  • button: Name des Buttons, der die Validierung auslösen soll. Die Validierung ist immer an das Event isSent eines Buttons oder Image-Buttons gebunden. (Zeichen: [A-Za-z0-9-_])
  • control: Name des Formular-Controls auf das die Validierung Anwendung finden soll. Sollen mehrere Controls mit der im Tag definierten Validierung belegt werden, so enthält das Attribut alle mit Pipe getrennte Feld-Namen (z.B. sender|recipient|subject). (Zeichen: [A-Za-z0-9-_|])
  • type: Sofern das optionale Attribut vorhanden und auf den Wert special gesetzt ist, werden nur noch Listener informiert, die im Attribut validator den Namen (=Klassen-Namen) des mit dem Tag definierten Validators enthalten. (Zeichen: special)
Hinweise zu speziellen Validator-Listenern findet sich auch im Wiki-Artikel Spezielle Validator-Listener.

Die Markierung von invaliden Formular-Elementen erfolgt auf Basis von CSS-Klassen. Dies ermöglicht flexiblere Formatierung pro Formular oder Anwendungsfall. Das Proposal zur Implementierung kann unter Weiterentwicklung Formular-Validierung nachgelesen werden.

Im Standard-Fall werden von Validatoren als fehlerhaft markierte Felder mit der CSS-Klasse apf-form-error ausgestattet. Ist dies nicht erwünscht, kann diese Klasse durch Setzen des Attributs valmarkerclass beim jeweiligen Formular-Element beeinflusst werden:

APF-Template
<form:text name="age" valmarkerclass="special-val-marker" />

Um alle fehlerhaften Formular-Elemente innerhalb eines Web-Projekts mit einem roten Rahmen zu versehen, muss das CSS folgende Klassen-Definition enthalten:

CSS-Code
.apf-form-error { border: 2px solid red; }

Die speziellen Klassen-Definitionen müssen ebenfalls im CSS abgebildet werden. Andernfalls wird ein als invalid gekennzeichnetes Feld u.U. optisch nicht als solches hervorgehoben.

4.1. Verfügbare Validatoren

Das APF liefert eine Reihe von Validatoren mit. Diese decken üblicherweise den Großteil der Anforderungen ab. Sollten diese nicht genügen, können eigene Validatoren implementiert werden. Dies ist im nächsten Kapitel beschrieben.

Validatoren können auch als optional deklariert werden. Dazu muss das optional zu validierende Formular-Feld das Attribut optional mit dem Wert true besitzten:
APF-Template
<html:form name="..."> <form:text name="age" optional="true"/> <form:addvalidator class="APF\tools\form\validator\IntegerValidator" button="send" control="age" /> <form:button name="send" value="Send" /> </html:form>
Bitte beachten Sie, dass optionale Validatoren aktuell nur für Text-Felder implementiert sind, da Select- und Checkbox-Felder hinsichtlich ihrer Verwendung nach Meinung der APF-Entwickler keine optionale Validierung benötigen.

Aktuell sind folgende Validatoren im Release verfügbar:

4.1.1. TextLengthValidator

Der TextLengthValidator überprüft ein Text-Formular-Feld (Text-Feld, Passwort-Feld, Text-Area), ob der enthaltene Text eine Mindestlänge aufweist. Standardmäßig wird von einer Länge von mindestens 3 Zeichen ausgegangen, die vom Benutzer eingegeben werden müssen, ehe das Feld als gültig markiert wird. Sofern eine andere Text-Länge als valide Eingabe erwünscht ist, kann dies im referenzierten Text-Feld mit den Attributen minlength und maxlength angegeben werden:

APF-Template
<html:form name="..."> <form:text name="firstname" /> <form:text name="lastname" minlength="5" /> <form:password name="pass" /> <form:area name="comment" minlength="20" maxlength="200"/> <form:button name="send" value="Send"/> <form:addvalidator class="APF\tools\form\validator\TextLengthValidator" button="send" control="firstname|lastname|pass|comment" /> </html:form>

Im abgebildeten Code-Block wird das Formular-Control firstname auf einen Text mit einer Zeichenlänge >=3 validiert, im Feld lastname müssen mindestens 5 aber höchstens 200 Zeichen enthalten sein.

Seit dem Release 1.12 ist es möglich, eine strikte Validierung der Textlänge zu aktivieren. Hierzu kann im referenzierten Text-Feld das Attribut mode mit dem Wert strict versehen werden. Ab diesem Zeitpunkt wendet der Validator die Funktion trim() auf die Eingabe an und erkennt nur Inhalte an, die nicht lediglich aus Leerzeichen bestehen.

4.1.2. NumberValidator

Der NumberValidator prüft, ob ein Text-Feld eine gültige Nummer enthält. Hierzu wird die PHP-Funktion is_numeric() genutzt.

APF-Template
<html:form name="..."> <form:text name="number" /> <form:button name="send" value="Send"/> <form:addvalidator class="APF\tools\form\validator\NumberValidator" button="send" control="number" /> </html:form>
4.1.3. EMailValidator

Der EMailValidator prüft, ob im referenzierten ein Form-Control eine gültige E-Mail-Addresse steht. Hierzu wird der Inhalt des Text-Feldes gegen einen regulären Ausdruck geprüft.

APF-Template
<html:form name="..."> <form:text name="email" /> <form:button name="send" value="Send"/> <form:addvalidator class="APF\tools\form\validator\EMailValidator" button="send" control="email" /> </html:form>
4.1.4. PhoneAndFaxValidator

Der PhoneAndFaxValidator prüft, ob ein Formular-Feld eine gültige Telefon- oder Fax-Nummer enthält. Hierzu wird der Inhalt des Text-Feldes gegen einen regulären Ausdruck geprüft.

APF-Template
<html:form name="..."> <form:text name="phone" /> <form:text name="fax" /> <form:button name="send" value="Send"/> <form:addvalidator class="APF\tools\form\validator\PhoneAndFaxValidator" button="send" control="phone|fax" /> </html:form>
4.1.5. FieldCompareValidator

Mit dem FieldCompareValidator ist es möglich, den Inhalt zweiter Felder mit einander zu vergleichen. Stimmen sie nicht überein, werden die beiden Felder auf invalid gesetzt.

Da ein Validator immer auf ein konkretes Control gesetzt wird, muss das Haupt-Feld definieren, welches Formular-Element als Referenz-Feld genutzt wird. Hierzu definiert dieses das Attribut ref, das den Namen des Referenz-Feldes enthält.

APF-Template
<html:form name="..."> <form:password name="pass" ref="pass2" /> <form:password name="pass2" /> <form:addvalidator class="APF\tools\form\validator\FieldCompareValidator" control="pass" button="login" /> <form:button name="login" value="login" /> </html:form>
4.1.6. SimpleBirthdayValidator

Der SimpleBirthdayValidator prüft ein Text-Feld auf ein korrektes Datum der Form dd.MM.YYYY.

Der Validator kann nur mit "normalen" Text-Feldern verwendet werden. Sofern ein Date-Control validiert werden soll, muss der SimpleDateControlValidator genutzt oder ein eigener Validator implementiert werden.
APF-Template
<html:form name="..."> <form:text name="birthday" /> <form:button name="send" value="Send"/> <form:addvalidator class="APF\tools\form\validator\SimpleBirthdayValidator" button="send" control="birthday" /> </html:form>
4.1.7. SimpleSelectControlValidator

Der SimpleSelectControlValidator ist für die Prüfung von statischen und dynamischen Select-Formular-Feldern geeignet. Er prüft ein Select-Feld, ob der ausgewählte Inhalt nicht leer ist.

APF-Template
<html:form name="..."> <form:select name="color"> <select:option value=""></select:option> <select:option value="red">Red color</select:option> <select:option value="green">Green color</select:option> </form:select> <form:button name="send" value="Send"/> <form:addvalidator class="APF\tools\form\validator\SimpleSelectControlValidator" button="send" control="color" /> </html:form>
4.1.8. MultiSelectFieldValidator

Der MultiSelectFieldValidator ist das Pendant zum SimpleSelectControlValidator. Er prüft Multi-Select-Felder auf eine nicht leere Auswahl.

APF-Template
<html:form name="..."> <form:multiselect name="colors"> <select:option value="red">Red color</select:option> <select:option value="green">Green color</select:option> </form:multiselect> <form:button name="send" value="Send"/> <form:addvalidator class="APF\tools\form\validator\MultiSelectFieldValidator" button="send" control="colors" /> </html:form>
4.1.9. SimpleRadioControlValidator

Mit dem SimpleRadioControlValidator kann ein Radio-Button, bzw. eine ganze Gruppe validiert werden. Anforderung des Validators ist, das eine Option der Gruppe ausgewählt ist. Der Validator ist sowohl für dynamische als auch für statische Formular-Definitionen geeignet.

APF-Template
<html:form name="..."> <form:radio id="red" name="color" /> Red color <form:radio id="green" name="color" /> Green color <form:radio id="blue" name="color" /> Blue color <form:button name="send" value="Send"/> <form:addvalidator class="APF\tools\form\validator\SimpleRadioControlValidator" button="send" control="color" /> </html:form>
4.1.10. SimpleDateControlValidator

Der SimpleDateControlValidator validiert ein Date-Control (siehe Kapitel 3.14.). Er erwartet, dass das dort ausgewählte Datum größer als das heutige ist.

APF-Template
<html:form name="..."> <form:date name="birthday" /> <form:button name="send" value="Send"/> <form:addvalidator class="APF\tools\form\validator\SimpleDateControlValidator" button="send" control="birthday" /> </html:form>
4.1.11. MimeTypeValidator

Der MimeTypeValidator prüft, ob der MIME-Typ der hochgeladenen Datei in der Liste der akzeptierten Typen zu finden ist. Die Liste der zugelassenen Datei-Typen wird als Pipe-separierte Liste im Attribut accepts des zu validierenden Formular-Elements erwartet.

Die Evaluierung der Datei-Typen wird ab PHP 5.3 mit Hilfe der finfo-Funktionen durchgeführt, für alle früheren Versionen wird die Information genutzt, die von PHP im Offset type des $_FILES-Array zur Verfügung gestellt wird (siehe auch $_FILES im PHP-Manual).

Aus der Bestimmung der Inhalts-Typen kann sich eine Änderung der Definition der akzeptierten Medien ergeben. Ab der PHP Version 5.3 können die akzeptierten Typen in der MIME-Typen-Schreibweise (z.B. application/pdf) definiert werden, in PHP Versionen < 5.3 lediglich über die Endung (z.B. pdf).

Im folgenden Formular akzeptiert ein Dateiupload-Feld lediglich PDF-Dateien. Das Formular wird solange als invalid gekennzeichnet, bis der Benutzer das richtige Datei-Format gewählt hat:

APF-Template
<html:form name="upload" method="post"> <fieldset> <label for="pdf">PDF file:</label> <form:file name="pdf" id="pdf" accepts="pdf|application/pdf" /> <form:addvalidator class="APF\tools\form\validator\MimeTypeValidator" control="pdf" button="send" /> <form:button name="send" value="GO" /> </fieldset> </html:form>

Wie dem Attribut accepts zu entnehmen ist, wurden hier aus Gründen der Kompatibilität beide Schreibweisen der Type-Definitionen eingefügt um bei einem Version-Upgrade weiter die gewünschte Funktion zu erhalten.

4.1.12. FileSizeValidator

Der FileSizeValidator prüft die hochgeladene Datei auf ihre Datei-Größe. Hierzu werden die optionalen Attribute minsize und maxsize genutzt um den Bereich der erlaubten Datei-Größe in Bytes zu definieren.

Ist das Attribut minsize im zu validierenden Formular-Element nicht definiert, wird ein Wert von 0 angenommen. Es ist damit möglich, 0-Byte-Dateien hochzuladen. Ist das Attribut maxsize nicht definiert, wird eine maximale Größe von 1024000 (=1 MB) zugelassen.

Im folgenden Formular werden nur Dateien zugelassen, die eine Mindest-Größe von 20kB und eine maximale Größe von 500kB haben:

APF-Template
<html:form name="upload" method="post"> <fieldset> <label for="image">Image:</label> <form:file name="image" id="image" minsize="20480" maxsize="512000" /> <form:addvalidator class="APF\tools\form\validator\FileSizeValidator" control="image" button="send" /> <form:button name="send" value="GO" /> </fieldset> </html:form>
4.1.13. CheckboxValidator

Der CheckboxValidator prüft, ob eine Checkbox aktiviert wurde. Ist diese nicht der Fall, wird das Feld als invalid markiert.

APF-Template
<html:form name="upload" method="post"> <fieldset> ... <form:checkbox name="agb" value="agb" /> Akzeptiere die AGBs. <form:addvalidator class="APF\tools\form\validator\CheckboxValidator" button="send" control="agb" /> <form:button name="send" value="GO" /> </fieldset> </html:form>
4.1.14. TimeCaptchaValidator

Mit dem TimeCaptchaValidator kann ein Formular in Kombination mit dem <form:timecaptcha /> vor (Spam-)Bots geschützt werden. Der Validator prüft die Zeit, welche zum Ausfüllen des Formulars gebraucht wurde. Da Bots Formulare meistens binnen Sekundenbruchteilen ausfüllen, genügt es standartmäßig alle Formulare, welche in weniger als 2 Sekunden ebgeschickt wurden als invalid zu kennzeichnen. Dieser Wert kann durch Angabe des optionalen seconds Parameters in der Taglib-Definition beeinflusst werden.

APF-Template
<html:form name="..."> <form:timecaptcha name="timecaptcha"/> <form:addvalidator class="APF\tools\form\validator\TimeCaptchaValidator" button="send" control="timecaptcha" /> <form:button name="send" value="Send"/> </html:form>
4.1.15. IntegerValidator

Der IntegerValidator validiert, ob die Eingabe einen validen Integer-Wert enthält:

APF-Template
<html:form name="..."> <form:text name="age" /> <form:button name="send" value="Send"/> <form:addvalidator class="APF\tools\form\validator\IntegerValidator" button="send" control="age" /> </html:form>
4.1.16. NumberScopeValidator

Der NumberScopeValidator validiert ein Eingabefeld auf eine ganze Zahl in einem definierten Bereich. Der Standard-Bereich geht von 0 bis 65535 (maximale Zahl für 16-Bit Integer). Die untere und obere Grenze kann mit Hilfe der Attribute minvalue und maxvalue am jeweiligen Formular-Feld definiert werden. Der untere oder obere Bereich kann jweils mit dem Wert null auf unendlich gesetzt werden.

APF-Template
<html:form name="..."> <form:text name="age" minvalue="10" maxvalue="100" /> <form:button name="send" value="Send"/> <form:addvalidator class="APF\tools\form\validator\NumberScopeValidator" button="send" control="age" /> </html:form>
4.1.17. UriValidator

Der UriValidator validiert ein Eingabefeld auf eine valide URI.

APF-Template
<html:form name="..."> <form:text name="url" /> <form:button name="send" value="Send"/> <form:addvalidator class="APF\tools\form\validator\UriValidator" button="send" control="url" /> </html:form>

4.2. Aufbau von Validatoren

Validatoren sind Klassen, die von AbstractFormValidator erben. Diese definiert das Interface aller Formular-Validatoren. Das ist notwendig, damit diese als Observer an alle Formular-Elemente geheftet werden können.

Das Interface eines Validators hat folgende gestalt:

PHP-Code
abstract class AbstractFormValidator extends APFObject { protected $control; protected $button; public function __construct(AbstractFormControl &$control, AbstractFormControl &$button){ $this->control = &$control; $this->button = &$button; } public abstract function validate($input); public abstract function notify(); public function isActive(){ return $this->button->isSent(); } }

Über den Konstruktor werden das zu validierende Form-Control und der Button, der als Trigger fungiert injiziert. Die Methode validate() wird vom Formular-Element mit dem zu validierenden Inhalt versorgt und muss den Validierungs-Code enthalten. Als Rückgabe wird true im Erfolgsfall und false im Fehlerfall erwartet.

Die Methode notify() wird aufgerufen, wenn ein Formular-Element nicht erfolgreich validiert werden konnte. Dieses kann dazu dienen, die Formular-Elemente mit weiteren CSS-Formatierungen zu versehen, Platzhalter zu füllen oder Änderungen am DOM-Baum vorzunehmen. Die übliche Vorgehensweise ist, das Feld entsprechen zu markieren und die registrierten Listener zu benachrichtigen.

Die Klassen-Variablen $control und $button enthalten jeweils die Instanz des zu validieren Formular-Elements und den Button, der als Trigger verwendet wird.

Voraussetzung für die Funktion von Validatoren ist, dass ein Formular-Element die Validierung unterstützt. Hierzu muss in jedem Formular-Control die Methode addValidator() implementiert sein. Diese in der Klasse AbstractFormControl definierte Methode hat folgende Signatur:

PHP-Code
public function addValidator(AbstractFormValidator &$validator){ if($validator->isActive()){ if(!$validator->validate($this->getAttribute('value'))){ $validator->notify(); } } }

Wie im Code-Snippet zu sehen ist, nimmt die Methode eine Instanz eines Validators entgegen, führt diesen - falls als aktiv gekennzeichnet - aus und involviert die notify()-Methode bei nicht erfolgreicher Validierung.

Wie ebenfalls zu erkennen ist, wird dem Validator by default das Tag-Attribut value übergeben, was nur für Text-Felder gültig ist. Aus diesem Grund überschreiben Nicht-Text-Felder diese Methode und übergeben dem Validator den relevanten Inhalt.

4.3. Implementierung von Validatoren

Wie bereits im letzten Kapitel angesprochen, muss ein Validator von der Klasse AbstractFormValidator erben. Das APF enthält daneben noch einige weitere Basis-Klassen, die für die Implementierung von Validatoren verwendet werden können. Diese sind:

  • TextFieldValidator: Basis für alle Text-Feld Validatoren
  • SelectFieldValidator: Basis für alle Select-Feld Validatoren

Diese sehen bereits vor, welche Änderungen am Formular-Element im Fehlerfall vorgenommen werden und welche Listener zu benachrichtigen sind.

Für die Implementierung eines eigenen Validators muss folgendes beachtet werden:

  • Der Validator muss von von der Klasse AbstractFormValidator erben.
  • Mit Hilfe der Methode markAsInvalid() kann ein Formular-Element als invalide gekennzeichnet werden.
  • Mit Hilfe der Methode notifyValidationListeners() können die Listener eines übergebenen Elements benachrichtigt werden.
  • Über den Button (Methode: isSent())kann der Entwickler abfragen, ob das Formular mit Klick auf diesen abgesendet wurde.

5. Filter

In den bisherigen Versionen des APF wurde die Filterung von Formular-Element-Werten ebenfalls direkt mit einem Formular-Element verknüpft und im Lifecycle einer Taglib ausgeführt. Hieraus ergeben sich ähnliche Nachteile wie es bei der Validierung der Fall ist. Deshalb wurde auch die Filterung in der Version 1.11 nach dem Konzept der Validierung angepasst. Ab Version 1.11 können Filter gleichermaßen als Observer auf ein Formular-Element angewendet werden.

Die Filterung von Formular-Felder wird vor der Validierung ausgeführt um zu verhindern, dass Eingaben, die durch einen Filter entfernt werden, eine positive Validierung erzeugen. Dies ist insbesondere beim TextLengthValidator relevant.

Die Definition der Filterung eines Formular-Feldes gestaltet sich dabei wie folgt:

APF-Template
<form:addfilter class="" button="" control="" />
Beschreibung der Attribute:
  • class: Der voll-qualifizierte Klassen-Name der Filter-Implementierung. (Zeichen: [A-Za-z0-9_\])
  • button: Name des Buttons, der die Filterung auslösen soll. Die Filterung ist immer an das Event isSent eines Buttons oder Image-Buttons gebunden. (Zeichen: [A-Za-z0-9-_])
  • control: Name des Formular-Controls auf das die Filterung Anwendung finden soll. Sollen mehrere Controls mit der im Tag definierten Filterung belegt werden, so enthält das Attribut alle mit Pipe getrennte Feld-Namen (z.B. sender|recipient|subject). (Zeichen: [A-Za-z0-9-_|])
Bitte beachten Sie, dass die Filterung von Werten lediglich innerhalb der Formular-Elemente greift. Die Werte in den Superglobals $_GET, $_POST und $_REQUEST bleiben davon unberührt. Es empfiehlt sich daher dringend, Inhalte direkt aus den Formular-Komponenten zu beziehen.

5.1. Verfügbare Filter

Wie auch in den Releases vor Version 1.11 werden eine Reihe von Filter mitgeliefert. Diese decken üblicherweise den Großteil der Anforderungen ab. Sollten diese nicht genügen, können eigene Filter implementiert werden. Dies ist im nächsten Kapitel beschrieben.

Ab Version 1.14 lassen sich die regulären Ausdrücke zahlreicher Filter über das Tag-Attribut filter-expr des zu filternden Formular-Elements steuern. Dies hilft beispielsweise Zeichensatz-Probleme wie im Forum diskutiert vermeiden.

Folgende Filter unterstützen das Überschreiben des Filter-Ausdrucks:

  • SpecialCharacterFilter
  • OnlyNumbersFilter
  • OnlyLettersFilter
  • OnlyIntegersFilter
  • NoSpecialCharactersFilter
  • EMailFilter

Darüber hinaus verwenden Zeichensatz-sensitive Funktions-Aufrufe der Filter nun den per Registry global konfigurierten Zeichensatz.

Aktuell sind folgende Filter im Release verfügbar:

5.1.1. EMailFilter

Der EMailFilter entfernt alle Zeichen, die für eine E-Mail-Adresse nicht relevant sind.

APF-Template
<html:form name="..."> <form:text name="email" /> <form:button name="send" value="Send"/> <form:addfilter class="APF\tools\form\filter\EMailFilter" button="send" control="email" /> </html:form>
5.1.2. NoSpecialCharactersFilter

Der NoSpecialCharactersFilter filtert alle Zeichen, die nicht dem regulären Ausdruck [^0-9A-Za-z-_\.& ] genügen.

APF-Template
<html:form name="..."> <form:text name="simplechars" /> <form:button name="send" value="Send"/> <form:addfilter class="APF\tools\form\filter\NoSpecialCharactersFilter" button="send" control="simplechars" /> </html:form>
5.1.3. OnlyHTMLEntitiesFilter

Mit dem OnlyHTMLEntitiesFilter kann erreicht werden, dass Sonderzeichen in ihre HTML Entity Entsprechungen umgewandelt werden. Hierbei muss jedoch beachtet werden, dass bei mehrmaligem Abschicken, Mehrfach-Codierungen möglich sind.

APF-Template
<html:form name="..."> <form:text name="htmlentitiestext" /> <form:button name="send" value="Send"/> <form:addfilter class="APF\tools\form\filter\OnlyHTMLEntitiesFilter" button="send" control="htmlentitiestext" /> </html:form>
5.1.4. OnlyIntegersFilter

Der OnlyIntegersFilter lässt nur Ziffern zu und filtert alle anderen Zeichen.

APF-Template
<html:form name="..."> <form:text name="zipcode" /> <form:button name="send" value="Send"/> <form:addfilter class="APF\tools\form\filter\OnlyIntegersFilter" button="send" control="zipcode" /> </html:form>
5.1.5. OnlyLettersFilter

Mit dem OnlyLettersFilter werden nur Standard-Zeichen des Alphabets zugelassen.

APF-Template
<html:form name="..."> <form:text name="productcode" /> <form:button name="send" value="Send"/> <form:addfilter class="APF\tools\form\filter\OnlyLettersFilter" button="send" control="productcode" /> </html:form>
5.1.6. OnlyNumbersFilter

Der OnlyNumbersFilter lässt nur Ziffern und Interpunktionen zu, die für die Trennung von 1000er Blöcken und Nachkommastellen notwendig sind.

APF-Template
<html:form name="..."> <form:text name="productprice" /> <form:button name="send" value="Send"/> <form:addfilter class="APF\tools\form\filter\OnlyNumbersFilter" button="send" control="productprice" /> </html:form>
5.1.7. SpecialCharacterFilter

Mit dem SpecialCharacterFilter werden nur Zeichen zugelassen, die im normalen Satzbau notwendig sind.

APF-Template
<html:form name="..."> <form:area name="simpletext" /> <form:button name="send" value="Send"/> <form:addfilter class="APF\tools\form\filter\SpecialCharacterFilter" button="send" control="simpletext" /> </html:form>
5.1.8. String2LowerFilter

Der String2LowerFilter wandelt alle Buchstaben in Klein-Buchstaben um.

APF-Template
<html:form name="..."> <form:area name="lowertext" /> <form:button name="send" value="Send"/> <form:addfilter class="APF\tools\form\filter\String2LowerFilter" button="send" control="lowertext" /> </html:form>
5.1.9. String2UpperFilter

Der String2UpperFilter wandelt alle Buchstaben in Groß-Buchstaben um.

APF-Template
<html:form name="..."> <form:area name="uppertext" /> <form:button name="send" value="Send"/> <form:addfilter class="APF\tools\form\filter\String2LowerFilter" button="send" control="uppertext" /> </html:form>
5.1.10. StripTagsFilter

Mit dem StripTagsFilter werden alle HTML- und PHP-Code-Fragmente aus dem Text entfernt. Dieser eignet sich gut für Felder, in denen viel Freitext eingegeben werden kann.

APF-Template
<html:form name="..."> <form:area name="notagstext" /> <form:button name="send" value="Send"/> <form:addfilter class="APF\tools\form\filter\StripTagsFilter" button="send" control="notagstext" /> </html:form>
5.1.11. FloatFilter

Der FloatFilter kann dazu genutzt werden, um Inhalte eines Text-Feldes in eine Fließkomma-Zahl umzuwandeln.

Dieser Filter ist vor Allem dann interessant, wenn Text-Felder zur Eingabe von Fließkomma-Zahlen angeboten werden. Damit entfällt bei der Verarbeitung die Konvertierung und erleichtert die Validierung.
APF-Template
<html:form name="..."> <form:area name="length" /> <form:button name="send" value="Send"/> <form:addfilter class="APF\tools\form\filter\FloatFilter" button="send" control="length" /> </html:form>

5.2. Aufbau von Filtern

Formular-Filter sind eine Spezialisierung der APF-Filter-API. Als Interface steht die abstrakte Klasse AbstractFormFilter zur Verfügung, die alle konkreten Formular-Filter implementieren müssen.

Ähnlich den im Kapitel 4.2 beschrieben Formular-Validatoren, müssen Formular-Validatoren einige Formular-spezifische Methoden implementieren. Die Klasse AbstractFormFilter hat folgenden Aufbau:

PHP-Code
abstract class AbstractFormFilter extends AbstractFilter { protected $control; protected $button; public function __construct(AbstractFormControl &$control, AbstractFormControl &$button){ $this->control = &$control; $this->button = &$button; } public function isActive(){ return $this->button->isSent(); } }

Über den Konstruktor werden das zu filternde Form-Control und der Button, der als Trigger fungiert injiziert. Die Methode filter() wird vom Formular-Element mit dem zu filternden Inhalt versorgt und muss den Filter-Code enthalten. Als Rückgabe wird der gefilterte Wert erwartet.

Die Methode isActive() dienen dazu, dem Filter zu fragen, ob er ausgeführt werden darf.

Die Klassen-Variablen $control und $button enthalten jeweils die Instanz des zu validieren Formular-Elements und den Button, der als Trigger verwendet wird.

Voraussetzung für die Funktion von Filtern ist, dass ein Formular-Element dies unterstützt. Hierzu muss in jedem Formular-Control die Methode addFilter() implementiert sein. Diese in der Klasse AbstractFormControl definierte Methode hat folgende Signatur:

PHP-Code
public function addFilter(AbstractFormFilter &$filter){ if($filter->isActive()){ $value = $this->getAttribute('value'); $filteredValue = $filter->filter($value); $this->setAttribute('value',$filteredValue); } }

Wie im Code-Snippet zu sehen ist, nimmt die Methode eine Instanz eines Filters entgegen, führt diesen - falls als aktiv gekennzeichnet - aus.

Wie ebenfalls zu erkennen ist, wird dem Filter by default das Tag-Attribut value übergeben, was nur für Text-Felder gültig ist. Aus diesem Grund überschreiben Nicht-Text-Felder diese Methode und übergeben dem Filter den relevanten Inhalt.

Filter finden üblicherweise nur bei Text-Feldern Anwendung. Für Felder mit komplexeren Datenstrukturen kann es Sinn machen einen Filter zu schreiben, im Fall der Select-Felder ist es jedoch für die Sicherheit nicht von Bedeutung. Aus diesem Grund liefert das APF für Select-Felder keine Filter mit.

5.3. Implementierung von Filtern

Wie bereits im letzten Kapitel angesprochen, muss ein Filter von der Klasse AbstractFormFilter erben.

Für die Implementierung eines eigenen Filters muss folgendes beachtet werden:

  • Der Filter muss von von der Klasse AbstractFormFilter erben.
  • Über den Button (Methode: isSent()) kann der Entwickler abfragen, ob das Formular mit Klick auf diesen abgesendet wurde.
  • Die Methode isActive() kann üblicherweise von AbstractFormFilter übernommen werden.
Auf Grund der Besonderheit, dass mit PHP >=5.2.10, bzw. >=5.3.0 die Signaturen von überschriebenen abstrakten Methoden Zeichen-identisch sein müssen, muss darauf geachtet werden, dass die Funktion public function filter($input) in der Filter-Implementierung exakt so definiert wurde!

6. Verwendung von Formularen

Die Verwendung von Formularen und die Verarbeitung mit Hilfe von Document Controllern ist im Kapitel Verwendung von Formularen näher beschrieben. Diese Seite soll lediglich als Referenz für die vorhandenen Taglibs und die Implementierung von Validatoren und Filtern dienen. Weiter wird auf die Erstellung von dynamischen Formularen eingegangen.

Kommentare

Möchten Sie den Artikel eine Anmerkung hinzufügen, oder haben Sie ergänzende Hinweise? Dann können Sie diese hier einfügen. Die bereits verfassten Anmerkungen und Kommentare finden Sie in der untenstehenden Liste.
« 1   »
Einträge/Seite: | 5 | 10 | 15 | 20 |
1
Christian 18.09.2011, 22:44:50
Hallo Werner,

\"key\" in ist nun auch gegen \"entry\" ersetzt. Danke für den Hinweis.
2
welworx 10.07.2011, 01:09:27
grad gesehn dass es bei listener:getstring auch noch einen key anstelle eines entry in der doku gibt
3
Christian 20.02.2011, 22:16:44
Hallo welworx,

korrekt, hier hat die Dokumentation einen Fehler. Selbiges galt auch für <success:getstring />, aber die beiden Fehler sind aber jetzt behoben.
4
welworx 27.01.2011, 02:45:28
die Zeile
<error:getstring namespace="" config="" key="" />
sollte
<error:getstring namespace="" config="" entry="" />
heißen