Zend_Form hace uso de Zend_Loader_PluginLoader para permitir a los desarroladores especificar la ubicación de elementos y decoradores alternativos. Cada uno tiene su propio plugin loader asociado, y métodos de acceso genéricos son usados para recuperar y modificar cada uno.

Los siguientes tipos de cargadores son usados con los variados métodos del plugin loader: 'element' y 'decorator'. Los nombres de los tipos no distinguen mayúsculas de minúsculas.

Los métodos usados para interactuar con plugin loaders son los siguientes:

Adicionalmente, puede especificar prefijos de rutas para todos los elementos y mostrar grupos creados a través de una instancia de Zend_Form usando los siguientes métodos:

Elementos y decoradores personalizados son una manera fácil de compartir funcionalidad entre formularios y encapsular funcionalidad personalizada. Vea el ejemplo de Etiqueta Personalizada en la documentación de elementos para un ejemplo de cómo elementos personalizados pueden ser usados como reemplazos para clases estándar.

Zend_Form proporciona varios métodos de acceso para añadir y eliminar elementos de el formulario. Éstos pueden tomar instancias de objetos de elemento o servir como fábricas para instanciar el objeto elemento a sí mismo.

El método más básico para añadir un elemento es addElement() . Este método puede tomar también un objeto de tipo Zend_Form_Element (o de una clase extendiendo Zend_Form_Element ), o argumentos para construir un nuevo elemento -- incluyendo el elemento tipo, nombre y algunas opciones de configuración.

Como algunos ejemplos:

// Usando un elemento instanciado:
$element = new Zend_Form_Element_Text('foo');
$form->addElement($element);

// Usando una fábrica
//
// Crea un elemento de tipo Zend_Form_Element_Text con el
// nombre de 'foo':
$form->addElement('text', 'foo');

// Pasa una opción etiqueta al elemento:
$form->addElement('text', 'foo', array('label' => 'Foo:'));

Una vez que el elemento ha sido añadido al formulario, puede recuperarlo por el nombre. Puede también finalizar usando el método getElement() o usando sobrecarga para acceder al elemento como una propiedad de objeto:

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

// Como propiedad del objeto:
$foo = $form->foo;

Ocasionalmente, se quiere crear un elemento sin adjuntarlo al formulario (para instanciar, si se desea hacer uso de las rutas de plugin introducidas con el formulario, pero después se desea adjuntar el objeto al subformulario). El método createElement() permite hacer eso:

// $username llega a ser un objeto Zend_Form_Element_Text:
$username = $form->createElement('text', 'username');

// Obtener todos los valores:
$values = $form->getValues();

// Obtener sólo los valores del elemento 'foo':
$value = $form->getValue('foo');

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

$form->reset();

// Determinar la ruta de acceso de prefijos global
// Crear rutas de acceso para los prefijos My_Foo_Filter, My_Foo_Validate,
// y My_Foo_Decorator
$form->addElementPrefixPath('My_Foo', 'My/Foo/');

// Sólo rutas de acceso de filtros:
$form->addElementPrefixPath('My_Foo_Filter',
                            'My/Foo/Filter',
                            'filter');

// Sólo rutas de acceso de validadores:
$form->addElementPrefixPath('My_Foo_Validate',
                            'My/Foo/Validate',
                            'validate');

// Sólo rutas de acceso de decoradores:
$form->addElementPrefixPath('My_Foo_Decorator',
                            'My/Foo/Decorator',
                            'decorator');

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

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

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

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

Los grupos de visualización (display groups) son una manera de crear grupos virtuales de elementos para propósitos de visualización. Todos los elementos quedan accesibles por nombre en el formulario, pero cuando interactúan o se ejecutan sobre el formulario, cualquiera de los elementos en un grupos de visualización son generados juntos. El caso más común de uso es agrupando los elementos en fieldsets. (TODO)

La clase base para los grupos de visualización es Zend_Form_DisplayGroup . Mientras puede ser instanciado directamente, es mejor usar el método addDisplayGroup() de la clase Zend_Form . Este método toma un array de elementos como primer argumento y el nombre para el grupo de visualización como segundo argumento. Opcionalmente, se puede pasar en una array de opciones o en un objeto Zend_Config como tercer argumento.

Asumiendo que los elementos 'username' y 'password' has sido determinados en el formulario, el siguiente código podría agrupar estos elementos en un grupo de visualización 'login':

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

Puede acceder a los grupos de visualización usando el método getDisplayGroup() , o mediante la sobrecarga usando el nombre del grupo de visualización:

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

// Usando sobrecarga:
$login = $form->login;

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

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

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

// Use the 'My_DisplayGroup' class
$form->addDisplayGroup(
    array('username', 'password'),
    'user',
    array('displayGroupClass' => 'My_DisplayGroup')
);

// Use the 'My_DisplayGroup' class for all display groups:
$form->setDefaultDisplayGroupClass('My_DisplayGroup');

Los Sub formularios sirven para diferentes propósitos:

Un sub formulario puede ser un objeto Zend_Form o mas originalmente, un objeto Zend_Form_SubForm . éste último contiene decoradores apropiados para la inclusión en un formulario extenso (i.e., no se generan adicionales formulario etiquetas HTML , pero si grupos de elementos). Para adjuntar un sub formulario, simplemente añádalo al formulario y déle un nombre:

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

Se puede recuperar un sub formulario usando ya sea getSubForm($name) o sobrecarga usando el nombre del sub formulario:

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

// Usando sobrecarga:
$subForm = $form->subform;

Los Subformularios son incluidos en la interacción del formulario, sin embargo los elementos que lo contienen no lo son

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

Mientras la utilidad de un formulario primariamente deriva de los elementos que contiene, también pueden contener otros metadatos, como un nombre (usado a menudo como ID único en el marcado HTML ); la accion y el método del formulario; el número de elementos, grupos y sub formularios que lo contienen; y arbitrariamente metadatos (usualmente usados para determinar atributos HTML para la etiqueta del propio formulario).

Se puede determinar y recuperar el nombre del formulario usando el accesor nombre:

// Determinar el nombre:
$form->setName('registration');

// Recuperar el nombre:
$name = $form->getName();

Para determinar la acción (url en el cual se envia el formulario) y método (método por el cual debería enviar, ej. 'POST' or 'GET'), use los accesores acción y método:

// Determinar la acción y método:
$form->setAction('/user/login')
     ->setMethod('post');

Se puede también especificar el tipo de codificación del fomulario usando el enctype accessors. Zend_Form define dos constantes, Zend_Form::ENCTYPE_URLENCODED y Zend_Form::ENCTYPE_MULTIPART , correspondiente a los valores 'application/x-www-form-urlencoded' y 'multipart/form-data', respectivamente; sin embargo, puede configurarlo con cualquier tipo de codificación.

// Determinar la acción, método y enctype:
$form->setAction('/user/login')
     ->setMethod('post')
     ->setEnctype(Zend_Form::ENCTYPE_MULTIPART);

Zend_Form implementa la interfaz Countable permitiéndole pasarlo como un argumento para contar:

$numItems = count($form);

Determinar metadatos arbitrariamente se realiza a través de los accesores 'atribs'. Dado que la sobrecarga en Zend_Form es usada para acceder elementos, grupos de visualización y subformularios, este es el único método para acceder a los metadatos.

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

// Recuperando atributos:
$class = $form->getAttrib('class');
$attribs = $form->getAttribs();

// Removiendo atributos:
$form->removeAttrib('onSubmit');

// Limpiando todos los atributos:
$form->clearAttribs();

Crear el marcado para un formulario es a menudo una tarea que consume mucho tiempo, particularmente si se planea reusar el mismo marcado para mostrar acciones tales como validación de errores, enviar valores, etc. La respuesta de Zend_Form a este problema es los decoradores .

Los decoradores para objetos Zend_Form pueden ser usados para generar un formulario. El decorador FormElements iterará a través de todos los elementos en un formulario -- elementos, grupos de visualización y subformularios -- y los generará, devolviendo el resultado. Adicionalmente, los decoradores pueden ser usados para envolver el contenido o anteponerlo o postponerlo.

Los decoradores por defecto de Zend_Form son FormElements, HtmlTag (envuelve una lista de definición) y Form; el código equivalente para crearlos es como sigue:

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

Que crea la salida como sigue:

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

Algunos de los atributos se determinan en el objeto formulario que será usado como atributos HTML de la etiqueta <form> .

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

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

// y recuperarlo después:
$form = $element->getDecorator('FooBar');

// Añadir dos decoradores 'HtmlTag', poniendo un alias a 'FooBar':
$form->addDecorators(
    array('HtmlTag', array('tag' => 'div')),
    array(
        'decorator' => array('FooBar' => 'HtmlTag'),
        'options' => array('tag' => 'dd')
    ),
);

// y recuperándolo después:
$htmlTag = $form->getDecorator('HtmlTag');
$fooBar  = $form->getDecorator('FooBar');

Puede crear su propio decorador para generar el formulario. Un caso de uso común es si sabe el HTML exacto que desea usar; su decorador puede crear el mismo HTML y simplemente retornarlo, potencialmente usando los decoradores de individuales elementos o grupos de visualización.

Los siguientes métodos puden ser usados para interactuar con decoradores:

Zend_Form también usa sobrecarga que permite generar decoradores específicos. __call() interceptará métodos que lleve con el texto 'render' y use el resto del nombre del método para buscar un decorador; si se encuentran, serán generados por un solo decorador. Cualquier argumento pasado a la llamada del método será usado como contenido que pasar al método render() del decorador. Como ejemplo:

// Generar solo los decoradores FormElements:
echo $form->renderFormElements();

// Generar solo el campo decorador, pasando el contenido:
echo $form->renderFieldset("<p>This is fieldset content</p>");

Si el decorador no existe, una excepción se creará.

Un caso de uso primario para formularios es validar datos enviados. Zend_Form le permite validar un formulario entero de una vez, o una parte de él, asi como también automatizar las respuestas de validación para XmlHttpRequests (AJAX). Si los datos enviados no son válidos, contiene métodos para recuperar los distintos códigos errores y los mensajes de elementos y subformularios de validaciones fallidas.

Para validar un formulario entero, use el método isValid() :

if (!$form->isValid($_POST)) {
    // validación fallida
}

isValid() validará cada elemento requerido, y algún elemento no requerido contenido en la data sometida.

Algunas veces se necesitará validar sólo un subset del dato; para esto use isValidPartial($data) :

if (!$form->isValidPartial($data)) {
    // validación fallida
}

isValidPartial() sólo intenta validar aquellos elementos en la información para los cuales existen similares elementos; si un elemento es no representado en la información, es pasado por alto.

Cuando se validan elementos o grupos de elementos para un requeirimiento AJAX , típicamente se validará un subset del formulario, y quiere la respuesta en JSON . processAjax() precisamente realiza eso:

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

Entonces, puede simplemente enviar la respuesta JSON al cliente. Si el formulario es válido, ésta será una respuesta booleana. Si no, será un objeto javascript conteniendo pares de clave/mensaje, donde cada 'message' es un array de validación de mensajes de error.

Para los formularios que fallan la validación, se pueden recuperar ambos códigos de error y mensajes de error, usando getErrors() y getMessages() , respectivamente:

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

Puede recuperar códigos y mensajes de error para elementos individuales simplemente pasando el nombre del elemento a cada uno:

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

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

La siguiente lista es la lista completa de métodos disponibles para Zend_Form , agrupados por tipo:

Zend_Form es totalmente configurable mediante setOptions() y setConfig() (o pasando opciones o un objeto Zend_Config al constructor). Usando estos métodos, se pueden especificar elementos formulario, grupos de visualización, decoradores, y metadatos.

Como regla general, si 'set' + la clave de opción (option key) hacen referencia a métodos Zend_Form , entonces el valor proporcionado será pasado al método. Si el accessor no existe, se asume que la clave referencia a un atributo, y será pasado a setAttrib() .

Excepciones a las reglas incluyen lo siguiente:

Como un ejemplo, aquí esta un archivo de configuración que pasa la configuración por cada tipo de datos configurables:

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

disableTranslator = 0

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

elements.username.type = "text"
elements.username.options.label = "Username"
elements.username.options.validators.alpha.validator = "Alpha"
elements.username.options.filters.lcase = "StringToLower"
; more elements, of course...

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

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

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

El código de arriba fácilmente puede ser abstraído a un XML o un archivo de configuración basado en arrays PHP .

Una alternativa a usar los formularios basados en configuraciones es realizar una subclase de Zend_Form . Esto tiene muchos beneficios:

El caso mas típico de uso sería el método init() para determinar elementos de formulario específicos y de configuración:

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

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

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

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

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

Este formulario puede ser instanciado simplemente así:

$form = new My_Form_Login();

y toda la funcionalidad está instalada y lista; no se necesitan archivos de configuración. (Note que este ejemplo esta simplificado, no contiene validadores o filtros para los elementos.)

Otra razón común para la extension es definir un conjunto de decoradores por defecto. Puede hacerlo sobreescribiendo el método loadDefaultDecorators() :

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