Zend Framework 1.7.9 Manual

Wird für die Erstellung von HTML Button Elementen verwendet wobei Zend_Form_Element_Button Zend_Form_Element_Submit erweitert, und seine eigene Funktionalität hinzufügt. Sie spezifiziert den 'formButton' View Helfer für die Dekoration.

Wie das Submit Element, verwendet es das Label des Elements als den Elementwert für Darstellungszwecke; in anderen Worten, um den Text des Buttons zu setzen, muß der Wert des Elements gesetzt werden. Das Label wird übersetzt wenn ein Übersetzungsadapter vorhanden ist.

Weil das Label als Teil des Elements verwendet wird, verwendet das Button Element nur den ViewHelper und den DtDdWrapper Dekorator.

Nach der Veröffentlichung oder Prüfung einer Form, kann geprüft werden ob der gegebene Button geklickt wurd indem die isChecked() Methode verwendet wird.

CAPTCHAs werden verwendet um automatische Übermittlung von Formularen durch Bots und andere automatische Prozesse zu verhindern.

Das Captcha Formularelement erlaubt es den Zend_Captcha Adapter der als Formular Captcha verwendet werden soll anzupassen. Er setzt dann diesen Adapter als Prüfung für das Objekt, und verwendet den Captcha Dekorator für die Darstellung (welche den Captcha Adapter aufruft).

Adapter können alle Adapter in Zend_Captcha sein, sowie jeder eigene Adapter der irgendwo anders definiert wurde. Um das z uerlauben, kann ein zusätzlicher Schlüssel für den Plugin Ladetyp, 'CAPTCHA' oder 'captcha' übergeben werden, wenn der Plugin Loader Präfixpfad spezifiziert wird:

$element->addPrefixPath('My_Captcha', 'My/Captcha/', 'captcha');

Captcha's können dann durch Verwendung der setCaptcha() Methode registriert werden, welche entweder eine konkrete Captcha Instanz, oder den Kurznamen des Captcha Adapters nimmt:

// Konkrete Instanz:
$element->setCaptcha(new Zend_Captcha_Figlet());

// Verwendung von Kurznamen:
$element->setCaptcha('Dumb');

Wenn das Element über die Konfiguration geladen werden soll, kann entweder der Schlüssel 'captcha' mit einem Array das den Schlüssel 'captcha' enthält spezifiziert werden, oder beide Schlüssel 'captcha' und 'captchaOptions':

// Verwendung eines einzelnen captcha Schlüssels:
$element = new Zend_Form_Element_Captcha('foo', array(
    'label' => "Bitte verifizieren Sie das Sie menschlich sind",
    'captcha' => array(
        'captcha' => 'Figlet',
        'wordLen' => 6,
        'timeout' => 300,
    ),
));

// Verwendung von beiden, captcha und captchaOptions:
$element = new Zend_Form_Element_Captcha('foo', array(
    'label' => "Bitte verifizieren Sie das Sie menschlich sind",
    'captcha' => 'Figlet',
    'captchaOptions' => array(
        'captcha' => 'Figlet',
        'wordLen' => 6,
        'timeout' => 300,
    ),
));

Der verwendete Dekorator wird durch die Abfrage des Captcha Adapters erkannt. Standardmäßig wird der Captcha Dekorator verwendet, aber ein Adapter kann einen anderen über die getDecorator() Methode spezifizieren.

Wie beschrieben, fungiert der Captcha Adapter selbst als Prüfnug für das Element. Zusätzlich wird die NotEmpty Prüfung nicht verwendet, und das Element wird als benötigt markiert. In den meisten Fällen sollte sonst nichts anderes mehr notwendig sein um das Captcha im eigenen Formular zu haben.

HTML Checkboxen erlauben es spezifische Werte zurückzugeben, arbeiten aber grundsätzlich als Boolean: Wenn Sie angehackt sind, wird der Wert übertragen; wenn Sie nicht angehackt sind, wird nichts übertragen. Intern erzwingt Zend_Form_Element_Checkbox diesen Status.

Standardmäßg ist der angehackte Wert '1', und der nicht angehackte Wert '0'. Dieser Wert kann spezifiziert werden indem die setCheckedValue() und setUncheckedValue() Zugriffsmethoden verwendet werden. Intern wird, jedesmal wenn der Wert gesetzt wird, wenn der angebotene Wert dem angehackten Wert entspricht, er gesetzt, aber jeder andere Wert bewirkt das der nicht angehackte Wert gesetzt wird.

Zusätzlich setzt, das Setzen des Werte, die checked Eigenschaft der Checkbox. Das kann abgefragt werden indem isChecked() verwendet wird oder einfach auf die Eigenschaft zugegriffen wird. Das Verwenden der setChecked($flag) Methode setzt beides, den Status des Flags sowie den entsprechenden gecheckten oder nicht gecheckten Wert im Element. Bitte verwenden Sie diese Methode wenn der gecheckte Status eines Checkbox Elements gesetzt wird um sicherzustellen das der Wert richtig gesetzt wird.

Zend_Form_Element_Checkbox verwendet den 'formCheckbox' View Helfer. Der angehackte Wert wird immer verwendet um Sie zu veröffentlichen.

Das File Formularelement bietet einen Mechanismus um File Upload-felder in eigenen Formularen zu Unterstützen. Es verwendet intern Zend_File_Transfer um diese Funktionalität zu bieten, und den FormFile Viewhelfer sowie den File Decorator um das Formularelement anzuzeigen.

Standardmäßig verwendet es den Http Transferadapter, welcher das $_FILES Array prüft und es erlaubt Prüfungen und Filter hinzuzufügen. Prüfungen und Filter die dem Formularelement hinzugefügt werden, werden dem Transferadapter hinzugefügt.

$element = new Zend_Form_Element_File('foo');
$element->setLabel('Ein Bild hochladen:')
        ->setDestination('/var/www/upload');
// Nur 1 Datei sicherstellen
$element->addValidator('Count', false, 1);
// Maximal 100k
$element->addValidator('Size', false, 102400);
// Nur JPEG, PNG, und GIFs
$element->addValidator('Extension', false, 'jpg,png,gif');
$form->addElement($element, 'foo');

$form->setAttrib('enctype', 'multipart/form-data');

if (!$form->isValid) {
    print "Ohoh... Prüfungsfehler";
}

if (!$form->foo->receive()) {
    print "Fehler beim Empfangen der Datei";
}

$location = $form->foo->getFileName();

Note: Standardmäßige Ablage von Uploads

Standardmäßig werden Dateien in das Temp Verzeichnis des Systems hochgeladen.

Note: Datei Werte

In HTTP hat das File Element keinen Wert. Deshalb, und aus Gründen der Sicherheit erhält man nur den hochgeladenen Dateinamen wenn man getValue() aufruft und nicht den kompletten Pfad. Wenn man die kompletten Informationen benötigt kann getFileName() aufgerufen werden, welches den Pfad und Namen der Datei zurückgibt.

Es gibt verschiedene Stati von hochgeladenen Dateien welche mit den folgenden Optionen geprüft werden können:

• isUploaded(): Prüft ob das Dateielement hochgeladen wurde oder nicht.

• isReceived(): Prüft ob das Dateielement bereits empfangen wurde.

• isFiltered(): Prüft ob die Filter bereits dem Dateielement angehängt wurden oder nicht.

$element = new Zend_Form_Element_File('foo');
$element->setLabel('Ein Bild hochladen:')
        ->setDestination('/var/www/upload')
        ->setRequired(false);
$element->addValidator('Size', false, 102400);
$form->addElement($element, 'foo');

// Das foo Dateielement is optional, aber wenn es angegeben wurde, gehe hier herein
if ($form->foo->isUploaded()) {
    // Die foo Datei ist angegeben... mach was
}

Zend_Form_Element_File unterstützt auch mehrere Dateien. Durch den Aufruf der setMultiFile($count) Methode kann die Anzahl an File Elementen die man erstellen will festgelegt werden. Das verhindert das die selben Einstellungen mehrere Male durchgeführt werden müssen.

$element = new Zend_Form_Element_File('foo');
$element->setLabel('Ein Bild hochladen:')
        ->setDestination('/var/www/upload');
// Mindestens 1 und maximal 3 Dateien sicherstellen
$element->addValidator('Count', false, array('min' => 1, 'max' => 3));
// Auf 100k limitieren
$element->addValidator('Size', false, 102400);
// Nur JPEG, PNG, und GIFs
$element->addValidator('Extension', false, 'jpg,png,gif');
// 3 identische Dateielemente definieren
$element->setMultiFile(3);
$form->addElement($element, 'foo');

Note: File Elemente in Subformularen

Wenn File Elemente in Subformularen verwendet werden muß man eindeutige Namen setzen. Sodas ein File Element in Subform1 das "file" heißt, in Subform2 einen anderen Namen erhalten muß.

Sobald es 2 identisch benannte File Elemente gibt, wird das zweite Element entweder nicht dargestellt oder nicht übertragen.

Um die Größe der Datei zu begrenzen, die vom Client hochgeladen wird, sollte man zusätzlich die maximale Dateigröße setzen die das Formular akzeptiert. Das begrenzt die Größe auf der Clientseite durch das Setzen der MAX_FILE_SIZE Option im Formular. Sobald der Wert, durch die Verwendung der setMaxFileSize($size) Methode, gesetzt ist, wird er mit dem File Element dargestellt.

$element = new Zend_Form_Element_File('foo');
$element->setLabel('Ein Bild hochladen:')
        ->setDestination('/var/www/upload')
        ->addValidator('Size', false, 102400) // Limitiert auf 100k
        ->setMaxFileSize(102400); // Limitiert die Dateigröße auf der Clientseite
$form->addElement($element, 'foo');

Note: MaxFileSize mit mehreren File Elementen

Wenn mehrere File Elemente im Formular verwendet werden muß man MAX_FILE_SIZE nur einmal setzen. Wenn man es nochmals setzt überschreibt der vorher gesetzte Wert überschrieben.

Es ist zu beachten das man MAX_FILE_SIZE nur einmal setzen kann, selbst wenn man mehrere Formuare verwendet.

Versteckte Elemente fügen Daten ein die übertragen werden sollen, aber welche der Benutzer nicht manipulieren soll. Zend_Form_Element_Hidden ermöglicht das durch die Verwendung des 'formHidden' View Helfers.

Dieses Element bietet Schutz vor CSRF Attacken auf Forms, und stellt sicher das die Daten die übertragen werden von der Benutzersession stammen die die Form erstellt hat und nicht durch ein bösartiges Skript. Sicherheit wird ermöglicht durch das hinzufügen eines Hash Elements zur form und dessen Prüfung wenn die Form übermittelt wird.

Der Name des Hash Elements sollte einmalig sein. Es ist notwendig das die salt Option für das Element verwendet wird, damit zwei Hashes mit dem gleichen Namen und unterschiedlichen Salts nicht kollidieren:

$form->addElement('hash', 'no_csrf_foo', array('salt' => 'unique'));

Das Salt kann später gesetzt werden durch Verwendung der setSalt($salt) Methode.

Intern speichert das Element einen eindeutigen Identifikator indem es Zend_Session_Namespace verwendet, und danach bei der Übertragung checkt (es wird geprüft das die TTL nicht abgelaufen ist). Die 'Identical' Prüfung wird Internally, the element stores a unique identifier using Zend_Session_Namespace, and checks for it at submission (checking that the TTL has not expired). The 'Identical' validator is then used to ensure the submitted hash matches the stored hash.

Der 'formHidden' View Helfer wird verwendet um das Element in der Form darzustellen.

Bilder können als Form Elemente verwendet werden und erlaubt es graphische Elemente als Form Buttons zu spezifizieren.

Bilder benötigen eine Bildquelle. Zend_Form_Element_Image erlaube dessen Spezifikation durch Verwendung der setImage() Zugriffsmethode (oder des 'image' Konfigurations Schlüssels). Es kann auch optional ein Wert spezifiziert werden der zu verwenden ist wenn das Bild übertragen wird indem die Zugriffsmethode setImageValue() verwendet wird (oder der 'imageValue Konfigurations Schlüssel). Wenn der Wert der für das Element gesetzt ist, mit imageValue übereinstimmt, gibt isChecked() true zurück.

Das Bild Element verwenden den Image Decorator für die Darstellung (genauso wie die Standard Error, HtmlTag und Label Dekoratore). Es kann optional ein Tag für den Image Dekorator spezifiziert werden der das Bild einbettet.

Oft hat man ein Set von zusammenhängenden Checkboxen, und die Ergebnisse sollen gruppiert werden. Das ist so ähnlich wie Multiselect aber statt das Sie in einer DropDown Liste sind, müssen Checkbox/Werte Paare dargestellt werden.

Zend_Form_Element_MultiCheckbox macht das in einem Rutsch. Wie alle anderen Elemente kann mit der Erweiterung des Basis MultiElements eine Liste von Optionen spezifiziert werden und einfach gegen die selbe Liste geprüft werden. Der 'formMultiCheckbox' View Helfer stellt sicher das Sie als Array bei der Übermittlung der Form zurückgegeben werden.

Standardmäßig registriert dieses Element die InArray Prüfung welche gegen Arrayschlüssel von registrierten Optionen prüft. Dieses Verhalten kann deaktiviert werden indem entweder setRegisterInArrayValidator(false) aufgerufen, oder indem ein false Wert an den registerInArrayValidator Konfigurationsschlüssel übergeben wird.

Die verschiedenen Checkbox Optionen können mit den folgenden Methoden manipuliert werden:

• addMultiOption($option, $value)

• addMultiOptions(array $options)

• setMultiOptions(array $options) (überschreibt existierende Optionen)

• getMultiOption($option)

• getMultiOptions()

• removeMultiOption($option)

• clearMultiOptions()

Um gecheckte Elemente zu markieren, muß ein Array an Werte an setValue() übergeben werden. Der folgende Code prüft die Werte "bar" und "bat":

$element = new Zend_Form_Element_MultiCheckbox('foo', array(
    'multiOptions' => array(
        'foo' => 'Foo Option',
        'bar' => 'Bar Option',
        'baz' => 'Baz Option',
        'bat' => 'Bat Option',
    );
));

$element->setValue(array('bar', 'bat'));

Beachte das man auch für das Setzen eines einzelnen Wertes ein Array übergeben muß.

XHTML select Elemente erlaube ein 'multiple' Attribut, das zeigt das mehrere Optionen für die Übermittlung ausgewählt werden können, statt normalerweise nur eines. Zend_Form_Element_Multiselect erweitert Zend_Form_Element_Select und setzt das multiple Attribut auf 'multiple'. Wie andere Klassen die von der Basisklasse Zend_Form_Element_Multi abgeleitet werden, können die Optionen für die Auswahl wie folgt verändert werden:

• addMultiOption($option, $value)

• addMultiOptions(array $options)

• setMultiOptions(array $options) (überschreibt existierende Optionen)

• getMultiOption($option)

• getMultiOptions()

• removeMultiOption($option)

• clearMultiOptions()

Wenn ein Übersetzungs Adapter in der Form und/oder dem Element registriert ist, werden Optionswerte für Darstellungzwecke übersetzt.

Standardmäßig registriert dieses Element die InArray Prüfung welche gegen Arrayschlüssel von registrierten Optionen prüft. Dieses Verhalten kann deaktiviert werden indem entweder setRegisterInArrayValidator(false) aufgerufen, oder indem ein false Wert an den registerInArrayValidator Konfigurationsschlüssel übergeben wird.

Passwort Element sind grundsätzlich normale Textelemente -- ausser das typischerweise das eingegebene Passwort nicht in Fehlermeldungen oder dem Element selbst angezeigt werden soll wenn die Form normals angezeigt wird.

Zend_Form_Element_Password ermöglicht das durch den Aufruf von setObscureValue(true) auf jeder Prüfung (und stellt sicher das das Passwort in der Prüfungs Fehlermeldung verschleiert wird), und verwendet den 'formPassword' View Helfer (welcher den an Ihn übergebenen Wert nicht anzeigt).

Radio Elemente erlauben es verschiedene Optionen zu spezifizieren, von denen ein einzelner Wert zurückgegeben wird. Zend_Form_Element_Radio erweitert die Basisklasse Zend_Form_Element_Multi und erlaubt es eine Anzahl von Optionen zu spezifizieren, und verwendet dann den formRadio View Helfer um diese darzustellen.

Standardmäßig registriert dieses Element die InArray Prüfung welche gegen Arrayschlüssel von registrierten Optionen prüft. Dieses Verhalten kann deaktiviert werden indem entweder setRegisterInArrayValidator(false) aufgerufen, oder indem ein false Wert an den registerInArrayValidator Konfigurationsschlüssel übergeben wird.

Wie alle Elemente die die Basisklasse des Mutli Elements erweitern, können die folgenden Methode verwendet werden um die Radio Optionen zu manipulieren die angezeigt werden:

• addMultiOption($option, $value)

• addMultiOptions(array $options)

• setMultiOptions(array $options) (überschreibt existierende Optionen)

• getMultiOption($option)

• getMultiOptions()

• removeMultiOption($option)

• clearMultiOptions()

Reset Buttons werden typischerweise verwendet um eine Form zu löschen, und sind nicht Teil der übermittelten Daten. Da Sie trotzdem einen Zweck in der Anzeige bieten, sind Sie in den Standardelementen enthalten.

Zend_Form_Element_Reset erweitert Zend_Form_Element_Submit. Deswegen wird das Label für die Anzeige des Buttons verwendet und wird übersetzt wenn ein Übersetzungs Adapter vorhanden ist. Es verwendet nur die 'ViewHelper' und 'DtDdWrapper' Dekoratore, da es nie Fehlermeldungen für solche Elemente geben sollte, noch sollte ein Label notwendig sein.

Auswahlboxen sind der übliche Weg um spezielle Auswahlen für gegebene Formdaten zu begrenzen. Zend_Form_Element_Select erlaubt es diese schnell und einfach zu erzeugen.

Standardmäßig registriert dieses Element die InArray Prüfung welche gegen Arrayschlüssel von registrierten Optionen prüft. Dieses Verhalten kann deaktiviert werden indem entweder setRegisterInArrayValidator(false) aufgerufen, oder indem ein false Wert an den registerInArrayValidator Konfigurationsschlüssel übergeben wird.

Da es das Basis Multielement erweitert, können die folgenden Methoden verwendet werden um die Auswahloptionen zu manipulieren:

• addMultiOption($option, $value)

• addMultiOptions(array $options)

• setMultiOptions(array $options) (überschreibt existierende Optionen)

• getMultiOption($option)

• getMultiOptions()

• removeMultiOption($option)

• clearMultiOptions()

Zend_Form_Element_Select verwendet den 'formSelect' View Helfer für die Dekoration.

Sendebuttons (Submit) werden verwendet um eine Form zu senden. Es kann gewünscht sein mehrere Sendebuttons zu verwendetn; die Buttons zur Übermittlung der Form können verwendet werden um auszuwählen welche Aktion mit den übermittelten Daten genommen werden soll. Zend_Form_Element_Submit macht die Entscheidung einfach, durch das Hinzufügen einer isChecked() Methode; da nur ein Button Element von der Form übermittelt wird, nachdem die Form übermittelt oder geprüft wurde, kann diese Methode auf jedem Sendebutton ausgerufen werden um festzustellen welcher verwendet wurde.

Zend_Form_Element_Submit verwendet das Label als den "Wert" des Sendebuttons, und übersetzt es wenn ein Übersetzungsadapter vorhanden ist. isChecked() prüft den übermittelten Wert gegen das Label um festzustellen ob der Button verwendet wurde.

Die ViewHelper und DtDdWrapper Dekoratore werden verwendet um das Element darzustellen. Es wird kein Labeldekorator verwendet, da das Label des Buttons verwendet wird wenn das Element dargestellt wird; typischerweise werden acuh keine Fehler mit einem Sendeelement assoziiert.

Der nützlichste Typ von Form Element ist das Text Element, das begrenzte Texteinträge erlaubt; es ist ein ideales Element für die meisten Dateneinträge. Zend_Form_Element_Text verwendet einfach den 'formText' View Helfer um das Element darzustellen.

Textbereiche werden verwendet wenn große Mengen von Text erwartet werden, und keine Begrenzung in der Anzahl des übermittelten Textes vorhanden sind (anders als das Limit der Maximalgröße wie vom Server von PHP diktiert). Zend_Form_Element_Textarea verwendet den 'textArea' View Helfer um solche Element darzustellen, und platziert den Wert als Inhalt des Elements.