Einführung
Der Zweck des Tutorials ist es neuen Benutzer einen Überblick über die Funktionen
und die Benutzung von QuickForm zu vermitteln.
Es beschreibt nur einen kleinen Teil der verfügbaren Funktionen, zeigt aber auch auf
die Teile der Dokumentation, die eine tiefere Erklärung bieten.
Es existiert auch ein umfangreicheres Tutorial unter
http://www.midnighthax.com/quickform.php
von Keith Edmunds.
Your first form
Beispiel 42-1. Grundlegende QuickForm-Benutzung // Load the main class
require_once 'HTML/QuickForm.php';
// Instantiate the HTML_QuickForm object
$form = new HTML_QuickForm('firstForm');
// Set defaults for the form elements
$form->setDefaults(array(
'name' => 'Joe User'
));
// Add some elements to the form
$form->addElement('header', null, 'QuickForm tutorial example');
$form->addElement('text', 'name', 'Enter your name:', array('size' => 50, 'maxlength' => 255));
$form->addElement('submit', null, 'Send');
// Define filters and validation rules
$form->applyFilter('name', 'trim');
$form->addRule('name', 'Please enter your name', 'required', null, 'client');
// Try to validate a form
if ($form->validate()) {
echo '<h1>Hello, ' . htmlspecialchars($form->exportValue('name')) . '!</h1>';
exit;
}
// Output the form
$form->display(); |
|
Schauen wir das Beispiel Schritt für Schritt an.
Aufbau des Formulars
Die Zeile
$form = new HTML_QuickForm('firstForm'); |
erzeugt ein
HTML_QuickForm-Objekt, das die Objekte für die einzelnen Elemente
und Zusatzinformationen enthält.
Wir übergeben nur einen Namen für den Formular-
Konstruktor,
damit werden die voreingestellten Werte für die übrigen Parameter benutzt.
Insbesondere wird die Sendemethode auf
POST gesetzt und der
action-Parameter auf den aktuellen Skriptnamen. Mit
QuickForm ist es einfach die Logik für die Formularverarbeitung
innerhalb eines Skriptes zu platzieren.
Sie werden vermuten, dass
$form->setDefaults(array(
'name' => 'Joe User'
)); |
den Wert
'Joe User' als Voreinstellung für das
name-Element setzt.
QuickForm unterstützt voreingestellte Werte
(über die
setDefaults()
-Methode) und Konstante-Werte (über
setConstants()).
Der Unterschied ist, dass Benutzereingabe voreingestellte Werte überschreiben aber keine Konstanten.
Das Formular besteht aus drei Elementen:
$form->addElement('header', null, 'QuickForm tutorial example');
$form->addElement('text', 'name', 'Enter your name:', array('size' => 50, 'maxlength' => 255));
$form->addElement('submit', null, 'Send'); |
Das Erste ist kein echtes Element, es ist nur eine Überschrift um die Darstellung zu verbessern.
Das zweite Element ist eine Texteingabebox und das Dritte ein Submit-Button.
Beachten Sie, dass die Parameter für die Methode
addElement()
sich bei den verschiedenenen Elementen unterscheiden. Das liegt daran, dass sie an den Konstruktor
des Elements weitergereicht werden.
Checking input
Die Zeile
$form->applyFilter('name', 'trim'); |
definiert einen
Filter
für das
'name'-Element - die Funktion wird auf den Wert angewendet, nach dem
dieser abgeschickt wird.
In diesem Fall wird die eingebaute Funktion
trim()
aufgerufen, es kann aber mögliche Funktion per
Callback
aufgerufen werden.
In diesem Fall werden alle Leerzeichen vom Namen entfernt, da wir diese nicht brauchen und
ausserdem sichergehen wollen, dass der eingegebene Name nicht nur aus Leerzeichen bestehen.
Als nächstes definieren wir eine
Regel für das Namensfeld:
$form->addRule('name', 'Please enter your name', 'required', null, 'client'); |
Das bedeutet, dass QuickForm eine Fehlermeldung anzeigt, wenn kein Name eingegeben wurde.
Die Angabe
'client' erzwingt die Prüfung per JavaScript bereits
beim Client erfolgt, zusätzlich zur Prüfung auf der Serverseite.
QuickForm kennzeichnet automatisch Elemente, die ausgefüllt werden müssen.
Prüfung und Verarbeitung
Das Formular wurde erzeugt und die Regeln definiert, jetzt müssen entscheiden,
ob das Formular erzeugt oder dargestellt werden soll:
if ($form->validate()) {
// Do some stuff
} |
Die
validate()-Methode
liefert
TRUE zurück, wenn Daten über das Formular abgeschickt wurden und alle Regeln eingehalten wurden.
Was in unserem Fall heisst: das
name-Element war nicht leer.
Wenn das Formular überprüft wurde, können die Werte verarbeitet werden:
echo '<h1>Hello, ' . htmlspecialchars($form->exportValue('name')) . '!</h1>';
exit; |
Das ist nur ein Beispiel, im realen Umfeld würden Sie Werte speichern und auf eine andere
Seite weiterleiten, um Mehrfacheingaben zu verhindern. Die Methoden
process()
und
exportvalues()
können hier von Interesse für Sie sein.
Die letzte Zeile ist einfach zu verstehen:
Wenn das Formular nicht validiert werden konnte, was bedeutet, dass es noch nicht
abgeschickt wurde oder es Fehler bei der Eingabe gab, dann wird es dargestellt.
Traten Eingabefehler auf, dann werden die beim verursachenden Formularelement
dargestellt.
Fortgeschrittenen Funktionen
Sie sollten nun ein grundsätzliches Verständnis davon besitzen, wir QuickForm funktioniert.
Es gibt viele weitere Funktionen, die vom Package bereitgestellt werden, diese werden
in seperaten Tutorials vorgestellt. Dieser Abschnitt zeigt einen Überblick über die
Zusatzfunktionen.
Gruppen erlauben
die Zusammenführung mehrerer Einzelelemente zu einem logischen Element.
Sie werden dazu benutzt um Pseudo-Elemente zu erzeugen wie date oder
hierselect.
QuickForm bietet viele Möglichkeiten um das Formularlayout und -aussehen anzupassen.
Die Formularausgabe erfolgt über
Renderer -
spezielle Klassen, welche die notwendige Logik enthalten. Es gibt Renderer, die
direkt HTML ausgeben
und welche
Templates dafür benutzen.
Und letztlich ist es auch möglich QuickForm zu erweitern, in dem
Sie eigene Elemente, Regeln und
Renderer
ergänzen.