Drupal : créer un champ auto-completé personnalisé

Drupal 7 vous offre nativement la possibilité de compléter un champ de manière semi automatique grâce au mécanisme d'autocomplétion.

Cette fonctionnalité permet l'affichage d'une liste de suggestions lors de la saisie par l'utilisateur des premières lettres du champ.

Cette liste de suggestions est le fruit d'un appel AJAX, c'est à dire un appel asynchrone au serveur qui, en fonction des paramètres donnés, renvoit les données correspondantes.

Nous allons voir comment parametrer la reponse du serveur afin d'obtenir une liste la plus precise possible.

Le formulaire

Afin de pouvoir completer le champ, nous avons besoin d'un formulaire.

Si vous ne l'avez pas déjà mis en place, je vous invite à implémenter le hook_form, si vous avez déjà votre hook_form il vous suffit d'ajouter le champ autocomplété :

function mon_module_form(){

$form = array();

$form['mon_item'] = array('...'); // Declaration des éléments du formulaires

[...]

$form['champ_autocomplete'] = array('#type' => 'textfield'
									, '#title' => t('Mon champ autocomplete')
									, '#autocomplete_path' => 'mon_module/monchamp/autocomplete'
									);
	return $form;
}

Le point important dans l'élément ajouté est le champ "#autocomplete_path" qui, comme son nom l'indique, fait appel à une URL/fonction.

Cette URL est un chemin implementé dans le hook_menu de votre module

Le hook_menu

Comme indiqué précédemment, pour le fonctionnement de l'auto-complétion, il vous faut créer un chemin d'accès. Ce chemin routera vers la fonction qui sélectionne les élèments à renvoyer dans la liste de suggestions.

Voici le code à insérer :

function mon_module_menu(){
$items = array();
$items['mon_module/monchamp/autocomplete'] = array(
				'title' => t('Mon champ s\'auto-complete')
				, 'callback' => 'mafonction_autocomplete'
				, 'access callback' => 'user_access'
				, 'access arguments' => array('access content')
				, 'type' => 'MENU_CALLBACK'
				);
				
				[..] //Vos items
return $items;
}

Le chemin 'mon_module/monchamp/autocomplete' est, comme vous l'aurez compris, le chemin appelé par votre champ lors de son remplissage. Ce chemin renvoit vers la fonction 'mafonction_autocomplete' on parle alors de callback.

Le callback

Un callback est, comme l'indique son nom, une fonction qui est appelée en aval. Dans notre cas, cette fonction renvoit la liste des éléments correspondant aux lettres tapées par l'utilisateur.

function mafonction_autocomplete($str = '')
{ $matches = array(); 
if ($str){
 $query = db_select('') // Votre requête SQL 
$res = $query->execute(); 
while($correspond = $res->fetchObject()){
 $matches[$correspond->FIELD] = $correspond->FIELD2;
 } 
} 
drupal_json_output($matches);
}

Comme vous le constatez, cette fonction est en fait une simple requete SQL qui vous permet de selectionner les champ correspondant en fonction des lettres tapées. On peut alors imaginer sélectionner les données en fonction de ces lettres, mais aussi en fonction d'autres élèments (uid, variables GET ...)