Lors de la navigation sur un site web classique, une structure commune se dégage souvent : des éléments comme l’en-tête, le menu ou le pied de page restent constants, tandis que le contenu principal change selon les pages.
Si chaque page utilisait un template distinct contenant ces éléments communs, cela poserait des problèmes de maintenance : une modification dans l’en-tête, par exemple, nécessiterait de modifier tous les templates. Cela va à l’encontre du principe DRY (Don’t Repeat Yourself).
C’est ici qu’interviennent les layouts, ou gabarits, qui permettent de factoriser le code commun en un seul endroit.
Table des matières : [Masquer]
Définition des gabarits
Un layout est un gabarit utilisé comme base pour construire d’autres pages. Il sert de « moule » pour les templates enfants qui peuvent personnaliser ou compléter son contenu.
Par défaut, Symfony propose un layout minimal nommé
base.html.twig, situé dans le répertoire
templates/.
Exemple :
base.html.twig
base.html.twig<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>{% block title %}Welcome!{% endblock %}</title>
{% block stylesheets %}{% endblock %}
{% block javascripts %}
{% block importmap %}{{ importmap('app') }}{% endblock %}
{% endblock %}
</head>
<body>
{% block body %}{% endblock %}
</body>
</html>
Dans cet exemple, plusieurs blocks Twig (comme
title
,
stylesheets
,
javascripts
, et
body
) définissent des zones modifiables. Les blocs permettent aux templates enfants de personnaliser leur contenu tout en réutilisant la structure générale.
Les blocks : zones personnalisables
Les blocks sont des zones définies dans un template, que les templates enfants peuvent redéfinir ou compléter.
Syntaxe pour définir un block :
{% block nom_du_block %}
Contenu du block
{% endblock %}
Exemple minimal :
{% block title %}Page d'accueil{% endblock %}
Les noms des blocks doivent être explicites (par exemple
title
,
body
, etc.), mais ils peuvent être choisis librement.
Héritage de templates avec Twig
Twig prend en charge l’héritage de templates, qui permet aux templates enfants de réutiliser le contenu d’un layout parent tout en apportant leurs propres modifications.
Exemple d’héritage :
Contrôleur :
namespace App\Controller;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;
class DefaultController extends AbstractController
{
#[Route("/")]
public function index(): Response
{
return $this->render('default/index.html.twig');
}
}
Template parent (
base.html.twig
) :
<!DOCTYPE html>
<html>
<head>
<title>{% block title %}Welcome!{% endblock %}</title>
</head>
<body>
{% block body %}{% endblock %}
</body>
</html>
Template enfant (
default/index.html.twig
) :
{% extends 'base.html.twig' %}
{% block body %}
<h1>Bonjour !</h1>
{% endblock %}
Résultat généré :
<!DOCTYPE html>
<html>
<head>
<title>Welcome!</title>
</head>
<body>
<h1>Bonjour !</h1>
</body>
</html>
Ici, le contenu du block
body
dans le template enfant remplace celui du parent.
Combiner contenu parent et enfant
Twig permet aussi de compléter un block défini dans un template parent au lieu de le remplacer entièrement.
Exemple : Compléter le contenu d’un block
Template enfant :
{% extends 'base.html.twig' %}
{% block title %}
{{ parent() }} - Page d'accueil
{% endblock %}
{% block body %}
<h1>Bienvenue sur la page d'accueil</h1>
<p>Contenu supplémentaire ici.</p>
{% endblock %}
Résultat généré :
<!DOCTYPE html>
<html>
<head>
<title>Welcome! - Page d'accueil</title>
</head>
<body>
<h1>Bienvenue sur la page d'accueil</h1>
<p>Contenu supplémentaire ici.</p>
</body>
</html>
L’instruction
{{ parent() }}
insère le contenu original du block
title
avant d’ajouter le texte supplémentaire.
Utilisation avancée : inclusion de JavaScript ou CSS spécifiques
L’héritage de blocks est particulièrement utile pour ajouter des scripts ou des feuilles de styles spécifiques à une page.
Exemple : Ajouter un script spécifique
Template enfant :
{% extends 'base.html.twig' %}
{% block javascripts %}
{{ parent() }}
<script src="/js/custom.js"></script>
{% endblock %}
Organisation et extension des layouts
Symfony permet d’ajouter plusieurs répertoires pour organiser vos layouts. Cette configuration se fait dans le fichier
config/packages/twig.yaml
.
Exemple de configuration :
twig:
paths:
'admin/templates': 'admin'
'frontend/templates': 'frontend'
Les templates dans ces répertoires peuvent être référencés avec des espaces de noms, par exemple :
{% extends '@admin/dashboard.html.twig' %}
Documentation Twig sur les blocks
Documentation officielle Symfony sur Twig
Cheatsheet Twig
Les gabarits de pages et les blocks sont des outils essentiels pour créer des interfaces web modulaires et maintenables. En utilisant les layouts et l’héritage de templates, vous pouvez factoriser le code commun et personnaliser facilement le contenu des pages. Ces techniques, associées à la flexibilité de Twig, vous permettent de construire des sites web robustes et élégants.