Moteur de template ?

Le moteurs de template sont des programmes permettant de super charger le html de fonctionnalités supplémentaires.

Ce sont des choses que nous pourrions faire directement en php, mais avoir un moteur de template éprouvé qui vient avec tout un tas de fonctionnalités très utile c'est toujours du temps de gagner !

Dans vos controller vous n'êtes pas obligé de renvoyer du html ou le résultat d'un moteur de template, la seule rêgle étant que vous renvoyiez une instance de la classe Response de Symfony

Twig n'est pas le seul moteur de template que vous pouvez installer sur Symfony, mais c'est celui que vous retrouverez dans 99% des projets symfony

Twig

Vous pouvez retrouver la documentation de twig sur le site twig.symfony.com

Installer twig

Pour installer twig, nous allons utiliser une receipe de symfony (Vous pouvez d'ailleurs la retrouver sur le site symfony.sh)

Ouvrez votre terminal, allez dans votre projet et tapez la commande suivante :

composer require twig

Et hop twig est installé !

Par contre, l'installation du paquet a modifié quelques fichiers, allons voir à quoie ça correspond.

Fichier config/bundle.php

Dans ce fichier l'installation a ajouté cette ligne là :

Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],

Qu'est ce que c'est et à quoi ça sert ?

Symfony utilise un systme de plugins qu'ils décrivent comme "Bundles", cest bundles sont fait par symfony, ou des membres de la communautés et permettent d'étendre le fonctionnement du framework.

Pour symfony 4 ces bundles sont principalement installés par les receipes, comme ça a été le cas pour notre moteur de template twig.

Fichier config/packages/twig.yaml

twig:
    paths: ['%kernel.project_dir%/templates']
    debug: '%kernel.debug%'
    strict_variables: '%kernel.debug%'

Ce fichier contient la configuration de twig, d'ailleurs ici, on peut voir que les templates que nous allons utilisé sont dans le chemin /templates au sein de notre projet, nous y reviendrons un peu plus tard.

Pour l'instant ne vous occupez pas des %kernel.qqchose%, ce sont des variables de configuration globales pour le framwork, nous y reviendrons plus tard dans ce cours. (Mais si vous avez un peu de nez, vous aurez compris que %kernel.project_dir% se réfères au dossier racine du projet)

Même si certains fichiers sont crées par des receipes, vous pouvez toujours les modifier, vous pouvez par exemple très bien renommer "templates" en "views" si cela vous enchante (à condition de renommer le dossier template dans votre projet hein)

Utiliser twig dans notre projet

Bon, maintenant que nous avons installé twig, nous allons l'utiliser dans notre controller !

Avant de faire ça, il va falloir changer quelques petites choses.

Tout d'abord, étendons notre controller avec la classe abstract controller

<?php

namespace App\Controller; 

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; // Nouveau use pour importer l'abstract controller

class ExempleController extends AbstractController
{
    /**
    * @Route("/")
    **/
    public function index() {
        return new Response('Hello world !'); 
    }
}

Vous n'êtes pas obligé d'étendre tous vos controllers par des abstract controller, mais ça nous ajoute pas mal de bénéfices plutôt sympa !

Désormais dans notre controller nous allons pour utiliser des méthodes shortcut, pour facilement utiliser twig

Maintenant vous pouvez désormais renvoyer un template :

<?php

namespace App\Controller; 

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; // Nouveau use pour importer l'abstract controller

class ExempleController extends AbstractController
{
    /**
    * @Route("/")
    **/
    public function index() {
        return $this->render('index.html.twig', []);
    }
}

La méthode render prends deux argument :

Le nom du template à utiliser
Un tableau de paramètres à faire passer à la vue

Bien sur vous pouvez avoir des templates qui sont dans des sous dossier, il suffit simplement de le référencer dans la partie template du render, exemple : article/detail.html.twig

Si on l'utilise pour afficher un titre dynamique :

<?php

namespace App\Controller; 

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; // Nouveau use pour importer l'abstract controller

class ExempleController extends AbstractController
{
    /**
    * @Route("/")
    **/
    public function index() {
        return $this->render('index.html.twig', [
            'title' => 'hello world'
        ]);
    }
}

N'essayez pas encore votre route, nous n'avons pas encore créé le template

Allez dans le dossier templates de votre projet (Si vous ne l'avez pas, c'est que vous n'avez pas installer twig)

Créez ensuite un nouveau fichier index.html.twig avec à l'intérieur :

<h1>{{ title }}</h1>

Si vous lancez votre route, une page avec du texte en gros devrait s'afficher. Ici twig a fait son travail et a remplacer la variable title par le titre que nous avons fait passé en paramètre !

Bravo, vous avez intégrer avec succès twig dans votre projet !

Bases de twig

Voilà quelques principes pour vous aider à aborder twig. Rassurez vous, c'est un moteur de template très accessible, si vous en avez déjà utilisé auparavant, vous serez loin d'être perdu !

Afficher des variable

Pour afficher des variable, il suffit de faire comme nous avons fait avec title précédement, en utilisant la synthaxe

{{ variable }}

Vous pouvez donc mettre ça au milieu de n'importe quelle basite HTML et twig s'occupe de l'afficher pour vous !

Utiliser des operateurs logiques

Pour utiliser des operateurs logiques tels que if ou for, vous pouvez utiliser la synthaxe suivante :

{% for item in things %}
    // votre code html
{% endfor %}

{% if item.property is defined %}
    // sera exécuté seulement si le if est considéré comme valide
{% endif %}

La boucle for ci dessus things doit être un tableau, et item sera remplit à chaque itération de la valeur courrante, comme dans une boucle foreach !

Commenter

Vous vous en doutez, les commentaires html ne marcherons pas pour commenter des variables

Vous pouvez donc utiliser la synthaxe suivante :

    {# {% if item.propery is defined %} #} // ne sera pas pris en en compte

Filtres

Autre aspect pratique de twig, les filtres ! Ce sont des choses assez pratiques pour afficher différentes choses de la variables, ou même encore formater / transformer le résultat

exemples :

 <h1>{{ title | length }}</h1> // donnera  la longeur de la chaine de caractère

 <h1>{{ title | upper }}</h1> // Title sera en uppercase

 //... et bien plus encore

Pour voir tous les filtres que propose twig, je vous invite à aller voir sur la documentation de twig (Non réélement faites le, c'est important de savoir ce qui est disponible)

Templates parent enfant

Avec Twig, il est possible de définir des tempates qui utilisent d'autres comme base, ce qui permet de simplifier le template (Pas besoin de mettre la base du html dans tous ses fichiers, on peut avoir le menu directement sur toutes les pages, et ça seulement avec un peu d'extension de templates)

Pour hériter d'un template avec twig, il faut utiliser cette synthaxe :

{% extends 'base.html.twig' %}

Ces éléments sont généralement mis en début du fichier twig, nous devons aussi référencer le nom du template (C'est pas magique non plus hein)

Une fois que vous avez importé le template vous avez accès à tous les blocs du parent !

Blocs

Les blocs sont des éléments où les enfants du template vont pouvoir venir injecter du code html

Ils se forment sous la forme suivante (Pris depuis le fichier base.html.twig, automatiquement ajouté à l'installation de twig):

{% block title %}Welcome!{% endblock %}

Alors qu'est ce que ça fait ?

Ici est déclaré un bloc avec le nom title, celui ci va pouvoir être utilisé par les enfants pour venir override la valeur Welcome! à l'intérieur. Dans le cas où personne n'utilise ce bloc, la valeur définie est choisie par défaut.

OK très bien, mais comment on l'utilise dans un template enfant ?

Très simplement de la même manière !

{% extends 'base.html.twig' %}

{% block title} title from child ! {% endblock %}

vous pouvez mettre des valeur texte, du html, css, js dans ces blocs, il faut juste que cela corersponde à du twig / html valide !

Bien sur ces blocs sont complétement personnalisables, vous pouvez en créer, les modifier, changer leur nom, les déplacer, vous êtes libre de tout 😎

Exemple avec notre template

{# '/template/base.html.twig' #}

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <title>{% block title %}Welcome!{% endblock %}</title>
        {% block stylesheets %}{% endblock %}
    </head>
    <body>
        {% block body %}{% endblock %}
        {% block javascripts %}{% endblock %}
    </body>
</html>

{# '/template/index.html.twig' #}

{% extends 'base.html.twig' %}

{% block title %}Homepage !{% endblock %}

{% block body %}
    <h1>{{ title }}</h1>
{% endblock %}

Et hop, de cette manière là, vous pouvez facilement créer des templates simples et modulaires !

Pour des petites applications ça peut vous sembler peu important, mais tôt ou tard le petit projet devient grand, il est donc important d'avoir les bons réflexes dès le début.

Utiliser les templates modulaires dès le début est un bon réflexe et une bonne habitude à prendre, et vous éviteras de perdre du temps à tout refaire lorsque ce sera necessaire.

Conclustion

Très bien, maintenant que vous êtes des experts twig, nous allons pouvoir passer à la suite !

N'oubliez pas, en cas de doute allez sur la documenation de twig

Twig : Moteur de template de symfony