repo_zf1/documentation/manual/es/module_specs/Zend_Form-Advanced.xml

<sect1 id="zend.form.advanced">
    <title>Uso avanzado de Zend_Form</title>

    <para>
        <code>Zend_Form</code> tiene una funcional riqueza, muchas de ellas dirigidas
        a expertos desarroladores. Este capítulo esta dirigido a documentar algunas de las
        funcionalidades con ejemplos y casos de uso.
    </para>

    <sect2 id="zend.form.advanced.arrayNotation">
        <title>Notación de array</title>

        <para>
        	Muchos desarroladores web experimentados les gusta agrupar relacionados elementos de formulario
        	usando notación de array en los nombres del elemento. Por ejemplo, si se tiene
        	dos direcciones que se desea capturar, un envio y una dirección de facturación,
        	se puede tener elementos idénticos; agrupandolos en un array se puede
        	asegurar que son capturados por separado. Notese el siguiente formulario
        	por ejemplo:
        </para>

        <programlisting role="html"><![CDATA[
<form>
    <fieldset>
        <legend>Shipping Address</legend>
        <dl>
            <dt><label for="recipient">Ship to:</label></dt>
            <dd><input name="recipient" type="text" value="" /></dd>

            <dt><label for="address">Address:</label></dt>
            <dd><input name="address" type="text" value="" /></dd>

            <dt><label for="municipality">City:</label></dt>
            <dd><input name="municipality" type="text" value="" /></dd>

            <dt><label for="province">State:</label></dt>
            <dd><input name="province" type="text" value="" /></dd>

            <dt><label for="postal">Postal Code:</label></dt>
            <dd><input name="postal" type="text" value="" /></dd>
        </dl>
    </fieldset>

    <fieldset>
        <legend>Billing Address</legend>
        <dl>
            <dt><label for="payer">Bill To:</label></dt>
            <dd><input name="payer" type="text" value="" /></dd>

            <dt><label for="address">Address:</label></dt>
            <dd><input name="address" type="text" value="" /></dd>

            <dt><label for="municipality">City:</label></dt>
            <dd><input name="municipality" type="text" value="" /></dd>

            <dt><label for="province">State:</label></dt>
            <dd><input name="province" type="text" value="" /></dd>

            <dt><label for="postal">Postal Code:</label></dt>
            <dd><input name="postal" type="text" value="" /></dd>
        </dl>
    </fieldset>

    <dl>
        <dt><label for="terms">I agree to the Terms of Service</label></dt>
        <dd><input name="terms" type="checkbox" value="" /></dd>

        <dt></dt>
        <dd><input name="save" type="submit" value="Save" /></dd>
    </dl>
</form>
]]>
</programlisting>

        <para>
        	En este ejemplo, la facturación y la dirección de envío contienen algunos
        	campos idénticos, eso significa uno puede sobre escribir al otro. Nosotros podemos
        	resolver esta solución usando una notación de array:

        	In this example, the billing and shipping address contain some
            identical fields, which means one would overwrite the other. We can
            solve this solution using array notation:
        </para>

        <programlisting role="html"><![CDATA[
<form>
    <fieldset>
        <legend>Shipping Address</legend>
        <dl>
            <dt><label for="shipping-recipient">Ship to:</label></dt>
            <dd><input name="shipping[recipient]" id="shipping-recipient"
                type="text" value="" /></dd>

            <dt><label for="shipping-address">Address:</label></dt>
            <dd><input name="shipping[address]" id="shipping-address"
                type="text" value="" /></dd>

            <dt><label for="shipping-municipality">City:</label></dt>
            <dd><input name="shipping[municipality]" id="shipping-municipality"
                type="text" value="" /></dd>

            <dt><label for="shipping-province">State:</label></dt>
            <dd><input name="shipping[province]" id="shipping-province"
                type="text" value="" /></dd>

            <dt><label for="shipping-postal">Postal Code:</label></dt>
            <dd><input name="shipping[postal]" id="shipping-postal"
                type="text" value="" /></dd>
        </dl>
    </fieldset>

    <fieldset>
        <legend>Billing Address</legend>
        <dl>
            <dt><label for="billing-payer">Bill To:</label></dt>
            <dd><input name="billing[payer]" id="billing-payer"
                type="text" value="" /></dd>

            <dt><label for="billing-address">Address:</label></dt>
            <dd><input name="billing[address]" id="billing-address"
                type="text" value="" /></dd>

            <dt><label for="billing-municipality">City:</label></dt>
            <dd><input name="billing[municipality]" id="billing-municipality"
                type="text" value="" /></dd>

            <dt><label for="billing-province">State:</label></dt>
            <dd><input name="billing[province]" id="billing-province"
                type="text" value="" /></dd>

            <dt><label for="billing-postal">Postal Code:</label></dt>
            <dd><input name="billing[postal]" id="billing-postal"
                type="text" value="" /></dd>
        </dl>
    </fieldset>

    <dl>
        <dt><label for="terms">I agree to the Terms of Service</label></dt>
        <dd><input name="terms" type="checkbox" value="" /></dd>

        <dt></dt>
        <dd><input name="save" type="submit" value="Save" /></dd>
    </dl>
</form>
]]>
</programlisting>

        <para>
        	En el ejemplo anterior, obtenemos separadas direcciones. En el formulario
        	sometido, ahora tenemos tres elementos, 'guardar' elemento para someterlo,
        	y dos arrays, 'envio' y 'cuenta', cada uno con
        	llaves para los variados elementos.
        </para>

        <para>
        	<code>Zend_Form</code> intenta automatizar este proceso con los
            <link linkend="zend.form.forms.subforms">sub formularios</link>. Por
            defecto, los sub formularios son generados usando la notación de array como se muestra
            en el anterior formulario HTML listado completo con identificadores. El nombre del array
            esta basado en el nombre del sub formulario, con las llaves basados en los elementos
            contenidos  en el sub formulario. Los sub formularios pueder ser anidados arbitrariamente,
            y esto puede crear arrays anidados que reflejan la estructura.
            Adicionalmente, las validaciones rutinarias en
            <code>Zend_Form</code> respetan la estructura del array, asegurando que sus
            formularios sean validados correctamente, no importa cuan arbitrariamente anidados esten los
            sub formularios. No se necesita hacer nada para beneficiarse; éste
            comportamiento esta activo por defecto.
        </para>

        <para>
        	Adicionalmente, existen facilidades que le permiten activar condicionalmente la notación
        	de un array, así como también especificar el específico array al
        	cual un elemento o coleccion pertenece:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                	<code>Zend_Form::setIsArray($flag)</code>: Definiendo la
                	bandera a verdadero, se puede indicar que un entero formulario deberia ser
                	tratado como un array. Por defecto, el nombre del formulario será
                	usado como el nombre del array, a no ser que
                    <code>setElementsBelongTo()</code> haya sido llamado. si el
                    formulario no tiene un específico nombre, o si
                    <code>setElementsBelongTo()</code> no ha sido definido, esta bandera
                    será ignorada (como no hay nombre del array al cual
                    los elementos puedan pertenecer).
                </para>

                <para>
                	Se deberá determinar si un formulario esta siendo tratado como un array
                	usando el acceso <code>isArray()</code>.
                </para>
            </listitem>

            <listitem><para>
            		<code>Zend_Form::setElementsBelongTo($array)</code>:
                    Usando este método, se puede especificar el nombre de un array al
                    cual todos los elementos del formulario pertenecen. Se puede determinar el
                    nombre usando el accesor <code>getElementsBelongTo()</code>.
            </para></listitem>
        </itemizedlist>

        <para>
        	Adicionalmente, sobre el nivel del elemento, se puede especificar
        	elementos individuales que puedan pertenecer a arrays particulares usando
            el método <code>Zend_Form_Element::setBelongsTo()</code>.
            Para descubrir el valor que tiene -- sea o no sea definido explicitamente o
            implicitamente a través del formulario -- se puede usar el
            acceso <code>getBelongsTo()</code>.
        </para>
    </sect2>

    <sect2 id="zend.form.advanced.multiPage">
        <title>Formularioss Multi-Página</title>

        <para>
        	Actualmente, los formularios multi-página no son oficialmente soportados in
            <code>Zend_Form</code>; sin embargo, mas soporte para implementarlos
            esta disponible y puede ser utilizado con una pequeña ayuda.
        </para>

        <para>
        	La clave para crear fomrularios multi-página es utilizar sub formularios, pero
        	solo para desplegar un solo sub formulario por página. Esto le permite
        	someter un solo sub formulario a la vez y validarlo, pero no procesar
        	el formulario hasta que todos los sub formularios esten completos.
        </para>

        <example id="zend.form.advanced.multiPage.registration">
            <title>Ejemplo de formulario registración</title>
            <para>
            	Vamos a usar un formulario registración como un ejemplo. para nuestros propósitos,
            	nosotros queremos capturar el nombre del usuario y la contraseña en la
            	primera página, despues la información del usuario -- nombre, apellido,
            	y ubicación -- y finalmente prmitirles decidir que lista de correo,
            	si ellos desean suscribirse.
            </para>

            <para>
            	Primero, vamos a crear nuestro propio formulario, y definir varios subformularios
            	dentro del mismo:
            </para>

            <programlisting role="php"><![CDATA[
class My_Form_Registration extends Zend_Form
{
    public function init()
    {
        // Crea un sub formulario usuario: username y password
        $user = new Zend_Form_SubForm();
        $user->addElements(array(
            new Zend_Form_Element_Text('username', array(
                'required'   => true,
                'label'      => 'Username:',
                'filters'    => array('StringTrim', 'StringToLower'),
                'validators' => array(
                    'Alnum',
                    array('Regex',
                          false,
                          array('/^[a-z][a-z0-9]{2,}$/'))
                )
            )),

            new Zend_Form_Element_Password('password', array(
                'required'   => true,
                'label'      => 'Password:',
                'filters'    => array('StringTrim'),
                'validators' => array(
                    'NotEmpty',
                    array('StringLength', false, array(6))
                )
            )),
        ));

        // Crea un sub formulario de datos demográficos : given name, family name, y
        // location
        $demog = new Zend_Form_SubForm();
        $demog->addElements(array(
            new Zend_Form_Element_Text('givenName', array(
                'required'   => true,
                'label'      => 'Given (First) Name:',
                'filters'    => array('StringTrim'),
                'validators' => array(
                    array('Regex',
                          false,
                          array('/^[a-z][a-z0-9., \'-]{2,}$/i'))
                )
            )),

            new Zend_Form_Element_Text('familyName', array(
                'required'   => true,
                'label'      => 'Family (Last) Name:',
                'filters'    => array('StringTrim'),
                'validators' => array(
                    array('Regex',
                          false,
                          array('/^[a-z][a-z0-9., \'-]{2,}$/i'))
                )
            )),

            new Zend_Form_Element_Text('location', array(
                'required'   => true,
                'label'      => 'Your Location:',
                'filters'    => array('StringTrim'),
                'validators' => array(
                    array('StringLength', false, array(2))
                )
            )),
        ));

        // Crea un sub fomulario de de correos
        $listOptions = array(
            'none'        => 'No lists, please',
            'fw-general'  => 'Zend Framework General List',
            'fw-mvc'      => 'Zend Framework MVC List',
            'fw-auth'     => 'Zend Framwork Authentication and ACL List',
            'fw-services' => 'Zend Framework Web Services List',
        );
        $lists = new Zend_Form_SubForm();
        $lists->addElements(array(
            new Zend_Form_Element_MultiCheckbox('subscriptions', array(
                'label'        =>
                    'Which lists would you like to subscribe to?',
                'multiOptions' => $listOptions,
                'required'     => true,
                'filters'      => array('StringTrim'),
                'validators'   => array(
                    array('InArray',
                          false,
                          array(array_keys($listOptions)))
                )
            )),
        ));

        // Adjuntando los sub formlarios al formulario principal
        $this->addSubForms(array(
            'user'  => $user,
            'demog' => $demog,
            'lists' => $lists
        ));
    }
}
]]>
            </programlisting>

            <para>
            	Note que hay botones de sometimiento, y que ni hemos hecho
            	nada con el decorador de sub formularios -- lo que significa que por
            	defecto serán desplegados como campos. Necesitaremos hacer
            	algo con ellos mientras desplegamos cada sub formulario indivisualmente,
            	y adicionar botones demanera que podamos actualmente procesarlos --
            	el cual requerira las propiedades acción y método. vamos adicionar
            	algunos scaffolding a nuestras clases para proveer esa información:
            </para>

            <programlisting role="php"><![CDATA[
class My_Form_Registration extends Zend_Form
{
    // ...

    /**
     * Prepara un sub formulario para mostrar
     *
     * @param  string|Zend_Form_SubForm $spec
     * @return Zend_Form_SubForm
     */
    public function prepareSubForm($spec)
    {
        if (is_string($spec)) {
            $subForm = $this->{$spec};
        } elseif ($spec instanceof Zend_Form_SubForm) {
            $subForm = $spec;
        } else {
            throw new Exception('Invalid argument passed to ' .
                                __FUNCTION__ . '()');
        }
        $this->setSubFormDecorators($subForm)
             ->addSubmitButton($subForm)
             ->addSubFormActions($subForm);
        return $subForm;
    }

    /**
     * Add form decorators to an individual sub form
     *
     * @param  Zend_Form_SubForm $subForm
     * @return My_Form_Registration
     */
    public function setSubFormDecorators(Zend_Form_SubForm $subForm)
    {
        $subForm->setDecorators(array(
            'FormElements',
            array('HtmlTag', array('tag' => 'dl',
                                   'class' => 'zend_form')),
            'Form',
        ));
        return $this;
    }

    /**
     * Añade un Boton de envio(submit) a cada sub formulario
     *
     * @param  Zend_Form_SubForm $subForm
     * @return My_Form_Registration
     */
    public function addSubmitButton(Zend_Form_SubForm $subForm)
    {
        $subForm->addElement(new Zend_Form_Element_Submit(
            'save',
            array(
                'label'    => 'Save and continue',
                'required' => false,
                'ignore'   => true,
            )
        ));
        return $this;
    }

    /**
     * Añade el method y el action a cada sub formulario
     *
     * @param  Zend_Form_SubForm $subForm
     * @return My_Form_Registration
     */
    public function addSubFormActions(Zend_Form_SubForm $subForm)
    {
        $subForm->setAction('/registration/process')
                ->setMethod('post');
        return $this;
    }
}
]]>
            </programlisting>

            <para>
            	Siguiente, necesitamos adicionar scaffolding en nuestro controlador acción,

            	y tener muchas consideraciones. Primero, necesitamos asegurar que
            	persiste la información del formulario entre los requerimientos, de esa manera determinar
            	cuadno terminar. Segundo, necesitamos alguna lógica para determinar que segmentos
            	del formulario han sido sometidos, y que sub formulario
            	desplegar de acuerdo a la información. Usaremos
                <code>Zend_Session_Namespace</code> para persistir la información, el cual
                nos ayudará a responder la pregunta de cual formulario someter.
            </para>

            <para>
            	Vamos a crear nuestro controlador, y adicionar un método para recuperar un
            	formulario instanciado:
            </para>

            <programlisting role="php"><![CDATA[
class RegistrationController extends Zend_Controller_Action
{
    protected $_form;

    public function getForm()
    {
        if (null === $this->_form) {
            $this->_form = new My_Form_Registration();
        }
        return $this->_form;
    }
}
]]>
            </programlisting>

            <para>
            	Ahora, vamos adicionar algunas funcionalidades para determinar cual formulario
            	desplegar. Basicamente, hasta que el entero formulario sea considerado válido,
            	necesitamos continuar desplegando segmentos de formulario. Adicionalmente,
            	queremos asegurar que estan en un orden particular: usuario,
            	demog, y despues las listas. Podemos determinar que información ha sido
            	sometida verificando nuestra sesión namespace para claves particulares
            	representando cada sub formulario.
            </para>

            <programlisting role="php"><![CDATA[
class RegistrationController extends Zend_Controller_Action
{
    // ...

    protected $_namespace = 'RegistrationController';
    protected $_session;

    /**
     * Obtiene el namespace de la sesión que estamos usando
     *
     * @return Zend_Session_Namespace
     */
    public function getSessionNamespace()
    {
        if (null === $this->_session) {
            $this->_session =
                new Zend_Session_Namespace($this->_namespace);
        }

        return $this->_session;
    }

    /**
     * Obtiene la lista de Formularios que ya estan almacenados en la sesión
     *
     * @return array
     */
    public function getStoredForms()
    {
        $stored = array();
        foreach ($this->getSessionNamespace() as $key => $value) {
            $stored[] = $key;
        }

        return $stored;
    }

    /**
     * Obtiene la lista de todos los subformularios disponibles
     *
     * @return array
     */
    public function getPotentialForms()
    {
        return array_keys($this->getForm()->getSubForms());
    }

    /**
     * Que sub formulario se envio?
     *
     * @return false|Zend_Form_SubForm
     */
    public function getCurrentSubForm()
    {
        $request = $this->getRequest();
        if (!$request->isPost()) {
            return false;
        }

        foreach ($this->getPotentialForms() as $name) {
            if ($data = $request->getPost($name, false)) {
                if (is_array($data)) {
                    return $this->getForm()->getSubForm($name);
                    break;
                }
            }
        }

        return false;
    }

    /**
     * Obtiene el siguiente sub formulario para mostratlo
     *
     * @return Zend_Form_SubForm|false
     */
    public function getNextSubForm()
    {
        $storedForms    = $this->getStoredForms();
        $potentialForms = $this->getPotentialForms();

        foreach ($potentialForms as $name) {
            if (!in_array($name, $storedForms)) {
                return $this->getForm()->getSubForm($name);
            }
        }

        return false;
    }
}
]]>
            </programlisting>

            <para>
            	El método de arriba nos permite usar notaciones tal como "<code>$subForm =
                    $this-&gt;getCurrentSubForm();</code>" recuperar el actual
                sub formulario para la validación, o "<code>$next =
                    $this-&gt;getNextSubForm();</code>" obtener el siguiente para
                desplegar.
            </para>

            <para>
            	Ahora, vamos a encontrar la manera para procesar y desplegar varios
            	sub formularios. pdemos usar <code>getCurrentSubForm()</code> para determianr
            	si algún sub formulario ha sido sometido (falso retorna ningún valor
            	ha sido desplegado o sometido), y
                <code>getNextSubForm()</code> recupera el formulario a desplegar. Podemos
                entonces usar el método del formulario <code>prepareSubForm()</code> para asegurar
                que el formulario esta listo para desplegar.
            </para>

            <para>
            	Cuando tenemos un formulario sometido, podemos validar el sub formulario,
            	y luego verificar si el entero formulario es válido ahora. Para hacer
            	esas tareas, necesitamos métodos adicionales que aseguren que la
            	información sometida es adicionada a la sesión, y que cuando validamos
            	el entero formulario, nosotros validamos contra todos los segmentos de
            	la sesión:
            </para>

            <programlisting role="php"><![CDATA[
class RegistrationController extends Zend_Controller_Action
{
    // ...

    /**
     * Es válido el sub formulario ?
     *
     * @param  Zend_Form_SubForm $subForm
     * @param  array $data
     * @return bool
     */
    public function subFormIsValid(Zend_Form_SubForm $subForm,
                                   array $data)
    {
        $name = $subForm->getName();
        if ($subForm->isValid($data)) {
            $this->getSessionNamespace()->$name = $subForm->getValues();
            return true;
        }

        return false;
    }

    /**
     * Es válido todo el formulario?
     *
     * @return bool
     */
    public function formIsValid()
    {
        $data = array();
        foreach ($this->getSessionNamespace() as $key => $info) {
            $data[$key] = $info;
        }

        return $this->getForm()->isValid($data);
    }
}
]]>
            </programlisting>

            <para>
            	Ahora que tenemos el trabajo preparado, vamos a construir las
            	acciones para este controlador. Necesitaremos una página landing
            	para el formulario, y luego un 'proceso' acción para procesar el formulario.
            </para>

            <programlisting role="php"><![CDATA[
class RegistrationController extends Zend_Controller_Action
{
    // ...

    public function indexAction()
    {
        // volver a mostrar la página actual, o mostrar el "siguiente"
        // (primer) sub formulario
        if (!$form = $this->getCurrentSubForm()) {
            $form = $this->getNextSubForm();
        }
        $this->view->form = $this->getForm()->prepareSubForm($form);
    }

    public function processAction()
    {
        if (!$form = $this->getCurrentSubForm()) {
            return $this->_forward('index');
        }

        if (!$this->subFormIsValid($form,
                                   $this->getRequest()->getPost())) {
            $this->view->form = $this->getForm()->prepareSubForm($form);
            return $this->render('index');
        }

        if (!$this->formIsValid()) {
            $form = $this->getNextSubForm();
            $this->view->form = $this->getForm()->prepareSubForm($form);
            return $this->render('index');
        }

        // Formulario Válido!
        // Render information in a verification page
        $this->view->info = $this->getSessionNamespace();
        $this->render('verification');
    }
}
]]>
            </programlisting>

            <para>
            	Como se ha notado, el código actual para procesar el formulario es
            	relativamente simple. Verificamos si tenemos un actual sub formulario
            	sometido y si no, retornamos a la página landing. Si tenemos
            	un sub formulario, intentaremos validarlo, redesplagandolo si tiene
            	fallas. Si el sub formulario es válido, entonces verificaremos si
            	el formulario es válido, lo que debería indicar hemos terminado; si no,
            	desplegaremos el siguiente segmento del formulario. Finalmente, desplegaremos una
            	página de verificación con el contenido de la sesión.
            </para>

            <para>
            	La vista de scripts son muy simples:
            </para>

            <programlisting role="php"><![CDATA[
<? // registration/index.phtml ?>
<h2>registro</h2>
<?= $this->form ?>

<? // registration/verification.phtml ?>
<h2>Gracias por Registrarse!</h2>
<p>
    Aquí está la información que nos ha proporcionado:
</p>

<?
// Tienen que construir esto con los items que estan almacenados en los namespaces
// de la sesión
foreach ($this->info as $info):
    foreach ($info as $form => $data): ?>
<h4><?= ucfirst($form) ?>:</h4>
<dl>
    <? foreach ($data as $key => $value): ?>
    <dt><?= ucfirst($key) ?></dt>
    <? if (is_array($value)):
        foreach ($value as $label => $val): ?>
    <dd><?= $val ?></dd>
        <? endforeach;
       else: ?>
    <dd><?= $this->escape($value) ?></dd>
    <? endif;
    endforeach; ?>
</dl>
<? endforeach;
endforeach ?>
]]>
            </programlisting>

            <para>
            	Próximas novedades de Zend Framework incluirán componentes
            	para hacer formularios multi páginas mas simple extrayendo la sesión y
            	el lógico orden. Mientras tanto, el ejemplo de arriba debería servir
            	como guia razonable en como alcanzar la tarea para su sitio.
            </para>
        </example>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->