11.4. QuickForm

Im PEAR Namespace des PHP Plattform-Projektes befindet sich die Unterstützung für das Erstellen und Auswerten von HTML Formularen auf Basis des Paketes PEAR::HTML_QuickForm.

Das QuickForm Template generiert für jede Klasse eine spezielle Form Klasse mit 3 statischen Methoden:

create

dient der Erstellung von QuickForm Formular Objekten, siehe Section 11.4.1, “Erstellen von QuickForm Objekten”

build...

dient der Erstellung von Domain Objekten aus QuickForm Objekten, siehe Section 11.4.2, “Konvertierung von Formularen zu Domain Objekten”

addCustomDefinition

dient der Möglichkeit Anpassungen und Ergänzungen an dem QuickForm Objekt innerhalb eines geschützten Bereiches durchzuführen, siehe Section 11.4.3, “Benutzerspezifische Definitionen”

11.4.1. Erstellen von QuickForm Objekten

Mit der create Methode werden QuickForm Objekte erstellt die ein Formular repräsentieren. Die Methode hat einen Parameter defaultValues um den Formularfeldern Standardwerte zuzuweisen. Dem Formular Objekt werden neben versteckten Feldern für jedes Attribute der Klasse ein Feld hinzugefügt. Weiterhin wird für jedes Attribut ein trim Filter hinzugefügt.

Am Ende wird die Methode addCustomDefinitions aufgerufen, welche einen geschützten Bereich für manuelle Implementierungen bereitstellt, um weitere Formulardefinitionen hinzuzufügen oder vorhandene abzuändern.

11.4.2. Konvertierung von Formularen zu Domain Objekten

Mit der Methode build... kann aus QuickForm Formular Objekten wieder ein Domain Objekt erstellt werden. Dazu hat die Methode 2 Parameter:

form

spezifiziert das notwendige QuickForm Objekt

<klassenname>

spezifiziert ein optionales Domain Objekt

Wird der zweite Parameter nicht genutzt, wird einfach ein neues Domain Objekt mit dem Standardkonstruktor erstellt.

Für jedes Attribut der Domain Klasse wird der Wert von dem Formular exportiert und dem Domain Objekt als Attributwert zugewiesen. Je nach verwendetem Persistenzframework kann sich die Art des Zugriffs auf Attribute unterschieden, weshalb die QuickForm Unterstützung mit dem Workflow Parameter propertyAccess die folgenden drei Möglichkeiten bereit stellt:

setter, (Standard)

Nutzung einer set Methode

$object->setAttribtue($form->exportValue('attribute'));
attribute

Setzen der Attributwerte mit direkten Zugriff auf die Attribute (bei nicht sichtbaren Attributen wird hier die magic set methode aufgerufen)

$object->attribute = $form->exportValue('attribute');
array

Setzen der Attributwerte als wäre das Objekt ein Array

$object['attribute'] = $form->exportValue('attribute');

Standardmäßig wird die Nutzung einer set Methode angenommen. Zum Schluss wird das Domain Objekt zurückgegeben.

11.4.3. Benutzerspezifische Definitionen

Die Methode addCustomDefinition ist lediglich ein Methoden-Stub mit einem Parameter form, der das QuickForm Objekt enthält. Innerhalb der geschützten Bereichen können weitere Einstellungen am Formular Objekt vorgenommen werden, weitere Felder hinzugefügt oder vorhandene Einstellungen geändert werden.

11.4.4. Spezielle Attribute

Neben dem oben beschriebenen Standard Pattern wird aktuell eine Ausnahme unterstützt: Attribute mit dem Stereotyp html, dem Tag type und dem Tagged Value PASSWORD versehen sind.

Für Passwörter werden in der create Methode 2 Formularfelder generiert sowie eine Validierungsregel welche die Gleichheit beider Formularwerte mit dem Validierungskonzept von QuickForm prüft. Weiterhin wird in der build... Methode der Wert des Passwortfeldes nur exportiert, wenn dieser kein leerer String ist.

11.4.5. Beispielcode

Da die Klassen automatisch aus anderen Klassen erstellt werden und die Methoden ebenfalls automatisch erzeugt werden ist der generierte Quellcode natürlich bereits dokumentiert. Im folgenden Listing ist der PHP Quellcode für eine Klasse xyz abgebildet.

<?php 
require_once 'HTML/QuickForm.php'; 

/** 
 * Support class for dealing with QuickForm form definitions 
 *  
 * It provides two methods for converting an object into a form definition and vise versa.  
 * An additional method is used to add some custom definitions to the form object. 
 *  
 * @see  http://pear.php.net/manual/en/package.html.html-quickform.php 
 * @author dreamer 
 */ 
class XyzForm { 

  /** 
   * creates a QuickForm form definition for a Xyz 
   * @param array $defaultValues default form values 
   * @return HTML_QuickForm form definition for a Xyz 
   * @see  http://pear.php.net/manual/en/package.html.html-quickform.html-quickform.setdefaults.php 
   */ 
  public static function create($defaultValues = array()) { 
    $form = new HTML_QuickForm('xyzForm'); 
    $form->setDefaults($defaultValues); 
    $form->addElement('hidden', '...'); 
    $form->addElement('text', '...', '...:'); 
    $form->addElement('password', 'password', 'password:'); 
    $form->addElement('password', 'passwordRepeat', 'Repeat password:'); 
    $form->addElement('submit', 'save', 'save'); 
    $form->addRule( 
      array('password', 'passwordRepeat'), 'The passwords you entered does not match!', 'compare');  
    $form->applyFilter('...', 'trim'); 
    self::addCustomDefinition($form); 
    return $form; 
  }

  /** 
   * sets the values of the form object to the Xyz object 
   * if the Xyz object is obmitted, a new instance is created 
   * @param HTML_QuickForm a form, submitted by the user 
   * @param Xyz an object to which the values of the form are set 
   * @return Xyz the object with the submitted values 
   */ 
  public static function buildXyz($form, $xyz = null) { 
    if ($xyz === null) { 
      $xyz = new Xyz(); 
    } 
    $xyz->... = $form->exportValue('...'); 
    if ($form->exportValue('password') != "") { 
      $xyz->password = $form->exportValue('password'); 
    } 
    return $xyz; 
  }
 
  /** 
   * method to add custom definitions to the form object 
   * @generated method stub for further implementation 
   * @param HTML_QuickForm the created form for further adjustments 
   * @see  create() 
   */ 
  private static function addCustomDefinition($form) { 
    /* PROTECTED REGION ID(pear.quickform.custom.definitions._14_0_b6f02e1_1206538020843_168097_254) ENABLED START */ 
    // TODO: further form definitions for class 'XyzForm' 
    /* PROTECTED REGION END */ 
  } 
} 
?>