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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2     <!-- EN-Revision: 16509 -->
   3     <!-- Reviewed: no -->
   4 <sect3 id="zend.controller.actionhelpers.autocomplete">
   5     <title>AutoComplete</title>
   6
   7     <para>
   8         Muchas bibliotecas de Javascript con
   9         <acronym>AJAX</acronym>
  10         ofrecen funcionalidad para
  11         proporcionar autocompletado según la cual un selectlist de
  12         resultados
  13         potencialmente concordantes se visualiza a medida que el usuario tipea.
  14         El ayudante
  15         <emphasis>AutoComplete</emphasis>
  16         pretende simplificar el retorno
  17         de respuestas aceptables a esos métodos.
  18     </para>
  19
  20     <para>
  21         Dado que no todas la bibliotecas JS implementan el autocompletado de
  22         la misma manera, el
  23         ayudante
  24         <emphasis>AutoComplete</emphasis>
  25         ofrece algunas
  26         funcionalidades abstractas de base necesarias para muchas bibliotecas,
  27         e
  28         implementaciones concretas para distintas bibliotecas.
  29         Los tipos de datos de retorno son
  30         generalmente o bien arrays de strings
  31         <acronym>JSON</acronym>
  32         , array de arrays
  33         <acronym>JSON</acronym>
  34         (donde cada miembro del array está en un array
  35         asociativo de metadatos utilizado para crear
  36         la selectlist), o
  37         <acronym>HTML</acronym>
  38         .
  39     </para>
  40
  41     <para>
  42         El uso básico para cada aplicación es el mismo:
  43    </para>
  44
  45     <programlisting language="php"><![CDATA[
  46 class FooController extends Zend_Controller_Action
  47 {
  48     public function barAction()
  49     {
  50         // Ejecutar alguna lógica...
  51
  52         // Codificar y enviar la respuesta;
  53         $this->_helper->autoCompleteDojo($data);
  54
  55         // O explicitamente:
  56         $response = $this->_helper->autoCompleteDojo
  57                                   ->sendAutoCompletion($data);
  58
  59         // O prepare simplemente la respuesta de autocompletado:
  60         $response = $this->_helper->autoCompleteDojo
  61                                   ->prepareAutoCompletion($data);
  62     }
  63 }
  64 ]]></programlisting>
  65
  66     <para>
  67         Por defecto, el autocompletado hace lo siguiente:
  68    </para>
  69
  70     <itemizedlist>
  71         <listitem>
  72             <para>
  73                 Desactiva esquemas y a ViewRenderer.
  74        </para>
  75         </listitem>
  76
  77         <listitem>
  78             <para>
  79                 Establece las cabeceras apropiadas para la respuesta.
  80        </para>
  81         </listitem>
  82
  83         <listitem>
  84             <para>
  85                 Establece el cuerpo de la respuesta con datos
  86                 codificados o formateados para
  87                 autocompletar.
  88        </para>
  89         </listitem>
  90
  91         <listitem>
  92             <para>
  93                 Envía la respuesta.
  94        </para>
  95         </listitem>
  96     </itemizedlist>
  97
  98     <para>
  99         Los métodos disponibles para el ayudante incluyen:
 100    </para>
 101
 102     <itemizedlist>
 103         <listitem>
 104             <para>
 105                 <methodname>disableLayouts()</methodname>
 106                 puede ser utilizada para
 107                 desactivar esquemas y a ViewRenderer. Típicamente, esto se
 108                 llama dentro de
 109                 <methodname>prepareAutoCompletion()</methodname>
 110                 .
 111             </para>
 112         </listitem>
 113
 114         <listitem>
 115             <para>
 116                 <methodname>encodeJson($data, $keepLayouts = false)</methodname>
 117                 codificará datos a
 118                 <acronym>JSON</acronym>
 119                 , y opcionalmente habilitando o
 120                 deshabilitando esquemas. Típicamente, esto se llama
 121                 dentro de
 122                 <methodname>prepareAutoCompletion()</methodname>
 123                 .
 124             </para>
 125         </listitem>
 126
 127         <listitem>
 128             <para>
 129                 <methodname>prepareAutoCompletion($data, $keepLayouts = false)</methodname>
 130                 se utiliza para preparar datos en el formato necesario de la
 131                 respuesta para la
 132                 aplicación concreta, opcionalmente los
 133                 esquemas pueden habilitarse o deshabilitarse.
 134                 El valor de retorno variará dependiendo de la implementación.
 135             </para>
 136         </listitem>
 137
 138         <listitem>
 139             <para>
 140                 <methodname>sendAutoCompletion($data, $keepLayouts = false)</methodname>
 141                 se utiliza para preparar datos en el formato necesario de la
 142                 respuesta para la
 143                 aplicación concreta. Esta llama a
 144                 <methodname>prepareAutoCompletion()</methodname>
 145                 , y entonces envía la
 146                 respuesta.
 147             </para>
 148         </listitem>
 149
 150         <listitem>
 151             <para>
 152                 <methodname>direct($data, $sendNow = true, $keepLayouts =
 153                     false)</methodname>
 154                 se utiliza cuando se llama al ayudante como
 155                 un método del ayudante intermediario. El flag
 156                 <varname>$sendNow</varname>
 157                 se utiliza para determinar si se debe
 158                 llamar a
 159                 <methodname>sendAutoCompletion()</methodname>
 160                 o a
 161                 <methodname>prepareAutoCompletion()</methodname>
 162                 , respectivamente.
 163             </para>
 164         </listitem>
 165     </itemizedlist>
 166
 167     <para>
 168         Actualmente,
 169         <emphasis>AutoComplete</emphasis>
 170         soporta las bibliotecas
 171         <acronym>AJAX</acronym>
 172         de
 173         Dojo y Scriptaculous.
 174     </para>
 175
 176     <sect4 id="zend.controller.actionhelpers.autocomplete.dojo">
 177         <title>AutoCompletado con Dojo</title>
 178
 179         <para>
 180             Dojo no tiene un widget de autocompletado per se, pero tiene dos
 181             widgets que pueden
 182             ejecutar AutoCompletado: ComboBox y
 183             FilteringSelect. En ambos casos, necesitan de un
 184             almacén de datos
 185             que implemente QueryReadStore; para obtener más información sobre
 186             estos
 187             temas, ver la documentación en
 188             <ulink
 189                 url="http://dojotoolkit.org/book/dojo-book-0-9/part-3-programmatic-dijit-and-dojo/data-retrieval-dojo-data-0"
 190             >dojo.data</ulink>
 191         </para>
 192
 193         <para>
 194             En Zend Framework, puede pasar un simple array indexado al ayudante
 195             AutoCompleteDojo, y
 196             este regresará una adecuada respuesta
 197             <acronym>JSON</acronym>
 198             para su uso como almacenamiento:
 199         </para>
 200
 201         <programlisting language="php"><![CDATA[
 202 // dentro del controlador de acción:
 203 $this->_helper->autoCompleteDojo($data);
 204 ]]></programlisting>
 205
 206         <example id="zend.controller.actionhelpers.autocomplete.dojo.example1">
 207             <title>AutoCompletion con Dojo Usando Zend MVC</title>
 208
 209             <para>
 210                 AutoCompletion con Dojo via Zend
 211                 <acronym>MVC</acronym>
 212                 requiere varias cosas:
 213                 generar un objeto form para el ComboBox en el que usted quiere
 214                 AutoCompletado, un controlador de acción para prestar servicio
 215                 a los resultados de
 216                 AutoCompletion, creando un QueryReadStore
 217                 personalizado para conectar a la acción
 218                 AutoCompletion,
 219                 y la generación del Javascript a utilizar en la inicializción
 220                 de
 221                 AutoCompletion del lado del servidor.
 222             </para>
 223
 224             <para>
 225                 En primer lugar, veamos el Javascript necesario. Dojo ofrece
 226                 un marco completo para
 227                 crear Javascript
 228                 <acronym>OOP</acronym>
 229                 , tal como lo hace
 230                 Zend Framework para
 231                 <acronym>PHP</acronym>
 232                 . Parte de eso es la capacidad de
 233                 crear pseudo-namespaces utilizando la jerarquía de
 234                 directorios.
 235                 Crearemos un directorio 'custom' en el mismo nivel en el cual
 236                 el
 237                 directorio de Dojo forma parte de la distribución Dojo.
 238                 Dentro del directorio,
 239                 crearemos un archivo Javascript,
 240                 <filename>TestNameReadStore.js</filename>
 241                 , con el siguiente contenido:
 242             </para>
 243
 244             <programlisting language="javascript"><![CDATA[
 245 dojo.provide("custom.TestNameReadStore");
 246 dojo.declare("custom.TestNameReadStore", dojox.data.QueryReadStore, {
 247     fetch:function (request) {
 248         request.serverQuery = { test:request.query.name };
 249         return this.inherited("fetch", arguments);
 250     }
 251 });
 252 ]]></programlisting>
 253
 254             <para>
 255                 Esta clase es simplemente una extensión del propio
 256                 QueryReadStore de Dojo, que es
 257                 de por sí misma una clase
 258                 abstracta. Simplemente definimos un método por el cual
 259                 realizamos la solicitud, y se le asigna al elemento 'test'.
 260            </para>
 261
 262             <para>
 263                 A continuación, vamos a crear el elemento form para el que
 264                 queremos AutoCompletion:
 265            </para>
 266
 267             <programlisting language="php"><![CDATA[
 268 class TestController extends Zend_Controller_Action
 269 {
 270     protected $_form;
 271
 272     public function getForm()
 273     {
 274         if (null === $this->_form) {
 275             $this->_form = new Zend_Form();
 276             $this->_form->setMethod('get')
 277                 ->setAction(
 278                     $this->getRequest()->getBaseUrl() . '/test/process'
 279                 )
 280                 ->addElements(array(
 281                     'test' => array('type' => 'text', 'options' => array(
 282                         'filters'        => array('StringTrim'),
 283                         'dojoType'       => array('dijit.form.ComboBox'),
 284                         'store'          => 'testStore',
 285                         'autoComplete'   => 'false',
 286                         'hasDownArrow'   => 'true',
 287                         'label' => 'Your input:',
 288                     )),
 289                     'go' => array('type' => 'submit',
 290                                   'options' => array('label' => 'Go!'))
 291                 ));
 292         }
 293         return $this->_form;
 294     }
 295 }
 296 ]]></programlisting>
 297
 298             <para>
 299                 Aquí, estamos simplemente creando un formulario con los métodos
 300                 'test' y 'go'. El
 301                 método 'test' agrega varios atributos
 302                 especiales específicos de Dojo: dojoType,
 303                 store,
 304                 <emphasis>AutoComplete</emphasis>
 305                 y hasDownArrow. El dojoType es utilizado para indicar que
 306                 estamos creando un
 307                 ComboBox, y que vamos a vincularlo
 308                 a un almacén de datos (clave 'store') de
 309                 'testStore'
 310                 -- veremos más de esto más adelante.
 311                 Especificando '
 312                 <emphasis>AutoComplete</emphasis>
 313                 ' como
 314                 <constant>FALSE</constant>
 315                 se le dice a Dojo que
 316                 no seleccione automáticamente el primer acierto, sino mostrar
 317                 una lista de aciertos. Por último, 'hasDownArrow' crea una
 318                 flecha abajo similar a un
 319                 select box para que podamos
 320                 mostrar y ocultar los aciertos o concordancias.
 321             </para>
 322
 323             <para>
 324                 Vamos a añadir un método para mostrar la forma, así como un
 325                 punto final para el
 326                 procesamiento de AutoCompletion:
 327            </para>
 328
 329             <programlisting language="php"><![CDATA[
 330 class TestController extends Zend_Controller_Action
 331 {
 332     // ...
 333
 334     /**
 335      * Página final
 336      */
 337     public function indexAction()
 338     {
 339         $this->view->form = $this->getForm();
 340     }
 341
 342     public function autocompleteAction()
 343     {
 344         if ('ajax' != $this->_getParam('format', false)) {
 345             return $this->_helper->redirector('index');
 346         }
 347         if ($this->getRequest()->isPost()) {
 348             return $this->_helper->redirector('index');
 349         }
 350
 351         $match = trim($this->getRequest()->getQuery('test', ''));
 352
 353         $matches = array();
 354         foreach ($this->getData() as $datum) {
 355             if (0 === strpos($datum, $match)) {
 356                 $matches[] = $datum;
 357             }
 358         }
 359         $this->_helper->autoCompleteDojo($matches);
 360     }
 361 }
 362 ]]></programlisting>
 363
 364             <para>
 365                 En nuestro
 366                 <methodname>autocompleteAction()</methodname>
 367                 hacemos una serie
 368                 de cosas. En primer lugar, esperamos a asegurarnos de que
 369                 tengamos
 370                 una petición post, y que existe un parámetro 'form'
 371                 establecido al valor 'ajax'; esto
 372                 es simplemente para ayudar a
 373                 reducir preguntas espúreas a la acción.
 374                 A continuación,
 375                 vamos a comprobar el parámetro 'test', y
 376                 compararlo contra nuestros datos. (Yo
 377                 deliberadamente dejé de
 378                 lado la implementación de
 379                 <methodname>getData()</methodname>
 380                 aquí --
 381                 podría ser cualquier tipo de fuente de datos). Por último,
 382                 enviamos nuestros
 383                 aciertos a nuestro ayudante AutoCompletion.
 384             </para>
 385
 386             <para>
 387                 Ahora que tenemos todas las piezas en el backend, veamos lo que
 388                 necesitamos para
 389                 entregar en nuestro script de vista para la
 390                 página final.
 391                 En primer lugar, necesitamos
 392                 configurar nuestro data store,
 393                 luego hacer nuestro formulario, y finalmente
 394                 garantizar que
 395                 las biblotecas Dojo apropiadas -- incluyendo que nuestro data
 396                 store
 397                 personalizado -- estén cargadas.
 398                 Veamos el script de vista, el cual comenta los
 399                 pasos:
 400            </para>
 401
 402             <programlisting language="php"><![CDATA[
 403 <?php // establecemos nuestro data store: ?>
 404 <div dojoType="custom.TestNameReadStore" jsId="testStore"
 405     url="<?php echo $this->baseUrl() ?>/unit-test/autocomplete/format/ajax"
 406     requestMethod="get"></div>
 407
 408 <?php // mostramos nuestro form: ?>
 409 <?php echo $this->form ?>
 410
 411 <?php // establecemos CSS relacionado con Dojo a cargar en HTML head: ?>
 412 <?php $this->headStyle()->captureStart() ?>
 413 @import "<?php echo $this->baseUrl()
 414 ?>/javascript/dijit/themes/tundra/tundra.css";
 415 @import "<?php echo $this->baseUrl() ?>/javascript/dojo/resources/dojo.css";
 416 <?php $this->headStyle()->captureEnd() ?>
 417
 418 <?php // setup de javascript para cargar en HTML head, incluyendo todas las
 419    // bibliotecas Dojo requeridas: ?>
 420 <?php $this->headScript()
 421         ->setAllowArbitraryAttributes(true)
 422         ->appendFile($this->baseUrl() . '/javascript/dojo/dojo.js',
 423             'text/javascript',
 424             array('djConfig' => 'parseOnLoad: true'))
 425         ->captureStart() ?>
 426 djConfig.usePlainJson=true;
 427 dojo.registerModulePath("custom","../custom");
 428 dojo.require("dojo.parser");
 429 dojo.require("dojox.data.QueryReadStore");
 430 dojo.require("dijit.form.ComboBox");
 431 dojo.require("custom.TestNameReadStore");
 432 <?php $this->headScript()->captureEnd()
 433 ]]></programlisting>
 434
 435             <para>
 436                 Note que las llamadas a los ayudantes de vista como headStyle
 437                 y headScript; son
 438                 ubicadores, que podemos suministrar a la
 439                 sección 'head' del
 440                 <acronym>HTML</acronym>
 441                 de nuestro script de vista.
 442             </para>
 443
 444             <para>
 445                 Ahora tenemos todas las piezas para que el AutoCompletion
 446                 de Dojo pueda trabajar.
 447            </para>
 448         </example>
 449     </sect4>
 450
 451     <sect4 id="zend.controller.actionhelpers.autocomplete.scriptaculous">
 452         <title>AutoCompletion con Scriptaculous</title>
 453         <para>
 454             <ulink url="http://wiki.script.aculo.us/scriptaculous/show/Ajax.Autocompleter">Scriptaculous</ulink>
 455             espera una respuesta
 456             <acronym>HTML</acronym>
 457             en un formato específico.
 458         </para>
 459
 460         <para>
 461             El ayudante para utilizar con esta biblioteca es
 462             'AutoCompleteScriptaculous'. Simplemente
 463             proporcionarle un array de
 464             datos, y el ayudante creará una respuesta
 465             <acronym>HTML</acronym>
 466             compatible con
 467             Ajax.Autocompleter.
 468         </para>
 469     </sect4>
 470 </sect3>
 471     <!--
 472 vim:se ts=4 sw=4 et:
 473 -->