Utilizado para crear elementos de botón HTML, Zend_Form_Element_Button extiende Zend_Form_Element_Submit, especificando algo de funcionalidad personalizada. Especifica el ayudante de vista 'formButton' para la decoración.

Al igual que el elemento submit, utiliza la etiqueta del elemento como el valor del elemento a efectos de visualización; en otras palabras, para establecer el texto del botón, establezca el valor del elemento. La etiqueta se traducirá si hay presente un adaptador de traducción.

Debido a que la etiqueta se utiliza como parte del elemento, el elemento button solo utiliza los decoradores ViewHelper y DtDdWrapper.

Los CAPTCHA se utilizan para evitar el envío automatizado de formularios por bots y otros procesos automatizados.

El elemento de formulario Captcha le permite especificar qué adaptador de Zend_Captcha desea utilizar como CAPTCHA de formulario. A continuación, establece dicho adaptador como un validador para el objeto y utiliza un decorador Captcha para el renderizado (que actúa como proxy hacia el adaptador CAPTCHA).

Los adaptadores pueden ser cualquiera de los adaptadores en Zend_Captcha, así como cualquier adaptador personalizado que usted haya definido en otro lugar. Para permitir esto, puede pasar una clave de tipo de plugin loader adicional, 'CAPTCHA' o 'captcha', al especificar una ruta de prefijo del plugin loader:

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

Los Captcha pueden entonces registrarse mediante el método setCaptcha(), que puede recibir bien una instancia CAPTCHA concreta, o bien el nombre corto de un adaptador CAPTCHA:

// Instancia concreta:
$element->setCaptcha(new Zend_Captcha_Figlet());

// Usando nombres cortos:
$element->setCaptcha('Dumb');

Si desea cargar su elemento mediante configuración, especifique bien la clave 'captcha' con un array que contenga la clave 'captcha', o tanto la clave 'captcha' como 'captchaOptions':

// Usando una única clave captcha:
$element = new Zend_Form_Element_Captcha('foo', array(
    'label' => "Please verify you're a human",
    'captcha' => array(
        'captcha' => 'Figlet',
        'wordLen' => 6,
        'timeout' => 300,
    ),
));

// Usando tanto captcha como captchaOptions:
$element = new Zend_Form_Element_Captcha('foo', array(
    'label' => "Please verify you're a human",
    'captcha' => 'Figlet',
    'captchaOptions' => array(
        'captcha' => 'Figlet',
        'wordLen' => 6,
        'timeout' => 300,
    ),
));

El decorador utilizado se determina consultando al adaptador captcha. Por defecto, se utiliza el decorador Captcha, pero un adaptador puede especificar uno diferente mediante su método getDecorator().

Como se ha señalado, el propio adaptador captcha actúa como validador para el elemento. Además, no se utiliza el validador NotEmpty, y el elemento se marca como obligatorio. En la mayoría de los casos, no debería necesitar hacer nada más para tener un captcha presente en su formulario.

Las casillas de verificación HTML le permiten devolver un valor específico, pero básicamente funcionan como booleanos. Cuando está marcada, se envía el valor de la casilla. Cuando la casilla no está marcada, no se envía nada. Internamente, Zend_Form_Element_Checkbox impone este estado.

Por defecto, el valor marcado es '1', y el valor no marcado '0'. Puede especificar los valores a utilizar mediante los accesores setCheckedValue() y setUncheckedValue(), respectivamente. Internamente, cada vez que se establece el valor, si el valor proporcionado coincide con el valor marcado, entonces se establece, pero cualquier otro valor provoca que se establezca el valor no marcado.

Además, establecer el valor establece la propiedad checked de la casilla. Puede consultar esto usando isChecked() o simplemente accediendo a la propiedad. Usar el método setChecked($flag) establecerá tanto el estado del flag como el valor marcado o no marcado apropiado en el elemento. Por favor, utilice este método al establecer el estado marcado de un elemento checkbox para asegurar que el valor se establezca correctamente.

Zend_Form_Element_Checkbox utiliza el ayudante de vista 'formCheckbox'. El valor marcado siempre se utiliza para rellenarlo.

El elemento de formulario File proporciona un mecanismo para incorporar campos de subida de archivos a su formulario. Utiliza internamente Zend_File_Transfer para proporcionar esta funcionalidad, y el ayudante de vista FormFile, así como el decorador File para mostrar el elemento de formulario.

Por defecto, utiliza el adaptador de transferencia Http, que inspecciona el array $_FILES y le permite adjuntar validadores y filtros. Los validadores y filtros adjuntados al elemento de formulario se adjuntan a su vez al adaptador de transferencia.

$element = new Zend_Form_Element_File('foo');
$element->setLabel('Upload an image:')
        ->setDestination('/var/www/upload');
// ensure only 1 file
$element->addValidator('Count', false, 1);
// limit to 100K
$element->addValidator('Size', false, 102400);
// only JPEG, PNG, and GIFs
$element->addValidator('Extension', false, 'jpg,png,gif');
$form->addElement($element, 'foo');

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

if (!$form->isValid()) {
    print "Uh oh... validation error";
}

if (!$form->foo->receive()) {
    print "Error receiving the file";
}

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

	Ubicación de subida por defecto
	Por defecto, los archivos se suben al directorio temporal del sistema.

	Valores de archivo
	Dentro de HTTP un elemento file no tiene valor. Por esta razón y por motivos de seguridad, getValue() devuelve únicamente el nombre del archivo subido y no la ruta completa. Si necesita la ruta del archivo, llame a getFileName(), que devuelve tanto la ruta como el nombre de el archivo.

	Valor devuelto por getFileName()
	El resultado devuelto por el método getFileName() cambiará dependiendo de cuántos archivos haya subido Zend_Form_Element_File: Un único archivo: cadena que contiene el nombre del único archivo. Múltiples archivos: un array, donde cada elemento es una cadena que contiene un único nombre de archivo. Ningún archivo: un array vacío

Por defecto el archivo se recibirá automáticamente cuando llame a getValues() en el formulario. La razón detrás de este comportamiento es que el propio archivo es el valor del elemento file.

$form->getValues();

	Nota
	Por lo tanto, otra llamada a receive() después de llamar a getValues() no tendrá efecto. Además, crear una instancia de Zend_File_Transfer no tendrá efecto, ya que no queda ningún archivo por recibir.

Aun así, a veces puede que desee llamar a getValues() sin recibir el archivo. Puede lograr esto llamando a setValueDisabled(true). Para obtener el valor actual de este flag puede llamar a isValueDisabled().

$element = new Zend_Form_Element_File('foo');
$element->setLabel('Upload an image:')
        ->setDestination('/var/www/upload')
        ->setValueDisabled(true);

$values = $form->getValues();

if ($form->isValid($form->getPost())) {
    if (!$form->foo->receive()) {
        print "Upload error";
    }
}

Hay varios estados del archivo subido que se pueden comprobar con los siguientes métodos:

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

// The foo file element is optional but when it's given go into here
if ($form->foo->isUploaded()) {
    // foo file given... do something
}

Zend_Form_Element_File también admite múltiples archivos. Llamando al método setMultiFile($count) puede establecer el número de elementos file que desea crear. Esto le evita tener que establecer los mismos ajustes varias veces.

$element = new Zend_Form_Element_File('foo');
$element->setLabel('Upload an image:')
        ->setDestination('/var/www/upload');
// ensure minimum 1, maximum 3 files
$element->addValidator('Count', false, array('min' => 1, 'max' => 3));
// limit to 100K
$element->addValidator('Size', false, 102400);
// only JPEG, PNG, and GIFs
$element->addValidator('Extension', false, 'jpg,png,gif');
// defines 3 identical file elements
$element->setMultiFile(3);
$form->addElement($element, 'foo');

Elementos file en subformularios

Cuando utiliza elementos file en subformularios debe establecer nombres únicos. Por ejemplo, si nombra a un elemento file en subform1 "file", debe darle a cualquier elemento file en subform2 un nombre diferente. Si hay 2 elementos file con el mismo nombre, el segundo elemento no se muestra ni se envía. Además, los elementos file no se renderizan dentro del subformulario. Así que cuando añade un elemento file a un subformulario, el elemento se renderizará dentro del formulario principal.

Para limitar el tamaño del archivo subido, puede especificar el tamaño máximo de archivo estableciendo la opción MAX_FILE_SIZE en el formulario. Cuando establece este valor mediante el método setMaxFileSize($size), se renderizará junto con el elemento file.

$element = new Zend_Form_Element_File('foo');
$element->setLabel('Upload an image:')
        ->setDestination('/var/www/upload')
        ->addValidator('Size', false, 102400) // limit to 100K
        ->setMaxFileSize(102400); // limits the filesize on the client side
$form->addElement($element, 'foo');

	MaxFileSize con múltiples elementos file
	Cuando utiliza múltiples elementos file en su formulario, debe establecer el valor MAX_FILE_SIZE solo una vez. Establecerlo de nuevo sobrescribirá el valor anterior. Tenga en cuenta que este también es el caso cuando utiliza varios formularios.

Los elementos hidden inyectan datos que deben enviarse, pero que no deben ser manipulados por el usuario. Zend_Form_Element_Hidden logra esto con el ayudante de vista 'formHidden'.

Este elemento proporciona protección contra ataques CSRF en formularios, asegurando que los datos sean enviados por la sesión de usuario que generó el formulario y no por un script malicioso. La protección se logra añadiendo un elemento hash a un formulario y verificándolo cuando el formulario se envía.

El nombre del elemento hash debe ser único. Recomendamos utilizar la opción salt para el elemento; dos hashes con el mismo nombre y diferentes salts no colisionarían:

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

Puede establecer el salt más tarde usando el método setSalt($salt).

Internamente, el elemento almacena un identificador único usando Zend_Session_Namespace, y lo comprueba en el envío (verificando que el TTL no haya expirado). Luego se utiliza el validador 'Identical' para asegurar que el hash enviado coincida con el hash almacenado.

El ayudante de vista 'formHidden' se utiliza para renderizar el elemento en el formulario.

Probar formularios que contienen Zend_Form_Element_Hash

Al realizar pruebas unitarias de un formulario que contiene un Zend_Form_Element_Hash es necesario llamar a initCsrfToken y initCsrfValidator antes de intentar validar el formulario. El valor hash del elemento Zend_Form_Element_Hash también debe inyectarse en el array de valores pasado como argumento a Zend_Form::isValid Ejemplo 36.12. Ejemplo sencillo de prueba de un formulario protegido contra CSRF public function testCsrfProtectedForm() { $form = new Zend_Form(); $form->addElement(new Zend_Form_Element_Hash('csrf')); $csrf = $form->getElement('csrf'); $csrf->initCsrfToken(); $csrf->initCsrfValidator(); $this->assertTrue($form->isValid(array( 'csrf' => $csrf->getHash() ))); }

Las imágenes pueden utilizarse como elementos de formulario, y puede usar estas imágenes como elementos gráficos en botones de formulario.

Las imágenes necesitan un origen de imagen. Zend_Form_Element_Image le permite especificarlo mediante el accesor setImage() (o la clave de configuración 'image'). También puede especificar opcionalmente un valor a utilizar al enviar la imagen usando el accesor setImageValue() (o la clave de configuración 'imageValue'). Cuando el valor establecido para el elemento coincide con imageValue, entonces el accesor isChecked() devolverá TRUE.

Los elementos image utilizan el decorador Image para el renderizado, además de los decoradores estándar Errors, HtmlTag y Label. Opcionalmente puede especificar una etiqueta al decorador Image que envolverá entonces el elemento image.

A menudo tiene un conjunto de casillas de verificación relacionadas, y desea agrupar los resultados. Esto es muy similar a un Multiselect, pero en lugar de estar en una lista desplegable, necesita mostrar pares checkbox/valor.

Zend_Form_Element_MultiCheckbox hace que esto sea muy sencillo. Como todos los demás elementos que extienden la clase base Multi, puede especificar una lista de opciones, y validar fácilmente contra esa misma lista. El ayudante de vista 'formMultiCheckbox' garantiza que se devuelvan como un array en el envío del formulario.

Por defecto, este elemento registra un validador InArray que valida contra las claves del array de opciones registradas. Puede deshabilitar este comportamiento llamando a setRegisterInArrayValidator(false), o pasando un valor FALSE a la clave de configuración registerInArrayValidator.

Puede manipular las diversas opciones de checkbox utilizando los siguientes métodos:

Para marcar los elementos seleccionados, necesita pasar un array de valores a setValue(). Lo siguiente marcará los valores "bar" y "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'));

Tenga en cuenta que incluso al establecer un único valor, debe pasar un array.

Los elementos select de XHTML permiten un atributo 'multiple', que indica que se pueden seleccionar varias opciones para su envío, en lugar de la habitual única. Zend_Form_Element_Multiselect extiende Zend_Form_Element_Select, y establece el atributo multiple a 'multiple'. Al igual que otras clases que heredan de la clase base Zend_Form_Element_Multi, puede manipular las opciones del select usando:

Si hay un adaptador de traducción registrado con el formulario y/o el elemento, los valores de las opciones se traducirán a efectos de visualización.

Por defecto, este elemento registra un validador InArray que valida contra las claves del array de opciones registradas. Puede deshabilitar este comportamiento llamando a setRegisterInArrayValidator(false), o pasando un valor FALSE a la clave de configuración registerInArrayValidator.

Los elementos password son básicamente elementos de texto normales, salvo que típicamente no desea que la contraseña enviada se muestre en los mensajes de error ni en el propio elemento cuando el formulario se vuelve a mostrar.

Zend_Form_Element_Password logra esto llamando a setObscureValue(true) en cada validador (asegurando que la contraseña se oculte en los mensajes de error de validación), y usando el ayudante de vista 'formPassword' (que no muestra el valor que se le pasa).

Los elementos radio le permiten especificar varias opciones, de las cuales necesita que se devuelva un único valor. Zend_Form_Element_Radio extiende la clase base Zend_Form_Element_Multi, permitiéndole especificar un número de opciones, y luego utiliza el ayudante de vista formRadio para mostrarlas.

Por defecto, este elemento registra un validador InArray que valida contra las claves del array de opciones registradas. Puede deshabilitar este comportamiento llamando a setRegisterInArrayValidator(false), o pasando un valor FALSE a la clave de configuración registerInArrayValidator.

Como todos los elementos que extienden la clase base Multi, los siguientes métodos pueden usarse para manipular las opciones radio mostradas:

Los botones reset se utilizan típicamente para vaciar un formulario, y no forman parte de los datos enviados. Sin embargo, dado que cumplen un propósito en la visualización, se incluyen en los elementos estándar.

Zend_Form_Element_Reset extiende Zend_Form_Element_Submit. Como tal, la etiqueta se utiliza para la visualización del botón, y se traducirá si hay presente un adaptador de traducción. Utiliza únicamente los decoradores 'ViewHelper' y 'DtDdWrapper', ya que nunca debería haber mensajes de error para tales elementos, ni tampoco será necesaria una etiqueta.

Los cuadros de selección son una forma habitual de limitar las opciones específicas para un determinado dato de formulario. Zend_Form_Element_Select le permite generarlos rápida y fácilmente.

Por defecto, este elemento registra un validador InArray que valida contra las claves del array de opciones registradas. Puede deshabilitar este comportamiento llamando a setRegisterInArrayValidator(false), o pasando un valor FALSE a la clave de configuración registerInArrayValidator.

Dado que extiende la clase base Multi, los siguientes métodos pueden usarse para manipular las opciones del select:

Zend_Form_Element_Select utiliza el ayudante de vista 'formSelect' para la decoración.

Los botones submit se utilizan para enviar un formulario. Puede usar múltiples botones submit; puede usar el botón utilizado para enviar el formulario para decidir qué acción tomar con los datos enviados. Zend_Form_Element_Submit facilita esta decisión, añadiendo un método isChecked(); ya que solo un botón se enviará mediante el formulario, después de rellenar o validar el formulario, puede llamar a este método en cada botón submit para determinar cuál se utilizó.

Zend_Form_Element_Submit utiliza la etiqueta como el "valor" del botón submit, traduciéndola si hay presente un adaptador de traducción. isChecked() compara el valor enviado con la etiqueta para determinar si se utilizó el botón.

Los decoradores ViewHelper y DtDdWrapper renderizan el elemento. No se utiliza ningún decorador de etiqueta, ya que la etiqueta del botón se utiliza al renderizar el elemento; además, normalmente, no asociará errores a un elemento submit.

Con diferencia, el tipo de elemento de formulario más frecuente es el elemento de texto, que permite una entrada de texto limitada; es un elemento ideal para la mayoría de la entrada de datos. Zend_Form_Element_Text simplemente utiliza el ayudante de vista 'formText' para mostrar el elemento.

Los textarea se utilizan cuando se esperan grandes cantidades de texto, y no imponen límites en la cantidad de texto enviado (aparte de los límites de tamaño máximo dictados por su servidor o PHP). Zend_Form_Element_Textarea utiliza el ayudante de vista 'textArea' para mostrar dichos elementos, colocando el valor como el contenido de el elemento.