Pxxo_Widget_Input_Livesearch

Ce widget se présente sous la forme d'un champ de saisie classique à inclure dans un formulaire généré ou non via un Pxxo_Widget_Form. Ce champ a la particularité de proposer au fur-et-à-mesure de la frappe des propositions “d'auto-complétion” (ou de résultats quelconques ayant un rapport avec la saisie) via une liste de type Livesearch. Ainsi il peut être utilisé en tant qu'aide à la saisie pour simplifier la frappe, la recherche ou encore autre chose …

• Exemple d'utilisation en ligne

On peut l'utiliser de 2 manières différentes : soit on l'instancie par l'intermédiaire d'un Pxxo_Widget_Form, soit l'utiliser directement dans un formulaire “maison”. Vous avez remarqué que ce widget peut prendre énormément de paramètre. De cette manière son comportement et les résultats obtenus sont très variés afin de répondre aux plus larges besoins.

Il suffit d'instancier un Pxxo_Widget_Form en lui spécifiant quelques paramètres comme le montre l'exemple suivant :

$params = array ( 'inputs' => array( 
                                 array( 
                                     'type' => 'livesearch', 
                                     'id' => 'test1', 
                                     'label' => 'pays',
                                     'required' => true,
                                     'urldest' => './query_pays.php',
                                     'activeGetLib' => true, 
                                     'activeLink' => true,
                                     'affLienSuivant' => false, 
                                     'affEnteteBloc' => false,
                                 ),
                         )
         );
$o = new Pxxo_Widget_Form($params);

Aucune subtilité (cf. paramètres) mise à part que le paramètre “form_id” doit être renseigné.

L'exemple ci-dessous illustre la structure attendue générée par le script interrogé pour répondre à la requête que le widget a constitué.

<div id=myResult>
  <span>61</span>
  <ul>
    <li>Commence par ...</li>
    <li>
      <ul>
        <li><span>TE.147253</span><span>ITALGIURE</span></li>
        <li><span>TE.118750</span><span>Italian ENEA</span></li>
        <li><span>TE.118751</span><span>Italian ENEL</span></li>
        <li><span>TE.141608</span><span>Italianisme</span></li>
        <li><span>TE.826</span><span>Italie</span></li>
      </ul>
    </li>
  </ul>
  <ul>
    <li>Contient ...</li>
    <li>
      <ul>
        <li><span>TE.11128</span><span>Brassica oleracea italica</span></li>            
      </ul>
    </li>
  </ul>
</div>

Dans cet exemple, on peut y voir le nombre de résultats de la requête, ici “61”, entre balise “span”. Par ailleurs, on peut voir deux blocs de résultats correspondant au premier niveau des “ul”, intitulés ici “Commence par” et “Contient…”. On pourrait très bien n'avoir qu'un bloc ou au contraire multiplier ceux-ci ou les faire varier en fonction des besoins et/ou des paramètres de la requête. Dans les niveaux plus profonds de chacun des blocs, on retrouve une liste (“ul”) dans laquelle se trouve la liste des items résultats. Chacun d'eux se trouvent dans un élément “li”. Le contenu de ce dernier est structuré via des balises “span”. Le premier “span” contient l'identifiant de l'item, le second contient le libellé qui sera affiché. La présence de l'identifiant est obligatoire mais celui-ci peut être égal au libellé dans le cas où, par exemple, l'applicatif n'a pas besoin de véhiculer un identifiant.

Il est possible de lier un ou plusieurs champs de formulaire au champ de saisie de saisie généré par ce widget. Cela permet d'enrichir les requêtes (et les liens générés) par les valeurs de ces champs qui constitue le contexte. Pour effectuer ce lien, il faut renseigner le paramètre “fieldlinked”. Celui-ci est un tableau de tableau qui respecte la structure illustrée dans l'exemple ci-dessous :

...
'fieldlinked' => array ( 
    array('id' => 'f1', 'label' => 'alt' ), 
    array('id' => 'lng', 'label' => 'lng' ) 
)
...

- La clef “id” correspond à l'identifiant (attribut html “id') de l'élément de formulaire à lier.

- La clef “label” est une chaine de caractère qui permet de “mapper” l'élément avec les paramètres du script de recherche. Concrètement, dans l'exemple ci-dessus, la valeur x de l'élément de formulaire dont l'identifiant est “f1”, et la valeur y de l'élément “lng” seront automatiquement ajoutées à la requête de la manière suivante : …&alt=x&lng=y

Quand le paramètre “activeLink” est à true, la sélection d'un item dans la liste de résultats générée par le widget renvoie systématiquement deux paramètres vers l'url précisée dans “urldest” : “id” et “lib”. Ces deux paramètres sont par défaut préfixés par le ClassID. Dans un contexte d'existant et pour simplifier l'intégration de ce widget à celui-ci, on peut avoir le besoin de ne pas renvoyer ces paramètres sous ces noms. Par exemple, dans le script php (ou autre) qui répondra à l'url précisées dans “urldest”, on peut attendre un paramètre d'url nommé “idt” au lieu de, par défaut, “id” préfixé par le ClassID. Pour cela, il suffit de mapper la variable en le spécifiant de la manière suivante dans les paramètres passés au constructeur de ce widget :

...
'activePrefixOut' => false,
'globalParamMapping' => array ( 
    array('in' => 'id', 'out' => 'idt' )
)
...

- “activePrefixOut” à false : désactive le “préfixage” des paramètres par le ClassID

- La clef “in” correspond au nom du paramètre à mapper.

- La clef “out” est le nom que le paramètre spécifié dans “in” utilisera en sortie.

On peut également mapper d'autres paramètres, par exemple, un champ lié au livesearch ou encore un paramètre utilisé pour générer les url des liens de type “la suite des résultats”. Exemple :

...
'activePrefixOut' => false,
'globalParamMapping' => array ( 
    array('in' => 'id', 'out' => 'idt' ),
    array('in' => 'lng', 'out' => 'lang' ),
    array('in' => 'qry', 'out' => 'q' )
)
...

Il est mentionné dans le tableau décrivant les paramètres :

Cette restriction est liée à l'utilisation d'AJAX. Cependant on peut être coincé et devoir utiliser, par exemple, un webservice ne se trouvant par sur le même serveur et/ou arborscence web pour executer la requête de recherche. Pour cela, il suffit de créer une page dans votre arborescence qui fera office de “proxy”. Dans cette page, il suffit d'en récupérer les paramètres et via la fonction php file_get_contents d'ouvrir l'url du webservice et d'en écrire le résultat. L'exemple suivant illustre ces propos :

// encodage de retour
header('Content-Type: text/html; charset=utf-8');
 
// les paramètres à faire suivre
$params  = ( isset($_GET['qry']) ? '&qry='.$_GET['qry'] : '' );
$params .= ( isset($_GET['lng']) ? '&lng='.$_GET['lng'] : '' );
 
// url de destination
$url = 'http://neotrouvetou.com/wbs/query.php?';
 
// récupération et écriture du résultat
echo ( $buffer=file_get_contents($url.$params) ? $buffer : '' );

Dans cet exemple, le script php qui fait office de “proxy” prend en paramètre la langue (“lng”), ainsi que la chaine à rechercher (“qry”). L'URL à interroger est la suivante http://neotrouvetou.com/wbs/query.php et renvoie un résultat encodé en UTF-8 (Attention à bien utiliser le même encodage de caractère en retour que sur la page qui accueille ce widget) et on affiche le retour si il y en a un.