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 mitgelieferten 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.
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:
<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:
class SearchController extends BaseDocumentController {
public function transformContent(){
$form = $this->getForm('Search');
$form->transformOnPlace();
}
}Die Absende-Methode eines Formulars lässt sich über das Attribut method bestimmen. Hier stehen die beiden Optionen post und get zur Verfügung. Als Standard wurde post definiert.
Im Fall eines POST werden alle Inhalte des Formulars in kodierter Form an die im Attribut action angegebene URL geschickt.
Das Verhalten für GET unterscheidet sich davon. Hier werden die Inhalte aller Felder des Formulars an die im Attribut action definierte URL angehängt und diese aufgerufen.
<html:form name="Search" action="/?page=search" method="get" submit-action-url-params="true">
<form:text name="searchterm" />
<form:button name="search" value="GO" />
</html:form>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.
Das Formular-Tag selbst besitzt drei funktionale Attribute, die zur Definition und Konfiguration dienen:
<html:form name="" [method=""] [action=""] [autocomplete="true|false"]>
...
[<html:placeholder name="" />]
[<html:getstring namespace="" config="" entry="" />]
[<core:addtaglib class="" prefix="" name="" />]
...
</html:form>-
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.
Registry::register('APF\tools', 'FormDefaultMethod','...')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.
<form:button name="" value="" />
<form:button name="">
<button:getstring
[name=""]
namespace=""
config=""
entry="" />
</form:button>-
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.
3.2. Image-Button
Der Image-Button erzeugt einen Button, der als Beschriftung ein Bild nutzt. Die Funktion ist identisch zum einfachen Button.
<form:imagebutton name="" src="" />-
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
Neben einem einfachen Button 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.
<form:reset name="" value="" />- value: Wert (Beschriftung) des Reset-Buttons.
3.4. Hidden-Feld
<form:hidden name="" value="" />-
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
<form:text name="" [value=""] />-
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.
<form:area name="" />
<form:area name="">...</form:area>-
name: Name des Textarea. Über den Namen kann auf das Element zugegriffen
werden. (Zeichen:
[A-Za-z0-9-_])
3.7. Passwort-Feld
<form:password name="" [value=""]/>-
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:
<form:file name="" />-
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:
<@controller
namespace="VENDOR\..\controller\FileUploadController"
@>
<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"/>
</p>
<p>
<form:button name="send" value="GO" />
<form:addvalidator
class="MimeTypeValidator"
control="image"
button="send"
/>
<form:addvalidator
class="FileSizeValidator"
control="image"
button="send"
/>
</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:
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.
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.
<form:checkbox name="" value="" [checked="checked"] />-
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.
<form:radio name="" value="" [checked="checked"]/>-
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.
Darüber hinaus können auch Options-Gruppen genutzt werden.
<form:select name="" />
<form:select name="">
<select:option value="" [selected="selected"]>...</select:option>
[<select:group label="">
<select:option value="" [selected="selected"]>...</select:option>
</select:group>]
</form:select>-
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.
<form:multiselect name="" />
<form:multiselect name="">
<select:option value="" [selected="selected"]></select:option>
[<select:group label="">
<select:option value="" [selected="selected"]>...</select:option>
<select:group>]
</form:multiselect>-
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.
3.13. 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.
<form:date
name=""
[yearrange=""]
[offsetnames=""]
[tab-indexes=""]
[prepend-empty-options="true|false"]
/>-
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-2007bzw.1990-nowum alle Jahre inkl. des aktuellen anzuzeigen. (Zeichen:[0-9-], now) -
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.14. 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.
<form:marker name="" />-
name: Name des Markers. Dieser dient zur Adressierung desselben.
(Zeichen:
[A-Za-z0-9_-])
3.15. 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.
<form:listener [name=""] control="..." [validator="..." ]>
...
[<html:getstring namespace="" config="" entry="" />]
[<html:placeholder name="" />]
[<core:addtaglib class="" prefix="" name=""/>]
...
</form:listener>-
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.
Details zum Platzhalter-Tag können Sie unter <html:placeholder /> nachlesen, die Ausgabe von Sprachabhängigen Werten lässt sich über den <html:getstring />-Tag realisieren.
Sollte die vorhandene Funktionalität nicht ausreichen, lassen sich eigene Tags sehr einfach per <core:addtaglib /> hinzufügen.
Zur Befüllung eines Platzhalters in einem Document-Controller kann folgender Code verwendet werden:
Template:<html:form name="name_form" method="post">
<form:listener name="name-listener" control="name">
Please fill in the <html:placeholder name="field-name" /> field!
</form:listener>
<form:text name="name" />
<form:button name="send" value="Send" />
<form:addvalidator
class="APF\tools\form\validator\TextLengthValidator"
control="name"
button="send"
/>
</html:form>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:
<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:button name="send" value="Send" />
<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"
/>
</html:form><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:button name="send" value="Send" />
<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"
/>
</html:form>${validationMarker(control name[, content])}3.16. 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.
<form:error [name=""]>
...
[<html:getstring namespace="" config="" entry="" />]
[<html:placeholder name="" />]
[<core:addtaglib class="" prefix="" name="" />]
[<form:listener control="" [name=""] [validator=""]/>]
...
</form:error>Details zum Platzhalter-Tag können Sie unter <html:placeholder /> nachlesen, die Ausgabe von Sprachabhängigen Werten lässt sich über den <html:getstring />-Tag realisieren.
Sollte die vorhandene Funktionalität nicht ausreichen, lassen sich eigene Tags sehr einfach per <core:addtaglib /> hinzufügen.
<form:error>
<p>
Ihre Eingaben enthalten Fehler! Bitte korrigieren Sie folgende Felder:
</p>
<ul>
<form:listener control="first-name">
<li>Vorname</li>
</form:listener>
<form:listener control="last-name">
<li>Nachname</li>
</form:listener>
</ul>
</form:error>3.17. 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 [name=""]>
...
[<html:getstring namespace="" config="" entry="" />]
[<html:placeholder name="" />]
[<core:addtaglib class="" prefix="" name="" />]
...
</form:success>Details zum Platzhalter-Tag können Sie unter <html:placeholder /> nachlesen, die Ausgabe von Sprachabhängigen Werten lässt sich über den <html:getstring />-Tag realisieren.
Sollte die vorhandene Funktionalität nicht ausreichen, lassen sich eigene Tags sehr einfach per <core:addtaglib /> hinzufügen.
3.18. 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.
<html:form name="...">
<form:timecaptcha name="timecaptcha" [seconds="3"]/>
...
</html:form>3.19. 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.
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:
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.
<form:csrfhash
salt=""
name=""
[class=""]
/>- 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.20. 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:
<form:time
name=""
[hoursrange=""]
[offsetnames=""]
[showseconds="true|false"]
[minutesinterval=""]
/>- 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.21. MultiFileUpload
Neben dem einfachen Datei-Upload gibt es ein weitere nützliches Tool: den MultiFileUpload. Alle wichtigen Informationen diesbezüglich entnehmen Sie bitte dem Wiki-Beitrag: MultiFileUpload im Wiki
3.22. Label
Beschriftung eines Formular-Elements können ebenso als APF-Tag definiert werden.
Der Label-Tag hat folgende Signatur:
<form:label for="">
[...]
[<label:getstring [name=""] namespace="" config="" entry="" />]
</form:label>- 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.
3.23. Group
Mit Hilfe des <form:group />-Tags lassen sich alle im Kapitel 3 aufgeführten Formular-Elemente gruppieren. Dies kann Ihnen beispielsweise helfen, mehrere Formular-Elemente inklusive des zugehörigen Markup bei Bedarf ohne aufwändige Logik im Controller auszublenden.
Der Formular-Element-Gruppen-Tag besitzt folgende Signatur:
<form:group name="" [id=""] [hidden="true|false"]>
...
</form:group>Die Attribute name bzw. id können genutzt werden um eine Gruppe innerhalb eines Controllers zu beziehen. Der Tag selbst erzeugt keine eigene Ausgabe, er zeigt lediglich die darin befindlichen Fomular-Elemente und das HTML an.
Mit Hilfe des Attributs hidden lässt sich die Gruppe direkt im Template ausblenden. Dies ist hilfreich, wenn das Formular aus mehreren Gruppen besteht, die nur bei Bedarf eingeblendet werden sollen.
Die folgende Code-Box zeigt eine Checkbox sowie eine Gruppe mit einem Textfeld und dem zugehörigen Label:
<html:form name="group-example">
<form:checkbox name="hide-group" /> Gruppe ausblenden?
<form:group name="grouped-text">
<p>
<form:label>Vorname</form:label>
<form:text name="surname" />
</p>
</form:group>
<form:button name="send" value="Absenden" />
</html:form>Im nachfolgende gezeigten Controller lässt sich das Feld zur Eingabe des Vornamens sehr einfach über das Ausblenden der Gruppe realisieren:
class SignUpController extends BaseDocumentController {
public function transformContent() {
$form = $this->getForm('group-example');
$groupSwitch = $form->getFormElementByName('hide-group');
if ($groupSwitch->isChecked()) {
$form->getFormElementByName('grouped-text')->hide();
}
$form->transformOnPlace();
}
}Weitere Hinweise zur Verwendung von Formular-Element-Gruppen finden Sie unter Verwendung von Formularen.
3.24. Such-Einfabe-Feld
Der HTML5-Standard definiert einen speziellen Feldtypen für Such-Eingabe-Felder - das <input type="search" />-Feld. Nähere Informationen dazu finden Sie unter mozilla.org.
Der Formular-Element-Tag besitzt folgende Signatur:
<form:html5-search name="" />- name: Name des Eingabe-Feldes. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
- minlength
- maxlength
- pattern
- required
3.25. Range-Feld
Der HTML5-Standard definiert einen speziellen Feldtypen für die grafische Auswahl von Werten in einem Bereich - das <input type="range" />-Feld. Nähere Informationen dazu finden Sie unter mozilla.org.
Der Formular-Element-Tag besitzt folgende Signatur:
<form:html5-range name="" min="" max="" [value=""] [step=""]/>- name: Name des Eingabe-Feldes. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
- min: Das untere Ende des Werte-Bereiches.
- max: Das obere Ende des Werte-Bereiches.
- value: Der initiale Wert der Eingabe-Komponente. (Zeichen: [0-9])
- step: Die Schrittgröße mit der der Wert über den Schiebe-Regler verändert werden kann.
- required
3.26. Datum-Auswahl
Der HTML5-Standard definiert einen speziellen Feldtypen für die Datums-Auswahl - das <input type="date" />-Feld. Nähere Informationen dazu finden Sie unter mozilla.org.
Der Formular-Element-Tag besitzt folgende Signatur:
<form:html5-date name="" [value=""]/>- name: Name des Eingabe-Feldes. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
- value: Der initiale Wert der Eingabe-Komponente. (Format: YYYY-MM-DD)
- min
- max
- required
3.27. Datum- und Uhrzeit-Auswahl
Der HTML5-Standard definiert einen speziellen Feldtypen für die gleichzeitige Datums- und Uhrzeit-Auswahl - das <input type="datetime-local" />-Feld. Nähere Informationen dazu finden Sie unter mozilla.org.
Der Formular-Element-Tag besitzt folgende Signatur:
<form:html5-date-time name="" [value=""]/>- name: Name des Eingabe-Feldes. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
- value: Der initiale Wert der Eingabe-Komponente. (Format: YYYY-MM-DDTHH:SS)
- min
- max
- required
3.28. Uhrzeit-Auswahl
Der HTML5-Standard definiert einen speziellen Feldtypen für die Uhrzeit-Auswahl - das <input type="time" />-Feld. Nähere Informationen dazu finden Sie unter mozilla.org.
Der Formular-Element-Tag besitzt folgende Signatur:
<form:html5-time name="" [value=""]/>- name: Name des Eingabe-Feldes. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
- value: Der initiale Wert der Eingabe-Komponente. (Format: HH:SS)
- min
- max
- required
3.29. Wochen-Auswahl
Der HTML5-Standard definiert einen speziellen Feldtypen für die Wochen-Auswahl - das <input type="week" />-Feld. Nähere Informationen dazu finden Sie unter mozilla.org.
Der Formular-Element-Tag besitzt folgende Signatur:
<form:html5-week name="" [value=""]/>- name: Name des Eingabe-Feldes. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
- value: Der initiale Wert der Eingabe-Komponente. (Format: YYYY-Www)
- min
- max
- required
3.30. Monats-Auswahl
Der HTML5-Standard definiert einen speziellen Feldtypen für die Monats-Auswahl - das <input type="month" />-Feld. Nähere Informationen dazu finden Sie unter mozilla.org.
Der Formular-Element-Tag besitzt folgende Signatur:
<form:html5-month name="" [value=""]/>- name: Name des Eingabe-Feldes. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
- value: Der initiale Wert der Eingabe-Komponente. (Format: YYYY-MM)
- min
- max
- required
3.31. Farb-Auswahl
Der HTML5-Standard definiert einen speziellen Feldtypen für die Farb-Auswahl - das <input type="color" />-Feld. Nähere Informationen dazu finden Sie unter mozilla.org.
Der Formular-Element-Tag besitzt folgende Signatur:
<form:html5-color name="" [value=""]/>- name: Name des Eingabe-Feldes. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
- value: Der initiale Wert der Eingabe-Komponente. (Format: #rrggbb)
- required
3.32. Zahlen-Auswahl
Der HTML5-Standard definiert einen speziellen Feldtypen für die Zahlen-Auswahl - das <input type="number" />-Feld. Nähere Informationen dazu finden Sie unter mozilla.org.
Der Formular-Element-Tag besitzt folgende Signatur:
<form:html5-number name="" [value=""]/>- name: Name des Eingabe-Feldes. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
- value: Der initiale Wert der Eingabe-Komponente. (Format: [0-9]+)
- required
- min
- max
3.33. Telefon-Nummer
Der HTML5-Standard definiert einen speziellen Feldtypen für die Telefon-Nummern-Eingabe - das <input type="tel" />-Feld. Nähere Informationen dazu finden Sie unter mozilla.org.
Der Formular-Element-Tag besitzt folgende Signatur:
<form:html5-tel name="" [value=""]/>- name: Name des Eingabe-Feldes. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
- value: Der initiale Wert der Eingabe-Komponente. (Format: [0-9+\- ]+)
- required
- minlength
- maxlength
- pattern
3.34. E-Mail
Der HTML5-Standard definiert einen speziellen Feldtypen für die Eingabe einer E-Mail-Adresse - das <input type="email" />-Feld. Nähere Informationen dazu finden Sie unter mozilla.org.
Der Formular-Element-Tag besitzt folgende Signatur:
<form:html5-email name="" [value=""]/>- name: Name des Eingabe-Feldes. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
- value: Der initiale Wert der Eingabe-Komponente. (Format: /^[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/)
- required
- minlength
- maxlength
- pattern
3.35. Url
Der HTML5-Standard definiert einen speziellen Feldtypen für die Eingabe einer URL - das <input type="url" />-Feld. Nähere Informationen dazu finden Sie unter mozilla.org.
Der Formular-Element-Tag besitzt folgende Signatur:
<form:html5-url name="" [value=""]/>- name: Name des Eingabe-Feldes. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
- value: Der initiale Wert der Eingabe-Komponente. (Format: siehe RFC-3986)
- required
- minlength
- maxlength
- pattern
3.36. Formular-Block
Der <form:block/>-Tag erlaubt die Definition von wiederverwendbaren Blöcken - bestehend aus beliebigem HTML-Markup und APF-Tags -, die sich innerhalb eines Formulars oder einer Applikation wiederholen. Durch die Definition eines Block-Templates lassen sich mehrfach verwendete Strukturen elegant auslagern und bei Bedarf zentral anpassen.
Inbesondere bei der Verwendung von Frontend-Frameworks wie z.B. Twitter Bootstrap hilft die Definition von Formular-Blöcken boilerplate-Code zu vermeiden und Formular-Felder inklusive umschließendem HTML-Markup zentral zu definieren.
Ein Formular-Block wird duch ein APF-Template repräsentiert, das beliebiges HTML-Markup und die gewünschten Formular-Elemente beinhaltet. Um einen Block mehrfach und mit unterschiedlicher Konfiguration einsetzen zu können, lassen sich innerhalb des Templates dynamische Platzhalter definieren. Diese werden zur Laufzeit mit den gewünschten Werten ersetzt werden.
Der Formular-Block-Tag besitzt folgende Signatur:
<form:block
namespace="..."
template="..."
[block-abc=...
block-xyz=...]
/>- namespace: Ein mit "\" getrennter Namespace-Pfad. (Zeichen: [A-Za-z0-9_\])
- template: Name eines Templates. (Zeichen: [A-Za-z0-9-_])
- block-*: dynamische Platzhalter zur Konfiguration des Formular-Blocks. (Zeichen: [A-Za-z0-9-_])
3.36.1. Template-Definition
Der folgende Formular-Block definiert ein Text-Feld inkl. zugehörigem Label und einem <form:listener />-Tag zur Ausgabe von Feld-basierten Fehlermeldungen:
<div class="...">
<form:label name="${name}-label" for="${name}" class="...">${label}</form:label>
<div class="...">
<form:text name="${name}" id="${name}" class="..."/>
<form:listener name="${name}-listener" control="${name}">
<span class="...">${listener}</span>
</form:listener>
</div>
</div>Die Platzhalter ${name}, ${label} und ${listener} dienen der dynamischen Konfiguration der jeweils definierten Formular-Felder für den jeweiligen Anwendungsfall.
3.36.2. Formular-Definition
Der in Kapitel 3.36.1 definierte Formular-Block lässt sich wie folgt zur Abfrage der postalischen Adresse in einem Anmelde-Formular einsetzen:
<html:form name="sign-up">
<h2>Anmeldung</h2>
...
<form:block
namespace="VENDOR\path\to\signup\templates"
template="form-block-1"
block-name="street"
block-label="Straße"
block-listener="Bitte geben Sie eine Straße ein!"
/>
<form:block
namespace="VENDOR\path\to\signup\templates"
template="form-block-1"
block-name="number"
block-label="Hausnummer"
block-listener="Bitte geben Sie eine Hausnummer ein!"
/>
<form:block
namespace="VENDOR\path\to\signup\templates"
template="form-block-1"
block-name="zip"
block-label="PLZ"
block-listener="Bitte geben Sie eine Postleitzahl ein!"
/>
<form:block
namespace="VENDOR\path\to\signup\templates"
template="form-block-1"
block-name="city"
block-label="Stadt"
block-listener="Bitte geben Sie eine Stadt ein!"
/>
<form:button name="send" value="Anmelden"/>
<form:addvalidator
class="APF\tools\form\validator\TextLengthValidator"
control="street|number|zip|city"
button="send"
/>
...
</html:form>Im Attribut namespace des <form:block />-Tags wird der Namespace bzw. der Pfad angegeben, unter dem das Block-Template zu finden ist. Die Definition erfolgt analog zum <core:importdesign />-Tag.
Das Attribut template definiert - ebenfalls analog zum <core:importdesign />-Tag - den Namen des APF-Templates, in dem der wiederverwendbare Formular-Block definiert ist (siehe Kapitel 3.36.1).
Die mit dem Präxix block- beginnenden Attribute dienen der dynamischen Konfiguration eines Blocks. Sie stehen innerhalb des Block-Templates als dynamische Platzhalter zur Verfügung. Mit dem Tag-Attribut block-name definieren Sie beispielsweise den Platzhalter ${name} innerhalb des Block-Templates. Pro <form:block />-Tag lassen sich eine beliebige Anzahl solcher Platzhalter definieren.
Im obigen Code-Block werden die Platzhalter ${name}, ${label} und ${listener} definiert um die dynamische Beschriftung der Felder sowie der Labels zu gewährleisten und einen Hinweistext bei Fehleingabe anzuzeigen.
Aus der Tag-Definition
<form:block
namespace="VENDOR\path\to\signup\templates"
template="form-block-1"
block-name="street"
block-label="Straße"
block-listener="Bitte geben Sie eine Straße ein!"
/>wird zur Laufzeit der folgende APF-Template-Code generiert und geladen:
<div class="...">
<form:label name="street-label" for="street" class="...">Straße</form:label>
<div class="...">
<form:text name="street" id="street" class="..."/>
<form:listener name="street-listener" control="street">
<span class="...">Bitte geben Sie eine Straße ein!</span>
</form:listener>
</div>
</div>Die dynamisch generierten Felder - z.B. das Text-Feld street - stehen wie statisch definierte Felder in Formular und Controller zur Verfügung.
4. Validierung
Validatoren werden ü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:
<form:addvalidator
class=""
button=""
control=""
[type="special"]
/>-
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)
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:
<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:
.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.
<html:form name="...">
<form:text name="age" optional="true"/>
<form:button name="send" value="Send" />
<form:addvalidator
class="APF\tools\form\validator\IntegerValidator"
button="send"
control="age"
/>
</html:form>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:
<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.
Es ist ebenso 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.
<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.
<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.
<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.
<html:form name="...">
<form:password name="pass" ref="pass2" />
<form:password name="pass2" />
<form:button name="login" value="login" />
<form:addvalidator
class="APF\tools\form\validator\FieldCompareValidator"
control="pass"
button="login"
/>
</html:form>4.1.6. SimpleBirthdayValidator
Der SimpleBirthdayValidator prüft ein Text-Feld auf ein korrektes Datum der Form dd.MM.YYYY.
<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.
<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.
<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.
<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.
<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).
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:
<html:form name="upload" method="post">
<fieldset>
<label for="pdf">PDF file:</label>
<form:file name="pdf" id="pdf" accepts="pdf|application/pdf" />
<form:button name="send" value="GO" />
<form:addvalidator
class="APF\tools\form\validator\MimeTypeValidator"
control="pdf"
button="send"
/>
</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:
<html:form name="upload" method="post">
<fieldset>
<label for="image">Image:</label>
<form:file name="image" id="image" minsize="20480" maxsize="512000" />
<form:button name="send" value="GO" />
<form:addvalidator
class="APF\tools\form\validator\FileSizeValidator"
control="image"
button="send"
/>
</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.
<html:form name="upload" method="post">
<fieldset>
...
<form:checkbox name="agb" value="agb" /> Akzeptiere die AGBs.
<form:button name="send" value="GO" />
<form:addvalidator
class="APF\tools\form\validator\CheckboxValidator"
button="send"
control="agb"
/>
</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.
<html:form name="...">
<form:timecaptcha name="timecaptcha"/>
<form:button name="send" value="Send"/<
<form:addvalidator
class="APF\tools\form\validator\TimeCaptchaValidator"
button="send"
control="timecaptcha"
/>
</html:form>4.1.15. IntegerValidator
Der IntegerValidator validiert, ob die Eingabe einen validen Integer-Wert enthält:
<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.
<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.
<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 FormValidator implementieren oder von AbstractFormValidator erben. Die Implementierung des Interface ist notwendig, damit diese als Observer an alle Formular-Elemente geheftet werden können.
Das Interface eines Validators hat folgende gestalt:
interface FormValidator extends ApplicationContext {
public function __construct(FormControl $control, FormControl $button, $type = null);
public function validate($input);
public function notify();
public function isActive();
}Ü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:
public function addValidator(FormValidator $validator) {
$this->validators[] = $validator;
}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 das Interface FormValidator implementieren oder von 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 das Interface FormValidator implementieren oder von 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
Ähnlich der Struktur der Validatoren werden auch Filter als Observer auf ein Formular-Element angewendet.
Die Definition der Filterung eines Formular-Feldes gestaltet sich dabei wie folgt:
<form:addfilter
class=""
button=""
control=""
/>-
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-_|])
5.1. Verfügbare Filter
Das APF liefert 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.
Regulären Ausdrücke zahlreicher Filter lassen sich ü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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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. Das Interface FormFilter definiert das Aussehen eines Filters und AbstractFormFilter stellt eine Basis-Implementierung zur Verfügung.
Ähnlich den im Kapitel 4.2 beschrieben Formular-Validatoren, müssen Formular-Validatoren einige Formular-spezifische Methoden implementieren. Das Interface FormFilter hat folgenden Aufbau:
interface FormFilter extends Filter, ApplicationContext {
public function __construct(FormControl $control, FormControl $button);
public function isActive();
}Über den Konstruktor werden das zu filternde Form-Control und der Button, der als Trigger fungiert injiziert. Die Methode filter() (aus dem Interface 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:
public function addFilter(FormFilter $filter) {
$this->filters[] = $filter;
if ($filter->isActive()) {
$value = $this->getValue();
$filteredValue = $filter->filter($value);
$this->setValue($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.
5.3. Implementierung von Filtern
Wie bereits im letzten Kapitel angesprochen, muss ein Filter das Interface FormFilter implementieren oder von AbstractFormFilter erben.
Für die Implementierung eines eigenen Filters muss folgendes beachtet werden:
- Der Filter muss Interface FormFilter implementieren oder von 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.
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
QUICKNAVI
Die Entwicklung des APF wird von JetBrains mit PHPStorm-Lizenzen unterstützt und wir sind überzeugt davon, dass PHPStorm die Qualität nachhaltig steigert. Benutzen auch Sie PHPStorm!
