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.
Grundlegende QuickForm-Benutzung
<?php
// 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.
Die Zeile
<?php
$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
<?php
$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:
<?php
$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.
Die Zeile
<?php
$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:
<?php
$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.
Das Formular wurde erzeugt und die Regeln definiert, jetzt müssen entscheiden, ob das Formular erzeugt oder dargestellt werden soll:
<?php
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:
<?php
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:
<?php
$form->display();
?>
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.
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.