ZF Zend Framework

Zend_Form_Element verwendet Zend_Loader_PluginLoader um es Entwicklern zu erlauben Orte für alternative Prüfungen, Filter und Dekoratore zu spezifizieren. Jeder hat seinen eigenen Plugin Loader assoziiert, und generelle Zugriffspunkte werden verwendet um jeden zu empfangen oder zu ändern.

Die folgenden Ladetypen werden mit den verschiedenen Plugin Loader Methoden verwendet: 'validate', 'filter', und 'decorator'. Die Typnamen sind unabhängig von der Schreibweise.

Die Methoden die für die Interaktion mit Plugin Loadern verwendet werden sind die folgenden:

Eigene Prüfungen, Filter und Dekoratore sind ein einfacher Weg um Funktionalität zwischen Forms zu teilen und eigene Funktionalitäten zu kapseln.

class My_Decorator_Label extends Zend_Form_Decorator_Abstract
{
    protected $_placement = 'PREPEND';

    public function render($content)
    {
        if (null === ($element = $this->getElement())) {
            return $content;
        }
        if (!method_exists($element, 'getLabel')) {
            return $content;
        }

        $label = $element->getLabel() . ':';

        if (null === ($view = $element->getView())) {
            return $this->renderLabel($content, $label);
        }

        $label = $view->formLabel($element->getName(), $label);

        return $this->renderLabel($content, $label);
    }

    public function renderLabel($content, $label)
    {
        $placement = $this->getPlacement();
        $separator = $this->getSeparator();

        switch ($placement) {
            case 'APPEND':
                return $content . $separator . $label;
            case 'PREPEND':
            default:
                return $label . $separator . $content;
        }
    }
}

$element->addPrefixPath('My_Decorator', 'My/Decorator/', 'decorator');

$form->addElementPrefixPath('My_Decorator', 'My/Decorator/', 'decorator');

Es ist oft nützlich und/oder notwendig einige Normalisierungen an Eingaben vorzunehmen bevor diese geprüft werden - zum Beispiel kann es gewünscht sein alles an HTML zu entfernen, aber die Prüfungen auf dem verbleibenden durchzuführen um sicherzustellen das die Übertragung gültig ist. Oder man will Leerzeichen bei Eingaben entfernen damit eine StringLength Prüfung kein falsches "Korrekt" zurückgibt. Diese Operationen können durchgeführt werden indem Zend_Filter verwendet wird, und Zend_Form_Element unterstützt Filterketten, was es erlaubt mehrere, sequentielle Filter zu spezifizieren und anzupassen. Das Filter geschieht wärend beidem, der Prüfung und wenn der Wert des Elements über getValue() geholt wird:

$filtered = $element->getValue();
?>

Filter können der Kette auf zwei Wegen hinzugefügt werden:

Sehen wir uns einige Beispiele an:

// Konkrete Filterinstanz:
$element->addFilter(new Zend_Filter_Alnum());

// Voll qualifizierter Klassenname:
$element->addFilter('Zend_Filter_Alnum');

// Kurzname des Filters:
$element->addFilter('Alnum');
$element->addFilter('alnum');
?>

Kurznamen sind typischerweise der Filtername ohne den Präfix. Im Standardfall bedeutet das keinen 'Zend_Filter_' Präfix. Zusätzlich muß der erste Buchstabe nicht großgeschrieben werden.

Eigene Filterklassen verwenden

Wenn man sein eigenes Set an Filterklassen hat, kann man Zend_Form_Element mitteilen diese zu verwenden indem addPrefixPath() verwendet wird. Wenn man zum Beispiel eigene Filter unter dem 'My_Filter' Präfix hat, kann Zend_Form_Element dies auf dem folgenden Weg mitgeteilt werden: $element->addPrefixPath('My_Filter', 'My/Filter/', 'filter'); ?> (Beachten Sie das das dritte Agument indiziert welcher Plugin Loader auf welcher Aktion durchgeführt werden soll.)

Wenn man zu irgendeiner Zeit den ungefilterten Wert benötigt, kann die getUnfilteredValue() Methode verwendet werden:

$unfiltered = $element->getUnfilteredValue();
?>

Für weitere Informationen über Filter, siehe die Dokumentation über Zend_Filter.

Die Methoden die mit Filtern assoziiert sind beinhalten:

Wenn man das Sicherheits-Mantra von "Eingabe filtern, Ausgabe escapen" unterschreibt dann wird man die Eingabe der form prüfen ("Eingabefilterung") wollen. In Zend_Form enthält jedes Element seine eigene Prüfkette, die aus Zend_Validate_* Prüfungen besteht.

Prüfungen können der Kette auf zwei Wegen hinzugefügt werden:

Einige Beispiele:

// Konkrete Prüfinstanz:
$element->addValidator(new Zend_Validate_Alnum());

// Voll qualifizierter Klassenname:
$element->addValidator('Zend_Validate_Alnum');

// Kurzer Prüfname:
$element->addValidator('Alnum');
$element->addValidator('alnum');
?>

Kurznamen sind typischerweise der Prüfnamen ohne den Präfix. Im Standardfall bedeutet das keinen 'Zend_Validate_' Präfix. Zusätzlich muß der erste Buchstabe nicht großgeschrieben werden.

Eigene Prüfklassen verwenden

Wenn man sein eigenes Set an Prüfklassen hat, kann man Zend_Form_Element mitteilen diese zu verwenden indem addPrefixPath() verwendet wird. Wenn man zum Beispiel eigene Prüfungen unter dem 'My_Validator' Präfix hat, kann Zend_Form_Element dies auf dem folgenden Weg mitgeteilt werden: $element->addPrefixPath('My_Validator', 'My/Validator/', 'validate'); ?> (Beachten Sie das das dritte Agument indiziert welcher Plugin Loader auf welcher Aktion durchgeführt werden soll.)

Wenn eine bestimmte Prüfung fehlschlägt und die Ausführung von späteren Prüfungen verhindert werden soll, kann ein boolsches true als zweiter Parameter übergeben werden:

$element->addValidator('alnum', true);
?>

Wenn ein Stringname verwendet wird um eine Prüfung hinzuzufügen und die Prüfklasse Argumente in Ihrem Kontruktor akzeptiert, können diese als dritter Parameter an addValidator() als Array übergeben werden:

$element->addValidator('StringLength', false, array(6, 20));
?>

Argumente die auf diesem Weg übergeben werden sollten in der Reihenfolge sein in der Sie im Kontruktor definiert sind. Das obige Beispiel instanziert die Zend_Validate_StringLenth Klasse mit den $min und $max Parametern:

$validator = new Zend_Validate_StringLength(6, 20);
?>

Eigene Fehlermeldungen für Prüfungen anbieten

Einige Entwickler wollen eigene Fehlermeldungen für eine Prüfung anbieten. Zend_Form_Element::addValidator()'s $options Argument erlaubt es das zu tun indem der Schlüssel 'messages' angegeben wird und es auf ein Array von Schlüssel/Werte Paaren gesetzt wird für das Setzen der Nachrichten Templates. Man muß die Fehlermeldungen für die verschiedenen Fehlertypen von Prüfungen wissen für die betreffende Prüfung. Eine bessere Option ist es Zend_Translate_Adapter in der Form zu verwenden. Fehlercodes werden automatisch dem Adapter durch den Standardmäßigen Fehlerdekorator übergeben; man kann das eigene Fehlermeldungs Strings definieren durch die Erstellung von Übersetzungen für die verschiedenen Fehlercodes der Prüfung.

Es können auch viele Prüfungen auf einmal gesetzt werden, indem addValidators() verwendet wird. Die grundsätzliche Verwendung ist es ein Array von Arrays zu übergeben, wobei jedes Array 1 bis 3 Werte enthält die dem Konstruktor von addValidator() entsprechen:

$element->addValidators(array(
    array('NotEmpty', true),
    array('alnum'),
    array('stringLength', false, array(6, 20)),
));
?>

Wenn man wortreicher oder expliziter sein will, dann können die Arrayschlüssel 'validator', 'breakChainOnFailure', und 'options' verwendet werden:

$element->addValidators(array(
    array(
        'validator'           => 'NotEmpty',
        'breakChainOnFailure' => true),
    array('validator' => 'alnum'),
    array(
        'validator' => 'stringLength',
        'options'   => array(6, 20)),
));
?>

Die Verwendung ist gut für die Illustration wie Prüfungen in einer Konfigdatei konfiguriert werden können:

element.validators.notempty.validator = "NotEmpty"
element.validators.notempty.breakChainOnFailure = true
element.validators.alnum.validator = "Alnum"
element.validators.strlen.validator = "StringLength"
element.validators.strlen.options.min = 6
element.validators.strlen.options.max = 20

Es ist zu beachten das jedes Element einen Schlüssel hat, egal ob er benötigt wird oder nicht; das ist eine Einschränkung bei der Verwendung von Konfigurationsdateien -- aber es macht auch klar für was die Argumente stehen. Es ist einfach zu beachten das jede Prüfungsoption in der richtigen Reihenfolge spezifiziert werden muß.

Um ein Element zu prüfen, muß der Wert an isValid() übergeben werden:

if ($element->isValid($value)) {
    // gülig
} else {
    // ungültig
}
?>

	Die Prüfung findet an gefilterten Werte statt
	Zend_Form_Element::isValid() filtert Werte durch die angegebene Filterkette vor der Überprüfung. Siehe das Kapitel über Filter für weitere Informationen.

Prüfungs Kontext

Zend_Form_Element::isValid() unterstützt ein zusätzliches Argument $context. Zend_Form::isValid() übergibt ein komplettes Array von Daten die Bearbeitet werden an $context wenn eine Form geprüft wird, und Zend_Form_Element::isValid(), übergibt es an jede Prüfung. Das bedeutet das man Prüfungen schreiben kann die auf die Daten die an andere Forms übergeben werden acht geben. Als Beispiel nehmen wir eine Standard Registrierung Form an die Felder für Passwort und Passwort Wiederholung hat; eine Prüfung würde sein das beide Felder passen. So eine Prüfung könnte wie folgt aussehen: class My_Validate_PasswordConfirmation extends Zend_Validate_Abstract {     const NOT_MATCH = 'notMatch';     protected $_messageTemplates = array(         self::NOT_MATCH => 'Die Passwortüberprüfung war nicht erfolgreich'     );     public function isValid($value, $context = null)     {         $value = (string) $value;         $this->_setValue($value);         if (is_array($context)) {             if (isset($context['password_confirm'])                 && ($value == $context['password_confirm']))             {                 return true;             }         } elseif (is_string($context) && ($value == $context)) {             return true;         }         $this->_error(self::NOT_MATCH);         return false;     } } ?>

Prüfungen werden in der Reihenfolge ausgeführt. Jede Prüfung wird ausgeführt solange bis eine Prüfung die mit einem true Wert für breakChainOnFailure bei Ihrer Prüfung fehlschlägt. Man sollte sichergehen das Prüfungen in einer begründeten Reihenfolge definiert werden.

Nach einer fehlgeschlagenen Prüfung können Fehlercodes und Nachrichten von der Prüfkette empfangen werden:

$errors   = $element->getErrors();
$messages = $element->getMessages();
?>

(Achtung: zurückgegebene Fehlermeldungen sind ein assoziatives Array von Fehlercodes / Fehlermeldung Paaren.)

Zusätzlich zu Prüfungen, kann spezifiziert werden das ein Element benötigt wird, indem setRequired(true) verwendet wird. Standardmäßig ist dieses Flag false, was bedeutet das die Prüfkette übersprungen wird wenn kein Wert an isValid() übergeben wird. Dieses verhalten kann auf verschiedene Weisen geändert werden:

Für weitere Informationen über Prüfungen kann in die Zend_Validate Dokumentation gesehen werden.

	Verwenden von Zend_Form_Elements als generell-eingesetzte Prüfung
	Zend_Form_Element implementiert Zend_Validate_Interface was bedeutet das ein Element auch als Prüfung füreinander verwendet werden kann, bezüglich nicht-Form Prüfketten.

Die mit der Prüfung assoziierten Methoden sind:

Ein möglicher Schmerzpunkt für viele Webentwickler ist die Erstellung von XHTML Forms selbst. Für jedes Element muß der Entwickler das Markup für das Element selbst erstellen, typischerweise ein Laben und, wenn Sie nett zu den Benutzern sind, das Markup für die Anzeige von Fehlermeldungen von Prüfungen. Je mehr Elemente auf einer Seite sind, desdo weniger trivial wird diese Aufgabe.

Zend_Form_Element versucht dieses Problem durch die Verwendung von "Dekoratoren" zu lösen. Dekoratore sind einfach Klassen die Zugriff auf das Element und eine Methode für die Darstellung des Inhalts haben. Für weitere Informationen darüber wie Dekoratore arbeiten, kann in das Kapitel über Zend_Form_Decorator gesehen werden.

Die von Zend_Form_Element verwendeten Standarddekoratore sind:

Standard Dekoratore müssen nicht geladen werden

Standardmäßig werden die Standarddekoratore wärend der Initialisierung des Objekts geladen. Das kann durch die Übergabe der 'disableLoadDefaultDecorators' Option an den Konstruktor ausgeschaltet werden: $element = new Zend_Form_Element('foo', array('disableLoadDefaultDecorators' => true)); Diese Option kann mit jeder anderen Option gemischt sein die übergeben wird, sowohl als Array Option oder in einem Zend_Config Objekt.

Da die Reihenfolge in der Dekoratre registriert werden von Bedeutung ist -- der zuerst registrierte Dekorator wird als erstes ausgeführt -- man muß sicherstellen das eigene Dekoratore in der richtigen Reihenfolge registriert werden, oder sicherstellen das die Platzierungs-Optionen in einem ausgewogenen Weg gesetzt werden. Um ein Beispiel zu geben, ist hier ein Code der dem Standarddekorator registriert:

$this->addDecorators(array(
    array('ViewHelper'),
    array('Errors'),
    array('HtmlTag', array('tag' => 'dd')),
    array('Label', array('tag' => 'dt')),
));
?>

Der anfängliche Inhalt wird vom 'ViewHelper' Dekorator erstellt, welche das Form Element selbst erstellt. Als nächstes fängt der 'Errors' Dekorator Fehlermeldungen vom Element und, wenn welche vorhanden sind, übergibt Sie an den 'FormErrors' View Helfer zur Darstellung. Der nächste Dekorator, 'HtmlTag', wrapt das Element und die Fehler in ein HTML <dd> Tag. Letztendlich, empfängt der letzte Dekorator, 'label' das Label des Elements und übergibt es an den 'FormLabel' View Helfer, und wrapt es in ein HTML <dt> Tag; der Wert wird dem Inhalt standardmäßig vorangestellt. Die resultierende Ausgabe sieht grundsätzlich wie folgt aus:

<dt><label for="foo" class="optional">Foo</label></dt>
<dd>
    <input type="text" name="foo" id="foo" value="123" />
    <ul class="errors">
        <li>"123" ist kein alphanummerischer Wert</li>
    </ul>
</dd>

Für weitere Informationen über Dekoratore gibt es das Kapitel über Zend_Form_Decorator.

Mehrere Dekoratore des gleichen Typs verwenden

Intern verwendet Zend_Form_Element eine Dekoratorklasse als Machanismus für das Nachschauen wenn Dekoratore empfangen werden. Als Ergebnis, können mehrere Dekratore nicht zur gleichen Zeit registriert werden; nachgeordnete Dekoratore überschreiben einfach jene die vorher existiert haben. Um das zu umgehen, können Aliase verwendet werden. Statt der Übergabe eines Dekorators oder Dekoratornamens als erstes Argument an addDecorator(), kann ein Array mit einem einzelnen Element übergeben werden, mit dem Alias der auf das Dekoratorobjekt oder -namen zeigt: // Alias zu 'FooBar': $element->addDecorator(array('FooBar' => 'HtmlTag'), array('tag' => 'div')); // Und es später erhalten: $decorator = $element->getDecorator('FooBar'); ?> In den addDecorators() und setDecorators() Methoden muß die 'decorator' Option im Array übergeben werden das den Dekorator repräsentiert: // Zwei 'HtmlTag' Dekoratore hinzufügen, einen Alias auf 'FooBar' setzen: $element->addDecorators(     array('HtmlTag', array('tag' => 'div')),     array(         'decorator' => array('FooBar' => 'HtmlTag'),         'options' => array('tag' => 'dd')     ), ); // Und sie später empfangen: $htmlTag = $element->getDecorator('HtmlTag'); $fooBar  = $element->getDecorator('FooBar'); ?>

Die folgenden Methoden sind mit Dekoratoren assoziiert:

Zend_Form_Element behandelt eine Vielzahl von Attributen und Metadaten des Elements. Basisattribute sind:

Form Elemente können zusätzliche Metadaten benötigen. Für XHTML Form Elemente zum Beispiel, kann es gewünscht sein Attribute wie die Klasse oder Id zu spezifizieren. Für die Durchführung gibt es ein Set von Zugriffsmethoden:

Die meiste Zeit kann auf Sie, trotzdem, einfach als Objekteigenschaften zugegriffen werden, da Zend_Form_Element das Überladen realisiert und den Zugriff zu Ihnen erlaubt:

// Gleichbedeutend mit $element->setAttrib('class', 'text'):
$element->class = 'text;
?>

Standardmäßig werden alle Attribute die an den View Helfer übergeben werden auch vom Element wärend der Darstellung verwendet, und als HTML Attribute des Element Tags dargestellt.

Zend_Form wird mit einer Anzahl an Standardelementen ausgeliefert; lesen Sie das Kapitel über Standard Elemente für vollständige Details.

Zend_Form_Element hat viele, viele Methode. Was folgt ist eine Schnellzusammenfassung Ihrer Signatur, gruppiert nach Typ:

Der Konstruktor von Zend_Form_Element akzeptiert entweder ein Array von Optionen oder ein Zend_Config Objekt das Optionen enthält, und es kann auch durch Verwendung von setOptions() oder setConfig() konfiguriert werden. Generell gesprochen, werden die Schlüssel wie folgt benannt:

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 = "foo"
value = "foobar"
label = "Foo:"
order = 10
required = true
allowEmpty = false
autoInsertNotEmptyValidator = true
description = "Foo Elemente sind für Beispiele"
ignore = false
attribs.id = "foo"
attribs.class = "element"
onclick = "autoComplete(this, '/form/autocomplete/element')" ; Setzt das 'onclick' Attribut
prefixPaths.decorator.prefix = "My_Decorator"
prefixPaths.decorator.path = "My/Decorator/"
disableTranslator = 0
validators.required.validator = "NotEmpty"
validators.required.breakChainOnFailure = true
validators.alpha.validator = "alpha"
validators.regex.validator = "regex"
validators.regex.options.pattern = "/^[A-F].*/$"
filters.ucase.filter = "StringToUpper"
decorators.element.decorator = "ViewHelper"
decorators.element.options.helper = "FormText"
decorators.label.decorator = "Label"

Es können eigene Elemente durch die Erweiterung der Zend_Form_Element Klasse erstellt werden. Übliche Gründe hierfür sind:

Es gibt zwei Methoden die typischerweise verwendet werden um ein Element zu erweitern: init(), was verwendet werden kann um eine eigene Initialisierungs-Logik zum Element hinzuzufügen, und loadDefaultDecorators(), was verwendet werden kann um eine Liste von Standard Dekoratoren zu setzen die vom Element verwendet werden sollen.

Als Beispiel nehmen wir an das alle Text Elemente einer Form die erstellt wird mit StringTrim gefiltert werden müssen, mit einer gemeinsamen Regular Expression und das ein eigener Dekorator 'My_Decorator_TextItem' verwendet werden soll der für die Darstellung von Ihnen erstellt wurde; zusätzlich gibt es eine Anzahl an Standardattributen, wie 'size', 'maxLength', und 'class' die spezifiziert werden sollen. So ein Element könnte wie folgt definiert werden:

class My_Element_Text extends Zend_Form_Element
{
    public function init()
    {
        $this->addPrefixPath('My_Decorator', 'My/Decorator/', 'decorator')
             ->addFilters('StringTrim')
             ->addValidator('Regex', false, array('/^[a-z0-9]{6,}$/i'))
             ->addDecorator('TextItem')
             ->setAttrib('size', 30)
             ->setAttrib('maxLength', 45)
             ->setAttrib('class', 'text');
    }
}
?>

Man könnte dann das Form Objekt über den Präfix Pfad für diese Elmeente informieren, und die Erstellung der Elemente beginnen:

$form->addPrefixPath('My_Element', 'My/Element/', 'element')
     ->addElement('foo', 'text');
?>

Das 'foo' Element wird vom Typ My_Element_Text sein, und dem beschriebenen Verhalten entsprechen.

Eine andere Methode die man überschreiben sollte wenn Zend_Form_Element erweitert wird ist die loadDefaultDecorators() Methode. Diese Methode lädt fallweise ein Set von Standarddekoratoren für das Element; es kann gewünscht sein eigene Dekoratore in der erweiterten Klasse zu verwenden:

class My_Element_Text extends Zend_Form_Element
{
    public function loadDefaultDecorators()
    {
        $this->addDecorator('ViewHelper')
             ->addDecorator('DisplayError')
             ->addDecorator('Label')
             ->addDecorator('HtmlTag', array('tag' => 'div', 'class' => 'element'));
    }
}
?>

Es gibt viele Wege Elemente anzupassen; man sollte sicherstellen die API Dokumentation von Zend_Form_Element zu lesen um alle vorhandenen Methoden zu kennen.