# AutoComplete

Beaucoup de librairies javascript AJAX propose une fonctionnalité dite d'auto-complétion. Une liste de résultats possibles est chargée au fur et à mesure que l'utilisateur saisit. L'aide AutoComplete est destinée à simplifier le retour de ces valeurs vers la librairie Javascript.

Toutes les librairies JS n'implémentant pas l'auto-complétion de la même manière, l'aide AutoComplete propose une solution abstraite, ainsi que des implémentations concrètes pour certaines librairies. Les types de valeur de retour sont en général des tableaux de chaînes JSON, des tableaux de tableaux JSON (avec chaque membre étant un tableau associatif de métadonnées utilisées pour créer la liste de sélection), ou du HTML.

L'utilisation basique ressemble à ceci :

    class FooController extends Zend_Controller_Action
    {
        public function barAction()
        {
            // Ici du travail ....

            // Encode et envoie la réponse
            $this->_helper->autoCompleteDojo($data);

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

            // Ou alors prépare simplement les données :
            $response = $this->_helper
                             ->autoCompleteDojo
                             ->prepareAutoCompletion($data);
        }
    }

Par défaut, l'auto-complétion :

- Désactive les layouts et le ViewRenderer.

- Affecte des en-têtes de réponse appropriés.

- Remplit le corps de la réponse avec les données d'auto-complétion encodées/formatées.

- Envoie la réponse.

Les méthodes disponibles sont :

- `disableLayouts()` est utilisée pour désactiver les layouts et le ViewRenderer. Cette méthode est appelées par `prepareAutoCompletion()`.

- `encodeJson($data, $keepLayouts = false)` va encoder les données en JSON. Cette méthode est appelées par `prepareAutoCompletion()`.

- `prepareAutoCompletion($data, $keepLayouts = false)` prépare les données dans le format de réponse nécessaire à une implémentation concrète. La valeur de retour va changer en fonction de l'implémentation (de la librairie utilisée).

- `sendAutoCompletion($data, $keepLayouts = false)` Va appeler `prepareAutoCompletion()`, puis envoyer la réponse.

- `direct($data, $sendNow = true, $keepLayouts = false)` est une méthode utilisée par le gestionnaire d'aides (helper broker). La valeur de `$sendNow` va déterminer si c'est `sendAutoCompletion()` ou `prepareAutoCompletion()`, qui doit être appelée.

Actuellement, AutoComplete supporte les librairies AJAX Dojo et Scriptaculous.

## AutoCompletion avec Dojo

Dojo n'a pas une fonctionnalité d'auto-complétion, mais deux : ComboBox et FilteringSelect. Dans les deux cas, elle demande une structure de données qui implémente QueryReadStore ; voyez la documentation de dojo.data

Dans Zend Framework, vous pouvez passer un simple tableau indexé à l'aide AutoCompleteDojo, elle retournera une réponse JSON compatible avec la structure de données Dojo :

    // à l'intérieur d'une action de contrôleur :
    $this->_helper->autoCompleteDojo($data);

### AutoCompletion avec Dojo en utilisant MVC

L'auto-complétion avec Dojo via MVC requière plusieurs choses : générer un objet formulaire sur le ComboBox sur lequel vous voulez de l'auto-complétion, un contrôleur avec une action pour servir les résultats, la création d'un QueryReadStore à connecter à l'action et la génération du javascript à utiliser pour initialiser l'auto-complétion coté serveur.

Voyons le javascript nécessaire. Dojo est une librairie complète pour la création de javascript OO, un peu comme Zend Framework pour PHP. Il est possible de créer des pseudo-namespaces en utilisant l'arborescence des répertoires. Nous allons créer un répertoire "custom" au même niveau que le répertoire Dojo. A l'intérieur, nous allons créer un fichier javascript, `TestNameReadStore.js`, avec le contenu suivant :

    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);
                 }
    });

Cette classe est une simple extension de QueryReadStore, qui est une classe abstraite. Nous définissons simplement une méthode de requête, et on lui assigne notre élément "test".

Ensuite, créons le formulaire sur lequel nous souhaitons une auto-complétion :

    class TestController extends Zend_Controller_Action
    {
        protected $_form;

        public function getForm()
        {
            if (null === $this->_form) {
                require_once 'Zend/Form.php';
                $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;
        }
    }

Ici, nous créons simplement un formulaire avec des méthodes "test" et "go". La méthode "test" ajoute plusieurs attributs Dojo spéciaux : dojoType, store, autoComplete, et hasDownArrow. dojoType est utilisé pour indiquer la création d'une ComboBox, et nous allons la relier au conteneur de données ("store") de "testStore". Mettre "autoComplete" à `FALSE` dit à Dojo de ne pas sélectionner automatiquement la première valeur, mais de plutôt montrer une liste de valeurs possibles. Enfin, "hasDownArrow" crée une flèche bas comme sur les select box.

Ajoutons une méthode pour afficher le formulaire, et une entrée pour traiter l'auto-complétion :

    class TestController extends Zend_Controller_Action
    {
        // ...

        /**
         * Landing page
         */
        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);
        }
    }

Dans `autocompleteAction()`, nous vérifions que nous avons bien une requête post, et un paramètre "format" avec la valeur "ajax". Ensuite, nous vérifions la présence d'un paramètre "test", et le comparons avec nos données. (`getData()` retourne des données quelconques). Enfin, nous envoyons nos résultats à notre aide AutoCompletion.

Voyons maintenant notre script de vue. Nous devons configurer notre entrepôt de données, puis rendre le formulaire, et s'assurer que les librairies Dojo appropriées sont bien chargées (ainsi que notre entrepôt). Voici le script de vue :

    <?php // configuration de l'entrepôt de données : ?>
    <div dojoType="custom.TestNameReadStore" jsId="testStore"
        url="<?php echo $this->baseUrl() ?>/unit-test/autocomplete/format/ajax"
        requestMethod="get"></div>

    <?php // rendu du formulaire : ?>
    <?php echo $this->form ?>

    <?php // configuration des CSS de Dojo dans le head HTML : ?>
    <?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 // configuration de javascript pour charger
          // les librairies Dojo dans le head HTML : ?>
    <?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() ?>

Notez les appels aux aides de vue comme headStyle et headScript ; celles-ci sont des emplacements réservés, que nous pouvons ensuite utiliser pour effectuer le rendu dans la section "head" du HTML de votre script de layout.

Nous pouvons dès lors faire fonctionner l'auto-complétion Dojo.

## AutoCompletion avec Scriptaculous

Scriptaculous attend une réponse HTML dans un format spécifique.

Utilisez l'aide "AutoCompleteScriptaculous". Passez lui un tableau de données et l'aide créera une réponse HTML compatible avec "Ajax.Autocompleter".