17.8 HTML_Form 
| Besprochene Version: 1.1.1 | Lizenz: PHP-Lizenz 3.0 |
| Klassendatei(en): HTML/Form.php | |
HTML_Form ist ein einfaches, aber leistungsfähiges Paket, um Formulare auszugeben. Der Fokus liegt hierbei darauf, die entsprechenden HTML-Tags zu generieren bzw. auszugeben. Eine automatische Prüfung von Eingaben ist nicht vorgesehen.
Die Methoden, die HTML_Form kennt, gliedern sich in drei Gruppen. Zum ersten sind das die Methoden, die mit add beginnen. Mit diesen kann man ein Formular im Speicher aufbauen und dann komplett ausgeben. In dem Fall werden die Formularfelder automatisch mithilfe einer HTML-Tabelle ausgerichtet.
Der zweite »Betriebsmodus« dient zur direkten Ausgabe von Formularelementen. Diese Methoden, die alle mit display beginnen, geben entweder nur ein Formularelement oder ein Formularelement in einer kompletten Tabellenzeile aus.
Der letzte Modus, in dem alle Methoden mit return eingeleitet werden, gibt die Formularelemente in Form eines Strings zurück. Auch hierbei ist es möglich, die Elemente als komplette Zeile einer HTML-Tabelle auszulesen, um sie dann weiterverarbeiten zu können.
Die display- und return-Methoden können mit zwei Ausnahmen alle statisch aufgerufen werden, wohingegen die add-Methoden alle ein Objekt benötigen. Die Ausnahmen bestehen in den Methoden, die das Formular öffnen und schließen. Da die Funktionalitäten des Pakets recht einfach gehalten sind, ist keine Fehlerbehandlung implementiert.
Ein einfaches Formular könnte beispielsweise so generiert werden wie in Listing 17.13.
require_once('HTML/Form.php');
$form=new HTML_Form($_SERVER['PHP_SELF'], 'post');
$form->addPlaintext('Anrede');
$form->addRadio('anrede','Herr','Herr',true);
$form->addRadio('anrede','Frau','Frau',false);
$form->addBlank(1);
$form->addText('vorname','Vorname','',20);
$form->addText('nachname','Nachname','',20);
$form->addBlank(1);
$form->addTextarea('kommentar','Ihr Kommentar');
$form->addSubmit('submit','Absenden');
$form->display();Listing 17.13 Ausgabe eines einfachen Formulars
Der Konstruktor bekommt die notwendigen, allgemeinen Informationen übergeben, die das gesamte Formular betreffen, also als Attribute im <form>-Tag abgelegt werden. Nach dem Wert für das Attribut action wird die Methode angegeben, mit der das Formular verschickt werden soll. Der Standard get wurde hier mit 'post' überschrieben. Als weitere Attribute können Sie noch den Namen des Formulars festlegen, einen Wert für das target-Attribut definieren, den Wert für das Attribut enctype übergeben sowie einen String mit weiteren, frei definierbaren Attributen übergeben.
Um die einzelnen Formularelemente auszugeben, stehen entsprechende Methoden zur Verfügung. So ist für die Ausgabe eines Radio-Buttons addRadio() vorgesehen und für eine Texteingabe-Zeile addText(). Das Erscheinungsbild des generierten Formulars sehen Sie in Abbildung 17.2.
Abbildung 17.2 Generiertes Formular im Browser
Der erste Parameter, der den Methoden übergeben wird, ist jeweils der Name, den das Formularelement bekommen soll. Bei einem Radio-Button handelt es sich hierbei natürlich um den Namen der Gruppe.
Der zweite Parameter ist jeweils der Kommentar, der links vor dem Element ausgegeben wird. Der Text wird hierbei immer in <th>-Tags ausgegeben, wohingegen das Formularelement selbst in <td>-Tags platziert wird. Somit können Sie auch recht einfach mit CSS arbeiten, ohne Klassen nutzen zu müssen.
Der nächste Parameter ist jeweils der Wert für das Attribut value beziehungsweise der Default-Wert bei einer Textarea.
Sie sehen schon, dass die Nutzung sehr einfach und effektiv ist. Die Methoden der anderen Modi sind in der Nutzung sehr ähnlich, wobei sie statisch aufgerufen werden können. Nachfolgend finden Sie drei Möglichkeiten, ein Text-Feld auszugeben:
require_once('HTML/Form.php');
// direkte Ausgabe
HTML_Form::displayText('vorname','',20);
// Ausgabe:
// <input type="text" name="vorname" size="20" value="" />
// Uebernahme in Variable mit nachfolgender Ausgabe
$text=HTML_Form::returnText('vorname','',20);
echo $text;
// Ausgabe:
// <input type="text" name="vorname" size="20" value="" />
// Ausgabe mit Tabellen-Tags
$text_row=HTML_Form::returnTextRow('vorname','Vorname','',20);
echo $text_row;
/* Ausgabe:
<tr>
<th align="right" valign="top">Vorname</th>
<td >
<input type="text" name="vorname" size="20" value="" />
</td>
</tr> */Um die Beschreibung der Möglichkeiten nicht zu langatmig werden zu lassen, habe ich nachfolgend zu jedem Formularelement vermerkt, auf welche Weise es ausgegeben werden kann. Parameter, die in eckigen Klammern stehen, sind hierbei jeweils optional. Die Parameterlisten der display- und return-Methoden sind identisch, so dass nur die display-Variante erläutert wird. Die display-Methoden, die auf Row enden, geben dabei jeweils eine ganze Tabellenzeile aus.
Hierbei sind die folgenden Attribute allgemein gültig: name ist jeweils der Name des Formularelements. In Elementen, bei denen eine Beschriftung ausgegeben wird, ist jeweils der Parameter title zu finden, mit dem ein String als Beschriftung übergeben wird. attr kann jeweils einen String übernehmen, mit dem Attribute für das Formularelement frei definiert werden können, also z. B. so etwas wie 'class="input_text"'. Dies ist insbesondere dann hilfreich, wenn Sie JavaScript-Funktionalitäten einbinden wollen. Ähnliches gilt für thattr und tdattr. Hiermit können die Attribute für das <th>- und das <td>-Tag übergeben werden, wenn das Element in einer Tabellen-Zeile aus- oder zurückgegeben wird. Die <td>-Tags bekommen standardmäßig den String 'align="right" valign="top"' als Attribut zugewiesen. Übergeben Sie anstelle von thattr also einen Wert, wird diese Vorbelegung überschrieben. Das <td> bekommt in der Voreinstellung keine Attribute zugewiesen.
Die Erläuterung der anderen Parameter finden Sie jeweils bei den Methoden.
- Einzeiliges Text-Feld
displayText(name, [default], [size], [maxlength], [attr])
displayTextRow(name, title, [default], [size], [maxlength], [attr], [thattr], [tdattr]) returnText(),returnTextRow()
-
- Mithilfe dieser Methoden können Sie jeweils ein Element vom Typ <input type="text"> generieren. default ist der Text, mit dem das Feld vorbelegt wird. size bezeichnet hier den Wert für das Attribut size im Tag, das standardmäßig mit 20 vorbelegt wird. Mit maxlength können Sie bestimmen, wie viele Zeichen maximal in das Feld eingegeben werden dürfen.
addPassword(name, title, [default], [size], [maxlength], [attr], [thattr], [tdattr])
displayPassword(name, [default], [size], [maxlength], [attr])
displayPasswordRow(name, title, [default], [size],[maxlength], [attr], [thattr], [tdattr])
returnPassword(), returnPasswordRow()
addHidden(name, value, [attr])
displayHidden(name, value, [attr])
returnHidden()
-
- Dass für die Ausgabe von versteckten Feldern (<input type="hidden">) weniger Methoden vorgesehen sind, hat eine recht einfache Begründung. Da diese vom Browser sowieso nicht dargestellt werden, entfallen hier die Row-Methoden sowie viele der Parameter. Mit dem Parameter value übergeben Sie hierbei den Wert, der im Feld abgelegt wird.
addTextarea(name, title, [default], [width], [height], [maxlength], [attr], [thattr], [tdattr])
displayTextareaRow(name, title, [default], [width], [height], [maxlength], [attr], [thattr], [tdattr])
returnTextarea(), returnTextareaRow()
-
- Nutzen Sie eine Textarea, so können Sie auch hier den Vorgabetext mit dem Attribut default übergeben. Bitte beachten Sie, dass der Text zwischen dem öffnenden und dem schließenden Tag ausgegeben wird, so dass sichergestellt werden sollte, dass keine Kleiner-als- oder Größer-als-Zeichen enthalten sind. Mit width und height definieren Sie, wie viele Zeichen nebeneinander bzw. wie viele Zeilen untereinander zu finden sein sollen. Geben Sie keine Werte an, ist das Feld 5 Zeilen hoch und 40 Zeichen breit.
addSelect(name, title, entries, [default], [size], [blank], [multiple], [attr], [thattr], [tdattr])
displaySelect( name, entries, [default], [size], [blank], [multiple], [attr])
displaySelectRow(name, title, entries, [default], [size], [blank], [multiple], [attr], [thattr], [tdattr])
returnSelect(), returnSelectRow()
-
- Die Optionen, die in einer Select-Box ausgegeben werden sollen, müssen Sie hierbei als Array anstelle von entries übergeben. Nutzen Sie ein indiziertes Array, werden die Werte automatisch mit null beginnend durchnummeriert. Die Optionen bekommen die entsprechende Zahl als Wert des value-Attributs übergeben. Bei einem assoziativen Array wird jeweils der Schlüssel als Wert genutzt. Mit default können Sie spezifizieren, welcher Wert selektiert sein soll, wenn die Seite geladen wird. Nutzen Sie ein indiziertes Array, ist hier eine Zahl zu übergeben, wohingegen die assoziative Variante den String verlangt, den das entsprechende Feld als Schlüssel nutzt. Übergeben Sie einen nicht existierenden Schlüssel, wird die Option einfach ignoriert. size legt fest, wie viele Zeilen zu sehen sein sollen, und mit blank können Sie einen zusätzlichen String übergeben, der als erstes Element in die Liste eingefügt wird. Dies dient meist dazu, den Benutzer darauf aufmerksam zu machen, dass er einen Wert selektieren soll. Dieser Wert bekommt den Value "" zugewiesen, so dass als Parameter default auch "" übergeben werden muss.
-
- An der Stelle multiple können Sie mithilfe eines booleschen Wertes festlegen, ob mehrere Einträge selektiert werden dürfen oder nicht.
addCheckbox(name, title, [default], [attr], [thattr], [tdattr])
displayCheckbox(name, [default], [attr])
displayCheckboxRow(name, title, [default], [attr], [thattr], [tdattr])
-
- Bei einer Checkbox, die mit diesen Methoden ausgegeben werden kann, dient der Parameter default dazu festzulegen, ob die Checkbox selektiert sein soll, wenn die Seite geladen wird. Möchten Sie einen value definieren, müssen Sie das mithilfe des Parameters attr machen, indem Sie beispielsweise 'value="mail"' übergeben.
addRadio(name, title, value, [default], [attr], [thattr], [tdattr])
displayRadio(name, value, [default], [attr])
displayRadioRow(name, title, value, default], [attr], [thattr], [tdattr])
returnRadio(); returnRadioRow()
-
- Radio-Buttons werden meist in Gruppen zusammengefasst, so dass name hierbei auch der Name der Gruppe und nicht eines individuellen Elements ist. Um später unterscheiden zu können, welcher Radio-Button selektiert wurde, müssen Sie einen value an die Methode übergeben.
addImage(name, title, src, [attr], [thattr], [tdattr])
displayImage(name, src, [attr])
displayImageRow(name, title, src, [attr], [thattr], [tdattr])
-
- Möchten Sie eine Grafik mithilfe von <image type="image" /> einbinden, helfen diese Methoden Ihnen weiter. Die URL, unter der die Grafik zu finden ist, wird als src übergeben. Die Methode prüft hierbei nicht, ob die URL gültig ist oder die angegebene Ressource existiert.
addFile(name, title, [maxsize], [size], [accept], [attr], [thattr], [tdattr])
displayFile(name, [maxsize], [size], [accept], [attr])
displayFileRow(name, title, [maxsize], [size], [accept], [attr], [thattr], [tdattr])
returnFile(), returnFileRow()
returnMultipleFiles( [name], [maxsize], [files], [size], [accept], [attr])
-
- Um eine Datei vom Client zum Server zu übertragen, sind in Formularen <input type="file">-Elemente vorzusehen. Den Methoden, die Sie dabei unterstützten, kann mit dem Parameter maxsize die maximal zulässige Dateigröße mit auf den Weg gegeben werden. Dieser Parameter wird dann mithilfe eines versteckten Feldes mit an den Server gesendet. Bitte verwechseln Sie das nicht mit dem Parameter size, der die Darstellungsgröße des Feldes festlegt. Mit dem Parameter accept können Sie zulässige MIME-Types definieren. Mit 'text/*' wären also beispielsweise alle MIME-Types akzeptabel, die mit text/ anfangen, wie z. B. text/html.
-
- Aus mir leider nicht bekannten Gründen ist in diesem Fall noch eine zusätzliche Methode vorgesehen, mit der mehrere <input type="file">-Elemente erzeugt werden können. returnMultipleFiles() gibt es für die anderen »Betriebsmodi« leider nicht. Rufen Sie diese Methode ohne Parameter auf, gibt sie Ihnen einen String mit 3 Feldern (zu steuern über files) zurück, die den Namen userfile[] (Parameter name) haben.
-
- Bitte beachten Sie bei der Arbeit mit Dateien, dass der Encoding-Typ mithilfe des Konstruktors bzw. von Hand auf multipart/form-data gesetzt werden muss.
addReset([title], [attr], [thattr], [tdattr])
displayReset([title], [attr])
displayResetRow([title], [attr], [thattr], [tdattr])
returnReset(), returnResetRow()
-
- Bei der Erstellung eines Reset-Buttons benötigen Sie keine Parameter. Allerdings ist die Nutzung des title-Parameters beim Reset- und auch beim Submit-Button ein wenig anders. Dieser Parameter dient zur Beschriftung des Buttons und nicht dazu, einen zusätzlichen Text ausgeben zu lassen. Ein Reset-Button wird standardmäßig mit Discard Changes beschriftet. Wenn Sie eine der tabellenorientierten Methoden nutzen, wird der Button im rechten Feld ausgegeben und das linke bleibt leer.
addSubmit([name], [title], [attr], [thattr], [tdattr])
displaySubmit([title], [name], [attr])
displaySubmitRow([name], [title], [attr], [thattr], [tdattr])
-
- Für die Submit-Button-Methoden gilt dasselbe wie für die des Reset-Buttons. Standardmäßig wird ein Submit-Button mit Submit Changes beschriftet und bekommt den Namen submit.
displayPlaintext([text])
displayPlaintextRow(title, [text], [thattr], [tdattr])
returnPlaintext(), returnPlaintextRow()
-
- Die Plaintext-Methoden dienen dazu, einen Text auszugeben. Das erscheint zwar nicht sonderlich spannend, gibt Ihnen aber die Möglichkeit, erläuternde Texte mit in das Formular ausgeben zu lassen. Bei den Methoden, die eine Tabellenzeile generieren, wird mit dem obligatorischen Parameter title ein Text für das linke Tabellenfeld definiert.
addBlank(anzahl, [title], [thattr], [tdattr])
displayBlank()
displayBlankRow(anzahl, [title], [thattr], [tdattr])
returnBlank( ), returnBlankRow()
-
- Die Blank-Methoden dienen dazu, eine Leerzeile in der Tabelle bzw. ein ausgeben zu lassen. Mit dem Parameter anzahl können Sie hierbei die Anzahl der Leerzeilen spezifizieren, die Sie benötigen. Allerdings wird die Anzahl der Zeilen ignoriert, wenn Sie mit title einen Text übergeben, der im linken Tabellenfeld erscheint.
Wie ich am Anfang des Kapitels erwähnt habe, sind im Rahmen der return-Methoden noch zwei Methoden definiert, die nicht statisch genutzt werden können. Hierbei handelt es sich um returnStart() und returnEnd(), die das öffnende und schließende <form>-Tag zurückgeben. Die Werte der Attribute für das öffnende <form>-Tag werden, wie am Anfang des Kapitels erwähnt, direkt an den Konstruktor übergeben. Um festzulegen, dass mit dem Formular eine Datei hochgeladen wird, müssen Sie der Methode returnStart() true übergeben.
