Previous Next

Erstellen von Form Elementen mit Hilfe von Zend_Form_Element

Eine Form ist aus Elementen gemacht, die typischerweise mit einer HTML Form Eingabe korrespondieren. Zend_Form_Element kapselt einzelne Form Elemente mit den folgenden Bereichen die erfüllt werden sollen:

  • Prüfung (ist der übertragene Wert gültig?)

    • Fangen von Fehlercodes und Nachrichten von Prüfungen

  • Filtern (wie wird das Element in Anführungsstriche gesetzt oder normalisiert bevor die Prüfung stattfinden und/oder für die Ausgabe?)

  • Darstellung (wie wird das Element angezeigt?)

  • Metadaten und Attribute (welche Informationen qualifizieren das Element näher?)

Die Basisklasse, Zend_Form_Element, hat begründete Standardwerte für viele Fälle, aber es ist am besten die Klasse zu erweitern für oft verwendete speziell benötigte Elemente. Zusätzlich wird der Zend Framework mit einer Anzahl an Standard XHTML Elementen ausgeliefert; über diese kann im Kapitel über Standard Elemente nachgelesen werden.

Plugin Loader

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:

  • setPluginLoader($loader, $type): $loader ist das Plugin Loader Objekt selbst, wärend $type eine der oben spezifizierten Typen ist. Das setzt den Plugin Loader für den gegebenen Typ auf das neu spezifizierte Loaderobjekt.

  • getPluginLoader($type): Empfängt den mit $type assoziierten Plugin Loader.

  • addPrefixPath($prefix, $path, $type = null): Fügt eine Präfix/Pfad Assoziation hinzu, Wenn $type null ist, wird versucht den Pfad zu allen Loadern hinzuzufügen durch anhängen des Präfix von jedem "_Validate", "_Filter", und "Decorator"; und anhängen des Pfades an "Validate/", "Filter/", und "Decorator/". Wenn alle extra Form Elementklassen unter einer üblichen Hirarchie stehen, ist das die bequemste Methode für das setzen von grundsätzlichen Präfixen für sie.

  • addPrefixPaths(array $spec): Erlaubt es viele Pfade auf einmal zu einem oder mehreren Plugin Loadern hinzuzufügen. Sie erwartet das jedes Arrayelement ein Array mit den Sclüsseln 'path', 'prefix', und 'type' ist.

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

Example #1 Eigenes Label

Ein üblicher Verwendungszweck ist es Ersetzungen für Standardklassen anzubieten. Zum Beispiel wenn man eine andere Implementation des 'Label' Dekorators anbieten will -- zum Beispiel um immer einen Bindestrich anzufügen -- dann könnte man einen eigenen 'Label' Dekorator mit einem eigenen Klassenpräfix erstellen, und diesen zum eigenen Präfix Pfad hinzufügen.

Beginnen wir mit einem eigenen Label Dekorator. Wir geben Ihm den Klassenpräfix "My_Decorator", und die Klasse selbst wird in der Datei "My/Decorator/Label.php" sein.

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;
        }
    }
}

Jetzt kann dem Element mitgeteilt werden diesen Plugin Pfad zu verwenden wenn nach Dekoratoren gesucht wird:

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

Alternativ kann das bei der Form gemacht werden um sicherzustellen das alle Dekoratore diesen Pfad verwenden:

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

Wird dieser Pfad hinzugefügt, wenn ein Dekorator hinzugefügt wird, wird der Pfad 'My/Decorator/' zuerst durchsucht um zu sehen ob der Dekorator dort existiert. Als Ergebnis wird 'My_Decorator_Label' jetzt verwendet wenn der 'Labe' Dekorator angefragt wird.

Filter

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:

getValue();
?>

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

  • Übergabe einer konkreten Filterinstanz

  • Angabe eines Filternamens - entweder ein Kurzname oder ein voll qualifizierter Klassenname

Sehen wir uns einige Beispiele an:

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.

Note: 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:

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:

getUnfilteredValue();
?>

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

Die Methoden die mit Filtern assoziiert sind beinhalten:

  • addFilter($nameOfFilter, array $options = null)

  • addFilters(array $filters)

  • setFilters(array $filters) (Überschreibt alle Filter)

  • getFilter($name) (Empfängt ein Filterobjekt durch seinen Namen)

  • getFilters() (Empfängt alle Filter)

  • removeFilter($name) (Entfernt einen Filter durch seinen Namen)

  • clearFilters() (Entfernt alle Filter)

Prüfungen

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:

  • Übergabe einer konkreten Prüfinstanz

  • Anbieten eines Prüfnamens - entweder ein Kurzname oder ein voll qualifizierter Klassenname

Einige Beispiele:

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.

Note: 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:

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:

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:

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:

Note: 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:

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:

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:

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

Note: 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.

Note: 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:

 '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:

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:

  • Standardmäßig, wenn ein Element benötigt wird, ist auch ein Flag 'allowEmpty' true. Das bedeutet das wenn ein Wert evaluiert wird der leer ist und an isValid() übergeben wird, die Prüfung übersprungen wird. Dieses Flag kann gewechselt werden mit Hilfe der Zugriffsmethode setAllowEmpty($flag); Wenn das Flag false ist, und ein Wert übergeben wird, werden die Prüfungen trotzdem durchlaufen.

  • Standardmäßig, wenn ein Element benötigt wird, es aber keine 'NotEmpty' Prüfung hat, wird isValid() eine an oberster Stelle im Stack platzieren. Das heißt das das Flag folgende semantische Bedeutung bekommt: Wenn kein Wert übergeben wird, wird die Übertragung sofort ungülig und der Benutzer wird informiert, was die anderen Prüfungen davon abhält ausgeführt zu werden auf Daten von denen wir bereits wissen das Sie ungültig sind.

    Wenn dieses Verhalten nicht gewünscht ist kann es durch die Übergebe eines false Werte an setAutoInsertNotEmptyValidator($flag) ausgeschaltet werden; das verhindert das isValid() die 'NotEmpty' Prüfung in der Prüfkette platziert.

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

Note: 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:

  • setRequired($flag) und isRequired() erlauben es den Status des 'required' Flag zu setzen und zu empfangen. Wenn der boolsche Wert true gesetzt wird, erzwingt dieses Flag das das Element, in den Daten die von Zend_Form bearbeitet werden, vorhanden ist.

  • setAllowEmpty($flag) und getAllowEmpty() erlauben es das Berhalten von optionalen Elementen (z.B. Elementen in denen das required Flag false ist) zu ändern. Wenn das 'allow empty' Flag true ist, werden leere Werte nicht an die Prüfkette übergeben.

  • setAutoInsertNotEmptyValidator($flag) erlaubt es zu definieren ob eine 'NotEmpty' Prüfung der Prüfkette vorangestellt wird wenn das Element enötigt wird. Standardmäßig ist dieses Flag true.

  • addValidator($nameOrValidator, $breakChainOnFailure = false, array $options = null)

  • addValidators(array $validators)

  • setValidators(array $validators) (Überschreibt alle Prüfer)

  • getValidator($name) (Empfängt ein Prüfobjekt durch seinen Namen)

  • getValidators() (Empfängt alle Prüfer)

  • removeValidator($name) (Entfernt einen Prüfer durch seinen Namen)

  • clearValidators() (Entfernt alle Prüfer)

Eigene Fehlermeldungen

Von Zeit zu Zeit ist es gewünscht ein oder mehrere spezielle Fehlermeldungen zu spezifizieren die statt den Fehlermeldungen verwendet werden sollen die von den Validatoren verwendet werden die dem Element angehängt sind. Zusätzlich will man von Zeit zu Zeit ein Element selbst als ungültig markieren. Ab 1.6.0 ist diese Funktionalität über die folgenden Methoden ermöglicht.

  • addErrorMessage($message): Fügt eine Fehlermeldung hinzu die bei Form-Überprüfungs-Fehlern angezeigt wird. Sie kann mehr als einmal aufgerufen werden, und neue Meldungen werden dem Stack angehängt.

  • addErrorMessages(array $messages): Fügt mehrere Fehlermeldungen hinzu die bei Form-Überprüfungs-Fehlern angezeigt werden.

  • setErrorMessages(array $messages): Fügt mehrere Fehlermeldungen hinzu die bei Form-Überprüfungs-Fehlern angezeigt werden, und überschreibt alle vorher gesetzten Fehlermeldungen.

  • getErrorMessages(): Empfängt eine Liste von selbstdefinierten Fehlermeldungen die vorher definiert wurden.

  • clearErrorMessages(): Entfernt alle eigenen Fehlermeldungen die vorher definiert wurden.

  • markAsError(): Markiert das Element wie wenn die Überprüfung fehlgeschlagen wäre.

  • hasErrors(): Erkennt ob ein Element eine Überprüfung nicht bestanden hat, oder ob es als ungültig markiert wurde.

  • addError($message): Fügt einen Fehler zum eigenen Stack der Fehlermeldungen hinzu und markiert das Element als ungültig.

  • addErrors(array $messages): Fügt mehrere Nachrichten zum eigenen Stack der Fehlermeldungen hinzu und markiert das Element als ungültig.

  • setErrors(array $messages): Überschreibt den eigenen Stack der Fehlermeldungen mit den angegebenen Meldungen und markiert das Element als ungültig.

Alle Fehler die auf diesem Weg gesetzt werden können übersetzt werden. Zusätzlich kann der Platzhalter "%value%" eingefügt werden um den Wert des Elements zu repräsentieren; dieser aktuelle Wert des Element wird eingefügt wenn die Fehlermeldung empfangen wird.

Dekoratore

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:

  • ViewHelper: Spezifiziert einen View Helfer der verwendet wird um das Element darzustellen. Das 'helper' Attribut des Elements kann verwendet werden um zu spezifizieren welcher View Helfer verwendet werden soll. Standardmäßig spezifiziert Zend_Form_Element den 'formText' View Helfer, aber individuelle Subklassen spezifizieren unterschiedliche Helfer.

  • Errors: Fügt Fehlermeldungen an das Element an indem es Zend_View_Helper_FormErrors verwendet. Wenn keine vorhanden sind wird auch nichts hinzugefügt.

  • HtmlTag: Wrapt das Element und Fehler in ein HTML <dd> Tag.

  • Label: Stell ein Label vor das Element indem es Zend_View_Helper_FormLabel verwendet, und wrapt es in ein <dt> Tag. Wenn kein Label angegeben wurde, wird nur das Definitionsbegriff Tag dargestellt.

Note: 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:

 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:

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:

  • "123" ist kein alphanummerischer Wert

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

Note: 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:

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:

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:

  • addDecorator($nameOrDecorator, array $options = null)

  • addDecorators(array $decorators)

  • setDecorators(array $decorators) (Überschreibt alle Dekoratore)

  • getDecorator($name) (Empfängt ein Dekoratorobjekt durch seinen Namen)

  • getDecorators() (Empfängt alle Dekoratore)

  • removeDecorator($name) (Entfernt einen Dekorator durch seinen Namen)

  • clearDecorators() (Entfernt alle Dekoratore)

Metadaten und Attribute

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

  • name: Der Name des Elements. Verwendet die Zugriffsmethoden setName() und getName().

  • label: Das Label des Elements. Verwendet die Zugriffsmethoden setLabel() und getLabel().

  • order: Der Index bei dem ein Element in der Form erscheinen soll. Verwendet die Zugriffsmethoden setOrder() und getOrder().

  • value: Der aktuelle Wert des Elements. Verwendet die Zugriffsmethoden setValue() und getValue().

  • description: Eine Beschreibung des Elements; wird oft verwendet um Tooltips oder Javascript mäßige Hinweise anzubieten die den Zweck des Elements beschreiben. Verwendet die Zugriffsmethoden setDescription() und getDescription().

  • required: Ein Flag das anzeigt ob ein Element benötigt wird wenn eine Prüfung der Form durchgeführt wird, oder nicht. Verwendet die Zugriffsmethoden setRequired() und getRequired(). Dieses Flag ist Standardmäßig false.

  • allowEmpty: Ein Flag das indiziert ob ein nicht-benötigtes (optionales) Element versuchen soll leere Werte zu prüfen. Wenn es true ist, und das required Flag false, dann werden leere Werte nicht an die Prüfkette übergeben, und es wird true angenommen. Verwendet die Zugriffsmethoden setAllowEmpty() und getAllowEmpty(). Dieses Flag ist Standardmäßig true.

  • autoInsertNotEmptyValidator: Ein Flag das indiziert ob eine 'NotEmpty' Prüfung eingefügt werden soll wenn das Element benötigt wird, oder nicht. Standardmäßig ist dieses Flag true. Das Flag kann mit setAutoInsertNotEmptyValidator($flag) gesetzt und der Wert mit autoInsertNotEmptyValidator() ermittelt werden.

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:

  • setAttrib($name, $value): Fügt ein Attribut hinzu

  • addAttribs(array $attribs): Fügt viele Attribute auf einmal hinzu

  • setAttribs(array $attribs): Wie addAttribs(), aber überschreibend

  • getAttrib($name): Empfägt einen einzelnen Attributwert

  • getAttribs(): Empfängt alle Attribute als Schlüssel/Wert Paare

  • removeAttrib($name): Entfernt ein einzelnes Attribut

  • clearAttribs(): Löscht alle Attribute

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:

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.

Standard Elemente

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

Zend_Form_Element Methoden

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

  • Konfiguration:

    • setOptions(array $options)

    • setConfig(Zend_Config $config)

  • I18n:

    • setTranslator(Zend_Translate_Adapter $translator = null)

    • getTranslator()

    • setDisableTranslator($flag)

    • translatorIsDisabled()

  • Eigenschaften:

    • setName($name)

    • getName()

    • setValue($value)

    • getValue()

    • getUnfilteredValue()

    • setLabel($label)

    • getLabel()

    • setDescription($description)

    • getDescription()

    • setOrder($order)

    • getOrder()

    • setRequired($flag)

    • getRequired()

    • setAllowEmpty($flag)

    • getAllowEmpty()

    • setAutoInsertNotEmptyValidator($flag)

    • autoInsertNotEmptyValidator()

    • setIgnore($flag)

    • getIgnore()

    • getType()

    • setAttrib($name, $value)

    • setAttribs(array $attribs)

    • getAttrib($name)

    • getAttribs()

  • Plugin Loader und Pfade:

    • setPluginLoader(Zend_Loader_PluginLoader_Interface $loader, $type)

    • getPluginLoader($type)

    • addPrefixPath($prefix, $path, $type = null)

    • addPrefixPaths(array $spec)

  • Prüfung:

    • addValidator($validator, $breakChainOnFailure = false, $options = array())

    • addValidators(array $validators)

    • setValidators(array $validators)

    • getValidator($name)

    • getValidators()

    • removeValidator($name)

    • clearValidators()

    • isValid($value, $context = null)

    • getErrors()

    • getMessages()

  • Filter:

    • addFilter($filter, $options = array())

    • addFilters(array $filters)

    • setFilters(array $filters)

    • getFilter($name)

    • getFilters()

    • removeFilter($name)

    • clearFilters()

  • Darstellung:

    • setView(Zend_View_Interface $view = null)

    • getView()

    • addDecorator($decorator, $options = null)

    • addDecorators(array $decorators)

    • setDecorators(array $decorators)

    • getDecorator($name)

    • getDecorators()

    • removeDecorator($name)

    • clearDecorators()

    • render(Zend_View_Interface $view = null)

Konfiguration

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:

  • Wenn 'set' + Schlüssel auf eine Zend_Form_Element Methoe zeigt, dann wird der angebotene Wert zu dieser Methode übermittelt.

  • Andernfalls wird der Wert verwendet um ein Attribut zu setzen.

Ausnahmen zu dieser Regel sind die folgenden:

  • prefixPath wird an addPrefixPaths() übergeben

  • Die folgenden Setzer können nicht auf diesem Weg gesetzt werden:

    • setAttrib (über setAttribs wird es funktionieren)

    • setConfig

    • setOptions

    • setPluginLoader

    • setTranslator

    • setView

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"

Eigene Elemente

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

  • Elemente die eine gemeinsame Prüfung und/oder Filter teilen

  • Elemente die eigene Dekorator Funktionalität haben

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:

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:

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:

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.

Previous Next
Introduction to Zend Framework
Übersicht
Installation
Zend_Acl
Einführung
Verfeinern der Zugriffskontrolle
Fortgeschrittene Verwendung
Zend_Auth
Einführung
Datenbanktabellen Authentifizierung
Digest Authentication
HTTP Authentication Adapter
LDAP Authentifizierung
Open ID Authentifikation
Zend_Cache
Einführung
Die Theorie des Cachens
Zend_Cache Frontends
Zend_Cache Backends
Zend_Captcha
Introduction
Captcha Operation
Captcha Adapters
Zend_Config
Einleitung
Theory of Operation
Zend_Config_Ini
Zend_Config_Xml
Zend_Console_Getopt
Einführung in Getopt
Definieren von Getopt Regeln
Holen von Optionen und Argumenten
Konfigurieren von Zend_Console_Getopt
Zend_Controller
Zend_Controller Schnellstart
Zend_Controller Grundlagen
Der Front Controller
Das Request Objekt
Der Standard Router: Zend_Controller_Router_Rewrite
Der Dispatcher
Action Kontroller
Action Helfer
Das Response Objekt
Plugins
Eine konventionelle modulare Verzeichnis Struktur verwenden
MVC Ausnahmen
Migration von vorhergehenden Versionen
Zend_Currency
Einführung in Zend_Currency
Arbeiten mit Währungen
Migration von vorhergehenden Versionen
Zend_Date
Einführung
Theorie der Arbeitsweise
Basis Methoden
Zend_Date API Übersicht
Erstellen von Datumswerten
Konstanten für generelle Datums Funktionen
Funktionierende Beispiele
Zend_Db
Zend_Db_Adapter
Zend_Db_Statement
Zend_Db_Profiler
Zend_Db_Select
Zend_Db_Table
Zend_Db_Table_Row
Zend_Db_Table_Rowset
Zend_Db_Table Relationships
Zend_Debug
Variablen ausgeben
Zend_Dojo
Introduction
Zend_Dojo_Data: dojo.data Envelopes
Dojo View Helpers
Dojo Form Elements and Decorators
Zend_Dom
Introduction
Zend_Dom_Query
Zend_Exception
Verwenden von Ausnahmen
Zend_Feed
Einführung
Feeds importieren
Feeds von Websites abrufen
Einen RSS Feed konsumieren
Einen Atom Feed konsumieren
Einen einzelnen Atom Eintrag konsumieren
Verändern der Feed- und Eintragsstruktur
Eigene Klassen für Feeds und Einträge
Zend_File
Zend_File_Transfer
Validators for Zend_File_Transfer
Zend_Filter
Einführung
Standard Filter Klassen
Filter Ketten
Filter schreiben
Zend_Filter_Input
Zend_Filter_Inflector
Zend_Form
Zend_Form
Schnellstart mit Zend_Form
Erstellen von Form Elementen mit Hilfe von Zend_Form_Element
Erstellen von Form durch Verwendung von Zend_Form
Erstellen von eigenem Form Markup durch Zend_Form_Decorator
Standard Form Elemente die mit dem With Zend Framework ausgeliefert werden
Standard Form Dekoratore die mit dem Zend Framework ausgeliefert werden
Internationalisierung von Zend_Form
Fortgeschrittene Verwendung von Zend_Form
Zend_Gdata
Einführung zu Gdata
Authentifizierung mit AuthSub
Authentifizieren mit ClientLogin
Google Kalender verwenden
Verwenden der Google Dokumente Listen Daten API
Google Tabellenkalkulation verwenden
Google Apps Provisionierung verwenden
Google Base verwenden
Verwenden der YouTube Daten API
Picasa Web Alben verwenden
Gdata Ausnahmen auffangen
Zend_Http
Zend_Http_Client - Einführung
Zend_Http_Client - Fortgeschrittende Nutzung
Zend_Http_Client - Verbindungsadapter
Zend_Http_Cookie und Zend_Http_CookieJar
Zend_Http_Response
Zend_InfoCard
Einführung
Zend_Json
Einführung
Grundlegende Verwendung
JSON Objects
XML zu JSON Konvertierung
Zend_Json_Server - JSON-RPC server
Zend_Layout
Einführung
Zend_Layout Schnellstart
Zend_Layout Konfigurations Optionen
Erweiterte Verwendung von Zend_Layout
Zend_Ldap
Einleitung
Zend_Loader
Dynamisches Laden von Dateien und Klassen
Plugins laden
Zend_Locale
Einführung
Zend_Locale verwenden
Normalisierung und Lokalisierung
Arbeiten mit Daten und Zeiten
Unterstützte Sprachen für Gebietsschemata
Unterstützte Regionen für Gebietsschemata
Zend_Log
Übersicht
Writer
Formatter
Filter
Zend_Mail
Einführung
Versand über SMTP
Versand von mehreren E-Mails über eine SMTP Verbindung
Verwendung von unterschiedlichen Versandwegen
HTML E-Mail
Anhänge
Empfänger hinzufügen
Die MIME Abgrenzung kontrollieren
Zusätzliche Kopfzeilen
Zeichensätze
Kodierung
SMTP Authentifizierung
SMTP Übertragungen sichern
Lesen von Mail Nachrichten
Zend_Measure
Einführung
Erstellung einer Maßeinheit
Ausgabe von Maßeinheiten
Manipulation von Maßeinheiten
Arten von Maßeinheiten
Zend_Memory
Übersicht
Memory Manager
Memory Objekte
Zend_Mime
Zend_Mime
Zend_Mime_Message
Zend_Mime_Part
Zend_OpenId
Einführung
Zend_OpenId_Consumer Grundlagen
Zend_OpenId_Provider
Zend_Paginator
Introduction
Usage
Configuration
Advanced usage
Zend_Pdf
Einführung
Erstellen und Laden von PDF Dokumenten
Änderungen von PDF Dokumenten speichern
Dokument Seiten
Zeichnen
Dokument Informationen und Metadaten
Anwendungsbeispiel für die Zend_Pdf Komponente
Zend_Registry
Die Registry verwenden
Zend_Rest
Einführung
Zend_Rest_Client
Zend_Rest_Server
Zend_Search_Lucene
Überblick
Indexerstellung
Einen Index durchsuchen
Abfragesprache
Abfrage Erzeugungs API
Zeichensätze
Erweiterbarkeit
Zusammenarbeit Mit Java Lucene
Erweitert
Die besten Anwendungen
Zend_Server
Einführung
Zend_Server_Reflection
Zend_Service
Einführung
Zend_Service_Akismet
Zend_Service_Amazon
Zend_Service_Audioscrobbler
Zend_Service_Delicious
Zend_Service_Flickr
Zend_Service_Nirvanix
Zend_Service_ReCaptcha
Zend_Service_Simpy
Einführung
Zend_Service_StrikeIron
Zend_Service_StrikeIron: Mitgelieferte Services
Zend_Service_StrikeIron: Erweiterte Verwendung
Zend_Service_Technorati
Zend_Service_Yahoo
Zend_Session
Einführung
Grundsätzliche Verwendung
Fortgeschrittene Benutzung
Globales Session Management
Zend_Session_SaveHandler_DbTable
Zend_Soap
Zend_Soap_Server
Zend_Soap_Client
WSDL Zugriffsmethoden
AutoDiscovery. Einführung
Automatische Erkennung von Klassen.
Funktionen für Autodiscovery.
Automatische Erkennung. Datentypen.
Zend_Test
Introduction
Zend_Test_PHPUnit
Zend_Text
Zend_Text_Figlet
Zend_TimeSync
Einführung
Arbeiten mit Zend_TimeSync
Zend_Translate
Einführung
Adapter für Zend_Translate
Benutzen von Übersetzungs Adaptoren
Zend_Uri
Zend_Uri
Zend_Validate
Einführung
Standard Prüfklassen
Kettenprüfungen
Schreiben von Prüfern
Zend_Version
Auslesen der Version des Zend Frameworks
Zend_View
Einführung
Controller Skripte
View Scripte
View Helfer
Zend_View_Abstract
Zend_Wildfire
Zend_Wildfire
Zend_XmlRpc
Einführung
Zend_XmlRpc_Client
Zend_XmlRpc_Server
Zend Framework Voraussetzungen
PHP Version
PHP Erweiterungen
Zend Framework Komponenten
Zend Framework Abhängigkeiten
Zend Framework Coding Standard für PHP
Übersicht
PHP Dateiformatierung
Namens Konventionen
Code Stil
Urheberrecht Informationen