Le besoin

Il est possible de surcharger un template directement via le thème en utilisant les suggestions (visibles directement dans le code source de la page quand vous activez le debug de twig.config dans services.yml).

Mais dans le cas où vous développez un module standalone, vous n'avez pas la possibilité de rajouter des template dans le thème. Il serait alors pratique de pouvoir surcharger un template directement via votre module ! C'est donc le sujet que nous allons voir.

Créer le template

Il faut tout d'abord rajouter un thème et un template associé, pour cela on va utiliser le hook_theme :

function mon_module_theme($existing, $type, $theme, $path)
{
    return array(
        'mon_theme_custom' => array(
            'variables' => array(),
            'template' => 'mon-template-custom',
        )
    );
}

Il faut bien faire attention à bien renseigner les variables avec les variables que vous souhaitez utiliser (cf le template de base que vous allez surcharger).

Vous devez créer le template dans un dossier "templates" à la racine de votre module :

/modules/custom/mon_module/templates/mon-template-custom.html.twig

Rajouter la suggestion de template

En suite, il faut indiquer à Drupal que vous souhaitez surcharger un template. Pour cela nous allons utiliser le hook suggestion :

function mon_module_theme_suggestions_alter(array &$suggestions, array $variables, $hook) {
    if(in_array('XXXX', $suggestions)){
        $suggestions[] = 'mon_theme_custom';
    }
}

Afin de savoir quoi mettre à la place de XXXX il vous faut sélectionner un hook qui correspond à votre besoin (à vous de retrouver le hook qui correspond à votre besoin dans la variable $suggestions).

Un vidage de cache plus tard, votre template devrait maintenant s'afficher !

Aller plus loin

Maintenant que votre template s'affiche, vous souhaiteriez peut être y injecter vos variables custom. Il faut tout d'abord bien penser à rajouter les variables que vous allez injecter dans le template dans la définition de votre thème dans le hook_theme.

function mon_module_theme($existing, $type, $theme, $path)
{
    return array(
        'mon_theme_custom' => array(
            'variables' => array('ma_variable' => NULL),
            'template' => 'mon-template-custom',
        )
    );
}

Ensuite il faut injecter la variable via un hook_preprocess_hook :

function mon_module_preprocess_mon_theme_custom(&$variables)
{
// Vous pouvez ici traitez des données, etc ...
    $ma_variable = '...';
    $variables['ma_variable'] = $ma_variable;
}

Maintenant 'ma_variable' est accessible dans votre template !

Vous avez un projet ? Concrétisons vos idées.