Sylius V2 - Personnalisation des templates avec Twig Hooks

Sylius V2 apporte des améliorations significatives dans la personnalisation des templates, en particulier grâce à l'utilisation des Twig Hooks. Cette fonctionnalité permet aux développeurs de personnaliser facilement l'interface utilisateur d'un site e-commerce sans modifier directement les fichiers de base du système. Grâce à cette approche, la personnalisation devient plus simple, plus flexible et mieux adaptée aux mises à jour de Sylius.

Pourquoi utiliser les Twig Hooks ?

Les Twig Hooks offrent une méthode puissante et modulaire pour personnaliser l’apparence de votre site. En injectant des blocs de contenu à des points d'extension définis, vous pouvez modifier ou ajouter des éléments à l'interface sans toucher au code de base. Cela vous permet de :

• Éviter la duplication de code : Pas besoin de réécrire des templates entiers pour une simple modification.
• Maintenir une structure propre et modulaire : Le code reste facile à maintenir et évolutif.
• Assurer la compatibilité avec les mises à jour : En utilisant des hooks, vous pouvez personnaliser votre interface sans risquer de perdre vos modifications lors des mises à jour de Sylius.

Qu'est-ce qu'un Twig Hook ?

Un Twig Hook est un point d'insertion défini dans un template, permettant d'ajouter ou de modifier dynamiquement des parties de contenu sans affecter le reste du fichier. Cette fonctionnalité est idéale pour insérer du contenu personnalisé tout en maintenant une séparation claire entre le code de base de l'application et les personnalisations.

Structure des Twig Hooks

Les Twig Hooks fonctionnent de manière modulaire, chaque hook pouvant contenir plusieurs hookables. Un hook représente un emplacement où du contenu peut être injecté, tandis qu’un hookable est le contenu que vous souhaitez insérer.

Exemple de code Twig avec un Hook

Voici un exemple de template où un hook est utilisé pour insérer un logo personnalisé dans l'en-tête du site :

    < !-- Template content -->
    < div id="header">
{% hook 'header.logo' %}
    < /div>
    < !-- Additional content -->

Ici, le hook header.logo permet d'ajouter ou de personnaliser le logo dans l'en-tête sans modifier directement les fichiers sources de Sylius.

Configurer les Twig Hooks

Une fois que vous avez identifié le hook à personnaliser, vous devez ajouter une configuration dans le fichier sylius_twig_hooks.yaml. Par exemple, pour personnaliser le logo, vous pouvez créer un fichier de configuration dans config/packages/sylius_twig_hooks.yaml comme suit :

sylius_twig_hooks:
    hooks:
'header.logo':
    'custom_logo':
template: 'shop/custom_logo.html.twig'

Cette configuration indique à Sylius de rendre le template custom_logo.html.twig chaque fois que le hook header.logo est invoqué.

Personnalisation d'un élément spécifique : Exemple du logo

Étape 1 : Identifier le template d'origine

Le fichier original pour le logo est généralement situé à cet emplacement :

/sylius/sylius/src/Sylius/Bundle/ShopBundle/Resources/views/Layout/Header/_logo.html.twig

Plutôt que de modifier ce fichier directement, vous allez définir un Twig Hook qui vous permettra d'ajouter votre propre contenu.

Étape 2 : Créer un template personnalisé

Créez un fichier de template dans le répertoire templates de votre projet. Par exemple, pour personnaliser le logo, placez votre fichier à l'emplacement suivant :

templates/bundles/SyliusShopBundle/Layout/Header/_logo.html.twig

Dans ce fichier, vous pouvez insérer votre propre code HTML pour le logo ou même du contenu dynamique, selon vos besoins.

Étape 3 : Ajouter la configuration des Hooks

Ensuite, dans votre fichier config/packages/sylius_twig_hooks.yaml, ajoutez une entrée pour le hook de logo :

sylius_twig_hooks:
    hooks:
'header.logo':
    'custom_logo':
template: 'bundles/SyliusShopBundle/Layout/Header/_logo.html.twig'

Cette configuration permet de remplacer le logo par le contenu personnalisé défini dans votre fichier templates/bundles/SyliusShopBundle/Layout/Header/_logo.html.twig.

Avantages des Twig Hooks dans Sylius V2

• Modularité et Réutilisabilité : Les Twig Hooks permettent de définir des points d'extension réutilisables dans toute l'application. Cela facilite la gestion du code et la réutilisation des éléments à différents endroits de votre site.
• Séparation des Responsabilités : Vous pouvez personnaliser l’apparence sans toucher à la logique métier sous-jacente. Cela rend le code plus clair, mieux structuré et plus facile à maintenir.
• Simplicité lors des Mises à Jour : En utilisant les Twig Hooks, vous évitez de modifier directement les fichiers de base de Sylius. Ainsi, lors des mises à jour du framework, vous pouvez facilement intégrer les nouvelles versions sans risquer de perdre vos personnalisations.
• Facilité de Personnalisation : Les Twig Hooks sont très faciles à mettre en place. Vous n’avez pas besoin de connaissances approfondies sur la structure du code de Sylius. Il vous suffit d’identifier le hook approprié et d'ajouter ou de modifier le contenu souhaité.

Exemple visuel de personnalisation avec Twig Hooks

1. Identifier le Hook

Pour personnaliser un élément comme le logo, vous pouvez utiliser l'outil de développement du navigateur pour repérer l'élément HTML correspondant. Par exemple, cliquez sur le logo et identifiez l'emplacement du code dans le DOM. Cela vous permettra de savoir quel hook utiliser pour personnaliser cet élément.

2. Configurer le Hook

Une fois que vous avez identifié le hook, créez le fichier de configuration dans sylius_twig_hooks.yaml. Par exemple, pour modifier le logo, vous pouvez utiliser la configuration suivante :

sylius_twig_hooks:
    hooks:
'header.logo':
    'custom_logo':
template: 'bundles/SyliusShopBundle/Layout/Header/_logo.html.twig'

Cela vous permet de remplacer le logo dans l’en-tête par votre version personnalisée sans affecter les fichiers d’origine de Sylius.

La personnalisation des templates dans Sylius V2 via les Twig Hooks offre une méthode flexible, propre et modulaire pour ajuster l’apparence de votre site e-commerce. En permettant aux développeurs d'injecter du contenu dans des points d'extension définis, cette fonctionnalité simplifie la personnalisation et assure une gestion facilitée des mises à jour. Que vous souhaitiez personnaliser un logo, un texte, ou d'autres éléments de l'interface utilisateur, les Twig Hooks offrent une solution idéale pour ajouter du contenu sans risquer de perturber la structure de base du site.