7.13. Ayudantes de Vista Estándares para Formularios

Los ayudantes de vista estándar para formularios provistos por ZF3 se muestran en las tablas 7.13 - 7.16 más abajo. Estas clases se encuentran en el namespace Zend\Form\View\Helper. Como podemos ver en la tabla los ayudantes de vista se pueden dividir en las siguientes categorías:

• Ayudantes de vista para formularios genéricas. Estas clases se diseñaron para imprimir el formulario completo (ayudante Form) o un solo elemento (ayudante FormElement) y posibles errores de validación (ayudante FormElementErrors).

• Ayudantes de vista para imprimir campos HTML de un tipo determinado. Estos permiten generar código HTML para campos concretos de formulario (ejemplo, FormButton, FormRadio, etc.) y una etiqueta de texto (FormLabel).

• Ayudantes de vista para imprimir campos de formulario introducidos en HTML5. Estos son análogos a los ayudantes de vista de la categoria anterior pero son para imprimir campos HTML5 (ejemplo, FormDate, FormUrl, etc.)

• Otros ayudantes de vista. En esta categoría podemos colocar las clases de ayudantes de vista diseñadas para imprimir campos específicos de ZF3 como FormMultiCheckbox, FormCaptcha, etc.

En las secciones siguientes daremos una visión general de varios ayudantes de vista para formularios que se usan frecuentemente junto con unos ejemplos de su uso.

7.13.1. Imprimir un Elemento del Formulario

Podemos imprimir un campo del formulario con el ayudante de vista FormElement. Se diseño pensando en maximizar la flexibilidad y reconoce tanto tipos de campo como es posible. Con este ayudante de vista podemos producir código HTML para campos de texto, botones, menús desplegables, etc.

Los métodos que provee este ayudante de vista se listan en la tabla 7.17.

Como podemos ver existen dos métodos que hacen la misma cosa:

• El método render() produce el código HTML para el campo de formulario. Acepta un solo argumento, la instancia del elemento a imprimir. Podemos recuperar los elementos del formulario con el método get() de modelo del formulario (ver el ejemplo más abajo).
• El método __invoke() es un envoltorio conveniente que reduce el código que es necesario escribir.

<?php
// We assume that the form model is stored in $form variable.
// Render the E-mail field with the render() method.
echo $this->formElement()->render($form->get('email')); ?>

// The same, but with __invoke
echo $this->formElement($form->get('email'));

Cuando se ejecuta el código de arriba genera el siguiente código HTML:

<input type="text" name="email" id="email" value="">

Generalmente no es necesario llamar al ayudante de vista con un campo HTML (o HTML5) concreto (ejemplo, FormText, FormSubmit, etc.) En su lugar podemos usar el ayudante de vista genérico FormElement que determina el tipo de campo automáticamente y produce el código HTML necesario.

7.13.2. Imprimir los Errores de Validación del Elemento

La clase de ayudante de vista FormElementErrors permite producir código HTML para los campos de validación de errores (si están presentes). Si no existen errores de validación para un determinado elemento este ayudante de vista no producen ninguna salida.

Un ejemplo del uso del ayudante de vista FormElementErrors se presenta abajo:

<?php
// We assume that the form model is stored in $form variable.
// Render validation errors for the E-mail field.
echo $this->formElementErrors($form->get('email'));

Si existe algún error de validación este código generará una lista no ordenada de errores usando la etiqueta HTML <ul> y la lista contendrá tantos elementos como errores existan para el campo. Un ejemplo de una lista como esta para el campo de correo electrónico del formulario de contacto se muestra abajo.

<ul>
  <li>&#039;hostname&#039; is not a valid hostname for the email address</li>
  <li>The input does not match the expected structure for a DNS hostname</li>
  <li>The input appears to be a local network name but local network names are not allowed</li>
</ul>

7.13.3. Imprimir la Etiqueta del Elemento

El ayudante FormLabel permite imprimir la etiqueta de texto para un elemento:

<?php
// We assume that the form model is stored in $form variable.
// Render text label for the E-mail field.
echo $this->formLabel($form->get('email'));

Cuando se ejecuta el código de arriba se genera el siguiente código HTML:

<label for="email">Your E-mail</label>

7.13.4. Imprimir un Formuario en Columna

El ayudate de vista FormRow está diseñado para simplificar la impresión de un campo de formulario, su etiqueta y los posibles errores de validación. Con esta clase podemos imprimirlos en un solo paso. Este ayudate es flexible en su configuración, con lo que se puede aplicar una decoración diferente a la columna del formulario. Los métodos de esta clase ayudante de vista se listan en la tabla 7.18.

Un ejemplo de uso del ayudante de vista FormRow se presenta abajo:

<?php
// We assume that the form model is stored in $form variable.
// Render the E-mail field, its label and (possible) validation errors.
echo $this->formRow($form->get('email'));

Cuando se ejecuta el código de arriba se genera un código HTML como el siguiente:

<label for="email">Your E-mail</label>
<input type="text" name="email" id="email">
<ul>
  <li>&#039;hostname&#039; is not a valid hostname for the email address</li>
  <li>The input does not match the expected structure for a DNS hostname</li>
  <li>The input appears to be a local network name but local network names
      are not allowed</li>
</ul>

7.13.5. Imprimir el Formulario Completo

El ayudante de vista Form permite imprimir la etiqueta de apertura <form> con sus atributos y la etiqueta de cierre </form>. Pero el principal propósito es imprimir el formulario completo y todos sus campos con una sola línea de código. Los métodos públicos de la clase ayudante de vista Form se resumen en la tabla 7.19.

Podemos imprimir todo el formulario con la ayuda del método render() de Form.

// We assume that the form model is stored in $form variable

// Render the whole form
echo $this->form()->render($form);

El mismo efecto se consigue con el método mágico __invoke (ver más abajo):

// The same, but with `__invoke`
echo $this->form($form);