En el tutorial anterior no definí ningún decorador, esto es porque el Zend Framework inicializa los decoradores con algunos por defecto. Veremos un poco del código interno del Zend Framework para entenderlo a detalle.

en Zend/Form/Element.php nos daremos cuenta que en el __construct (inicialización del elemento) hasta al final hay una llamada a la función loadDefaultDecorators que es la siguiente:

public function loadDefaultDecorators()
{
    if ($this->loadDefaultDecoratorsIsDisabled()) {
        return;
    }

    $decorators = $this->getDecorators();
    if (empty($decorators)) {
        $this->addDecorator('ViewHelper')
            ->addDecorator('Errors')
            ->addDecorator('HtmlTag', array('tag' => 'dd'))
            ->addDecorator('Label', array('tag' => 'dt'));
    }
}

Estos cuatro decoradores son la base de como los elementos son renderizados. El sistema procesa en orden lineal de como definimos los decoradores, si no modificamos entonces el orden es de procesar primero ViewHelper, luego Errors, HtmlTag y por último Label.

Cada decorador al momento de procesar en la función render, el sistema le pasa una cadena con el contenido actual y regresa una cadena de texto que procesó. Idealmente debe de utilizarse la cadena del contenido actual, pero con esto también podemos incluso procesar los elementos procesados y sobreescribir todo el resultado o hacer otras cosas interesantes (aunque podría ser no recomendable en un elemento que tenga como propósito ser parte de una librería).

Los elementos por defecto funciona de la siguiente manera:

• ViewHelper: renderea en sí el elemento mediante un helper. Por ejemplo un elemento Zend_Form_Element_Select que tiene un helper formSelect utilizará este último helper para mostrar el elemento como <select>...</select>
• Errors: renderea las partes de los errores, utiliza una plantilla de la siguiente forma:

  <ul class="errores"[opciones html]>
  <li>[error1]</li>
  ....
  <li>[errorN]</li>
  </ul>

• HtmlTag: Le da un poco de formato al elemento ya que lo agrega en una plantilla de la siguiente forma:

  <dd>
  ...
  </dd>

• Label: Asigna una etiqueta de la siguiente forma:

  <dt><label>Etiqueta</label></dt>

Los decoradores por defecto tienen opciones para ser puestos al inicio (PREPEND) o al final (APPEND) del contenido, por defecto Errors se pone al final, HtmlTag pone el contenido en medio de las etiquetas y Label se pone al inicio del contenido.

Por lo que con las opciones por defecto la plantilla de como se verá nuestro elemento es:

<dt><label>[Etiqueta del elemento]</label></dt>
<dd>
    [Elemento]
    <ul class="errors">
        <li>[Errores]</li>
    </ul>
</dd>

Si queremos cambiar el orden, o forma de presentación tenemos que cambiar un poco el formato de salida; por ejemplo con el siguiente código (modificándolo de IndexController.php del tutorial de Zend Form):

$decoradores = array(
     'ViewHelper',
     'Errors',
     array('HtmlTag', array('tag' => 'div', 'class' => 'formElement')),
     array('Label', array('tag' => 'div'))
);

$nombre = $formulario->createElement('text', 'nombre_completo')
               ->setLabel('Nombre Completo')
               ->setDecorators($decoradores)
               ->setRequired(true);

Esto nos mostrará un resultado como el siguiente:

Como hemos definido todos los decoradores que vamos a utilizar es fácil aplicarlo a los demás elementos (en el ejemplo anterior, sólo se aplicó al primer elemento.

Hay que hacer notar que sólo podemos utilizar una vez el decorador en un elemento, si agregamos otro HtmlTag por ejemplo, el último sobreescribirá al primero.

Si queremos construir algo más complejo existe un decorador que nos permite tener mucho mayor control: ViewScript, este decorador básicamente llamará a un archivo de la carpeta de vista (views/scripts) y le pasará tres parámetros:

• content: El contenido actual producto del renderizado de los otros decoradores
• element: El Zend_Form_Element que estamos renderizados
• decorator: Una referencia al decorador ViewScript

Por defecto el resultado se agrega al final, si pasamos como opcion que la posición sea false entonces el contenido que resulte de renderizar este decorador será el único contenido.

Por ejemplo lo siguiente crea un “contenedor” al elemento:

$decoradores = array(
           'ViewHelper',
           'Errors',
           array('HtmlTag', array('tag' => 'div', 'class' => 'formElement')),
           array('Label', array('tag' => 'div')),
           array('ViewScript', array('viewScript' => 'decorador-contenedor.phtml', 'placement' => false)),
    );

Y el decorador está especificado como (archivo nombreado como: views/scripts/decorador-contenedor.phtml:

<div class="formElementContent">
	<?=$this->content ?>
</div>

El resultado es el siguiente (con un poco de CSS):

Ahora bien, si queremos podemos prácticamente reconstruir todo los demás decoradores mediante un un decorador de ViewHelper y un decorador ViewScript de la siguiente manera:

$decoradores = array(
          'ViewHelper',
          array('ViewScript', array('viewScript' => 'decorador-avanzado.phtml', 'placement' => false)),
     );

Y el decorador seria de la siguiente manera:

<!-- Esta primera parte reemplazaria HtmlTag -->
<div class="formElementContent">
	<!--  parte que remplaza el decorador Label -->
	<div>
    <?php
    	$attribs = $this->element->getAttribs();
    	$label = $this->element->getLabel();

    	//nuevo, verificamos si el elemento es requerido,
    	//entonces agregamos un elemento en html al final de la etiqueta
    	if ($this->element->isRequired()) {
    		$attribs['escape'] = false;
    		$label = $this->escape($label). ' <span class="required">*</span>';
    	}

    	echo $this->formLabel($this->element->getName(), $label, $attribs);
    ?>
    </div>

    <!-- parte del elemento -->
    <?=$this->content ?>

    <!--
    	parte que reemplaza Errors
    	observen que estoy poniendo los errores
    	con simples saltos de linea en lugar de lista
     -->
	<?php if ($this->element->getMessages()) { ?>
	<div class="errors">
		<?=implode('<br />', $this->element->getMessages())?>
	</div>
	<?php } ?>

    <!-- esta parte es opcional si agregaron una descripción -->
    <div class="hint"><?= $this->element->getDescription() ?></div>
</div>

El resultado con un poco de CSS es el siguiente:

Como se puede observar el anterior ejemplo nos da completo control sobre como mostrar los elementos.

También en un caso más complejo y avanzado podemos incluso definir con algunos cambios sobre el formulario principal (Zend_Form) para definir un decorador que nos permita sobre la vista definir el orden de los elementos, mostrar un formulario totalmente estilizado que no sea regular o incluso no mostrar elementos o crear nuevos para cosas como AJAX/Javascript por ejemplo.

Pero de eso hablaría en otro pequeño tutorial =).

Código Fuente:

DanguerArticle_Zend_Form_Decorator.tar.gz

Visitar Sitio Demo

Un formulario (Zend_Form) es un contenedor de elementos (por ejemplo una entrada de texto, una casilla de verificación, etc), del lado del controlador debemos definir los elementos, una vez hecho esto entonces podemos visualizar (render) la forma del lado de la vista ya sea asignándole una vista o simplemente con <?=$formulario?> donde $formulario es por supuesto nuestro objeto de tipo Zend_Form

Los elementos que maneja Zend Framework son básicamente los objetos en HTML a los que estamos acostumbrados, pero no estamos limitados a ellos ya que podemos crear los elementos que necesitemos.
Un elemento puede tener validadores (subclases de Zend_Validate_Abstract) que nos permiten validar la entrada, aunque ya existen muchos validadores muy útiles y de uso frecuente.
El elemento puede ser asignado uno o varios “Decoradores“; un Decorador es un objeto que pasa información a un Helper de la vista, los decoradores que tiene Zend Framework integrado nos permiten fácilmente alterar la salida de un elemento y también añadir fácilmente un diseño.

Esquema

El siguiente es un esquema de cómo funciona Zend_Form, podemos ver que el controlador se encargará de crear el formato del formulario y la parte de vista se encargará de mostrar el formulario y de mostrar los errores que hayan surgido.

Crear un formulario

Para crear un formulario debemos hacer lo siguiente:

1. Crear un formulario (Zend_Form)
2. Crear elementos ya sea mediante
   $elemento = $formulario->createElement('tipo_elemento', 'nombre_elemento');
   o mediante un objeto de tipo Zend_Form_Element:
   $elemento = new Zend_Form_Element_Text('nombre_elemento');
3. Asignar propiedades al elemento:
   setLabel('nombre_etiqueta'); //asigna el nombre de la etiqueta del elemento
setValue('valor'); //asigna el valor del elemento (sobreescribe la entrada del usuario)
setDecorators($arreglo_decoradores); //asigna los decoradores a usarse
setRequired(true/false); //indica si el valor no debe estar vacio
addValidator($validador); //indica el validador a utilizar
4. Agregar el elemento al formulario:
   $formulario->addElement($elemento);
   los elementos se visualizarán en el orden en que han sido agregados, aunque esto puede cambiarse si se modifica el elemento mediante $elemento->setOrder($numero);
5. Pasar el formulario a la vista para que sea renderizado:
   $this->view->assign('formulario', $formulario);
6. Renderizarlo en la vista:
   <?=$this->formulario?>

Validar un formulario

Una vez que hemos renderizado el formulario y el usuario ha enviado datos, lo siguiente que debemos hacer es validar la entrada, para esto debemos de crear nuevamente el formulario y verificar si se han enviado datos (porque Zend Framework solo envia valores y no información sobre el formulario), si se han enviado datos entonces podemos utilizar la función isValid($_POST); que regresará un valor de verdadero en caso de que todos los validadores fueron satisfechos o falso en caso de que alguno no lo fuera.

La ventaja de Zend es que automáticamente agregará un mensaje de error al renderizar el elemento que tuvo un error; inicialmente el código de error estará en inglés, por lo que deberemos de traducir los mensajes (más adelante).

Opciones de Validación

Zend Framework tiene varias opciones para validar las entradas, todas ellas son subclases de Zend_Validate_Abstract, para agregar un validador debemos llamarlo de la siguiente manera:

$elemento->addValidator('nombre_validador', $romper_cadena_al_fallar, $arreglo_opciones);

Los validadores más importantes son (el nombre de validador es el que está entre paréntesis):

• Zend_Validate_Alnum (alnum)
  Nos permite verificar que la entrada solo contenda caracteres alfanuméricos (letras y dígitos), opcionalmente se le puede pasar como opción un booleano para definir si se deben aceptar espacios en blanco (predeterminado en falso)
• Zend_Validate_Alpha (alpha)
  Nos permite verificar que la entrada sea sólo letras, al igual que el anterior permite una opción para aceptar espacios en blanco
• Zend_Validate_Digits (digits)
  Permite verificar que la entrada sea sólo números
• Zend_Validate_StringLength (stringLength)
  Nos permite definir que la entrada sólo contenga un número mínimo o máximo de valores; que deben ser especificado en las opciones por ejemplo:
  $element->addValidator('stringLength', false, array(3, 20));
  Que especifica una cadena de al menos 3 caracteres y máximo 20 caracteres.
• Zend_Validate_EmailAddress (emailAddress)
  Es un validador muy poderoso que nos permite verificar que un correo sea válido (al menos en cuanto a formato y servidor válido incluso)
• Zend_Validate_NotEmpty (notEmpty)
  Este validador nos permite verificar que el usuario ha introducido un valor, lamentablemente no permite eliminar espacios en blanco con trim por ejemplo.

Traducción

Los mensajes de error que mostrará Zend Framework de manera predeterminada serán en inglés; para poderlos mostrar en español debemos utilizar la parte de traducción de Zend (Zend_Translate).

Zend_Translate permite muchas opciones pero aqui haremos una de las más básicas que es mediante un archivo PHP, esto nos permitirá usar las constantes de Zend, para esto simplemente hay que crear un archivo en PHP donde tendrá los mensajes en español, por ejemplo: app/langs/es.php

En este archivo deberemos regresar un arreglo con la llave la cadena a traducir y el valor con la cadena traducida, por ejemplo:

<?php
require_once 'Zend/Validate/NotEmpty.php';
require_once 'Zend/Validate/StringLength.php';
require_once 'Zend/Validate/EmailAddress.php';

return array(
Zend_Validate_NotEmpty::IS_EMPTY => 'El campo no puede estar vacío',
Zend_Validate_StringLength::TOO_LONG => 'El campo debe contener por lo menos %min% caracteres',
Zend_Validate_StringLength::TOO_SHORT => 'El campo debe contener un máximo de %max% caracteres',
Zend_Validate_EmailAddress::INVALID => 'La dirección de correo no es válida',
Zend_Validate_EmailAddress::QUOTED_STRING => "'%localPart%' no concuerda con el formato de comillas",
Zend_Validate_EmailAddress::DOT_ATOM => "'%localPart%' no concuerda con el formato de punto",
Zend_Validate_EmailAddress::INVALID_HOSTNAME => "'%hostname%' no es un nombre de dominio válido",
Zend_Validate_EmailAddress::INVALID_LOCAL_PART => "'%localPart%' no es una parte local válida",
Zend_Validate_EmailAddress::INVALID_MX_RECORD => "'%hostname%' no tiene un dominio de correo asignado",
);

?>

Debemos consultar la API para ver las cadenas que debemos traducir para cada validador. En el ejemplo sólo usaremos tres notEmpty, stringLength y emailAddress

Entonces debemos de asignar estas traducciones a todos los componentes de Zend_Form de la siguiente manera:

$traduccion = new Zend_Translate('array', 'app/langs/es.php', 'es');
Zend_Form::setDefaultTranslator($traduccion);

Obtención de Valores

Los valores del formulario estarán en $_POST['nombre_elemento'] o $_GET['nombre_elemento'] según sea el caso, pero podemos pedirle al formulario que nos regrese solamente los valores que le corresponden de la entrada (si es que pasamos más datos), por lo que debemos hacer:

$valores = $formulario->getValues();

Ejemplo

Para el ejemplo tendremos dos archivos, IndexController.php (Controlador) e index.phtml (vista), simplemente mostraremos un formulario y mostraremos los valores.

El código del ejemplo puede ser obtenido en esta liga:
http://vida.danguer.com/archivos/articulos/Zend_Form/DanguerArticle_Zend_Form.tar.gz

Mientras que el ejemplo puede visualizarse en la siguiente liga:
http://dev.fangit.com/DanguerArticle_Zend_Form/