7.8. Elementos del Formulario

En un modelo de formulario un campo de entrada está generalmente acompañado de una etiqueta de texto (Las etiquetas <label> y <input> se usan juntas). A este par de etiquetas se les conoce como elemento del modelo de formulario.

Análogamente a un campo de un formulario HTML un elemento del modelo de formulario puede contener el nombre y otros atributos opcionales como: "id", "class", etc. Adicionalmente, podemos colocar opciones a un elemento; las opciones permiten principalmente especificar el texto y los atributos para la etiqueta del elemento.

Todos los elementos del modelo de formulario se heredan de la clase base Element que además pertenece al componente Zend\Form. La clase base Element implementa la interfaz ElementInterface. El diagrama de herencia de clases se muestra en la figura 7.11.

Figura 7.11. Herencia de clases de los elementos del formulario

Los clases de los elementos concretos del formulario extienden de la clase base Element. Ellos se listan en las tablas 7.3 - 7.7. Estas clases están en el namespace Zend\Form\Element.

En la tabla de arriba podemos ver que los elementos del formulario que provee ZF3 están directamente asociados con los campos de entrada de HTML4 y HTML5 (discutido al comienzo de este capítulo).

Además, por conveniencia ZF3 provee varios campos «compuestos». El campo MultiCheckbox es un campo que está compuesto por un grupo de casillas de verificación relacionadas unas con otras. Los elementos DateTimeSelect, DateSelect y MonthSelect son análogos a sus correspondientes elementos HTML5 pero simulan ser un campo de selección usual. Estos campos de entrada tienen la ventaja de que son soportados por todos los navegadores web a diferencia de los campos correspondientes a HTML5. La representación visual de estos elementos se pueden ver en la figura 7.12.

Figura 7.12. Campos de formulario compuesto

Además, ZF3 provee los campos de «seguridad» Captcha y Csrf que se pueden usar en un formulario para mejorar la seguridad. El elemento Captcha es un elemento gráfico (imagen) que se coloca en el formulario para revisar si el usuario del sitio es un humano o un robot. El elemento Csrf no tiene una representación visual y se usa para prevenir los ataques CSRF ²⁰ de crackers.

Existe otro elemento especial de formulario llamado Collection. Este elemento es análogo a un conjunto de datos (fieldset), porque este nos permite agrupar elementos del formulario relacionados. Pero, esta diseñado para agregar elementos al formulario dinámicamente mediante la asociación de un arreglo de objetos al formulario.

7.8.1. Agregar Elemento a un Formulario

Los métodos heredados por la clase base Form de la clase Fieldset se usan para agregar elementos (y conjuntos de campos) al modelo de formulario. Estos métodos se resumen en la tabla 7.8.

Especialmente, estamos interesados en el método add() que se usa para añadir un elemento al formulario. El método add() toma dos argumentos: el primero de ellos (llamado $elementOrFieldset) es el elemento que se insertará y el segundo argumento (llamado $flags) es una bandera opcional.

El parámetro $elementOrFieldset puede ser una instancia de una clase Element derivada (o la clase Fieldset) o un arreglo describiendo el elemento que debe ser creado.

El argumento opcional $flags es un arreglo que puede contener una combinación de las siguientes llaves: name (permite colocar el nombre del elemento) y priority (permite especificar el índice, comenzando en cero, en la lista de elementos donde se insertará). Si la bandera de prioridad no se especifica el elemento se insertará al final de la lista de elementos del modelo de formulario.

Abajo, proveemos dos ejemplos que ilustran dos maneras posibles de agregar elementos al formulario.

7.8.2. Método 1: Pasar una Instancia de un Elemento

El siguiente fragmento de código crea una instancia de la clase Zend\Form\Element\Text y agrega el elemento al modelo de formulario:

<?php
namespace Application\Form;

// Define an alias for the class name
use Zend\Form\Form;
use Zend\Form\Element\Text;

// A feedback form model
class ContactForm extends Form
{
  // Constructor.
  public function __construct()
  {
    // Create the form fields here ...
    $element = new Text(
                'subject',            // Name of the element
                [                     // Array of options
                 'label'=> 'Subject'  // Text label
                ]);
    $element->setAttribute('id', 'subject');

    // Add the "subject" field to the form
    $this->add($element);
  }
}

En el código de arriba hemos creado una instancia de la clase Zend\Form\Element\Text (línea 15). La clase constructora toma dos parámetros: el nombre del elemento ("subject") y una arreglo de opciones (que aquí usamos para especificar la etiqueta de texto "Subject").

Además, podemos configurar un elemento usando los métodos provistos por la clase base Element. Por ejemplo, en la línea 20, colocamos el atributo «id» con el método setAttribute(). Para nuestra referencia, los método más importantes de la clase base Element que se pueden usar para configurar un elemento del formulario se presentan en la tabla 7.9.

7.8.3. Método 2: Usando un Arreglo con las Especificaciones

El segundo ejemplo que se muestra abajo es equivalente al primero y muestra como usar un arreglo de especificaciones para agregar un elemento al formulario. Este método es preferibles porque requiere menos código que escribir.

Cuando se usa un arreglo de especificaciones para agregar una elemento al formulario el elemento será instanciado y configurado automáticamente. Internamente esto es posible con la ayuda de la clase fábrica Zend\Form\Factory (como se muestra en la figura 7.13).

Figura 7.13. La lógica del método add()

{line-numbers=on, lang=php}

<?php
namespace Application\Form;

// Define an alias for the class name
use Zend\Form\Form;

// A feedback form model
class ContactForm extends Form
{
  // Constructor.
  public function __construct()
  {
    // Add "subject" field
    $this->add([
      'type'  => 'text',        // Element type
      'name' => 'subject',      // Field name
      'attributes' => [         // Array of attributes
        'id'  => 'subject',
      ],
      'options' => [            // Array of options
         'label' => 'Subject',  // Text label
      ],
    ]);
  }
}

Arriba en la línea 14 llamamos al método add() del modelo de formulario para agregar un elemento al formulario. Pasamos las especificaciones del elemento al método add() en forma de arreglo. El arreglo tiene generalmente las siguientes llaves:

• La llave type (línea 15) define el nombre de la clase que se usará para instanciar el elemento. Aquí podemos usar el nombre completo de la clase (por ejemplo, Text::class) o su alias ²¹ (por ejemplo, "text").

• La llave name (línea 16) define el nombre del campo ("subject").

• La llave attributes (línea 17) define la lista de atributos HTML que se colocarán (en esta ocasión colocamos el atributo "id").

• El arreglo de options (línea 18) permite especificar el texto de la etiqueta para el elemento.