Créer des templates (fichier.tpl.php) pour themer vos modules

Lors de la création de vos modules vous pouvez être amenés à mettre en forme votre contenu pour garder une approche cohérence avec la dissociation fond / forme. Il est donc nécessaire de donner la possibilité au themer de pouvoir modifier la mise en forme du contenu que vous aller afficher. Afin de rendre une telle action possible, vous allez devoir déclarer au sein de votre module un hook_theme, qui va déclarer les éléments qui pourront être themés via vos templates. Le hook_theme est simplement constitué d'un tableau d'éléments skinnables avec pour chaque entrée une clé "template" qui correspond au nom du fichier .tpl.php utilisé pour le theme et une clé "arguments" correspondant à un tableau de paramètres à passer à la fonction de theme().

function hook_theme() {
  return array(
    'my_themeable_call' => array(
      'template' => 'gabarit.tpl.php',
      'arguments' => array("param1" => NULL),
    ),
  );
}

A noter : Le ".tpl.php" est facultatif car toujours suggéré par le moteur de template et il est recommandé d'utiliser le même nom comme clé et comme nom de fichier pour le template. (Les noms sont ici différents pour vous permettre de décortiquer la mécanique). [Merci Cyril pour la remarque]

Voilà votre fonction de thème déclarée, il ne reste plus qu'à l'utiliser. Prenons l'exemple d'un bloc, vous souhaitez utiliser votre fonction de thème dans son contenu, il vous suffit d'utiliser dans le contenu du bloc (cf hook_block) votre fonction de theme : $bloc['content'] = theme('my_themeable_call', $param1); De cette façon vous enverrez à votre fichier de template la variable $param1 (pouvant contenir tout type de données). Si vous omettez de passer un argument, la valeur par défaut déclarée dans le hook_theme sera utilisée (dans notre exemple si j'omets $param1, sa valeur sera NULL).

Plaçons-nous maintenant dans notre fichier de template gabarit.tpl.php, c'est le fichier que votre themer pourra surcharger en le copiant collant dans le dossier de son thème. Les variables à disposition sont celles que vous avez passé en paramètres lors de l'appel de la fonction de thème (ici $param1) et les éventuelles variables ajoutées par les fonctions de preprocess. (La signature de la fonction est template_preprocess_my_themeable_call, surchargeable par THEME_preprocess_my_themeable_call).

De cette façon vous pouvez donc créer vos propres fichiers de theming lors de la publication de vos modules afin de vous faire adorer par les themers !