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.

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

2. Aufbau von Formularen

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

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

APF-Template

<html:form name="Search">
   <form:text name="searchterm" /> <form:button name="search" value="GO" />
</html:form>

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

Zur Anzeige des Formulars ist folgender Code im Controller erforderlich:

PHP-Code

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

Die 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.

Bitte beachten Sie, dass gemäß HTML5-Spezifikation alle URL-Parameter der im Attribut action definierte URL bei einer Übermittlung per GET verworfen werden. Um diese zu erhalten, setzen Sie bitte das Attribut submit-action-url-params auf den Wert true:

APF-Template

<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>

Mit der beschriebenen Vorgehensweise stellen Sie sicher, dass der URL-Parameter page bei der Anfrage mit übertragen wird.

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

3. Mitgelieferte Tags

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

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

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

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

Ein weiteres generische Attribute ist optional, das zur Kennzeichnung von optionalen Feldern hinsichtlich der Validierung genutzt wird. Details können im Kapitel Verfügbare Validatoren nachgelesen werden.

Attribute, die mit "[" und "]" geklammert dargestellt sind, haben optionalen Charakter, die übrigen müssen verpflichtend angegeben werden.

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

APF-Template

<html:form name="" [method=""] [action=""] [autocomplete="true|false"]>
   ...
   [<html:placeholder name="" />]
   [<html:getstring namespace="" config="" entry="" />]
   [<core:addtaglib class="" prefix="" name="" />]
   ...
</html:form>

Beschreibung der Attribute:

name: Name des Formulars. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
method: Versand-Methode des Formulars. Standardmäßig wird post verwendet. (Zeichen: [get|post])
action: URL, die bei Klick auf den Button aufgerufen werden soll.
autocomplete: Ist der Wert auf true gesetzt, wird dem Browser gestattet die Inhalte des Formulars für ein erneutes Ausfüllen zu speichern. Diese Funktion wird mit false verhindert. Letzteres wird insbesondere für Login-Formulare empfohlen.

Es ist möglich, einen globalen Standard-Wert für das Attribut action über die Registry zu definieren. Dies ist in der Bootstrap-Datei durch den Aufruf von

PHP-Code

Registry::register('APF\tools', 'FormDefaultMethod','...')

möglich. Damit erhalten alle Formulare - sofern das Attribut in der Tag-Definition nicht gesetzt ist - den dort definierten Standard-Wert. Sofern auch dieser nicht gesetzt ist, wird "post" verwendet.

Bitte beachten Sie, dass Text-Felder keine Array-Notation für Namen unterstützen (Beispiel: text[de]). Grund dafür ist, dass Text-Felder skalare Werte enthalten sollen. Dieser Vereinbarung gemäß lesen die Validatoren auch nur skalare Werte aus und können nicht mit Arrays umgehen.

3.1. Button

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

APF-Template

<form:button name="" value="" />

<form:button name="">
   <button:getstring
      [name=""]
      namespace=""
      config=""
      entry="" />
</form:button>

Beschreibung der Attribute:

name: Name des Buttons. Über den Namen kann auf das Element zugegriffen werden. Dies ist insbesondere für die Validatoren und Filter notwendig. (Zeichen: [A-Za-z0-9-_])
value: Wert des Buttons. Dieser dient der Beschriftung.

Zur Beschriftung des Buttons kann der <button:getstring />-Tag eingesetzt werden. Details zur Definition der Konfigurations-Dateien können der Definition des Tags <html:getstring /> entnommen werden.

3.2. Image-Button

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

APF-Template

<form:imagebutton name="" src="" />

Beschreibung der Attribute:

name: Name des Buttons. Über den Namen kann auf das Element zugegriffen werden. Dies ist insbesondere für die Validatoren und Filter notwendig. (Zeichen: [A-Za-z0-9-_])
src: Bild-Quelle des Buttons.

3.3. Reset-Button

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.

Mit einem Reset-Button ist keine Validierung bzw. Filterung möglich!

APF-Template

<form:reset name="" value="" />

Beschreibung der Attribute:

value: Wert (Beschriftung) des Reset-Buttons.

3.4. Hidden-Feld

APF-Template

<form:hidden name="" value="" />

Beschreibung der Attribute:

name: Name des Hidden-Felds. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
value: Wert des Hidden-Feldes.

3.5. Text-Feld

APF-Template

<form:text name="" [value=""] />

Beschreibung der Attribute:

name: Name des Text-Felds. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
value: Wert des Text-Feldes.

3.6. Textarea

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

APF-Template

<form:area name="" />
<form:area name="">...</form:area>

Beschreibung der Attribute:

name: Name des Textarea. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])

3.7. Passwort-Feld

APF-Template

<form:password name="" [value=""]/>

Beschreibung der Attribute:

name: Name des Passwort-Felds. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
value: Wert des Passwort-Feldes.

3.8. Dateiupload-Feld

Das Dateiupload-Feld besitzt folgende Signatur:

APF-Template

<form:file name="" />

Beschreibung der Attribute:

name: Name des Dateiupload-Felds. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])

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

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

Das folgende Formular zeigt Ihnen ein Anwendungsbeispiel des Tags:

APF-Template

<@controller
   namespace="VENDOR\..\controller\FileUploadController"
@>
<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:

PHP-Code

namespace VENDOR\..\controller;

use APF\core\pagecontroller\BaseDocumentController;
use APF\tools\filesystem\FilesystemManager;
use APF\tools\form\taglib\FileUploadTag;

class FileUploadController extends BaseDocumentController {

   public function transformContent() {

      $form = & $this->getForm('upload');

      if ($form->isSent() && $form->isValid()) {

         $name = & $form->getFormElementByName('name');

         /* @var $image FileUploadTag */
         $image = & $form->getFormElementByName('image');

         $file = $image->getFile();
         $fileName = $file->getName();
         $tmpFile = $file->getTemporaryName();
         FilesystemManager::copyFile($tmpFile, './upload/' . $fileName, true);

      } else {
         $form->transformOnPlace();
      }

   }

}

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

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

3.9. Checkbox

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

APF-Template

<form:checkbox name="" value="" [checked="checked"] />

Beschreibung der Attribute:

name: Name der Checkbox. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
value: Wert der Checkbox.
checked: Definiert, ob die Checkbox vorselektiert ist.

3.10. Radio-Button

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

APF-Template

<form:radio name="" value="" [checked="checked"]/>

Beschreibung der Attribute:

name: Name des Radio-Buttons. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
value: Wert des Radio-Buttons bzw. der aktuellen Option.
checked: Zeigt an, ob der Radio-Button vorselektiert ist.

3.11. Select-Feld

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

Darüber hinaus können auch Options-Gruppen genutzt werden.

APF-Template

<form:select name="" />

<form:select name="">
  <select:option value="" [selected="selected"]>...</select:option>
  [<select:group label="">
     <group:option value="" [selected="selected"]>...</group:option>
  </select:group>]
</form:select>

Beschreibung der Attribute:

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

3.12. Multiselect-Feld

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

APF-Template

<form:multiselect name="" />

<form:multiselect name="">
  <select:option value="" [selected="selected"]></select:option>
  [<select:group label="">
     <group:option value="" [selected="selected"]>...</group:option>
  <select:group>]
</form:multiselect>

Beschreibung der Attribute:

name: Name des Multiselect-Felds. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
value: Wert der Optionen. (Zeichen: [A-Za-z0-9-_])
selected: Soll eine Option vorausgewählt dargestellt werden, so muss das Attribut selected mit dem gleichnamigen Wert gefüllt sein.
label: Beinhaltet die Beschriftung einer Gruppe von Optionen.

Der Name des Formular-Feldes darf am Schluss kein "[]" enthalten, da es sonst zu Fehlern bei der Übertragung der Optionen kommt.

3.13. Datums-Control

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

APF-Template

<form:date
   name=""
   [yearrange=""]
   [offsetnames=""]
   [tab-indexes=""]
   [prepend-empty-options="true|false"]
/>

Beschreibung der Attribute:

name: Name des Datum-Controls. Über den Namen kann auf das Element zugegriffen werden. (Zeichen: [A-Za-z0-9-_])
yearrange: Range des Jahres-Feldes. Beispiel: 1990-2007 bzw. 1990-now um 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.

APF-Template

<form:marker name="" />

Beschreibung der Attribute:

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.

APF-Template

<form:listener [name=""] control="..." [validator="..." ]>
  ...
  [<html:getstring namespace="" config="" entry="" />]
  [<html:placeholder name="" />]
  [<core:addtaglib class="" prefix="" name=""/>]
  ...
</form:listener>

Beschreibung der Attribute:

control: Name des Formular-Elements auf dessen fehlgeschlagene Validierung der Inhalt angezeigt werden soll. (Zeichen: [A-Za-z0-9_-])
name: Name des Listeners. Dient zur Adressierung des Elements innerhalb des Formulars. (Zeichen: [A-Za-z0-9_-])
validator: Name des Validators, der den Listener bei fehlgeschlagener Validierung aktivieren darf.

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:

APF-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>

Controller:

PHP-Code

class FormController extends BaseDocumentController {
   public function transformContent(){
      $form = &$this->getForm('name-form');
      $listener = &$form->getFormElementByName('name-listener');
      $listener->setPlaceHolder('field-name', 'name');
   }
}

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

APF-Template

<html:form name="email_form" method="post">
   <form:listener control="email" validator="APF\tools\form\validator\TextLengthValidator">
      Please fill in the email field!
   </form:listener>
   <form:listener control="email" validator="APF\tools\form\validator\EMailValidator">
      Please fill in the email field with a correct email address!
   </form:listener>
   <form:text name="email" />
   <form: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>

Bitte beachten Sie, dass Validatoren, die für das Attribut type den Wert special enthalten nur spezielle Validator-Listener benachrichtigen. Sofern die oben ausgegebenen Validator-Meldungen noch mit einer Markierung versehen werden sollen, bietet sich an, einen EMailValidator zu definieren, deren Listener als Rahmen-gebende Elemente fungieren:

APF-Template

<html:form name="email_form" method="post">
   <form:listener control="email">
      <div class="error-container">
   </form:listener>
   <form:listener control="email" validator="APF\tools\form\validator\TextLengthValidator">
      Please fill in the email field!
   </form:listener>
   <form:listener control="email" validator="APF\tools\form\validator\EMailValidator">
      Please fill in the email field with a correct email address!
   </form:listener>
   <form:listener control="email">
      </div>
   </form:listener>
   <form:text name="email" />
   <form: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>

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.

APF-Template

<form:error [name=""]>
  ...
  [<html:getstring namespace="" config="" entry="" />]
  [<html:placeholder name="" />]
  [<core:addtaglib class="" prefix="" name="" />]
  ...
</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.

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 />-Tag stellt einen Inhalt dar, wenn alle Felder des Formulars als valide gekennzeichnet werden. Die Definition gestaltet sich wie folgt:

APF-Template

<form:success [name=""]>
  ...
  [<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.

APF-Template

<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.

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

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

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

PHP-Code

class EncryptedSIDHashProvider extends APFObject implements CSRFHashProvider {
   public function generateHash($salt) {
      if(!defined('SID')) {
         session_start();
      }

      return md5($salt.SID);
   }
}

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

APF-Template

<form:csrfhash
   salt=""
   name=""
   [class=""]
/>

Beschreibung der Attribute:

salt: Der Salt, der zur sicheren Berechnung des Hash eingesetzt wird.
name: Der Name des Feldes (Zeichen: [A-Za-z0-9_]).
class: Der voll-qualifizierte Klassen-Name der Provider-Implementierung. (Zeichen: [A-Za-z0-9_\])

3.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:

APF-Template

<form:time
   name=""
   [hoursrange=""]
   [offsetnames=""]
   [showseconds="true|false"]
   [minutesinterval=""]
/>

Beschreibung der Attribute:

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

3.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:

APF-Template

<form:label for="">
   [...]
   [<label:getstring [name=""] namespace="" config="" entry="" />]
</form:label>

Beschreibung der Attribute:

for: HTML-Id des Formular-Elements auf das sich die Beschriftung bezieht. (Zeichen: [A-Za-z0-9-_])
Inhalt: Der Inhalt des Tags kann entweder durch einen statischen Text oder mit Hilfe eines <label:getstring />-Tags definiert werden.

Details zur Definition der für den <button:getstring />-Tag notwendigen Konfigurations-Dateien können der Dokumentation des Tags <html:getstring /> entnommen werden.

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.

Eine Gruppe von Formular-Elementen kann weitere Gruppen enthalten. So lassen sich sehr einfach quasi-dynamische Formulare erstellen, die sich im Controller je nach Anwendungsfall steuern lassen.

Der Formular-Element-Gruppen-Tag besitzt folgende Signatur:

APF-Template

<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:

APF-Template

<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:

PHP-Code

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.

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:

APF-Template

<form:addvalidator
   class=""
   button=""
   control=""
   [type="special"]
/>

Beschreibung der Attribute:

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

Hinweise zu speziellen Validator-Listenern findet sich auch im Wiki-Artikel Spezielle Validator-Listener.

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

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

APF-Template

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

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

CSS-Code

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

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

4.1. Verfügbare Validatoren

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

Bitte beachten Sie, dass <form:addvalidator />-Tags im Template stets nach der zugehörigen <form:button />- bzw. <form:imagebutton />-Definition platziert ist. Dies ist erforderlich, damit der angegebene Validator den referenzierten Button auflösen kann.

Validatoren können auch als optional deklariert werden. Dazu muss das optional zu validierende Formular-Feld das Attribut optional mit dem Wert true besitzten:

APF-Template

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

Bitte beachten Sie, dass optionale Validatoren aktuell nur für Text-Felder implementiert sind, da Select- und Checkbox-Felder hinsichtlich ihrer Verwendung nach Meinung der APF-Entwickler keine optionale Validierung benötigen.

Der Großteil der verfügbaren Formular-Validatoren basiert auf den mit dem APF mitgelieferten Validatoren. Details hierzu finden Sie auf der Seite Validierung.

Aktuell sind folgende Validatoren im Release verfügbar:

4.1.1. TextLengthValidator

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

APF-Template

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

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

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.

APF-Template

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

4.1.3. EMailValidator

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

APF-Template

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

4.1.4. PhoneAndFaxValidator

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

APF-Template

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

4.1.5. FieldCompareValidator

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

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

APF-Template

<html:form name="...">
   <form:password name="pass" ref="pass2" />
   <form:password name="pass2" />
   <form: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.

Der Validator kann nur mit "normalen" Text-Feldern verwendet werden. Sofern ein Date-Control validiert werden soll, muss der SimpleDateControlValidator genutzt oder ein eigener Validator implementiert werden.

APF-Template

<html:form name="...">
   <form:text name="birthday" />
   <form:button name="send" value="Send"/>
   <form:addvalidator
      class="APF\tools\form\validator\SimpleBirthdayValidator"
      button="send"
      control="birthday"
   />
</html:form>

4.1.7. SimpleSelectControlValidator

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

APF-Template

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

4.1.8. MultiSelectFieldValidator

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

APF-Template

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

4.1.9. SimpleRadioControlValidator

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

APF-Template

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

4.1.10. SimpleDateControlValidator

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

APF-Template

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

4.1.11. MimeTypeValidator

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

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

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

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

APF-Template

<html:form name="upload" method="post">
   <fieldset>
      <label for="pdf">PDF file:</label>
      <form:file name="pdf" id="pdf" accepts="pdf|application/pdf" />
      <form: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:

APF-Template

<html:form name="upload" method="post">
   <fieldset>
      <label for="image">Image:</label>
      <form:file name="image" id="image" minsize="20480" maxsize="512000" />
      <form: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.

APF-Template

<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.

APF-Template

<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:

APF-Template

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

4.1.16. NumberScopeValidator

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

APF-Template

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

4.1.17. UriValidator

Der UriValidator validiert ein Eingabefeld auf eine valide URI.

APF-Template

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

4.2. Aufbau von Validatoren

Validatoren sind Klassen, die 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:

PHP-Code

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:

PHP-Code

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

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

APF-Template

<form:addfilter
   class=""
   button=""
   control=""
/>

Beschreibung der Attribute:

class: Der voll-qualifizierte Klassen-Name der Filter-Implementierung. (Zeichen: [A-Za-z0-9_\])
button: Name des Buttons, der die Filterung auslösen soll. Die Filterung ist immer an das Event isSent eines Buttons oder Image-Buttons gebunden. (Zeichen: [A-Za-z0-9-_])
control: Name des Formular-Controls auf das die Filterung Anwendung finden soll. Sollen mehrere Controls mit der im Tag definierten Filterung belegt werden, so enthält das Attribut alle mit Pipe getrennte Feld-Namen (z.B. sender|recipient|subject). (Zeichen: [A-Za-z0-9-_|])

Bitte beachten Sie, dass die Filterung von Werten lediglich innerhalb der Formular-Elemente greift. Die Werte in den Superglobals $_GET, $_POST und $_REQUEST bleiben davon unberührt. Es empfiehlt sich daher dringend, Inhalte direkt aus den Formular-Komponenten zu beziehen.

5.1. Verfügbare Filter

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.

Bitte beachten Sie, dass <form:addfilter />-Tags im Template stets nach der zugehörigen <form:button />- bzw. <form:imagebutton />-Definition platziert ist. Dies ist erforderlich, damit der angegebene Filter den referenzierten Button auflösen kann.

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.

APF-Template

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

5.1.2. NoSpecialCharactersFilter

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

APF-Template

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

5.1.3. OnlyHTMLEntitiesFilter

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

APF-Template

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

5.1.4. OnlyIntegersFilter

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

APF-Template

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

5.1.5. OnlyLettersFilter

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

APF-Template

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

5.1.6. OnlyNumbersFilter

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

APF-Template

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

5.1.7. SpecialCharacterFilter

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

APF-Template

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

5.1.8. String2LowerFilter

Der String2LowerFilter wandelt alle Buchstaben in Klein-Buchstaben um.

APF-Template

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

5.1.9. String2UpperFilter

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

APF-Template

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

5.1.10. StripTagsFilter

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

APF-Template

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

5.1.11. FloatFilter

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

Dieser Filter ist vor Allem dann interessant, wenn Text-Felder zur Eingabe von Fließkomma-Zahlen angeboten werden. Damit entfällt bei der Verarbeitung die Konvertierung und erleichtert die Validierung.

APF-Template

<html:form name="...">
   <form:area name="length" />
   <form:button name="send" value="Send"/>
   <form:addfilter
      class="APF\tools\form\filter\FloatFilter"
      button="send"
      control="length"
   />
</html:form>

5.2. Aufbau von Filtern

Formular-Filter sind eine Spezialisierung der APF-Filter-API. 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:

PHP-Code

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:

PHP-Code

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.

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

5.3. Implementierung von Filtern

Wie bereits im letzten Kapitel angesprochen, muss ein Filter 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

Möchten Sie den Artikel eine Anmerkung hinzufügen, oder haben Sie ergänzende Hinweise? Dann können Sie diese hier einfügen. Die bereits verfassten Anmerkungen und Kommentare finden Sie in der untenstehenden Liste.

Christian 18.09.2011, 22:44:50

Hallo Werner,

\"key\" in ist nun auch gegen \"entry\" ersetzt. Danke für den Hinweis.

welworx 10.07.2011, 01:09:27

grad gesehn dass es bei listener:getstring auch noch einen key anstelle eines entry in der doku gibt

Christian 20.02.2011, 22:16:44

Hallo welworx,

korrekt, hier hat die Dokumentation einen Fehler. Selbiges galt auch für <success:getstring />, aber die beiden Fehler sind aber jetzt behoben.

welworx 27.01.2011, 02:45:28

die Zeile
<error:getstring namespace="" config="" key="" />
sollte
<error:getstring namespace="" config="" entry="" />
heißen

Formulare

Kommentare

QUICKNAVI