17.9 HTML_QuickForm 
| Besprochene Version: 3.24pl1 | Lizenz: PHP-Lizenz |
| Klassendatei(en): HTML/QuickForm.php | |
HTML_QuickForm oder kurz QuickForm ist eine wirklich geniale Klasse zum Generieren von HTML-Formularen. Trotz meines ostwestfälisch zurückhaltenden Gemüts kann ich nur sagen, dass ich von der Klasse begeistert bin.
Leider ist das Paket sehr umfangreich, so dass ich nicht alles erläutern kann.
Das Paket kann nicht nur einfach Formulare generieren. Sie können auch Funktionalitäten vorsehen, die die Daten server- oder auch clientseitig validieren, und es gibt sogar einige Formularelemente, die weit über den üblichen Standard hinausgehen.
In Listing 17.14 finden Sie ein Beispiel für die Ausgabe eines einfachen Formulars.
require_once('HTML/QuickForm.php');
$form=new HTML_QuickForm('eingabe','post',
$_SERVER['PHP_SELF']);
$form->addElement('radio','anrede','Anrede', 'Herr',1);
$form->addElement('radio','anrede','', 'Frau',2);
$form->addElement('text','vorname','Vorname');
$form->addElement('text','nachname','Nachname');
$form->addElement('submit','submit','Absenden');
$form->display();Listing 17.14 Ausgabe eines einfachen Formulars mit HTML_QuickForm
Auch hier bekommt der Konstruktor die Informationen übergeben, die für das <form>-Tag benötigt werden. Der erste Parameter ist hierbei der Name des Formulars (für einen Zugriff mit JavaScript). Alle weiteren Parameter sind optional – wie der zweite Parameter, mit dem die Versandmethode festgelegt wird, die standardmäßig auf post eingestellt ist. An dritter Stelle kann der Wert für das Attribut action angegeben werden. Übergeben Sie keinen Wert, so bleibt das Attribut leer, was dazu führt, dass die Seite sich selbst aufruft. Danach können Sie noch einen Wert für das Attribut target und einen frei formulierbaren String angeben, der beliebige Attribute und Werte enthalten kann. An letzter Stelle ist es noch möglich, mit einem booleschen Wert zu definieren, ob das System ein verstecktes Feld einfügen soll, mit dem festgestellt werden kann, ob das Formular bereits einmal abgeschickt wurde.
Der einfachste Weg, um Formularelemente hinzuzufügen, ist die Methode addElement(). Wie Sie schon dem Listing entnehmen können, ist die Parameterliste dieser Methode variabel. Sie erwartet mindestens einen Parameter, der definiert, welches Element benötigt wird. Das ist der String, der jeweils an der ersten Stelle der Parameterliste zu finden ist. Die anderen Parameter richten sich nach dem benötigten Objekt. Was in diesem Beispiel nicht genutzt wird, ist die Möglichkeit, an letzter Stelle noch einen String mit Attributen zu übergeben, die dann direkt in das Tag eingefügt werden. Denkbar wäre beispielsweise 'size="20"', um die Darstellungsgröße des Feldes zu beeinflussen.
Um das Formular auszugeben, ist die Methode display() implementiert. Die Texte und Formularelemente werden auch in diesem Paket mithilfe von Tabellenfeldern ausgerichtet.
Abbildung 17.3 Ausgabe eines Formulars mit HTML_QuickForm
addElement() stellt aber nur eine Möglichkeit dar. Die zweite Variante ist, mit createElement() zu arbeiten. Im ersten Fall wird das Element direkt in das Formular eingefügt. Im zweiten Fall liefert die Methode, die Sie statisch aufrufen können, Ihnen ein Objekt zurück, das Sie dann dem Formular hinzufügen können. Die zweite Variante hat den Vorteil, dass Sie direkten Zugriff auf das Objekt haben, in dem das Element abgespeichert ist. Daraus resultiert, dass Sie Methoden nutzen können, um das zu beeinflussen, die Ihnen sonst nicht zur Verfügung stehen. Ein Element mit createElement() zu generieren könnte so aussehen:
$inp_txt = HTML_QuickForm::createElement('text','vorname',
'Vorname');
$inp_txt->setSize(20);
$inp_txt->setMaxlength(40);
$form->addElement($inp_txt);Die Methode bekommt die gleichen Parameter übergeben wie addElement(), liefert aber ein Objekt zurück, das die Methoden setSize() und setMaxlength() kennt. Nachdem Sie das Objekt fertig konfiguriert haben, können Sie es mit addElement() zum Formular hinzufügen.
Zusätzlich gäbe es auch noch die Möglichkeit, das Objekt erst mit addElement() in das Formular einzufügen, dann eine Referenz auf das Objekt mithilfe von getElement() [Sollten Sie PHP 4 benutzen, achten Sie bitte darauf, =& getElement() zu nutzen. ] auszulesen und damit anschließend die Methoden aufzurufen. Die folgenden Zeilen würden also dasselbe leisten wie das vorhergehende Beispiel.
$form->addElement('text','vorname','Vorname');
$inp_txt = $form->getElement('vorname');
$inp_txt->setSize(20);
$inp_txt->setMaxlength(40);17.9.1 Standard-Formularelemente
Nachfolgend finden Sie jeweils unter dem Typ des Formularelements die Möglichkeiten, um es hinzuzufügen bzw. zu manipulieren.
Die Parameter in den Klammern sind jeweils optional. Allerdings sollten Sie dabei immer beachten, dass einige Parameter zwingend erforderlich sind, um sinnvoll mit einem Formular arbeiten zu können, obwohl sie optional sind.
name steht für den Namen des Elements, title bezeichnet den Text, der links vor dem Element eingeblendet wird, und attr ist ein String mit frei definierbaren Attributen, die direkt in das Tag eingefügt werden.
-
- Direktes Hinzufügen:
$form->addElement('text',[name], [title], [attr]);
-
- Indirektes Hinzufügen:
$obj=HTML_QuickForm::createElement('text',[name], [title], [attr]); $obj->setSize(20); // Legt die Darstellungsgroesse fest $obj->setMaxlength(20); // Maximale Eingabelaenge
-
- Mit 'text' können Sie ein einzeiliges Text-Feld, also ein <input type="text">, hinzufügen.
-
- Direktes Hinzufügen:
$form->addElement('password',[name], [title], [attr]);
-
- Indirektes Hinzufügen:
$obj=HTML_QuickForm::createElement('password',[name], [title], [attr]); $obj->setSize(20); // Legt die Darstellungsgroesse fest $obj->setMaxlength(20); // Maximale Eingabelaenge
-
- Um ein Passwortfeld zu erzeugen, können Sie den Methoden 'password' übergeben.
-
- Direktes Hinzufügen:
$form->addElement('hidden',[name], [value], [attr]);
-
- Indirektes Hinzufügen:
$obj=HTML_QuickForm::createElement('hidden',[name], [value], [attr]);
-
- Direktes Hinzufügen:
$form->addElement('textarea',[name], [title], [attr]);
-
- Indirektes Hinzufügen:
$obj=HTML_QuickForm::createElement('textarea',[name], [title], [attr]); $obj->setRows(5); // Anzahl der Zeilen $obj->setCols(20); // Anzahl der Spalten $obj->setWrap('soft'); // Verwaltung der Umbrueche $obj->setValue('Hallo'); // Default-Wert festlegen
-
- Die Methoden setRows() und setCols() definieren die Anzahl der Zeilen und Spalten. Gültige Werte für setWrap() sind 'soft', 'virtual', 'hard', 'physical' und 'off', die als Werte an das Attribut wrap übergeben werden.
-
- Soll das Feld mit einem Text vorbelegt werden, können Sie bei einer Textarea nicht den Attribut-String verwenden. Hierzu müssen Sie die Methode setValue() mit dem gewünschten Text aufrufen.
-
- Direktes Hinzufügen:
$form->addElement('checkbox',[name], [title], [text], [attr]);
$obj=HTML_QuickForm::createElement('checkbox',[name], [title], [text], [attr]); $obj->setChecked(true); // Legt die Default-Einstellung fest $obj->setValue('OK'); // Legt den Rueckgabewert fest $obj->setText('Bitte anklicken'); // Legt den Text fest
-
- Mit dem Parameter text können Sie einen Text definieren, der rechts neben der Checkbox ausgegeben wird. Hierbei handelt es sich um denselben Text, der auch mit setText() gesetzt werden kann.
-
- Beim direkten Hinzufügen mit addElement() ist der Wert für value immer 1. Möchten Sie einen anderen Wert übergeben, müssen Sie setValue() nutzen und der Methode den gewünschten Wert übergeben. setChecked() akzeptiert einen booleschen Wert als Parameter, mit dem definiert wird, ob die Checkbox beim Laden des Formulars sofort selektiert ist.
-
- Direktes Hinzufügen:
$form->addElement('radio',[name], [title], [text], [value], [attr]);
-
- Indirektes Hinzufügen:
$obj=HTML_QuickForm::createElement('radio',[name],[title], [text],[value],[attr]); $obj->setChecked(true); // Legt die Default-Einstellung fest $obj->setText('Bitte anklicken'); // Legt den Text fest
-
- Direktes Hinzufügen:
$form->addElement('image',[name], [src], [attr]);
-
- Indirektes Hinzufügen:
$obj=HTML_QuickForm::createElement('image',[name], [src], [attr]); $obj->setSrc('bild.gif'); // Legt den Wert fuer src fest $obj->setAlign('left'); // Ausrichtung des Bildes $obj->setBorder(0); // Dicke des Rahmens in Pixeln
-
- Fügen Sie einem Formular ein Image-Element hinzu, müssen Sie natürlich den Parameter src angeben, der die URL des Bildes enthält, oder den Wert nachträglich mit setSrc() setzen.
-
- setAlign() übernimmt einen der Strings 'bottom', 'middle', 'top', 'left' oder 'right' als Wert für das align-Attribut. Mit setBorder() können Sie die Dicke des Rahmens definieren.
-
- Direktes Hinzufügen:
$form->addElement('file',[name], [title], [attr]);
-
- Indirektes Hinzufügen:
$obj=HTML_QuickForm::createElement('file',[name], [title], [attr]); $obj->setSize(20); // Legt die Darstellungsgroesse fest
-
- Mit setSize() können Sie auch bei einem Element vom Typ file die Breite definieren. Der korrekte Encoding-Typ wird automatisch eingefügt, so dass Sie sich darum nicht kümmern müssen.
-
- Möchten Sie die maximale Größe einer Datei festlegen, hilft die Methode setMaxFileSize() Ihnen weiter. Diese Methode des HTML_QuickForm-Objekts bekommt eine Zahl übergeben, die die maximal akzeptable Dateigröße als Anzahl von Bytes repräsentiert, und fügt dann ein <input type='hidden' name=' MAX_FILE_SIZE' /> mit dem entsprechenden value in das Formular ein.
-
- Direktes Hinzufügen:
-
- Indirektes Hinzufügen:
$obj=HTML_QuickForm::createElement('button',[name], [value], [attr]); $obj->setSize(20); // Legt die Darstellungsgroesse fest
-
- Alle Buttons, also <input>-Tags, bei denen der Typ button, submit oder reset ist, benutzen dieselbe API, so dass ich diese Elemente zusammengefasst habe. Um einen entsprechenden Button zu erzeugen, müssen Sie natürlich den korrekten Typ an die Methode übergeben. Für die Buttons ist eine Beschriftung, die links neben ihnen ausgegeben wird, nicht vorgesehen. Der String, den Sie als Parameter value übergeben, wird zur Beschriftung des jeweiligen Buttons genutzt. Eine Default-Beschriftung der Buttons ist nicht vorgesehen.
-
- Direktes Hinzufügen:
$form->addElement('select',[name], [title], [options], [attr]);
-
- Indirektes Hinzufügen:
$obj=HTML_QuickForm::createElement('select',[name], [title], [options], [attr]); $obj->setMultiple(true); // Mehrere Werte selektierbar? $obj->setSize(3); //Angezeigte Zeilen $obj->setSelected('1,5,9'); // Selektierte Werte $obj->loadArray(options,[selected]); // Laedt und selektiert
-
- Die Optionsliste, auch Select-Box genannt, ist das Standard-Element mit den komplexesten Möglichkeiten. Die Parameter name und title definieren auch hier wieder den Namen des Elements bzw. den Text, der links daneben erscheint. Anstelle von options werden die Optionen übergeben, die in der Liste erscheinen sollen. Sie können als indiziertes oder assoziatives Array übergeben werden. Wenn Sie ein indiziertes Array nutzen, bekommen die einzelnen Optionen automatisch den Index des jeweiligen Wertes als value zugewiesen. Bei einem assoziativen Array werden die Schlüssel des Arrays als Wert für value genutzt. Sollte ein Array nur teilweise mit Schlüsseln versehen sein, wird der Rest der Werte automatisch durchnummeriert.
-
- Übergeben Sie der Methode setMultiple() den Wert true als Parameter, so wird damit definiert, dass mehrere Werte in der Optionsliste selektiert werden können.
-
- Wenn Sie diese Option einschalten, so ist es sinnvoll, mehrere Zeilen der Box auf einmal anzeigen zu lassen. Dieses Verhalten wiederum können Sie mit setSize() steuern. Die Methode bekommt die Anzahl der Zeilen übergeben, die gleichzeitig zu sehen sein sollen.
-
- Natürlich haben Sie auch die Möglichkeit anzugeben, welche Optionen bereits selektiert sein sollen. Übergeben Sie der Methode setSelected() nur eine Zahl oder einen value, so wird die damit verbundene Option selektiert. Um mehrere Optionen zu selektieren, können die entsprechenden Zahlen oder value-Werte in Form eines Arrays oder in Form eines Strings übergeben werden. Wenn Sie einen String nutzen, müssen die einzelnen Werte durch Kommata voneinander getrennt werden.
-
- Mit loadArray(), das mindestens ein Array übergeben bekommt, können die Daten für die Optionen auch nachträglich geladen werden. Die Methode akzeptiert noch einen zweiten Parameter, mit dem Sie die selektierten Werte definieren können, wie es bei setSelected() beschrieben ist.
-
- Ein ganz besonderes Schmankerl hierbei ist, dass die Daten für eine Optionsliste auch direkt aus einer Datenbank übernommen werden können. »Direkt aus einer Datenbank« heißt an dieser Stelle, dass das Paket PEAR::DB zur Kommunikation mit der Datenbank genutzt wird. HTML_QuickForm kann entweder ein Ergebnis-Objekt als Datengrundlage nutzen oder eine SQL-Abfrage zu einer unterstützten Datenbank schicken und das Ergebnis direkt nutzen.
-
- Sie bekommt als ersten Parameter eine Referenz auf das DbResult-Objekt übergeben. Wichtig ist, dass in diesem Objekt mindestens zwei Spalten enthalten sind. Diese dürfen sogar identische Werte enthalten, aber es müssen zwei Spalten sein: eine für die eigentlichen Optionen und eine für die Werte der value-Attribute. Der zweite Parameter ist der Name der Spalte, die zum Generieren der Werte genutzt werden soll. Wenn Sie diese Information nicht angeben – der Parameter ist optional –, wird einfach die erste Spalte genutzt. Mit dem dritten Parameter, der, wie der vierte auch, optional ist, können Sie den Namen einer Spalte definieren, die zum Generieren der Werte für die value-Attribute genutzt werden soll. Der letzte Parameter kann auch hier wieder genutzt werden, um den oder die selektierten Werte zu markieren. Der Aufbau dieses Parameters entspricht dem von setSelected().
-
- Mit den beiden Zeilen
$obj=HTML_QuickForm::createElement('select','s','User'); $obj->loadDbResult($db_result,'user', 'id');
-
- Wie schon erwähnt, können Sie die Daten aber auch direkt mit einer SQL-Abfrage aus der Datenbank beziehen, was die Methode loadQuery() für Sie übernimmt.
-
- Diese bekommt entweder eine bereits geöffnete Datenbankverbindung oder einen gültigen DSN [Den Aufbau von DSNs entnehmen Sie bitte dem Abschnitt 15.1, der PEAR::DB erläutert. ] übergeben. Der zweite Parameter ist das SQL-Statement, das auch hier wieder mindestens zwei datenführende Spalten generieren muss. Darauf folgen drei optionale Parameter. Der erste ist der Name der Spalte, aus der die Optionen bezogen werden sollen. Danach kann der Name der Spalte folgen, die die Werte für die value-Attribute zur Verfügung stellt, und zu guter Letzt kann auch hier wieder definiert werden, welche Optionen aktiv sein sollen.
require_once('HTML/QuickForm.php'); // Neues Formular-Objekt $form=new HTML_QuickForm('eingabe','post', $_SERVER['PHP_SELF']); // Select-Box ableiten $select=HTML_QuickForm::createElement('select','user','User'); // dsn konstruieren $dsn='mysql://netviser:geheim@localhost/netviser'; // SQL-Abfrage ueber _zwei_ Spalten $sql='select username, username from auth'; // Daten laden $erg=$select->loadQuery($dsn,$sql,'username'); if (true===PEAR::isError($erg)) { die ($erg->getMessage()); } $form->addElement($select); $form->display();
Listing 17.15 Automatisches Erstellen einer Select-Box
-
- Die meisten Punkte in Listing 17.15 habe ich bereits erläutert. Nur auf die SQL-Abfrage möchte ich noch einmal eingehen. Der Befehl select username, username from auth sieht ein wenig komisch aus, da die Spalte username doppelt vorkommt. Das ist kein Tippfehler, sondern soll ein deutlicher Hinweis darauf sein, dass die Methode loadQuery() wirklich zwei Spalten benötigt, weil sonst Notices ausgegeben werden.
-
- In diesem Beispiel habe ich eine Abfrage mit eingebaut, ob ein Fehler generiert wurde. Ein Großteil der QuickForm-Methoden kann Fehlermeldungen liefern. Da die Wahrscheinlichkeit, dass ein Fehler auftritt, im Allgemeinen aber recht gering ist, habe ich in den meisten Fällen nicht auf das Auftreten eines Fehlers geprüft.
17.9.2 Erweiterte Formularelemente
Die normalen Formularelemente sind zwar sicher sehr hilfreich, aber wenn Sie die Möglichkeiten von HTML-Formularen mit denen von Windows-Programmen vergleichen, werden Sie feststellen, dass die Möglichkeiten doch recht eingeschränkt sind. HTML_QuickForm kennt hier einige wirklich interessante Erweiterungen. Allerdings basieren diese zum Großteil auf JavaScript, so dass es im Einzelfall sinnvoll ist, vor der Nutzung zu prüfen, ob der Client JavaScript unterstützt.
-
- Direktes Hinzufügen:
$form->addElement('date',[name], [title], [format]);
-
- Indirektes Hinzufügen:
$obj=HTML_QuickForm::createElement('date',[name], [title], [format]); $obj->setValue(time()); // Vorgegebenes Datum selektieren
-
- Die Ausgabe von Datumsfeldern für ein Formular kann recht aufwändig sein. Wenn Sie nicht nur einfache Text-Eingabefelder, sondern Select-Boxen nutzen und diese dann vielleicht noch in unterschiedlichen Sprachen ausgeben lassen wollen, kann das schon recht umfangreich werden.
-
- Das Formularelement 'date' stellt eine einfache Möglichkeit dar, um solche Datumsfelder auszugeben. Hierbei werden verschiedenste Formate unterstützt, die Sie mithilfe des dritten Parameters in Form eines Arrays übergeben können. Übergeben Sie keine Formatierungsanweisung, besteht die Ausgabe aus drei Feldern, mit denen der Benutzer Tag, Monat und Jahr numerisch selektieren kann. Die Jahreszahlen laufen hierbei von 2001 bis 2010.
-
- Um eine andere Formatierung vorzugeben, müssen Sie mithilfe des Array-Schlüssels 'format' einen String übergeben, der das Erscheinungsbild definiert. Dieser String basiert auf den Möglichkeiten, die PHPs date()-Funktion bietet. Momentan werden die folgenden Platzhalter erkannt:
-
- Mit den Schlüsseln minYear und maxYear können Sie für den Jahresanteil im Datum einen kleinsten und einen größten Wert definieren.
-
- Damit Sie erkennen können, ob ein Benutzer überhaupt ein Datum selektiert hat, gibt es die Möglichkeit, am Anfang der Optionslisten leere Felder einzufügen. Übergeben Sie dem Array-Schlüssel addEmptyOption ein true, wird eine leere Option eingefügt, die über den Schlüssel emptyOptionText mit einem Text und über den Schlüssel emptyOptionValue mit einem Wert für das value-Attribut bestückt werden kann.
-
- Wenn Sie eine Uhrzeit ausgeben lassen, die Minuten oder Sekunden beinhaltet, können Sie für diese auch die Schrittweite definieren, so dass die Sekunden beispielsweise nicht mehr in Einer- sondern in Fünferschritten gewählt werden. Hierzu übergeben Sie dem Schlüssel optionIncrement ein Array, das 'i' und 's' als Schlüssel enthalten darf. Mit dem Schlüssel 'i' kann die Schrittweite für die Minuten definiert werden, wohingegen der Schlüssel 's' für die Sekunden zuständig ist. Die Schrittweite ist jeweils als Wert zu übergeben.
-
- Wenn Sie eine textuelle Darstellung der Monate oder Tage nutzen, können Sie auch noch die Sprache einstellen, was über den Schlüssel language erfolgt. Er bekommt den ISO-Sprachcode der gewünschten Sprache übergeben. Die Nutzung der Lokalisierung ist systemunabhängig, da die Sprachen im Paket selbst abgelegt sind. Momentan sind Englisch ('en'), Deutsch ('de'), Französisch ('fr'), Ungarisch ('hu'), Polnisch ('pl'), Russisch ('ru'), Spanisch ('es'), Isländisch ('is'), Italienisch ('it'), Slowenisch ('sl'), Slowakisch ('sk'), Tchechisch ('cs'), Dänisch ('da'), Armenisch ('hy'), Niederländisch ('nl'), Estnisch ('et'), Türkisch ('tr'), Norwegisch ('no') und Esperanto ('eo') definiert.
-
- Beim indirekten Hinzufügen haben Sie darüber hinaus die Möglichkeit, das voreingestellte Datum mithilfe von setValue() festzulegen.
require_once('HTML/QuickForm.php'); // Neues Datumsobjekt $form=new HTML_QuickForm('eingabe','post', $_SERVER['PHP_SELF']); // Optionen fuer das erste Datum $options = array( 'language' => 'de', // Deutsche Texte 'format' => 'dlY', // Tag Monat Jahr 'minYear' => 2005, // Erstes Jahr 'maxYear' => 2010, // Letztes Jahr ); // Datum hinzufuegen $form->addElement('date', 'datum1', 'Datum 1', $options); // Optionen fuer das zweite Datum $options = array( 'language' => 'de', //Sprache Deutsch 'format' => 'dlY H:i:s',//Tag,Mon,Jahr,Zeit 'minYear' => 2000, // Erstes Jahr 'maxYear' => 2010, // Letztes Jahr 'addEmptyOption' => true, // Leeres Feld einfuegen 'emptyOptionValue' => '0', // Value des leeren Feldes 'emptyOptionText' => '-----', // "Text" des Feldes 'optionIncrement' => array( 'i' => 5, // Schrittweite Min 's' => 10 // Schrittweite Sek ) ); // Neues Objekt ableiten $date=HTML_QuickForm::createElement('date','datum2', 'Datum 2', $options); // Zeit setzen und Objekt hinzufuegen $date->setValue(time()); $form->addElement($date); $form->display();
Listing 17.16 Ausgabe von Datumsfeldern mit HTML_QuickForm
Abbildung 17.4 Ausgabe im Browser
-
- Das Datum wird jeweils in Form eines Arrays zurück an den Browser geschickt. Der Name des Elements wird hierbei zum Namen des Arrays, und der gewählte Platzhalter wird zum Schlüssel, der den Wert enthält.
-
- Für das erste Datum aus Listing 17.16 wird also das Array $_POST['datum1'] zurückgegeben, das über die Schlüssel 'd' (Tag), 'l' (Monat) und 'Y' (Jahr) verfügt.
-
- Direktes Hinzufügen:
$form->addElement('advcheckbox',[name], [title], [text], [attr],[values]);
-
- Indirektes Hinzufügen:
$obj=HTML_QuickForm::createElement('advcheckbox',[name], [title],[text],[attr],[values]); $obj->setChecked(true); // Legt die Default-Einstellung fest $obj->setValues(array('Nein','Ja'));//Definiert Rueckgabewerte $obj->setText('Bitte anklicken'); // Legt den Text fest
-
- Eine normale Checkbox hat den unschönen Nachteil, dass sie nur dann verschickt wird, wenn sie auch angeklickt ist. Das wiederum hat zur Folge, dass Sie bei der Auswertung des Formulars mit isset() prüfen müssen, ob die Checkbox angeklickt wurde. Bei Nutzung einer Advanced Checkbox wird immer ein Wert versandt.
-
- Die Parameterliste zum Hinzufügen einer Advanced Checkbox unterscheidet sich von der einer normalen Checkbox dadurch, dass es hier noch möglich ist, mit dem Parameter values zu definieren, welcher Wert im nicht-selektierten und im selektierten Zustand übergeben werden soll. Übergeben Sie nur einen Wert, wird der für den aktiven Zustand genutzt. Möchten Sie zwei Werte übergeben, muss das in Form eines Arrays passieren.
-
- Wenn Sie eine Advanced Checkbox mit dem Befehl
$form->addElement('advcheckbox', 'agb_gelesen', 'AGB gelesen?', 'Ja, ich habe die AGB gelesen',null,array('Nein','ja'));
-
- hinzufügen, wird der folgende Code an den Browser gesandt:
<tr> <td align="right" valign="top"><b>AGB gelesen?</b></td> <td valign="top" align="left"> <input name="__agb_gelesen" type="checkbox" value="1" id="qf_9abcad" checked="checked" onclick="if (this.checked) { this.form['agb_gelesen'].value='ja'; }else { this.form['agb_gelesen'].value='Nein'; } "/> <label for="qf_9abcad">Ja, ich habe die AGB gelesen </label><input type="hidden" name="agb_gelesen" value="ja" /></td> </tr>
-
- Wie Sie erkennen können, wird mithilfe einer kurzen JavaScript-Zeile und eines versteckten Feldes sichergestellt, dass auf jeden Fall Daten verschickt werden. Ist JavaScript deaktiviert, wird immer der Standardwert des versteckten Feldes übergeben. Es würde also immer der Eindruck entstehen, dass die Checkbox nicht angeklickt war. Für einen solchen Fall ist ein »Fallback-System« eingebaut. Ist die Chekbox angeklickt worden, so wird sie unabhängig von der JavaScript-Einstellung auf jeden Fall verschickt. Allerdings wird dann der von Ihnen vorgegebene Name um zwei Unterstriche ergänzt, so dass eine Checkbox mit Namen agb_gelesen im Array $_POST[] unter dem Schlüssel __agb_gelesen zu finden ist.
-
- Direktes Hinzufügen:
$form->addElement('autocomplete',[name], [title], [opts], [attr]);
-
- Indirektes Hinzufügen:
-
- Bei einem »Autocomplete-Text-Feld« handelt es sich um ein einzeiliges Eingabefeld. Im Gegensatz zu einem normalen Text-Feld beherrscht diese Variante allerdings die Möglichkeit, Texte automatisch zu vervollständigen. Das heißt: Wenn Sie einen Text eingeben, der mit P beginnt, überprüft das System, ob es einen Vorgabetext gibt, der auch mit P beginnt. Ist das der Fall, wird dieser Text automatisch eingeblendet.
-
- Indirektes Hinzufügen:
$obj=HTML_QuickForm::createElement('hierselect',[name], [title], [attr], [sep]); $obj->setOptions(opts); // Setzt die Optionen
-
- Bei hierarchischen Optionslisten handelt es sich um Select-Listen, die voneinander abhängig sind. Das heißt, wenn in der ersten Liste ein bestimmter Wert selektiert wird, sollen in einer zweiten nur bestimmte Werte zu sehen sein. Wird dort ein bestimmter Wert angeklickt, sollen in einer dritten Optionsliste wiederum nur bestimmte Werte zu sehen sein und so weiter. Wenn Sie so etwas schon einmal von Hand programmiert haben, dann wissen Sie sicher, was das für einen Aufwand bedeutet.
-
- Genau dieses Problem lösen Elemente vom Typ hierselect für Sie. Sie bekommen einfach ein Array mit Daten übergeben, konstruieren daraus die Optionslisten und stellen die Abhängigkeiten mithilfe von JavaScript her. Im folgenden Beispiel finden Sie den Code für drei voneinander abhängige Optionslisten.
require_once('HTML/QuickForm.php'); // Neues Datumsobjekt $form=new HTML_QuickForm('eingabe','post', $_SERVER['PHP_SELF']); //Werte fuer die erste Liste $typ[0]='--------------'; $typ[1]='Heißgetränke'; $typ[2]='Kaltgetränke'; // Default-Wert fuer die zweite Liste $getraenke[0][0]='--------------'; // Folgewerte fuer Heissgetraenke $getraenke[1][0]='Kaffee'; $getraenke[1][1]='Tee'; // Folgewert fuer Kaltgetraenke $getraenke[2][0]='Cola'; // Default-Wert fuer die dritte Liste $zubehoer[0][0][0]='--------------'; // Folgewerte fuer Kaffee $zubehoer[1][0][0]='Milch'; $zubehoer[1][0][1]='Zucker'; $zubehoer[1][0][2]='Milch und Zucker'; // Folgewerte fuer Tee $zubehoer[1][1][0]='Milch'; // Folgewerte fuer Cola $zubehoer[2][0][0]='Eiswürfel'; $zubehoer[2][0][1]='Zitrone'; // Werte in einem Array zusammenfuehren $opts[]=$typ; $opts[]=$getraenke; $opts[]=$zubehoer; $obj =HTML_QuickForm::createElement('hierselect','getraenke', 'Wählen Sie Ihr Getränk', 'style="width:15em"','<br />'); $obj->setOptions($opts); $form->addElement($obj); $form->display();
Listing 17.17 Nutzung von hierarchischen Optionslisten
-
- Die Methode createElement(), die das HTML_QuickForm_hierselect-Objekt erstellt, bekommt den String 'hierselect', den Namen des Elements und danach den erläuternden Text übergeben. Die Möglichkeit, als nächsten Parameter Attribute zu übergeben, kann in diesem Fall gut genutzt werden, um alle Optionslisten auf dieselbe Breite zu bringen. Danach ist es noch möglich, einen String anzugeben, der nach jeder Liste eingefügt wird. Hier bietet sich ein <br /> an, um die Elemente untereinander zu platzieren.
-
- Die Daten für jede Optionsliste werden in einem Array zusammengefasst. Im Array $typ, das für die erste Optionsliste zuständig ist, findet sich beispielsweise der Wert Kaltgetränke im Element 1. Die Werte, die in der zweiten Select-Box angezeigt werden sollen, wurden im Array $getraenke zusammengefasst. Dieses Array ist zweidimensional. Die erste Dimension hängt von dem Array $typ ab. Werte, die in der ersten Dimension eine 1 als Schlüssel haben, werden nur dann eingeblendet, wenn in der ersten Liste die Option mit dem Schlüssel 1, also Kaffee, selektiert wird. Die zweite Dimension des Arrays wird dazu genutzt, die Werte durchzunummerieren und eine Referenz für das dritte Array bereitzustellen.
-
- Bei dem dritten Array, $zubehoer, wird dasselbe Prinzip genutzt. Wird im ersten Array Heißgetränke selektiert (Indexwert 1) und im zweiten Kaffee (Indexwert 0), so stehen im dritten alle Werte zur Verfügung, die in den ersten beiden Dimensionen die Schlüssel 1 und 0 nutzen. Der dritte Wert dient auch hier wieder zum Nummerieren der Werte bzw. als Bezug für eine vierte Box.
-
- Die unterschiedlichen Arrays werden in einem Arry, in diesem Fall $opts, zusammengefasst. Jedes der Arrays wird hierbei einem neuen Feld zugewiesen. Um die Werte an das Objekt zu übergeben, ist die Methode setOptions() definiert.
-
- Ein direktes Hinzufügen, wie es bei den anderen Objekten möglich ist, kann hier nicht genutzt werden.
-
- Das generierte Formular finden Sie in Abbildung 17.5.
Abbildung 17.5 Hierarchische Optionsliste
-
- Wenn Sie eine hierarchische Optionsliste nutzen wollen, beachten Sie bitte, dass sie, falls JavaScript nicht aktiviert ist, keine Funktionalität bietet.
$form->addElement('static',[name], [title], [text]);
-
- Ein statischer Text ist ein Formularelement, das genutzt werden kann, um erläuternden Text in ein Formular einzubringen. Der Parameter title wird in der linken Tabellenspalte ausgegeben, und der String, den Sie als text übergeben, in der rechten Spalte, in der die Formularelemente zu finden sind. Ein Anwendungsbeispiel finden Sie in Listing 17.18.
-
- Direktes Hinzufügen:
$form->addElement('header',[name], [title]);
-
- Indirektes Hinzufügen:
$obj=HTML_QuickForm::createElement('header',[name], [title]);
-
- Eine Überschrift ist eine Möglichkeit, verschiedene logische Bereiche gegeneinander abzugrenzen. Die Überschrift wird grau hinterlegt, und der Text wird in der linken Zeile der Tabelle eingeblendet. Ein Anwendungsbeispiel finden Sie in Listing 17.18.
-
- Direktes Hinzufügen:
$form->addElement('link',[name], [title], [href], [text], [attr]);
-
- Indirektes Hinzufügen:
$obj=HTML_QuickForm::createElement('link',[name], [title], [href], [text], [attr]);
-
- Einen Link in ein Formular einzufügen gestaltet sich mit diesen Methoden recht unproblematisch. Nach dem Namen und Titel des Links wird das Ziel für den Verweis übergeben. Das Attribut text bezeichnet den Text, den der Benutzer anklicken kann. Mit attr können auch hier wieder selbst definierte Attribute übergeben werden. Ein Anwendungsbeispiel finden Sie in Listing 17.18.
-
- Direktes Hinzufügen:
-
- Um ein möglichst hohes Maß an Flexibilität vorzusehen, haben die Entwickler auch eine Möglichkeit geschaffen, HTML-Code direkt in das Formular auszugeben. Dieser Code wird direkt ausgegeben und nicht in die Tabelle eingefügt. Soll der Code also Teil der Tabelle werden, müssen Sie die entsprechenden Tags mit ausgeben. Ein Anwendungsbeispiel finden Sie in Listing 17.18.
require_once('HTML/QuickForm.php'); // Neues Datumsobjekt $form=new HTML_QuickForm('eingabe','post', $_SERVER['PHP_SELF']); // HTML-Code vorbereiten $html='<tr><td colspan="2" align="right" bgcolor="green"> <img src="http://pear.php.net/gifs/pearsmall.gif" /> </td></tr>'; // HTML-Code hinzufuegen $form->addElement('html',$html); // Header einbauen $form->addElement('header','ueber','Ihre Angaben'); // Statischen Text hinzufuegen $form->addElement('static','text','Erläuterungen', 'Hier bitte schreiben'); //Link einblenden $form->addElement('link','link','Erklärungen finden Sie hier','http://www.example.org', 'Erklärungen', 'target="_blank"'); $form->addElement('text','vorname','Vorname'); $form->display();
Listing 17.18 Nutzung von header, static, html und link
Abbildung 17.6 Ausgabe im Browser
17.9.3 Gruppen
Bisher habe ich alle Elemente direkt in das Formular eingefügt. Das hat den Nachteil, dass alle Elemente immer untereinander stehen. Zwar ist das in vielen Fällen sicher akzeptabel, aber das Layout ist schnell langweilig und unpraktisch.
Eine einfache Abhilfe stellen Gruppen dar, in denen Sie verschiedene Formularelemente zusammenfassen können. Diese werden dann in einem Tabellenfeld zusammengefasst und können dadurch auch hintereinander und nicht nur untereinander ausgegeben werden.
Um eine Gruppe zu generieren, werden die Objekte jeweils mithilfe von createElement() generiert und danach einem Array zugewiesen. Ist dieses Array dann »bestückt«, können die darin enthaltenen Objekte mithilfe von addGroup() in das Formular eingebunden werden. Die folgenden Zeilen fassen zwei Text-Elemente zu einer Gruppe zusammen:
$name[]=HTML_QuickForm::createElement('text','vorname');
$name[]=HTML_QuickForm::createElement('text','nachname');
$form->addGroup($name,'name', 'Ihr Name:');Wie Sie sehen, bekommen die beiden Text-Elemente nur den Namen übergeben. Würden Sie eine Beschriftung mit in der Parameterliste angeben, würde diese ignoriert. Allerdings können Sie ohne Probleme Attribute übergeben.
Die Methode addGroup() bekommt an erster Stelle das Array mit den Objekten übergeben. Der zweite Parameter ist der Name der Gruppe, und an letzter Stelle wird ein Text übergeben, der in der linken Tabellenspalte als Beschriftung erscheint.
Der generierte HTML-Code für diese Objekte sieht vielleicht ein wenig anders aus, als Sie es erwarten:
<tr> <td align="right" valign="top"><b>Ihr Name:</b></td> <td valign="top" align="left"> <input name="name[vorname]" type="text" /> <input name="name[nachname]" type="text" /></td> </tr>
Es werden also nicht nur einfach die Formularelemente in einem gemeinsamen Tabellenfeld ausgegeben, sondern die Felder bekommen auch den Namen der Gruppe als eigenen Namen zugewiesen. Die Namen der Felder, die Sie bei der Instanziierung übergeben haben, erscheinen nur als »Array-Schlüssel«. Dieses System wird übrigens auch bei Datumselementen beibehalten, so dass sich hier dann mehrdimensionale Arrays ergeben und die Felder Namen wie eingabe[datum][d] haben.
Dieses Verhalten können Sie allerdings steuern. Und zwar können Sie der Methode addGroup() noch zwei weitere Attribute übergeben. Das erste ist ein zusätzlicher String, der als Separator bezeichnet und nach jedem Formularelement ausgegeben wird. Hier könnten Sie beispielsweise ein '<br />' übergeben, um die Elemente untereinander zu platzieren. Ein schönes Feature ist, dass der Separator auch in Form eines Arrays übergeben werden kann. Nutzen Sie beispielsweise array(' ', '<br />'), wird hinter dem ersten, dritten, fünften usw. Element ein eingefügt. Hinter allen Feldern mit gerader Ordnungsnummer folgt ein <br />.
Nach dem Separator können Sie der Methode noch einen booleschen Wert übergeben. Nutzen Sie hier ein true, bekommen die Formularelemente nicht den Gruppennamen zugewiesen, sondern behalten den Namen, den Sie bei createElement() genutzt haben.
Auf diese Weise können Sie dann auch recht einfach Radio-Buttons gruppieren, ohne sich Gedanken über die Namensproblematik machen zu müssen.
$anrede[]=HTML_QuickForm::createElement('radio','anrede','',
'Herr','herr');
$anrede[]=HTML_QuickForm::createElement('radio','anrede','',
'Frau','frau');
$form->addGroup($name,'anrede', 'Anrede:','<br />',false);17.9.4 Verarbeitung des Formulars
In den meisten Fällen werden heutzutage Affenformulare eingesetzt. Das heißt, es handelt sich um eine PHP-Datei, die das Formular ausgibt und dann dafür sorgt, dass das Formular dieselbe Datei wieder aufruft, da die Daten in dieser Datei auch verarbeitet werden.
Dazu stellt sich natürlich die Frage, wie Sie am einfachsten feststellen, ob das Formular ausgegeben werden soll oder ob das Formular bereits abgeschickt wurde. Die Methode getSubmittedValues() prüft, ob Werte übergeben wurden, und liest diese aus. Wurden keine Werte an die Seite übergeben, ist der Rückgabewert der Methode false.
require_once('HTML/QuickForm.php');
// Neues Datumsobjekt
$form=new HTML_QuickForm('eingabe','get',
$_SERVER['PHP_SELF']);
$form->addElement('text','name','Name');
$form->addElement('submit','abschicken','Abschicken');
// Daten auslesen
$daten=$form->getSubmitValues();
// Wurde das Feld abschicken uebergeben?
if (false===isset($daten['abschicken']))
{
// Nein => Formular ausgeben
$form->display();
}
else
{
// Daten verarbeiten
}Listing 17.19 Einfache Verarbeitung eines Formulars
Möchten Sie nicht alle Werte auf einmal auslesen, steht auch die Methode getSubmitValue() zur Verfügung. Diese bekommt den Namen eines Formularelements übergeben und gibt seinen Wert zurück.
Auf den ersten Blick mag sich die Frage stellen, ob man nicht gleich mit $_POST arbeiten sollte, wenn getSubmitValues() doch sowieso ein Array zurückgibt. Der Vorteil besteht darin, dass Sie sich keine Gedanken über die verwendete Methode machen müssen und somit nicht zwischen $_GET und $_POST unterscheiden müssen.
Ich möchte auch darauf hinweisen, dass die Formularelemente bewusst vor der if-Abfrage initialisiert wurden. In diesem Fall wäre das zwar nicht nötig. Es ist aber Standard bei der Arbeit mit QuickForm, die Elemente frühzeitig zu initialisieren, da die validierenden Funktionen, die Sie gleich kennen lernen werden, das voraussetzen.
Die oben beschriebene Vorgehensweise hat allerdings den Nachteil, dass die Gliederung des gesamten Quellcodes mithilfe einer großen if-Abfrage schnell unübersichtlich wird. Um solche Probleme zu vermeiden, sieht das Paket die Nutzung einer Callback-Funktion vor. Hierbei handelt es sich um eine normale Funktion, die durch das Paket aufgerufen werden kann und der dann alle Werte übergeben werden, die aus dem Formular extrahiert wurden.
Obiges Beispiel, erweitert um eine Callback-Funktion, könnte so aussehen wie in Listing 17.20.
function daten_verarbeiten ($val)
{
echo "Sie gaben ein: $val[name]";
}
// Neues Datumsobjekt
$form=new HTML_QuickForm('eingabe','post',
'$_SERVER[PHP_SELF]');
$form->addElement('text','name','Name');
$form->addElement('submit','abschicken','Abschicken');
$daten=$form->getSubmitValues();
if (false===isset($daten['abschicken']))
{
$form->display();
}
else
{
$form->process('daten_verarbeiten');
}Listing 17.20 Nutzung einer Callback-Funktion
Die Methode process() bekommt den Namen der Funktion übergeben und ruft sie dann auf. Angenehm ist, dass Sie sich keine Gedanken über die Funktionsparameter machen müssen. Alle Werte, die aus dem Formular übernommen wurden, werden in einem Array übergeben. Somit kann in der Funktion auf $val[name] zugegriffen werden.
17.9.5 Filter
Ein weiteres sehr schönes Feature dieses Pakets ist die Unterstützung von Filtern. Hierbei handelt es sich um Funktionen, die einen String übergeben bekommen, diesen verarbeiten und wieder zurückgeben. Bei den Funktionen darf es sich sowohl um native PHP- als auch um selbst erstellte Funktionen handeln.
Ein solcher Filter kann mit der Methode applyFilter() hinzugefügt werden. Ihr werden der Name des Elements und der des Filters übergeben. Um beispielsweise alle Whitespaces vor und hinter einer Eingabe zu entfernen, in diesem Fall das Formular-Feld vorname, könnten Sie trim() als Filter nutzen.
Wie erwähnt können Sie auch selbst Funktionen spezifizieren, die als Filter dienen sollen. Wichtig ist nur, dass die Funktion einen String als Parameter akzeptiert und auch einen String zurückgibt.
// Macht den ersten Buchstaben groß und den Rest klein
function my_filter ($str)
{
return ucfirst(strtolower($str));
}
$form->applyFilter('vorname','my_filter');Sollten Sie es wünschen, so können Sie einem Feld auch mehrere Filter zuordnen. Diese werden in der Reihenfolge abgearbeitet, in der Sie sie zugewiesen haben.
Möchten Sie einen Filter auf alle Formularelemente anwenden, können Sie anstatt der Namen die Konstante __ALL__ angeben.
17.9.6 Serverseitige Validierung
Wie ich am Anfang des Kapitels erwähnt habe, unterstützt HTML_QuickForm auch eine automatische Validierung der eingegebenen Werte. Hierzu sind so genannte Rules vorgesehen. Mit diesen Regeln können Sie festlegen, welches Element welchen Inhalt haben oder angeklickt sein soll.
Jede Regel, die überwacht werden soll, muss mithilfe von addRule() beim System angemeldet werden. Die Methode validate() übernimmt die Prüfung der Regeln und bestätigt ihre Einhaltung mit einem true oder gibt false zurück, wenn die Regeln nicht erfüllt wurden.
$form=new HTML_QuickForm('eingabe','post',
"$_SERVER[PHP_SELF]");
// Erlaeuterung fuer den *
$form->setRequiredNote('<span style="font-size:80 %;
color:#ff0000;">*</span><span style="font-size:80 %;">
markiert ein erforderliches Feld</span>');
$form->addElement('text','vorname','Vorname');
$form->addElement('text','nachname','Nachame');
$form->addElement('submit','abschicken','Abschicken');
// Filter zum Entfernen von Whitespaces
$form->applyFilter('nachname','trim');
// Regel hinzufuegen
$form->addRule('nachname','Bitte Namen eingeben','required');
// Validierung in Ordnung?
if (false==$form->validate())
{ // Formular ausgeben
$form->display();
}
else
{ // Callback-Funktion aufrufen
$form->process('daten_verarbeiten');
}Listing 17.21 Validierendes Formular mit HTML_QuickForm
Das Verhalten des Formulars im Browser sehen Sie in Abbildung 17.7 und Abbildung 17.8.
Abbildung 17.7 Formular beim ersten Aufruf
Beim ersten Aufruf der Datei wird also das normale Formular angezeigt. Pflichtfelder werden mit einem Stern markiert. Unter dem Formular wird eine Erläuterung angezeigt, was der Stern zu bedeuten hat. Geben Sie keinen anderen Text vor, nutzt das Paket den Text »* denotes a required Field«. Um diesen Text zu ersetzen, ist die Methode setRequiredNote() vorgesehen, die den entsprechenden String übergeben bekommt.
Abbildung 17.8 Fehlerhaft ausgefülltes Formular
In Abbildung 17.8 sehen Sie ein Formular, das unvollständig ausgefüllt abgeschickt wurde.
Der Filter trim sorgt dafür, dass Leerzeichen, die eventuell in das Feld für den Nachnamen eingegeben wurden, entfernt werden, und die Regel, die nachfolgend mit addRule() hinzugefügt wird, definiert, dass das Feld vorname einen Inhalt haben muss. Die Einhaltung dieser Regel wird dann wiederum von validate() geprüft. Stellt validate() fest, dass die Regel bzw. eine der Regeln, wenn Sie mehrere definiert haben, nicht eingehalten wurde, wird das Formular noch mal ausgegeben. Für die Felder, die die Regel nicht erfüllt haben, wird die Meldung eingeblendet, die der Methode addRule() übergeben wurde. addRule() bekommt den Namen eines zu prüfenden Formularelements, den Text, der bei einer Verletzung der Regel ausgegeben werden soll, sowie den Namen der Regel übergeben.
Einige Regeln erwarten noch weitere Parameter, wie beispielsweise minlength, mit der Sie die minimale Länge eines erforderlichen Feldes definieren können. Möchten Sie festlegen, dass ein Feld einen Text mit mindestens 5 Zeichen Länge zurückgeben muss, könnte das so lauten:
$form->addRule('nachname','Name erforderlich','required');
$form->addRule('nachname','Name muss mindestens 5 Zeichen lang
sein,'minlength',5);Dass hier zwei Filter genutzt werden, hat einen einfachen Grund. Würde der Benutzer das Feld komplett leer lassen, greift die Regel minlength gar nicht. Das mag zwar etwas kurios erscheinen, aber ein nicht vorhandener Text kann eben auch nicht zu kurz sein.
In Tabelle 17.4 finden Sie die momentan definierten Filter.
| Rule | Erläuterung |
| required | Das Element muss einen Wert zurückgeben. |
| maxlength | Maximale Länge des Rückgabewertes; erfordert einen weiteren Parameter. |
| minlength | Minimal erforderliche Länge des Rückgabewertes; erfordert einen weiteren Parameter. |
| rangelength | Definiert einen Bereich, in dem sich die Länge der Eingabe bewegen muss. Benötigt als zweiten Parameter ein Array aus zwei Integer-Zahlen; die die Ober- und Untergrenze definieren. |
| Prüft den Rückgabewert auf Basis eines regulären Ausdrucks daraufhin, ob es sich um eine E-Mail-Adresse handelt. | |
| regex | Dieser Filter erwartet einen weiteren Parameter, in dem ein regulärer Ausdruck in PCRE-Syntax definiert wird. Der übergebene Wert wird daraufhin geprüft, ob er dem Ausdruck entspricht. |
| lettersonly | Akzeptiert nur Buchstaben im Rückgabewert. |
| alphanumeric | Testet den übergebenen Wert daraufhin, ob er nur aus Buchstaben und Zahlen besteht. |
| numeric | Akzeptiert Werte, die nur aus Zahlen und dem Dezimalpunkt bestehen. |
| nopunctuation | Definiert, dass der geprüfte Wert keine Satzzeichen enthalten darf. Unzulässig sind die Zeichen ^ ( )./ * ? # ! @ $ % + = , " ' > < ~ [ ] { } |
| nonzero | Erwartet eine Zahl, die nicht mit Null beginnen darf. |
| compare | Dieser Regel vergleicht zwei Felder miteinander. Die Namen der Felder werden an erster Stelle als Array übergeben. Als zusätzlicher Parameter muss der gewünschte Vergleichsoperator übergeben werden. Schlägt die Regel fehl, wird die Fehlermeldung bei dem Feld ausgegeben, das im Array an erster Stelle steht. |
Um herauszufinden, welche Filter in der gerade aktuellen Version von HTML_QuickForm vorhanden sind, können Sie die Methode getRegisteredRules() nutzen, die Ihnen die Namen aller bekannten Filter als Array zurückgibt.
Sie können zusätzlich auch eigene Regeln definieren, auf deren Basis ein Rückgabewert geprüft wird. Eine solche Regel kann auf Basis eines regulären Ausdrucks oder einer Funktion deklariert werden.
Reguläre Ausdrücke können zwar, wie oben beschrieben, auch direkt übergeben werden, aber wenn Sie einen regulären Ausdruck mehrfach nutzen möchten, dann ist es geschickter, ihn einmal als Regel zu definieren und ihn dann über den Namen der Regel ansprechen zu können.
Um eine neue Regel zu definieren, ist die Methode registerRule() vorgesehen. Die Methode bekommt als ersten Parameter den Namen übergeben, den die Regel bekommen soll. Der zweite definiert, ob es sich um einen regulären Ausdruck ('regex') oder eine Funktion ('callback') handelt. Der dritte Parameter enthält entweder den regulären Ausdruck oder den Namen der Funktion, die als Callback genutzt werden soll.
Um eine Eingabe daraufhin zu prüfen, ob sie eine gültige Postleitzahl enthalten könnte, wären folgende Zeilen hilfreich:
$form->registerRule('rule_plz','regex','/^\d{5}$/');
$form->addRule('plz','Bitte korrekte PLZ eingeben',
'rule_plz');Hiermit würde also der reguläre Ausdruck /^\d{5}$/ als Regel unter dem Namen rule_plz registriert. Erfüllt die Eingabe die Regel des regulären Ausdrucks nicht, wird das Formular nochmals mit einer Fehlermeldung ausgegeben.
Wie bereits erwähnt wurde, können Sie auch komplette Funktionen zur Prüfung eines Inhalts nutzen:
function plz_test ($value, $din=false)
{
if (false === $din)
{
$regex='/^\d{5}$/';
}
else
{
$regex='/^[Dd]{1}-\d{5}$/';
}
return preg_match($regex,$value);
}
// Registrieren der Funktion als Rule
$form->registerRule('rule_plz','callback','plz_test');
$form->addRule('plz','Bitte korrekte PLZ eingeben',
'rule_plz',true);Die Funktion bekommt als ersten Parameter den Wert des Formular-Feldes übergeben. Der zweite Parameter, der hier deklariert wird, ist nicht zwingend vorgeschrieben. In diesem Fall eröffnet er die Möglichkeit, zwischen zwei Arten von Postleitzahlen (33619 und D-33619) zu unterscheiden. Dieser Parameter kann beim Hinzufügen der Rule mittels addRule() nach dem Namen der Regel angehängt werden. Natürlich können Sie hier auch ein Array übergeben.
Wenn Sie mehrere Felder gleichzeitig überprüfen oder zueinander in Beziehung setzen wollen, ist das auch mit einer Callback-Funktion möglich.
Fügen Sie die Regel z. B. mit
$elements = array ('vorname', 'nachname', 'firma');
$form->addRule($elements,'Werte nicht korrekt', 'my_rule');hinzu, dann wird der Funktion, die für diese Regel genutzt wurde, ein indiziertes Array mit den Werten der Felder vorname, nachname und firma übergeben.
Regeln für Gruppen
Da es möglich ist, Elemente zu Gruppen zusammenzufassen, können Sie auch Regeln für ganze Gruppen festlegen. Das kann beispielsweise dann sehr praktisch sein, wenn Sie eine Gruppe von Checkboxen haben, bei der mindestens eine angeklickt werden soll.
// Drei Checkboxen
$checkbox[] = HTML_QuickForm::createElement('advcheckbox',
'mail',null, 'E-Mail');
$checkbox[] = HTML_QuickForm::createElement('advcheckbox',
'fax', null, 'Fax');
$checkbox[] = HTML_QuickForm::createElement('advcheckbox',
'telefon', null, 'Telefon');
// Gruppe hinzufuegen
$form->addGroup($checkbox, 'kontakt',
'Wie dürfen wir Sie kontaktieren?', '<br />');
// Regel hinzufuegen
$form->addGroupRule('kontakt', 'Wählen Sie mindestens
eine Kontaktart', 'required', null,1);Die drei Checkboxen werden in der Gruppe kontakt zusammengefasst. Die anzuwendende Regel wird mithilfe der Methode addGroupRule() zugewiesen, die den Namen der Gruppe, eine Fehlermeldung, die über der Gruppe eingeblendet wird, und die Regel, in diesem Fall required, zugewiesen bekommt. Der Parameter nach dem Regelnamen, in diesem Beispiel null, ist für zusätzliche Daten gedacht, die die Regel benötigt. Wäre die Regel also beispielsweise regex, würde hier der reguläre Ausdruck stehen. Die 1, die hier als letzter Parameter übergeben wird, definiert, wie viele Elemente die Regel mindestens erfüllen müssen. Stände hier eine 2, müssten zwei Checkboxen selektiert sein.
Es ist auch möglich, die einzelnen Elemente einer Gruppe einzeln zu prüfen. In folgendem Beispiel werden eine Postleitzahl und ein Ortsname erfragt. Beide Werte sind erforderlich. Die PLZ soll exakt fünf Ziffern aufweisen und darf ein D- vor der Zahl haben. Der Ortsname muss dabei länger als zwei Zeichen sein und darf nur auch aus Buchstaben, dem Leerzeichen, dem Slash und dem Punkt bestehen.
// Elemente fuer das Formular
$Adresse[] = HTML_QuickForm::createElement('text', 'plz',
'','size="5"');
$Adresse[] = HTML_QuickForm::createElement('text', 'ort', '',
'size="15"');
$form->addGroup($Adresse, 'adresse', 'PLZ und Ort:'
,array(' ','<br />'));
// Filter zum Entfernen von Whitespaces
$form->applyFilter('__ALL__','trim');
// Regeln hinzufuegen
$form->addGroupRule('adresse', array(
'plz' => array( // Regeln fuer die PLZ
array('Sie müssen eine PLZ angeben','required'),
array('Die PLZ ist ungültig', 'regex',
'/^(D-)?\d{5}$/i')
),
'ort' => array( //Regeln fuer den Ort
array('Der Ortsname ist erforderlich','required'),
array('Der Ortsname ist zu kurz','minlength',2),
array('Der Ortsname enthält ungültige
Zeichen','regex','/^[ a-z\/\.äöüß]+$/i'),
)
));Die Regeln für die Elemente müssen in Form eines Arrays übergeben werden. Der Schlüssel ist hierbei der Name des Formularelements. Dieser verweist seinerseits wieder auf ein Array aus Arrays. Innerhalb dieser Arrays werden die notwendigen Informationen spezifiziert. Die Reihenfolge und Anzahl der Parameter richtet sich dabei nach den Parametern, die addRule() übergeben bekommen würde.
17.9.7 Clientseitige Validierung
QuickForm bietet Ihnen auch die Möglichkeit, die Daten direkt beim Client prüfen zu lassen. Der hierfür notwendige JavaScript-Code wird automatisch generiert und in das Formular eingebunden. Eine zusätzliche Überprüfung auf dem Server findet auf jeden Fall auch noch statt.
Möchten Sie eine zusätzliche clientseitige Prüfung der Regeln nutzen, übergeben Sie der Methode addRule() zusätzlich zu den schon erwähnten Parametern noch den String 'client'. Zusätzlich ist es möglich, noch einen booleschen Wert zu ergänzen, der definiert, ob das Formularelement, das gegen die Regel verstoßen hat, wieder auf seinen ursprünglichen Wert zurückgesetzt werden soll.
require_once('HTML/QuickForm.php');
$form=new HTML_QuickForm('');
// Erlaeuterungstext definieren
$form->setRequiredNote('<span style="font-size:80 %;
color:#ff0000;">*</span><span style="font-size:80 %;">
markiert ein erforderliches Feld</span>');
// JavaScript-Warnung ergaenzen
$form->setJsWarnings('Folgende Fehler sind aufgetreten',
'Bitte korrigieren Sie diese Felder');
// Elemente hinzufuegen
$form->addElement('text','plz','PLZ');
$form->addElement('text','ort','Ort');
$form->addElement('submit','submit','Abschicken');
$form->applyFilter('__ALL__','trim');
// Rules festlegen
$form->addRule('plz','PLZ ist erforderlich','required',
'','client');
$form->addRule('plz','PLZ nicht korrekt','regex',
'/^(D-)?\d{5}$/i','client',true);
$form->addRule('ort','Ort erforderlich','required',
'','client');
// Serverseitige Validierung
if (false==$form->validate())
{
$form->display();
}
else
{
$form->process('daten_verarbeiten');
}Listing 17.22 Formular mit client- und serverseitiger Prüfung
Die Methode setJSWarnings(), die am Anfang genutzt wird, dient dazu, die von JavaScript generierte Fehlermeldung mit deutschen Texten zu versehen. Die Meldungen, die für die Regeln definiert wurden, werden eins zu eins übernommen. Zusätzlich wird aber noch vor und hinter den Fehlermeldungen ein Text ausgegeben. Der erste String, den Sie hier übergeben, wird über und der zweite unter den Regel-Meldungen ausgegeben, wie Sie in Abbildung 17.9 erkennen können.
Da die Fehlermeldungen der Rules auch für die JavaScript-Ausgabe genutzt werden, ist es nicht möglich, mit Entitäten wie ä etc. zu arbeiten. Sie müssten also entweder mit Umlauten arbeiten, oder Sie dürfen einfach keine Wörter mit Umlauten benutzen.
Abbildung 17.9 Ausgabe der Fehlermeldung im Browser
17.9.8 Datei-Uploads
Das Paket sieht einige Funktionalitäten vor, um den Upload von Dateien zu handhaben. Die hierbei angebotenen Möglichkeiten gehen über das hinaus, was man von einem Paket zur Ausgabe von Formularen erwarten würde.
Zum Ersten sind spezielle Rules zur Handhabung von Dateien definiert, die Sie in Tabelle 17.5 finden.
| Rule | Erläuterung |
| maxfilesize | Die Regel erwartet noch einen weiteren Wert, der die maximal erlaubte Dateigröße definiert. |
| mimetype | Mit dieser Regel können zulässige MIME-Types definiert werden. Sie benötigt als zweiten Parameter einen String oder ein Array von Strings, in dem jeweils ein zulässiger MIME-Type enthalten ist. |
| filename | Erwartet einen zusätzlichen Parameter, der in Form eines regulären Ausdrucks (Perl-kompatibel) definiert, welcher Dateiname akzeptabel ist. |
Nachdem eine Datei auf den Server hochgeladen wurde, können Sie ein HTML_QuickForm_File-Objekt ableiten, in dem die Informationen zu dieser Datei enthalten sind. Die Instanziierung des Elements übernimmt die Methode getElement() für Sie, der Sie den Namen des Formularelements übergeben müssen. Nachdem das Objekt abgeleitet wurde, steht Ihnen die Methode moveUploadedFile() zur Verfügung. Sie kann die hochgeladene Datei, die ja erst in einem temporären Verzeichnis abgelegt wird, an ihren Bestimmungsort verschieben. Die Methode bekommt das Zielverzeichnis übergeben und akzeptiert als zweiten, optionalen Parameter den Namen, den die Datei bekommen soll. Übergeben Sie keinen Namen, wird der ursprüngliche Name genutzt. Die Methode nutzt intern die PHP-Funktion move_uploaded_file(). Diese kann fehlschlagen, wenn das temporäre und das Zielverzeichnis auf physikalisch unterschiedlichen Festplatten liegen. Sollte ein Fehler während des Verschiebens auftauchen, teilt die Methode Ihnen das dadurch mit, dass sie ein false zurückliefert. In dem Fall können Sie einen zweiten Kopiervorgang mit der PHP-Funktion copy() versuchen.
In dem HTML_QuickForm_File-Objekt sind mehr Informationen enthalten als in den anderen Rückgabewerten. Die Methode getValue() liest die enthaltenen Daten aus und gibt ein Array zurück, das die Schlüssel aus Tabelle 17.6 enthält.
| Schlüssel | Wert |
| name | Name, den die Datei beim Client hatte |
| type | MIME-Type der Datei |
| tmp_name | Temporärer Name der Datei auf dem Server |
| size | Größe der Datei in Byte |
| error | Eventueller Fehlercode |
Im Schlüssel error können Fehlercodes enthalten sein, mit denen etwaige Probleme beim Upload erkannt werden können. 0 bedeutet, dass der Upload erfolgreich war. 1 bedeutet, dass die Datei größer war als die Vorgabe der Konfigurationsdirektive upload_max_filesize. Lesen Sie eine 2 aus, ist die Datei größer als die Vorgabe aus dem Formular, die mit dem Feld MAX_FILE_SIZE übergeben wurde. 3 bedeutet, dass die Datei nur zum Teil übertragen wurde, und 4 sagt aus, dass keine Datei hochgeladen wurde.
require_once('HTML/QuickForm.php');
// Variable mit maximaler Dateigroesse
$maxfilesize=20*1024; // 20 KB
$form=new HTML_QuickForm('');
$form->addElement('file','datei','Datei (nur JPG bis 20KB)');
$form->setMaxFileSize($maxfilesize);
$form->addElement('submit','submit','Abschicken');
// Regel zum Pruefen der Dateigroesse
$form->addRule('datei','Datei zu groß','maxfilesize',
$maxfilesize);
// Regel zum Pruefen des MIME-Types
$form->addRule('datei','Nur JPG erlaubt','mimetype',
'image/jpeg');
if (false===$form->validate())
{
$form->display();
}
else
{
// Daten auslesen
$datei = $form->getElement('datei');
$daten= $datei->getValue();
// Fehler aufgetreten?
if (0!=$datei['error'])
{
echo 'Ein Fehler ist aufgetreten';
}
else
{
// Datei verschieben
if (false === $datei->moveUploadedFile('/daten'))
{
if (false===copy ($daten['tmp_name'],
"/daten/$daten[name]"))_$ret_ {
die ('Konnte Datei nicht kopieren ');
}
}
// Informationen zur Datei ausgeben
echo "Name: $daten[name]<br />";
echo "MIME-Type: $daten[type]<br />";
echo "Temporärer Name: $daten[tmp_name]<br />";
echo "Größe: $daten[size]<br />";
}
}Listing 17.23 Upload einer Datei mit HTM_QuickForm
17.9.9 Templates
Zwar sind die Möglichkeiten zur Formatierung, die HTML_QuickForm bietet, schon relativ flexibel, aber in einigen Fällen mag die vorgegebene Tabellenstruktur nicht unbedingt das sein, was Sie benötigen.
In solchen Fällen können Sie selbst Templates erstellen und mit QuickForm nutzen. Solche Templates stellen Vorlagen dar, wie Inhalte formatiert werden sollen. Sie können mit allen relevanten Teilen eines QuickForm-Formulars genutzt werden. Eine solche Formatierungsvorlage können Sie also sowohl für einzelne Elemente als auch für Gruppen von Elementen definieren.
Im folgenden Beispiel sollen die Erläuterungen, was in ein Feld einzugeben ist, nicht links daneben, sondern direkt über dem Feld stehen. Des Weiteren sollen die Fehlermeldungen unter dem Eingabefeld erscheinen.
Um dies zu gewährleisten, sollen die einzelnen Formulare jeweils in eigenständige Tabellen ausgegeben werden.
$form=new HTML_QuickForm('');
// Renderer – Objekt ableiten
$renderer = $form->defaultRenderer();
// Text fuer erforderliche Felder
$form->setRequiredNote('<span style="font-size:80 %;
color:#ff0000;">*</span><span style="font-size:80 %;">
markiert ein erforderliches Feld</span>');
// Template fuer das gesamte Formular
$renderer->setFormTemplate ('
<form {attributes}>
<table><tr><td>
{content}
</td></tr></table>
</form>');
// Template fuer ein Element
$renderer->setElementTemplate ('
<table>
<tr><td>
{label}
<!-- BEGIN required -->
<span style="color: #ff0000">*</span>
<!-- END required -->
</td></tr>
<tr><td>
{element}
</td></tr>
<tr><td>
<!-- BEGIN error -->
<span style="color: #ff0000">
{error}
</span>
<!-- END error -->
</td></tr>
</table>');
// Template fuer die "required Note"
$renderer->setRequiredNoteTemplate('
<tr><td><b>{requiredNote}</b></td></tr>');
// Felder hinzufuegen
$form->addElement('text','vorname','Vorname');
$form->addElement('text','nachname','Nachname');
$form->addElement('submit','submit','Abschicken');
// Regeln hinzufuegen
$form->addRule('vorname','Vorname erforderlich','required');
$form->addRule('nachname','Nachname erforderlich','required');
// Verarbeitung des FormularsDie Darstellung des Formulars sehen Sie in Abbildung 17.10.
In diesem Beispiel wurden drei unterschiedliche Arten von Templates genutzt. Um diese Vorlagen einbinden zu können, benötigen Sie eine Objekt-Instanz des Renderers. Da der Renderer später für die Ausgabe des HTML-Codes zuständig ist, müssen die neuen Templates bei ihm angemeldet werden. Das Einbinden einer zusätzlichen Datei ist dabei nicht nötig.
Abbildung 17.10 Formular auf Basis von eigenen Templates
Das erste der drei Templates bezieht sich auf das gesamte Formular. Dieses muss mindestens aus dem öffnenden und schließenden <form>-Tag bestehen. In diesem Fall wurde noch eine zusätzliche Tabelle genutzt. Damit QuickForm die Vorlage nutzen kann, muss klar definiert sein, an welchen Stellen die Inhalte einzufügen sind. Die Platzierung der Attribute wird bei der Formular-Vorlage mit dem Platzhalter {attributes} definiert. Die Stelle, an der das eigentliche Formular eingefügt wird, ist durch die Position von {content} definiert. Der Hinweis, welche Felder erforderlich sind, wird automatisch nach dem letzten Element eingefügt und kann hier nicht verschoben werden.
Mit setElementTemplate() wird das Template für ein Element definiert. Wenn Sie die Methode nur mit dem Code für die Vorlage als ersten Parameter aufrufen, wird diese für alle Elemente genutzt. Sie können allerdings als zweiten Parameter noch den Namen eines Elements angeben, so dass dieses Template dann nur für dieses eine Element genutzt wird. Innerhalb dieses Templates muss mindestens der Platzhalter {element} vorhanden sein, an dessen Stelle das Formularelement eingefügt wird. Der Text, der rechts neben Radio-Buttons und Checkboxen ausgegeben wird, wird als Teil des Formularelements betrachtet und auch an dieser Stelle ausgegeben.
Der Platzhalter {label} definiert, wo der erläuternde Text ausgegeben wird, der normalerweise links neben dem Element steht. Ist ein Feld als »required« eingestuft, muss das System erkennen können, wo der Stern oder Hinweis ausgegeben werden soll, der darauf hinweist. Dies wird nicht durch einen Platzhalter im eigentlichen Sinne, sondern durch eine Art if-Abfrage realisiert. Diese wird durch die Platzhalter <!-- BEGIN required --> und <!-- END required --> erzeugt. Haben Sie einem Feld die Regel required zugewiesen, wird der Text eingeblendet, der zwischen den beiden Platzhaltern steht.
Die gleiche Technik wird auch bei dem Token {error} genutzt, das durch die Fehlermeldung einer Regel ersetzt werden kann. Da nicht immer ein Fehler ausgegeben wird, wird dieser Platzhalter in <!-- BEGIN error --> und <!-- END error --> eingeschlossen.
Das letzte hier genutzte Template ist das für die »required Notice«, also die Erläuterung, wie Pflichtfelder markiert sind. Hier wird nur der Platzhalter {requiredNote} unterstützt.
Fassen Sie Elemente zu Gruppen zusammen, können Sie dafür spezielle Templates definieren. Mit der Methode setGroupElementTemplate() kann ein Template für die Elemente selbst definiert werden. Hierbei werden die Platzhalter {element}, {label} und {error} unterstützt. Für die gesamte Gruppe kann mithilfe von setGroupTemplate() ein Template vorgegeben werden. Hierbei wird allerdings nur das Token {content} unterstützt, an dessen Stelle die Formularelemente eingefügt werden. Somit ist es bei der Arbeit mit einem eigenen Gruppen-Template möglich, ein Label zu nutzen. Ein wenig kurios ist, dass die Methode setGroupTemplate() den Namen einer Gruppe als zweiten Parameter benötigt.
Bei allen Templates, in denen Sie den Platzhalter {label} nutzen können, ist übrigens auch der Platzhalter {label_2} zulässig. Damit können Sie dem Element jeweils noch einen erläuternden Text zuweisen. Möchten Sie einen zweiten Text nutzen, müssen Sie der Methode addElement() die Texte in Form eines Arrays übergeben.
$form->addElement('text', 'plz',
array('PLZ:', 'Format 12345 oder D-12345'));Last but not least können Sie auch explizit eine Formatierungsvorlage für Header-Elemente erstellen. Hierzu nutzen Sie die Methode setHeaderTemplate(), die den Platzhalter {header} unterstützt.
