(c) 2005/2006 Carsten Meier
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Formitude ist eine in PHP geschriebene Bibliothek zum Generieren und Validieren von HTML-Formularen. Der Inhalt der Formulare wird über Items festgelegt, die die Darstellung und die Validierung der einzelnen Daten übernehmen. Es sind bereits Item-Klassen für die folgenden Anwendungen enthalten:
Durch die offene Architektur von Formitude läßt sich die Bibliothek leicht um weitere Item-Klassen für spezielle Einsatzzwecke erweitern. Dabei werden sowohl einseitige als auch mehrseitige Formulare unterstützt. Das Aussehen läßt sich durch die konsequente Nutzung von HTML-Klassen und -IDs leicht über Stylesheets anpassen. Außerdem können die auszugebenden Statusmeldungen frei bestimmt werden.
Bei der vorliegenden Fassung handelt es sich um Version 1.4 vom 18.8.2006. Aktuelle Informationen finden Sie auf der Formitude-Homepage.
Das Archiv enthält folgende Dateien:
Es wird PHP >= 4.3.0 benötigt. Das Skript wurde unter den PHP-Versionen 4.3.3 und 5.1.4 mit den Laufzeit-Optionen register_globals off und allow_call_time_pass_reference off getestet.
Um die Formitude-Funktionen zu nutzen, kopieren Sie einfach die Datei formitude.php in ein Verzeichnis innerhalb Ihres PHP-Include-Pfades.
Die Demo-Dateien formitude-demo.php und formitude.css können Sie an einem beliebigen Ort unterhalb Ihres Doc-Root-Verzeichnisses ablegen. Die Demo soll nun im Detail erläutert werden.
Nach dem Einbinden der Bibliothek mittels
include_once 'formitude.php';wird zunächst das Grundgerüst des Formulars mit der Funktion
formitude_create_form() erzeugt. Diese hat folgende Signatur:
function &formitude_create_form($url, $method, $charset, &$messages,
$htmlidprefix = 'formitude_', $htmlclassprefix = 'formitude_',
$optionidprefix = '_', $submitctl = '__formitude_submit_button',
$namectl = '__formitude_form_name')Der Funktion werden die folgenden Argumente übergeben:
Die letzten fünf Parameter sind mit Vorgabewerten belegt und können in den meisten Fällen einfach weggelassen werden:
Bei dem zurückgegebenen Formular handelt es sich um ein Array, bei dem folgende Schlüssel, je nach später verwendeter Darstellungsfunktion, noch manuell gesetzt werden müssen, oder automatisch gesetzt werden:
Der entsprechende Funktionsaufruf in der Demo sieht folgendermaßen aus:
$form = &formitude_create_form(
'http://'.$_SERVER['SERVER_NAME'].$_SERVER['PHP_SELF'], 'post',
'iso-8859-1', $formitude_messages_de);Danach werden die anzuzeigenden Items des Formulars erzeugt und in einem Array abgelegt. Da es sich um ein einseitiges Formular handelt, wird das erzeugte Array direkt in das 'items'-Feld eingetragen.
$form['items'] = array(
formitude_create_block('<h3>Demoformular</h3>', 'caption'),
formitude_create_text_field('name', 'Name', true, 80),
formitude_create_select('figur', 'Lieblingsfigur',
array(
'milhouse' => 'Milhouse',
'burns' => 'Clifford Montgomery Burns',
'flanders' => 'Flanders'),
false, 0),
formitude_create_check_box('todd_smells', 'Todd müffelt'),
formitude_create_text_area('kommentar', 'Kommentar', true, 200),
formitude_create_email_address_field('email', 'E-Mail', true),
formitude_create_http_address_field('url', 'Homepage', false),
formitude_create_check_box(
'serious', 'Diese Angaben sind wirklich ernst gemeint!', true),
formitude_create_block('<h4>Nächste Folge</h4>', 'caption'),
formitude_create_date_field('datum', 'Datum', false),
formitude_create_time_field('zeit', 'Uhrzeit', false)
);Den Erzeugungsfunktionen für Controls werden, neben anderen Argumenten, zuerst der Control-Name und die anzuzeigenden Beschriftung übergeben. Auf die einzelnen Items wird später noch genauer eingegangen.
Mit dem Setzen des 'submit_buttons'-Feldes ist die Initialisierung des Formulars abgeschlossen:
$form['submit_buttons'] = array('submit' => 'Absenden');Bei einseitigen Formularen wird die Anzeige, sowie die komplette
Ablaufsteuerung inkl. Validierung, von der Funktion
formitude_perform_dialog() übernommen:
$values = array(
'todd_smells' => '1',
'url' => 'http://www.internalscripts.de/');
$button = formitude_perform_dialog($form, $values,
'<p>Die mit * gekennzeichneten Felder müssen ausgefüllt werden!</p>');Die Funktion bekommt folgende Argumente übergeben:
Nach erfolgreicher Validierung wird der Schlüssel des benutzten Submit-Buttons zurückgegeben. Bei der ersten Anzeige des Formulars oder bei fehlgeschlagener Validierung wird NULL geliefert.
if($button == 'submit')
{
// Formular wurde validiert, Daten ausgeben
formitude_print_entries($form);
...
}Die Werte des Formulars können mit Hilfe der Funktion
formitude_print_entries() als Tabelle ausgegeben werden. Wenn Sie
die Daten des Formulars als E-Mail verschicken, oder vor der Ausgabe noch weiter
bearbeiten möchten, können Sie alternativ auch die Funktion
formitude_get_entries() benutzen, die diese Tabelle als String
zurückgibt:
$ctlnames = NULL;
$str = formitude_get_entries(
$form, $ctlnames, 'Sie haben folgende Daten eingegeben');Die Variable $ctlnames enthält nun ein Array mit allen ausgegebenen Control-Namen (nicht die Formularwerte!), die Variable $str die Tabelle als String. Das optionale dritte Argument bestimmt die auszugebende Statusmeldung.
Die Formulare werden als zweispaltige HTML-Tabelle ausgegeben. Dabei werden
den einzelnen Tabellenzellen sowie dem umgebenden <form>-Element
die unten angegebenen HTML-Klassen zugewiesen. Beachten Sie bitte, daß den
Klassen jeweils noch das bei der Formularerzeugung angegebene Präfix
vorangestellt wird.
+---------------------------------------+ <form> | form | | +-----------------------------------+ | <table> | | status | | Statuszeile | +---------+-------------------------+ | | | label | field | | beliebiges Eingabefeld | +---------+-------------------------+ | | | label | radio | | Radio-Buttons | +---------+-------------------------+ | | | checkbox | | Checkbox | +-----------------------------------+ | | | error | | evtl. Fehlermeldung | +-----------------------------------+ | | | action | | Submit-Buttons | +-----------------------------------+ | +---------------------------------------+
In der Demo wird außerdem noch die Klasse caption benutzt um die Überschriften farblich zu hinterlegen.
Bei Ausgabe der Formularwerte mittels formitude_print_entries()
wird das umgebende <form>-Element durch eine
<div> mit der Klasse entries ersetzt.
Die einzelnen Werte werden dabei in ein <div>-Element mit der
Klasse value eingeschlossen.
Analog zu den Klassen wird auch allen IDs ein Präfix vorangestellt. Den
umgebenden <form>- oder <div>-Elementen werden
die IDs Präfix + form bzw. entries zugewiesen,
für die Controls wird Präfix + Control-Name benutzt.
Nachfolgend sind alle Item-Klassen mit den dazugehörigen Erzeugungsfunktionen aufgeführt. Diese geben jeweils eine Referenz auf ein Array zurück.
Ein Block kann zur Ausgabe beliebiger Inhalte dienen. Bei der Erzeugung werden der Text (evtl. auch mit HTML-Auszeichnungen) und die zu verwendende HTML-Klasse übergeben. In der Demo sind die Überschriften auf diese Weise realisiert.
function &formitude_create_block($text, $htmlclass)Info-Items werden typischerweise zur Anzeige von Daten verwendet, die in vorhergehenden Formularseiten gesammelt wurden. Es muß die Beschriftung und der auszugebende Text angegeben werden. Außerdem kann angegeben werden, ob in dem Text vorhandene HTML-Sonderzeichen automatisch HTML-Entity-kodiert werden sollen.
function &formitude_create_info($label, $text, $htmlencodetext = false)Einzeiliges Text-Eingabe-Feld. Neben dem Control-Namen und der Beschriftung wird angegeben, ob eine Eingabe zwingend erforderlich ist und wieviele Zeichen maximal eingegeben werden können.
function &formitude_create_text_field(
$name, $label, $required, $maxlen)Dient zur Eingabe einer HTTP-URL. Führende und angehängte Whitespace-Zeichen werden automatisch aus den Formulardaten entfernt. Whitespace-Zeichen innerhalb der eingegebenen Adresse werden nicht akzeptiert.
function &formitude_create_http_address_field(
$name, $label, $required)Dient zur Eingabe einer E-Mail-Adresse. Führende und angehängte Whitespace-Zeichen werden automatisch aus den Formulardaten entfernt. Whitespace-Zeichen innerhalb der eingegebenen Adresse werden nicht akzeptiert.
function &formitude_create_email_address_field(
$name, $label, $required)Dient zur Eingabe eines Datums. Es sind nur Daten erlaubt, die sich mit einem *nix-Zeitstempel darstellen lassen (ungefähr 1901-2038). Führende und angehängte Whitespace-Zeichen werden automatisch aus den Formulardaten entfernt.
function &formitude_create_date_field(
$name, $label, $required)Zum Parsen des als String zurückgegebenen Datums können Sie die Funktion
formitude_parse_date() benutzen, die ein Array mit den Feldern
0 => Monat, 1 => Tag, 2 => Jahr liefert.
Dient zur Eingabe einer Uhrzeit. Führende und angehängte Whitespace-Zeichen werden automatisch aus den Formulardaten entfernt.
function &formitude_create_time_field(
$name, $label, $required)Zum Parsen der als String zurückgegebenen Uhrzeit können Sie die Funktion
formitude_parse_time() benutzen, die ein Array mit den Feldern
0 => Stunden, 1 => Minuten, 2 => Sekunden liefert.
Mehrzeiliges Text-Eingabe-Feld.
function &formitude_create_text_area(
$name, $label, $required, $maxlen)Zur Erzeugung eines Ein-/Aus-Schalters wird der Control-Name, die Beschriftung und ein optionales Argument übergeben, mit dem der Schalter als Pflichtfeld markiert werden kann.
function &formitude_create_check_box(
$name, $label, $required = false)Bei einer aktivierten Checkbox wird der Formularwert '1' als String zurückgegeben.
Auswahlliste, die entweder als Drop-Down-Box oder als Listbox angezeigt werden kann. Mit dem $rows-Parameter wird die Anzahl der Zeilen der Listbox angegeben. Ist dieser gleich 0 wird eine Drop-Down-Box angezeigt.
Die einzelnen Optionen werden als Array mit dem $options-Argument übergeben. Der Schlüssel wird dabei als Formulardatum verwendet, der Wert bestimmt die anzuzeigende Beschriftung. Ist bei $htmlencodeopt true angegeben, so werden in der Beschriftung vorkommende HTML-Sonderzeichen automatisch als Entity-Referenzen kodiert.
function &formitude_create_select(
$name, $label, $options, $required, $rows = 0, $htmlencodeopt = false)Knopfliste, bei der jeweils nur ein Knopf aktiv sein kann. Mit dem $br-Parameter wird festgelegt, ob nach jeder Auswahlmöglichkeit ein Zeilenumbruch eingefügt werden soll. Hier ist true oder false möglich.
Die einzelnen Optionen werden als Array mit dem $options-Argument übergeben. Der Schlüssel wird dabei als Formulardatum verwendet, der Wert bestimmt die anzuzeigende Beschriftung.
function &formitude_create_radio(
$name, $label, $options, $required, $br = 0)Den einzelnen <input>-Elementen wird dabei eine ID
zugewiesen, die sich folgendermaßen zusammensetzt:
HTML-ID-Präfix + Control-Name + Option-ID-Präfix + Formularwert
Bei mehrseitigen Formularen wird zunächst wie oben gezeigt, ein Formular mit
Hilfe der Funktion formitude_create_form() angelegt. Dies muß jedoch
nicht weiter initialisiert werden, da die Felder 'name',
'items' und 'submit_buttons' während der Durchführung
eines Dialogs mit der folgenden Funktion automatisch gesetzt werden.
function formitude_perform_multipage_dialog(
&$form, &$values, &$pages, $preface = '')Diese bekommt die folgenden Argumente übergeben:
Nach erfolgreicher Anzeige und Validierung aller Formularseiten wird true zurückgegeben, ansonsten false. Bitte beachten Sie, daß nach dem Absenden einer beliebigen Formularseite auch die Validierungsfunktionen aller vorhergehenden Seiten ausgeführt werden, um das Einschmuggeln falscher Werte zu verhindern.
function formitude_get_submitted_form_name(&$form)Gibt den Namen des übermittelten Formulars zurück.
function formitude_get_submit_button(&$form)Gibt den Namen des übermittelten Submit-Buttons zurück. Dabei findet keine Prüfung statt, ob der Button zu dem übergebenen Formular gehört.
function formitude_import_submitted_values(&$form)Die übermittelten Werte werden in das Formular-Objekt kopiert. Die Variablen zur internen Ablaufsteuerung werden dabei nicht übernommen.
function formitude_check_values(&$form)Überprüft die Werte des Formulars mit Hilfe der Validierungsfunktionen der Items und setzt die Fehlermeldungen entsprechend. Entsprechen alle Werte der gewünschten Form, wird true zurückgegeben, ansonsten false.
function formitude_get_form(&$form, $statusmsg = '')Holt das Formular als darstellbaren String. $statusmsg wird im Kopf des Formulars angezeigt.
function formitude_build_get_url($url, &$getvars)Erzeugt zu $url einen fertig kodierten GET-Request-String. $getvars ist ein Array mit den entsprechenden Schlüssel-/Wert-Paaren. Ist das Array leer, wird nur $url geliefert.
function &formitude_get_request_method_vars($method)Gibt, abhängig von $method ('get' oder 'post'), eine Referenz auf das Array $_GET oder $_POST zurück.
Die Item-Objekte sind als Arrays angelegt, in denen die folgenden Felder als Variablenfunktionen erwartet werden:
function(&$item, &$form, &$ctlnames_out)function(&$item, &$form, &$ctlnames_out)function(&$item, &$form)Die Variablenfunktionen 'get_control' und 'get_entry' geben die Ausgabe als String zurück. Außerdem wird erwartet, daß die mit diesem Item assoziierten Control-Namen in $ctlnames_out als Array ablegt werden. Bei rein optischen Elementen muß ggf. ein leeres Array zugewiesen werden.
Um die umschließenden Elemente eines Controls zu erzeugen, sollten die von den folgenden Funktionen gelieferten Strings dem eigentlichen Element vorangestellt bzw. angehängt werden:
function &formitude_get_control_prefix(&$item, &$form,
$labelcol, $labelfor, $add, $fieldclass)function &formitude_get_control_postfix(&$item,
&$form)Der Wahrheitswert $labelcol bestimmt, ob eine separate Spalte
mit der Beschriftung ausgegeben werden soll. $labelfor gibt den
Namen des Controls an, für das ein <label>-Element erzeugt
werden soll. Wird hier ein leerer String oder NULL übergeben, wird
die Beschriftung nicht in ein <label>-Element eingebettet.
In $add kann ein zusätzlich zur Beschriftung auszugebener Text
angegeben werden. $fieldclass spezifiziert die der Tabellenzelle
zuzuordnende HTML-Klasse ohne Präfix.
Analog ist bei der Ausgabe des Werts über 'get_entry' vorzugehen:
function &formitude_get_entry_prefix(&$item,
&$form)function &formitude_get_entry_postfix(&$item,
&$form)Folgende Daten können von Item-Objekten über das übergebene $form-Array ausgelesen werden:
Alle hier aufgeführten Versionen sind (solange keine undokumentierten Funktionen benutzt wurden) abwärtskompatibel zu Vorgängerversionen. Ein Update kann durch das Kopieren der Datei formitude.php erfolgen.
formitude_check_select() wurde behoben,
der es erlaubte ungültige Werte bei Select-Controls die nicht als
Pflichtfeld markiert sind, einzuschleusen.formitude_get_control_prefix(),
formitude_get_control_postfix(),
formitude_get_entry_prefix() und
formitude_get_entry_postfix() wurden geändert und werden jetzt
dokumentiert. Diese sollten nun von Erweiterungen zur Ausgabe der
umschließenden Elemente eines Controls verwendet werden.formitude_get_submitted_form_name() wurde geändert. Es muß nun ein
Formular-Objekt übergeben werden. Außerdem wird diese Funktion jetzt offiziell
dokumentiert.formitude_get_submit_button() wurde leicht geändert. Es wird nun
nicht mehr zuerst getestet, ob der übermittelte Formular-Name mit dem des
Formular-Objekts übereinstimmt. Außerdem wird diese Funktion jetzt offiziell
dokumentiert.htmlspecialchars() wird zusätzlich der bei
der Formularerzeugung angegebene $charset-Parameter übergeben.formitude_get_text_entry() werden
Newline-Zeichen nicht mehr nach <br />, sondern nach
<br> konvertiert. Außerdem werden Tabulatoren durch
vier -Zeichen ersetzt.formitude_get_entries() und
formitude_get_form() wurden hinzugefügtAktuelle Informationen und die neueste Version finden Sie auf der Formitude-Homepage. Wenn Sie Fragen zu dem Skript stellen, oder einen Kommentar abgeben möchten, können Sie dies im Formitude-Forum tun. Bitte geben Sie bei Problemen unbedingt die verwendeten PHP- und Skript-Versionen, sowie das verwendete Betriebssystem an!
Unterstützen Sie die Entwicklung weiterer, frei verfügbarer Skripte durch das Setzen eines Links zu http://www.internalscripts.de/ . Vielen Dank!
Fragen zur Benutzung des Skripts bitte im Forum stellen!