repo_zf1/documentation/manual/es/module_specs/Zend_Controller-ActionHelpers-AutoComplete.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15103 -->
<!-- Reviewed: no -->
<sect3 id="zend.controller.actionhelpers.autocomplete">
    <title>AutoComplete</title>

    <para>
        Muchas bibliotecas de Javascript con AJAX ofrecen funcionalidad para
        proporcionar autocompletado según la cual un selectlist de resultados
        potencialmente concordantes se visualiza a medida que el usuario tipea.
        El ayudante <methodname>AutoComplete</methodname> pretende simplificar el retorno
        de respuestas aceptables a esos métodos.
    </para>

    <para>
        Dado que no todas la bibliotecas JS implementan el autocompletado de
        la misma manera, el ayudante <methodname>AutoComplete</methodname> ofrece algunas
        funcionalidades abstractas de base necesarias para muchas bibliotecas,
        e implementaciones concretas para distintas bibliotecas.
        Los tipos de datos de retorno son generalmente o bien arrays de strings
        JSON, array de arrays JSON (donde cada miembro del array está en un array
        asociativo de metadatos utilizado para crear la selectlist), o HTML.
    </para>

    <para>
        El uso básico para cada aplicación es el mismo:
    </para>

         <programlisting language="php"><![CDATA[
class FooController extends Zend_Controller_Action
{
    public function barAction()
    {
        // Ejecutar alguna lógica...

        // Codificar y enviar la respuesta;
        $this->_helper->autoCompleteDojo($data);

        // O explicitamente:
        $response = $this->_helper->autoCompleteDojo
                                  ->sendAutoCompletion($data);

        // O prepare simplemente la respuesta de autocompletado:
        $response = $this->_helper->autoCompleteDojo
                                  ->prepareAutoCompletion($data);
    }
}
]]></programlisting>

    <para>
        Por defecto, el autocompletado hace lo siguiente:
    </para>

    <itemizedlist>
        <listitem><para>
                Desactiva esquemas y a ViewRenderer.
        </para></listitem>

        <listitem><para>
                Establece las cabeceras apropiadas para la respuesta.
        </para></listitem>

        <listitem><para>
                Establece el cuerpo de la respuesta con datos
                codificados/formateados para autocompletar.
        </para></listitem>

        <listitem><para>
                Envía la respuesta.
        </para></listitem>
    </itemizedlist>

    <para>
        Los métodos disponibles para el ayudante incluyen:
    </para>

    <itemizedlist>
        <listitem><para>
                <methodname>disableLayouts()</methodname> puede ser utilizada para
                desactivar esquemas y a ViewRenderer. Típicamente, esto se
                llama dentro de <methodname>prepareAutoCompletion()</methodname>.
        </para></listitem>

        <listitem><para>
                <methodname>encodeJson($data, $keepLayouts = false)</methodname>
                codificará datos a JSON, y opcionalmente habilitando o
                deshabilitando esquemas. Típicamente, esto se llama dentro de
                <methodname>prepareAutoCompletion()</methodname>.
        </para></listitem>

        <listitem><para>
                <methodname>prepareAutoCompletion($data, $keepLayouts = false)</methodname>
                se utiliza para preparar datos en el formato necesario de la
                respuesta para la aplicación concreta, opcionalmente los
                esquemas pueden habilitarse o deshabilitarse.
                El valor de retorno variará dependiendo de la implementación.
        </para></listitem>

        <listitem><para>
                <methodname>sendAutoCompletion($data, $keepLayouts = false)</methodname>
                se utiliza para preparar datos en el formato necesario de la
                respuesta para la aplicación concreta. Esta llama a
                <methodname>prepareAutoCompletion()</methodname>, y entonces envía la
                respuesta.
        </para></listitem>

        <listitem><para>
                <methodname>direct($data, $sendNow = true, $keepLayouts =
                    false)</methodname> se utiliza cuando se llama al ayudante como
                    un método del ayudante intermediario. El flag
                    <methodname>$sendNow</methodname> se utiliza para determinar si se debe
                    llamar a <methodname>sendAutoCompletion()</methodname> o a
                    <methodname>prepareAutoCompletion()</methodname>, respectivamente.
        </para></listitem>
    </itemizedlist>

    <para>
        Actualmente, <methodname>AutoComplete</methodname> soporta las bibliotecas AJAX de
        Dojo y Scriptaculous.
    </para>

    <sect4 id="zend.controller.actionhelpers.autocomplete.dojo">
        <title>AutoCompletado con Dojo</title>

        <para>
            Dojo no tiene un widget de autocompletado per se, pero tiene dos
            widgets que pueden ejecutar AutoCompletado: ComboBox y
            FilteringSelect. En ambos casos, necesitan de un almacén de datos
            que implemente QueryReadStore; para obtener más información sobre
            estos temas, ver la documentación en
            <ulink url="http://dojotoolkit.org/book/dojo-book-0-9/part-3-programmatic-dijit-and-dojo/data-retrieval-dojo-data-0">dojo.data</ulink>
        </para>

        <para>
            En Zend Framework, puede pasar un simple array indexado al ayudante
            AutoCompleteDojo, y este regresará una adecuada respuesta JSON
            para su uso como almacenamiento:
        </para>

         <programlisting language="php"><![CDATA[
// dentro del controlador de acción:
$this->_helper->autoCompleteDojo($data);
]]></programlisting>

        <example id="zend.controller.actionhelpers.autocomplete.dojo.example1">
            <title>AutoCompletion con Dojo Usando Zend MVC</title>

            <para>
                AutoCompletion con Dojo via Zend MVC requiere varias cosas:
                generar un objeto form para el ComboBox en el que usted quiere
                AutoCompletado, un controlador de acción para prestar servicio
                a los resultados de AutoCompletion, creando un QueryReadStore
                personalizado para conectar a la acción AutoCompletion,
                y la generación del Javascript a utilizar en la inicializción
                de AutoCompletion del lado del servidor.
            </para>

            <para>
                En primer lugar, veamos el Javascript necesario. Dojo ofrece
                un marco completo para crear Javascript OOP, tal como lo hace
                Zend Framework para PHP. Parte de eso es la capacidad de
                crear pseudo-namespaces utilizando la jerarquía de directorios.
                Crearemos un directorio 'custom' en el mismo nivel en el cual
                el directorio de Dojo forma parte de la distribución Dojo.
                Dentro del directorio, crearemos un archivo Javascript,
                TestNameReadStore.js, con el siguiente contenido:
            </para>

            <programlisting language="javascript"><![CDATA[
dojo.provide("custom.TestNameReadStore");
dojo.declare("custom.TestNameReadStore", dojox.data.QueryReadStore, {
    fetch:function (request) {
        request.serverQuery = { test:request.query.name };
        return this.inherited("fetch", arguments);
    }
});
]]></programlisting>

            <para>
                Esta clase es simplemente una extensión del propio
                QueryReadStore de Dojo, que es de por sí misma una clase
                abstracta. Simplemente definimos un método por el cual
                realizamos la solicitud, y se le asigna al elemento 'test'.
            </para>

            <para>
                A continuación, vamos a crear el elemento form para el que
                queremos AutoCompletion:
            </para>

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

    public function getForm()
    {
        if (null === $this->_form) {
            $this->_form = new Zend_Form();
            $this->_form->setMethod('get')
                ->setAction(
                    $this->getRequest()->getBaseUrl() . '/test/process'
                )
                ->addElements(array(
                    'test' => array('type' => 'text', 'options' => array(
                        'filters'        => array('StringTrim'),
                        'dojoType'       => array('dijit.form.ComboBox'),
                        'store'          => 'testStore',
                        'autoComplete'   => 'false',
                        'hasDownArrow'   => 'true',
                        'label' => 'Your input:',
                    )),
                    'go' => array('type' => 'submit',
                                  'options' => array('label' => 'Go!'))
                ));
        }
        return $this->_form;
    }
}
]]></programlisting>

            <para>
                Aquí, estamos simplemente creando un formulario con los métodos
                'test' y 'go'. El método 'test' agrega varios atributos
                especiales específicos de Dojo: dojoType, store, autoComplete
                y hasDownArrow. El dojoType es utilizado para indicar que
                estamos creando un ComboBox, y que vamos a vincularlo
                a un almacén de datos (clave 'store') de 'testStore'
                -- veremos más de esto más adelante.
                Especificando 'autoComplete' como falso se le dice a Dojo que
                no seleccione automáticamente el primer acierto, sino mostrar
                una lista de aciertos. Por último, 'hasDownArrow' crea una
                flecha abajo similar a un select box para que podamos
                mostrar y ocultar los aciertos o concordancias.
            </para>

            <para>
                Vamos a añadir un método para mostrar la forma, así como un
                punto final para el procesamiento de AutoCompletion:
            </para>

             <programlisting language="php"><![CDATA[
class TestController extends Zend_Controller_Action
{
    // ...

    /**
     * Página final
     */
    public function indexAction()
    {
        $this->view->form = $this->getForm();
    }

    public function autocompleteAction()
    {
        if ('ajax' != $this->_getParam('format', false)) {
            return $this->_helper->redirector('index');
        }
        if ($this->getRequest()->isPost()) {
            return $this->_helper->redirector('index');
        }

        $match = trim($this->getRequest()->getQuery('test', ''));

        $matches = array();
        foreach ($this->getData() as $datum) {
            if (0 === strpos($datum, $match)) {
                $matches[] = $datum;
            }
        }
        $this->_helper->autoCompleteDojo($matches);
    }
}
]]></programlisting>

            <para>
                En nuestro <methodname>autocompleteAction()</methodname> hacemos una serie
                de cosas. En primer lugar, esperamos a asegurarnos de que
                tengamos una petición post, y que existe un parámetro 'form'
                establecido al valor 'ajax'; esto es simplemente para ayudar a
                reducir preguntas espúreas a la acción.
                A continuación, vamos a comprobar el parámetro 'test', y
                compararlo contra nuestros datos. (Yo deliberadamente dejé de
                lado la implementación de <methodname>getData()</methodname> aquí --
                podría ser cualquier tipo de fuente de datos). Por último,
                enviamos nuestros aciertos a nuestro ayudante AutoCompletion.
            </para>

            <para>
                Ahora que tenemos todas las piezas en el backend, veamos lo que
                necesitamos para entregar en nuestro script de vista para la
                página final.
                En primer lugar, necesitamos configurar nuestro data store,
                luego hacer nuestro formulario, y finalmente garantizar que
                las biblotecas Dojo apropiadas -- incluyendo que nuestro data
                store personalizado -- estén cargadas.
                Veamos el script de vista, el cual comenta los pasos:
            </para>

             <programlisting language="php"><![CDATA[
<?php // establecemos nuestro data store: ?>
<div dojoType="custom.TestNameReadStore" jsId="testStore"
    url="<?php echo $this->baseUrl() ?>/unit-test/autocomplete/format/ajax"
    requestMethod="get"></div>

<?php // mostramos nuestro form: ?>
<?php echo $this->form ?>

<?php // establecemos CSS relacionado con Dojo a cargar en HTML head: ?>
<?php $this->headStyle()->captureStart() ?>
@import "<?php echo $this->baseUrl()
?>/javascript/dijit/themes/tundra/tundra.css";
@import "<?php echo $this->baseUrl() ?>/javascript/dojo/resources/dojo.css";
<?php $this->headStyle()->captureEnd() ?>

<?php // setup de javascript para cargar en HTML head, incluyendo todas las
   // bibliotecas Dojo requeridas: ?>
<?php $this->headScript()
        ->setAllowArbitraryAttributes(true)
        ->appendFile($this->baseUrl() . '/javascript/dojo/dojo.js',
            'text/javascript',
            array('djConfig' => 'parseOnLoad: true'))
        ->captureStart() ?>
djConfig.usePlainJson=true;
dojo.registerModulePath("custom","../custom");
dojo.require("dojo.parser");
dojo.require("dojox.data.QueryReadStore");
dojo.require("dijit.form.ComboBox");
dojo.require("custom.TestNameReadStore");
<?php $this->headScript()->captureEnd()
]]></programlisting>

            <para>
                Note que las llamadas a los ayudantes de vista como headStyle
                y headScript; son ubicadores, que podemos suministrar a la
                sección 'head' del HTML de nuestro script de vista.
            </para>

            <para>
                Ahora tenemos todas las piezas para que el AutoCompletion
                de Dojo pueda trabajar.
            </para>
        </example>
    </sect4>

    <sect4 id="zend.controller.actionhelpers.autocomplete.scriptaculous">
        <title>AutoCompletion con Scriptaculous</title>
        <para>
            <ulink url="http://wiki.script.aculo.us/scriptaculous/show/Ajax.Autocompleter">Scriptaculous</ulink>
            espera una respuesta HTML en un formato específico.
        </para>

        <para>
            El ayudante para utilizar con esta biblioteca es
            'AutoCompleteScriptaculous'. Simplemente proporcionarle un array de
            datos, y el ayudante creará una respuesta HTML compatible con
            Ajax.Autocompleter.
        </para>
    </sect4>
</sect3>
<!--
vim:se ts=4 sw=4 et:
-->