Zend_Form verwendet Zend_Loader_PluginLoader um es Entwicklern zu erlauben Orte von alternativen Elementen und Dekoratoren zu spezifizieren. Jeder hat seinen eigenen mit Ihm assoziierten Plugin Loader, und generelle Zugriffspunkte werden verwendet um jeden zu empfangen und zu ändern.

Die folgenden Loadertypen werden mit den verschiedenen Plugin Loader Methoden verwendet: 'element' und 'decorator'. Die Typnamen sind unabhängig von der Schreibweise.

Die Methoden um mit Plugin Loader zu interagieren sind die folgenden:

Zusätzlich kann ein Präfixpfad für alle Elemente und Anzeigegruppen die durch eine Zend_Form Instanz erstellt wurden, spezifiziert werden, durch Verwendung der folgenden Methoden:

Eigene Elemente und Dekoratore sind ein einfacher Weg um Funktionalitäten zwischen Forms zu teilen und eigene Funktionalitäten zu kapseln. Siehe das Eigene Label Beispiel in der Dokumentation über Elemente als Beispiel dafür, wie eigene Elemente als Ersatz für Standardklassen verwendet werden können.

Zend_Form bietet verschiedene Zugriffsmethoden für das Hinzufügen und Entfernen von Elementen aus einer Form. Diese können Instanzen von Elemente Objekten nehmen oder als Factories für das Instanzieren der Element Objekte selbe herhalten.

Die grundsätzlichste Methode für das Hinzufügen eines Elements ist addElement(). Diese Methode kann entweder ein Objekt vom Typ Zend_Form_Element sein (oder einer Klasse die Zend_Form_Element erweitert), oder Argumente für das Erstellen eines neuen Elements -- inklusive dem Elementtyp, Namen, und jegliche Konfigurationsoption.

Einige Beispiele:

// Eine Instanz eines Elements verwenden:
$element = new Zend_Form_Element_Text('foo');
$form->addElement($element);

// Eine Factory verwenden
//
// Erstellt ein Element von Typ Zend_Form_Element_Text mit dem
// Namen 'foo':
$form->addElement('text', 'foo');

// Eine Label Option an das Element übergeben:
$form->addElement('text', 'foo', array('label' => 'Foo:'));

Sobald ein Element der Form hinzugefügt wurde, kann es durch den Namen empfangen werden. Das kann entweder durch die Verwendung der getElement() Methode, oder durch Verwendung von Überladen um auf das Element als Objekteigenschaft zuzugreifen:

// getElement():
$foo = $form->getElement('foo');

// Als Objekteigenschaft:
$foo = $form->foo;

Fallweise, will man ein Element erstellen ohne es einer Form hinzuzufügen (zum Beispiel, wenn man die verschiedenen Plugin Pfade verwenden, aber das Objekt später zu einer Subform hinzufügen will). Die createElement() Methode erlaubt das:

// $username wird ein Zend_Form_Element_Text Objekt:
$username = $form->createElement('text', 'username');

// Alle Werte erhalten:
$values = $form->getValues();

// Nur den Wert des 'foo' Elements erhalten:
$value = $form->getValue('foo');

$form->setDefaults($data);
$form->populate($data);

$form->reset();

// Einen gobalen Präfix setzen:
// Erstellt Pfade für die Präfixe My_Foo_Filter, My_Foo_Validate,
// und My_Foo_Decorator
$form->addElementPrefixPath('My_Foo', 'My/Foo/');

// Nur Filterpfade:
$form->addElementPrefixPath('My_Foo_Filter',
                            'My/Foo/Filter',
                            'filter');

// Nur Prüfungspfade:
$form->addElementPrefixPath('My_Foo_Validate',
                            'My/Foo/Validate',
                            'validate');

// Nur Dekoratorpfade:
$form->addElementPrefixPath('My_Foo_Decorator',
                            'My/Foo/Decorator',
                            'decorator');

$form->setElementDecorators(array(
    'ViewHelper',
    'Label'
));

$form->setElementDecorators(
    array(
        'ViewHelper',
        'Label'
    ),
    array(
        'foo',
        'bar'
    )
);

$form->setElementDecorators(
    array(
        'ViewHelper',
        'Label'
    ),
    array(
        'foo',
        'bar'
    ),
    false
);

$form->setElementFilters(array('StringTrim'));

Anzeigegruppen sind ein Weg um virtuell Gruppierungen von Elementen für Anzeigezwecke zu erstellen. Alle Elemente bleiben durch Ihren Namen in der Form zugreifbar, aber wenn die Form iteriert oder dargestellt wird, werden alle Elemente in Anzeigegruppen gemeinsam dargestellt. Üblicherweise wird das für die Gruppierung von Elementen in Fieldsets verwendet.

Die Basisklasse für Anzeigegruppen ist Zend_Form_DisplayGroup. Wärend Sie direkt Instanziert werden kann, ist es normalerweise am besten die addDisplayGroup() Methode von Zend_Form zu verwenden um das zu erledigen. Diese Methode nimmt ein Array von Elementen als erstes Argument, und einen Namen für die Anzeigegruppe als zweites Argument. Es kann optional ein Array von Optionen oder ein Zend_Config Objekt als drittes Argument übergeben werden.

Angenommen das die Elemente 'username' und 'passwort' bereits in der Form gesetzt wurden. Dann würde der folgende Code diese Elemente in einer 'login' Anzeigegruppe gruppieren:

$form->addDisplayGroup(array('username', 'password'), 'login');

Auf Displaygruppen kann mithilfe der getDisplayGroup() Methode zugegriffen werden, oder über Überladung inden der Name der Anzeigegruppe verwendet wird:

// getDisplayGroup() verwenden:
$login = $form->getDisplayGroup('login');

// Überladen verwenden:
$login = $form->login;

$form->addDisplayGroup(
    array('foo', 'bar'),
    'foobar',
    array('disableLoadDefaultDecorators' => true)
);

$form->addDisplayGroupPrefixPath('My_Foo_Decorator', 'My/Foo/Decorator');

$form->setDisplayGroupDecorators(array(
    'FormElements',
    'Fieldset'
));

// Verwenden der 'My_DisplayGroup' Klasse
$form->addDisplayGroup(
    array('username', 'password'),
    'user',
    array('displayGroupClass' => 'My_DisplayGroup')
);

// Verwenden der Klasse 'My_DisplayGroup' für alle Anzeigegruppen:
$form->setDefaultDisplayGroupClass('My_DisplayGroup');

Subformen haben unterschiedliche Zwecke:

Eine Subform kann ein Zend_Form Objekt sein, oder typischerweise ein Zend_Form_SubForm Objekt. Das zweitere enthält Dekoratore die für das Einfügen in größere Formen passen (z.B. gibt es keine zusätzlichen HTML form Tags aus, gruppiert aber Elemente). Um eine Subform anzuhängen, muß diese einfach der Form hinzugefügt und ein Name vergeben werden:

$form->addSubForm($subForm, 'subform');

Eine Subform kann empfangen werden indem entweder getSubForm($name) oder Überladung mithilfe des Namens der Subform verwendet wird:

// Verwenden von getSubForm():
$subForm = $form->getSubForm('subform');

// Verwenden von Überladen:
$subForm = $form->subform;

Subformen sind bei der Iteration der Form enthalten, aber die Elemente die Sie enthalten nicht.

$form->setSubFormDecorators(array(
    'FormElements',
    'Fieldset'
));

Wärend die Nützlichkeit von Formen primär von den Elementen die Sie enthalten her rührt, enthhalten Sie auch anderen Metadaten, wie einen Namen (oft verwendet als eindeutige ID im HTML Markup); die Aktion und Methode der Form; die Anzahl an Elementen, Gruppen, und Subformen die Sie enthält; und sonstige Metadaten (die normalerweise verwendet werden um HTML Attribute für das Form Tag selbst zu setzen).

Der Name der Form kann mithilfe der name Zugriffsmethoden gesetzt und empfangen werden:

// Den Namen setzen:
$form->setName('registration');

// Den Namen empfangen:
$name = $form->getName();

Um die Aktion (URL zu der die Form übermittelt) und Methode (Methode mit der übermittelt werden soll, 'POST' oder 'GET') zu setzen, können die Zugriffsmethoden für action und method verwendet werden:

// action und method setzen:
$form->setAction('/user/login')
     ->setMethod('post');

Man kann auch den Encoding Typ des Formulars spezifizieren indem die Enctype Zugriffsmethode verwendet wird. Zend_Form definiert zwei Konstanten, Zend_Form::ENCTYPE_URLENCODED und Zend_Form::ENCTYPE_MULTIPART, die den Werten 'application/x-www-form-urlencoded' und 'multipart/form-data' entsprechen; trotzdem kann das auf jeden gewünschten Encodingtyp gesetzt werden.

// Setzt die Aktion, Methoden, und Enctype:
$form->setAction('/user/login')
     ->setMethod('post')
     ->setEnctype(Zend_Form::ENCTYPE_MULTIPART);

Zend_Form implementiert das Countable Interface, welches es erlaubt es als Argument fürs Zählen zu übergeben:

$numItems = count($form);

Das Setzen von eigenen Metadaten wird durch die attribs Zugriffsmethode durchgeführt. Da Überladen in Zend_Form verwendet wird um auf Elemente, Anzeigegruppen, und Subformen zuzugreifen ist das die einzige Methode für den Zugriff auf Metadaten.

// Setzen von Attributen:
$form->setAttrib('class', 'zend-form')
     ->addAttribs(array(
         'id'       => 'registration',
         'onSubmit' => 'validate(this)',
     ));

// Empfangen von Attributen:
$class = $form->getAttrib('class');
$attribs = $form->getAttribs();

// Entfernen eines Attributes:
$form->removeAttrib('onSubmit');

// Löschen aller Attribute:
$form->clearAttribs();

Das Erstellen des Markups für eine Form ist oft ein zeitintensiver Arbeitsschritt, speziell wenn man plant das selbe Markup wiederzuverwenden um Dinge zu zeigen wie Prüffehler, übermittelte Werte, usw. Zend_Form's Antwort hierfür sind Dekoratore.

Dekoratore für Zend_Form Objekte können verwendet werden um eine Form darzustellen. Der FormElements Dekorator iteriert durch alle Elemente in einer Form -- Elemente, Anzeigegruppen, und Subformen -- stellt sie dar, und gibt das Ergebnis zurück. Zusätzliche Dekoratore können dann verwendet werden um diese Inhalte zu wrappen, sie anzufügen oder sie voranzustellen.

Die Standarddekoratore für Zend_Form sind FormElemente, HtmlTag (wrappt in einer Definitionsliste), und Form; der entsprechende Code für deren Erstellung ist wie folgt:

$form->setDecorators(array(
    'FormElements',
    array('HtmlTag', array('tag' => 'dl')),
    'Form'
));

Das erstellt eine Ausgabe wie die folgende:

<form action="/form/action" method="post">
<dl>
...
</dl>
</form>

Jegliche Attribute die auf dem Form Objekt gesetzt sindwerden als HTML Attribute des <form> Tags verwendet.

$form = new Zend_Form(array('disableLoadDefaultDecorators' => true));

// Alias zu 'FooBar':
$form->addDecorator(array('FooBar' => 'HtmlTag'), array('tag' => 'div'));

// Und Ihn später empfangen:
$form = $element->getDecorator('FooBar');

// Zwei 'HtmlTag' Dekoratore hinzufügen und einen mit 'FooBar' benennen:
$form->addDecorators(
    array('HtmlTag', array('tag' => 'div')),
    array(
        'decorator' => array('FooBar' => 'HtmlTag'),
        'options' => array('tag' => 'dd')
    ),
);

// Und Sie später empfangen:
$htmlTag = $form->getDecorator('HtmlTag');
$fooBar  = $form->getDecorator('FooBar');

Man kann eigene Dekoratore für die Erzeugung der Form erstellen. Ein üblicher Grund hierfür ist, wenn man das exakte HTML weiß das man verwenden will; der Dekorator könnte das exakte HTML erstellen und es einfach zurückgeben, wobei potentiell die Dekoratore der individuellen Elemente oder Anzeigegruppen verwendet werden.

Die folgenden Methoden können verwendet werden um mit Dekoratoren zu interagieren:

Zend_Form verwendet auch das Überladen um die Darstellung von speziellen Dekoratoren zu erlauben. __call() interagiert mit Methoden die mit dem Text 'render' beginnen und verwendet den Rest des Methodennamens um nach einem Dekorator zu suchen; wenn er gefunden wird, wird dieser einzelne Dekorator dargestellt. Jedes Argument das dem Methodenaufruf übergeben wird, wird als Inhalt an die render() Methode des Dekorators übergeben. Als Beispiel:

// Stellt nur den FormElements Dekorator dar:
echo $form->renderFormElements();

// Stell nur den Fieldset Dekorator dar, und übergibt Inhalte:
echo $form->renderFieldset("<p>Das ist der Fieldset Inhalt</p>");

Wenn der Dekorator nicht existiert, wird eine Exception geworfen.

Ein primärer Verwendungszweck für Forms ist die Überprüfung von übermittelten Daten. Zend_Form erlaubt es eine komplette Form, eine teilweise Form, oder Antworten von XmlHttpRequests (AJAX) zu prüfen. Wenn die übertragenen Daten nicht gültig sind, hat es Methoden für das Empfangen der verschiedenen Fehlercodes und Nachrichten für Elemente und Subformen.

Um eine ganze Form zu prüfen, kann die isValid() Methode verwendet werden:

if (!$form->isValid($_POST)) {
    // Prüfung fehlgeschlagen
}

isValid() prüft jedes benötigte Element, und jedes nicht benötigte Element das in den übermittelten Daten enthalten ist.

Manchmal muß nur ein Subset der Daten geprüft werden; dafür kann isValidPartial($data) verwendet werden:

if (!$form->isValidPartial($data)) {
    // Prüfung fehlgeschlagen
}

isValidPartial() versucht nur die Teile zu prüfen für die es passende Elemente gibt; wenn ein Element nicht in den Daten repräsentiert ist, wird es übersprungen.

Wenn Elemente oder Gruppen von Elementen für eine AJAX Anfrage geprüft werden, wird üblicherweise ein Subset der Form geprüft, und die Antwort in JSON zurückgegeben. processAjax() führt das präzise durch:

$json = $form->processAjax($data);

Man kann dann einfach die JSON Antwort an den Client senden. Wenn die Form gültig ist, wird das eine boolsche TRUE Antwort sein. Wenn nicht, wird es ein Javascript Objekt sein das Schlüssel/Nachricht Paare enthält, wobei jede Nachricht 'message' ein Array von Prüf-Fehlermeldungen enthält.

Für Forms bei denen die Prüfung fehlschlägt, können beide, Fehlercodes und Fehlermeldung empfangen werden, indem getErrors() und getMessages() verwendet werden:

$codes = $form->getErrors();
$messages = $form->getMessages();

Codes und Fehlermeldungen kann man für individuelle Elemente erhalten indem einfach der Name des Elements an jede übergeben wird:

$codes = $form->getErrors('username');
$messages = $form->getMessages('username');

$validValues = $form->getValidValues($_POST);

Nachfolgend ist eine komplette Liste der in Zend_Form vorhandenen Methoden, gruppiert nach Typ:

Zend_Form ist über setOptions() und setConfig() vollständig konfigurierbar (oder durch die Übergabe von Optionen oder einem Zend_Config Objekt an den Konstruktor). Durch Verwendung dieser Methoden können Form Elemente, Anzeigegruppen, Dekoratore, und Metadaten spezifiziert werden.

Als generelle Regel, wenn 'set' + der Optionsschlüssel zu einer Zend_Form Methode referieren, wird der angebotene Wert zu dieser Methode übergeben. Wenn die Methode nicht existiert, wird angenommen das der Schlüssel eine Referenz zu einem Attribut ist, und wird an setAttrib() übergeben.

Ausnahmen zu dieser Regel sind die folgenden:

Als Beispiel ist hier eine Konfigurationsdatei die eine Konfiguration für jeden Typ von konfigurierbaren Daten übergibt:

[element]
name = "Registrierung"
action = "/user/register"
method = "post"
attribs.class = "zend_form"
attribs.onclick = "validate(this)"

disableTranslator = 0

prefixPath.element.prefix = "My_Element"
prefixPath.element.path = "My/Element/"
elementPrefixPath.validate.prefix = "My_Validate"
elementPrefixPath.validate.path = "My/Validate/"
displayGroupPrefixPath.prefix = "My_Group"
displayGroupPrefixPath.path = "My/Group/"

elements.username.type = "text"
elements.username.options.label = "Benutzername"
elements.username.options.validators.alpha.validator = "Alpha"
elements.username.options.filters.lcase = "StringToLower"
; natürlich mehr Elemente...

elementFilters.trim = "StringTrim"
;elementDecorators.trim = "StringTrim"

displayGroups.login.elements.username = "username"
displayGroups.login.elements.password = "password"
displayGroupDecorators.elements.decorator = "FormElements"
displayGroupDecorators.fieldset.decorator = "Fieldset"

decorators.elements.decorator = "FormElements"
decorators.fieldset.decorator = "FieldSet"
decorators.fieldset.decorator.options.class = "zend_form"
decorators.form.decorator = "Form"

Das obige könnte einfach abstrahiert werden zu einer XML oder PHP Array-basierenden Konfigurations Datei.

Eine Alternative zur Verwendung von Konfigurations-basierenden Forms ist es Zend_Form abzuleiten. Das hat einige Vorteile:

Der typischste Anwendungsfall würde sein die init() Methode zu verwenden um spezielle Form Elemente und Konfigurationen zu definieren:

class My_Form_Login extends Zend_Form
{
    public function init()
    {
        $username = new Zend_Form_Element_Text('username');
        $username->class = 'formtext';
        $username->setLabel('Benutzername:')
                 ->setDecorators(array(
                     array('ViewHelper',
                           array('helper' => 'formText')),
                     array('Label',
                           array('class' => 'label'))
                 ));

        $password = new Zend_Form_Element_Password('password');
        $password->class = 'formtext';
        $password->setLabel('Passwort:')
                 ->setDecorators(array(
                     array('ViewHelper',
                           array('helper' => 'formPassword')),
                     array('Label',
                           array('class' => 'label'))
                 ));

        $submit = new Zend_Form_Element_Submit('login');
        $submit->class = 'formsubmit';
        $submit->setValue('Anmeldung')
               ->setDecorators(array(
                   array('ViewHelper',
                   array('helper' => 'formSubmit'))
               ));

        $this->addElements(array(
            $username,
            $password,
            $submit
        ));

        $this->setDecorators(array(
            'FormElements',
            'Fieldset',
            'Form'
        ));
    }
}

Diese form kann instanziert werden mit einem einfachen:

$form = new My_Form_Login();

und die gesamte Funktionalität ist bereits eingestellt und bereit; keine Konfigurationsdateien notwendig. (Bitte beachten das dieses Beispiel sehr vereinfacht ist, da es keine Prüfungen oder Filter für die Elemente enthält.)

Ein anderer üblicher Grund für die Erweiterung ist es ein Set von Standard Dekoratoren zu definieren. Das kann durch überladen der loadDefaultDecorators() Methode durchgeführt werden:

class My_Form_Login extends Zend_Form
{
    public function loadDefaultDecorators()
    {
        $this->setDecorators(array(
            'FormElements',
            'Fieldset',
            'Form'
        ));
    }
}