Wikibooks

Websiteentwicklung: PHP: PEAR: HTML QuickForm

Das HTML_Quickform-Paket wird benutzt, um HTML-Formulare komfortabel aus PHP zu erzeugen. Optional erzeugt es auch eine Überprüfungsroutine (validation), die Serverseitig oder auch Clientseitig (Javascript) funktioniert.

Paketinhalt

Bearbeiten
  • Mehr als 20 fertige Formularelemente (darunter auch hierachische Selectboxen (Comboboxen))
  • XHTML Standard
  • Numerische und weitere Überprüfungsmethoden genannt rules (Regeln)
  • automatische Serverseitige Überprüfung und filtern
  • Dateiupload-Unterstützung
  • totale Benutzerfreiheit in der Gestaltung der Formulare
  • Unterstützt externe Templates Engines (ITX, Sigma, Flexy und Smarty)

Elemente

Bearbeiten

Derzeit existieren folgende Formularelemente:

  • text
    • Standard input textbox
  • textarea
    • Standard textarea
  • hierselect
    • Hierachische Selectbox (klickt man auf die erste Box wird die zweite gleich aktualisiert)
  • radio
    • Standard input radiobox
  • button
    • Standard input button
  • checkbox
    • Standard input checkbox
  • advcheckbox
    • Standard input checkbox + im Postobjekt findet man auch die nicht veränderten Boxen
  • autocomplete
    • Standard input text + wenn man einen Text eintippt, wird ein Textvorschlag erzeugt
  • hidden
    • Standard input hidden
  • hiddenselect
    • Standard input select + erzeugt normale hidden text boxen
  • submit
    • Standard input submit
  • image
    • Standard input image
  • date
    • erzeugt Selectboxen (Tag Monat Jahr)
  • link
    • Standard a link
  • password
    • Standard input password (Felder sind mit * geschützt)
  • select
    • Standard select
  • reset
    • Standard input reset
  • file
    • Standard input file
  • static
    • Erzeugt eine Zeile mit Text
  • html
    • Damit kann man einen selbst erzeugten HTML-String ausgeben

Regeln

Bearbeiten

Regeln werden zu Überprüfung von Formularelementen benötigt.

Regel Argument Beschreibung
required Eingabe wird benötigt
maxlength $length Die Eingabe darf max. $length lang sein
minlength $length Die Eingabe darf min. $length lang sein
rangelength $min, $max Die Eingabe muss zwischen $min und $max liegen
regex $regex Die Eingabe muss einen regularen Ausdruck beinhalten
email true (überprüft DNS) Gültigkeit der Email adresse
lettersonly Nur alphapetische Werte werden akzeptiert
alphanumeric Nur alphapetische und numerische Werte werden akzeptiert
numeric Nur numerische Werte werden akzeptiert
nopunctuation Die Eingabe darf folgende Werte nicht beinhalten (). / * ^ ? # ! @ $ % + = , " ' > < ~ [ ] { }
nonzero Nur numerische Werte werden akzeptiert aber kein 0
compare Zwei Eingabefelder werden miteinander überprüft
uploadedfile Datei muss muss ausgewählt worden sein
maxfilesize $size Datei darf max. $size gross sein
mimetype $mime Datei muss folgenden $mime Type haben (image/jpg,text/plain, usw.)
filename $file_regex Die Uploaddateiname muss mit dem $file_regex übereinstimmen (Regulärer Ausdruck)
callback Aufruf einer selbsterstellten Regel

Anwendung

Bearbeiten

Vorweg: Viele Wege führen zu einem gutem Quickformular, denn es gibt verschiedene Aufrufe, um die Elemente richtig zu benutzen. Diese Variante ist die einfachste und schnellste. Um Quickform erfolgreich anzuwenden, muss man sich im Klaren sein, was sein Formular alles können soll. Warum ist das wichtig? Ein entscheidener Faktor ist die Überlegung, ob man das Default Template oder ein externes verwendet, beispielsweise Smarty, ITX oder den Tableless Renderer.

Was ist der Unterschied zwischen dem Default und einem externen Template? Er besteht großteils in der Darstellung meines Formulars.

Default und ITX Template

Bearbeiten

Initialisierung

Bearbeiten 
<?php
include_once("/usr/share/pear/HTML/QuickForm.php");
$quickform = new HTML_QuickForm("frmenter", "post", "http://". $HTTP_SERVER_VARS["HTTP_HOST"] . "/formular.php");
?>

Erklärung (Parameter): Formularname, POST/GET, POST/GET Aktionsaufruf

Damit haben wir nun erfolgreich das Formular initialisiert.

Defaultwerte

Bearbeiten

Ein großer Vorteil das manuelle setzen von vorausgefüllten Werten: 

<?php
$_default['givenname'] = 'Dein Vorname';

//or

$_default = array('givenname'=> 'David');

if (is_array($_default)) {
   $quickform->setDefaults($_default);	
}
?>

Element hinzufügen

Bearbeiten

text,submit,button

Bearbeiten

Der nächste Schritt wäre schon die Initiierung der Formularelemente 

<?php
$quickform->addElement('text','givenname','Vorname: ',$_addons);
?>

Erklärung (Parameter): ELEMENT (siehe oben), Elementname, Elementbeschriftung, zusatz Parameter Array

Zusatz Parameter: Hier kann man zum Beispiel CSS-Klassen oder -Stile übergeben, aber natürlich auch width, height usw. 

<?php
$_addons = array('class' => 'textbox', 'style' => 'background-color:red;');
?>

radio,checkbox,advcheckbox

Bearbeiten

Gruppierte Ansicht 

<?php
$group[] =& $quickform->createElement('radio',null,null,'Hund',0);
$group[] =& $quickform->createElement('radio',null,null,'Katze',1);
$group[] =& $quickform->createElement('radio',null,null,'Vogel',2);
		
$quickform->addGroup($group, 'tier', null, '&nbsp;');
?>

Erklärung (Parameter): //createElement

ELEMENT (siehe oben), null, null, Beschriftung, Wert

//addGroup

array der Gruppierung, Elementname,null, Zwischen den Elmenten hier könnte man auch ein Break machen

Dies ist nun eine Gruppierung von Elementen, was heißt das nun? Ganz einfach: mit dem Gruppieren von Elementen kann man zum Beispiel Elemente untereinander verschachteln. Mit dem Befehl createElement ziehen wir unsere Elemente in den Speicher und erst mit dem Befehl addGroup werden sie dem Formular hinzugefügt. 

<?php
$quickform->addElement('checkbox', 'age', 'Bist du alt genug?');
?>

<?php
// Checkbox Gruppe 
$hobbies = array('1'=>'Laufen', '2' => 'Schreiben', '3' =>'Schlafen');
foreach ($hobbies as $name => $value) {
     $group[] =& $quickform->createElement('checkbox',$name,null,'&nbsp;' . $value);
}
$quickform->addGroup($group, 'fieldname', 'Welche Hobbies hast du?', '<br>');
?>

// Adv Checkboxen 

<?php
$quickform->addElement('advcheckbox', 'age', 'Bist du alt genug? ');
?>

select,hierselect

Bearbeiten

Dies ist nun ein einfache Selectbox: 

<?php
$arr_gender = array('male'=> 'Herr', 'female' => 'Frau');

$quickform->addElement('select', 'gender', 'Geschlecht', $arr_gender, $_addons); 

?>

ELEMENT (siehe oben), Elementname, Elementbeschriftung, Elementinhalt Array, zusatz Parameter Array

Die hierarchische Selectbox ist wirklich eine feine Sache, der Nachteil dieser Box ist, dass sie nur mit JavaScript funktioniert. 

<?php
$_addon = array('class'=>'hierselect');

//erste Selectbox
$optscountries[0] = 'Österreich';
$optscountries[1] = 'Deutschland';

//zweite Selectbox ( bei Auswahl von Österreich)
$optstate[0][0] = 'Oberösterreich';
$optstate[0][1] = 'Niederösterreich';
$optstate[0][2] = 'Salzburg';

//zweite Selectbox (bei Auswahl von Deutschland)
$optstate[1][0] = 'Bayern';
$optstate[1][1] = 'Berlin';
$optstate[1][2] = 'Hamburg';

$obj_country=& $quickform->addElement('hierselect', 'country', 'Land/Bundesland', $_addon, '<br />');
$obj_country->setOptions(array($optscountries,$optstate));	

?>

ELEMENT (siehe oben), Elementname, Elementbeschriftung, Elementinhalt Array, zusatz Parameter Array, Trennung zwischen den Boxen

textarea

Bearbeiten 
<?php
$t =& $quickform->createElement("textarea", "comment", 'Kommentar',$attrs);
$t->setRows("10");
$t->setCols("90");
$quickform->addElement($t);
?>

ELEMENT (siehe oben), Elementtyp, Elementname, Elementbeschriftung, optionaler Parameter

Weiteres: Mit den Befehlen setRows und setCols werden die Zeilen und Spalten gesetzt.

date

Bearbeiten

Es besteht die Möglichkeit mit Comboboxen (Klappboxen) eine Datumauswahl zu erstellen, leider ist diese nicht so gelungen. 

<?php
$quickform->addElement('date', 'birthday', 'Geboren am:', array('format'=>'d-m-Y','language'=>'de', 'minYear'=>1950, 'maxYear'=>2000));
?>

ELEMENT (siehe oben), Elementname, Elementbeschriftung,Definierungsarray

Definierungsarray:

  • format (Datumsformat)
  • language (Sprachenkürzel: en,de usw.)
  • minYear (min. Jahrauswahl)
  • maxYear (max. Jahrauswahl)

Rules hinzufügen/anwenden

Bearbeiten

Die Rules sind wohl das Herzstück von diesem Paket, man spart sich damit das händische und fehleranfällige Ausprogrammieren der Fehlerroutinen.

Es gibt zwei Möglichkeiten: server und client Wie oben kurz erklärt:

  • server = HTML anzeige (nach post oder get)
  • client = Javascript
<?php
//Beispiel 1
$quickform->addRule('street', 'Strasse fehlt', 'required', null, 'server');


//Beispiel 2
$quickform->addRule('mail', 'Email adresse ist nicht korrekt', 'email', null, 'server');


//Beispiel 3
function myRule($value) {
    if ($value == 12) {
        return true;
    }
    return false;
}
$quickform->registerRule('ownrule', 'callback', 'myrule');
$quickform->addRule('age', 'Bitte geben Sie ihr Alter ein', 'ownrule');
?>


<?
// Beispiel 4
// Eigene Rules über eine Class

include_once('HTML/QuickForm/Rule.php');
$quickform->registerRule('ownrule', null, "CLASSNAME"); 

class CLASSNAME extends HTML_QuickForm_Rule {
    
    function validate($value, $options=null) {
        if ('GEHT DOCH' == $value) return true;
        return false;
    } // validate

    function getValidationScript($options = null) {
    } // getValidationScript

    
} // CLASSNAME

?>

<?
// Beispiel 5
// Eigene Rules innerhalb einer eigenen Class

class CLASSNAME {

    function myDisplay() {
        //[...]
        $quickform->registerRule('ownrule', 'myRule', $this);
    } //myDisplay
 
    function myRule($value) {
        if ($value == 12) {
            return true;
        }
        return false;
    } //myRule

} // CLASSNAME


?>
  • Beispiel 1
    • Eingabe muss vorhanden sein
  • Beispiel 2
    • Emailadresse muss korrekt ausgefüllt sein
  • Beispiel 3
    • Aufruf einer eigenen Funktion
  • Beispiel 4
    • Aufruf einer eigenen Class
  • Beispiel 5
    • Aufruf innerhalb einer eigenen Class

Validierung

Bearbeiten

Mit Quickform kann man mit einem Befehl alle Rules überprüfen 

<?php
$quickform->validate();
?>

Dieser Aufruf gibt True/False zurück.

Zur Anwendung: 

<?php
if ($quickform->validate()) {
    echo 'Formular wurde erfolgreich versendet';
} else {
    $quickform->display();
}
?>

Mit dem Befehl display zeigen wir unser Formular an. (Defaulttemplate)

Elemente anzeigen

Bearbeiten

Wie eben erklärt zeigt man mit dem Befehl display das Formular an. Doch das war noch lange nicht alles, es besteht auch die Möglichkeit mittels Templates das Formular auf den Bildschirm zu bringen.

Dazu verwenden wir nun das ITX-Template Info: Aufruf erst nach den Rules! 

<?php
include_once('/HTML/QuickForm/Renderer/ITStatic.php');
include_once('/HTML/Template/ITX.php');

//Templatepfad
$tpl =& new HTML_Template_ITX('/html/navigation');
//Templatename
$tpl->loadTemplateFile('template_myform.html');	
					
$renderer =& new HTML_QuickForm_Renderer_ITStatic($tpl);

//Falls eine Regel mit ''required'' definiert wurde (Pflichtfelder)
$renderer->setRequiredTemplate('{label}<font color="red" size="1">*</font>');

//Fehlerdefinition
$renderer->setErrorTemplate('<font color="red" size="1">{error}</font><br />{html}');

//setze Statische Werte
$vars = array (
	'L_STATIC_HELLO'	=> 'Hello World!',
        'L_STATIC_END'		=> 'Danke'
);
$tpl->setVariable($vars);
$quickform->accept($renderer);

//Zeige Formular
$tpl->show();

?>

Nun erstelle eine Datei die template_myform.html heißt und füge folgende Werte ein: 

<!-- BEGIN form_error_loop -->
<font style="color:red;">{frmenter_error}</font><br /><!-- END form_error_loop -->

<form {frmenter_attributes}>
{frmenter_session_html}
Binde nun Elemente ein
</form>

Wie binde ich nun meine Elemente ein?

  • {FORMULARNAME_ELEMENTNAME_LABEL}
    • Erzeugt Bezeichnungsfeld zb. {frmenter_street_label}
  • {FORMULARNAME_ELEMENTNAME_HTML}
    • Erzeugt HTML-Feld zb. {frmenter_street_html}

Wie binde ich nun meine Statischen Elemente ein?

  • {L_STATIC_HELLO}
    • erzeut Hello World usw.
Bearbeiten 
PHP Pear
Pear Quickform Tutorial
Abgerufen von „https://de.wikibooks.org/w/index.php?title=Websiteentwicklung:_PHP:_PEAR:_HTML_QuickForm&oldid=982414“