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.
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.
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
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>
[A-Za-z0-9-_]
)
[get|post]
)
Registry::register('APF\tools', 'FormDefaultMethod','...')
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>
[A-Za-z0-9-_]
)
Der Image-Button erzeugt einen Button, der als Beschriftung ein Bild nutzt. Die Funktion ist identisch zum einfachen Button.
<form:imagebutton name="" src="" />
[A-Za-z0-9-_]
)
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="" />
<form:hidden name="" value="" />
[A-Za-z0-9-_]
)
<form:text name="" [value=""] />
[A-Za-z0-9-_]
)
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>
[A-Za-z0-9-_]
)
<form:password name="" [value=""]/>
[A-Za-z0-9-_]
)
Das Dateiupload-Feld besitzt folgende Signatur:
<form:file name="" />
[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:
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.
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"] />
[A-Za-z0-9-_]
)
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"]/>
[A-Za-z0-9-_]
)
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>
[A-Za-z0-9-_]
)
[A-Za-z0-9-_]
)
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>
[A-Za-z0-9-_]
)
[A-Za-z0-9-_]
)
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"]
/>
[A-Za-z0-9-_]
)
1990-2007
bzw. 1990-now
um alle Jahre inkl. des aktuellen anzuzeigen.
(Zeichen: [0-9-], now
)
Tag;Monat;Jahr
.
(Zeichen: [A-Za-z;]
)
1;2;3
.
(Zeichen: [0-9;]
)
true|false
)
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="" />
[A-Za-z0-9_-]
)
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>
[A-Za-z0-9_-]
)
[A-Za-z0-9_-]
)
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])}
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>
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.
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>
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=""]
/>
[A-Za-z0-9_\]
)
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=""]
/>
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
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>
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.
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="" />
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=""]/>
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=""]/>
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=""]/>
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=""]/>
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=""]/>
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=""]/>
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=""]/>
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=""]/>
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=""]/>
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=""]/>
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=""]/>
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=...]
/>
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.
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.
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"]
/>
[A-Za-z0-9_\]
)
[A-Za-z0-9-_]
)
[A-Za-z0-9-_|]
)
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.
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:
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.
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>
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>
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>
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>
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>
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>
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>
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>
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>
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.
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>
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>
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>
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>
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>
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>
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.
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:
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:
Ä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=""
/>
[A-Za-z0-9_\]
)
[A-Za-z0-9-_]
)
[A-Za-z0-9-_|]
)
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:
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:
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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.
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:
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.
Um unsere Webseite für Sie optimal zu gestalten und fortlaufend verbessern zu können, verwenden wir Cookies. Durch die Nutzung der Webseite stimmen Sie der Verwendung von Cookies zu. Weitere Informationen finden Sie in den Datenschutzrichtlinien.