API des formulaire : Theming d'un formulaire

Voir documentation sur l'API des formulaires http://drupalfr.org/node/8337

Nous avons vu précédemment que le html de notre formulaire est généré automatiquement par l'API des formulaires de Drupal. Mais comment faire si nous voulons justement controler la mise en forme html de nos éléments, le présenter par exemple en trois colonnes, chacune étant un div avec un titre ? La réponse est : en utilisant une fonction theme.

Ecrire une fonction de theme

Pour cela nous devons déclarer une nouvelle fonction chargé de mettre en forme notre formulaire. Dans notre exemple, la fonction générant notre formulaire s'appelle "mon_formulaire". Si nous créons une fonction nommée "theme_mon_formulaire", celle ci sera utilisée par le systeme de theme de Drupal pour mettre en forme notre formulaire d'exemple à la place de l'affichage par défaut.

<?php
function theme_mon_formulaire($form){
  $output  = drupal_render($form['submit']);
  $output .= '<div>';
  $output .= '<h1>Entrez votre nom ! </h1>';
  $output .= drupal_render($form['nom']);
  $output .= '</div>';  
  $output .= drupal_render($form);
  return $output;
}
?>

Explications :
- La fonction drupal_render() est utilisée pour généré le html d'une partie de notre formulaire. drupal_render($form['submit']) va générer automatiquement le code html pour notre bouton de soumission.
- Notez bien que à la fin nous faisons un drupal_render sur tout le formulaire afin d'être sur qu'aucun élément de notre formulaire n'a été oublié par notre fonction theme : on est ainsi sûr d'afficher tout ce que nous n'avons pas affiché manuellement par drupal_render() et également que les champs cachés dont Drupal a besoin pour traiter un formulaire seront eux aussi bien présents.

Déclarer à Drupal notre fonction theme !

Le code ci-dessus ne modifiera en aucune façon l'affichage de votre formulaire pour le moment. Drupal doit en effet savoir que cette fonction theme existe, la convention de nommage avec 'theme_+nom_du_formulaire' n'est pas suffisante sur Drupal 6. Drupal fonctionne avec un "registre de themes" (theme registry) : il s'agit de la liste de toutes les fonctions themes déclarées par les modules.

Il faut donc maintenant que nous informions Drupal de l'existence de notre fonction theme, et pour cela nous devons la déclarer au registre des themes via un hook dans notre module :

<?php
function formexample_theme(){
  $themes = array();
  $themes['mon_formulaire'] = array(
    'arguments' => array(), //notre fonction n'a besoin d'aucun argument, on laisse vide.
  );
  return $themes;
}
?>

Un hook_theme peut contenir plusieurs themes, c'est pour cela qu'il est déclaré en tant que array.
Ici on indique l'existence d'un theme 'mon_formulaire', ce qui signifie que Drupal cherchera la fonction "theme_mon_formulaire" pour générer notre html.

Il faut enfin vider le cache de Drupal (site > configuration > performance > vider le cache) afin que drupal rescanne tous les modules pour reconstruire le registre de thèùes en prenant en compte notre nouvelle fonction.

Déclarer une fonction theme alternative pour un formulaire

Il existe une autre manière de déclarer quel fonction theme doit utiliser le formulaire : en la déclarant dans la fonction 'mon_formulaire' en ajoutant ceci :

<?php
$form['#theme'] = 'mon_formulaire_alternatif';
?>

il faudra ensuit également avertir le theme de registrer de l'existence de cette nouvelle fonction theme via notre hook theme qui ressemblera alors à ceci :

<?php
function formexample_theme(){
  $themes = array();
  $themes['mon_formulaire'] = array(
    'arguments' => array(),
  );
  $themes['mon_formulaire_alternatif'] = array(
    'arguments' => array(),
  );
  return $themes;
}
?>

Après avoir vidé le cache, drupal cherchera la fonction theme_mon_formulaire_alternatif. Celle ci sera cherchée avant la fonction theme_mon_formulaire qui du coup ne sera pas utilisée, si ces deux fonctions themes co-existent.