[Partie 1] - Configuration de Symfony2 et utilisation des templates¶

L’enregistrement du bundle¶

Notre nouveau bundle BloggerBlogBundle a été enregistré dans le noyau (Kernel) situé dans app/AppKernel.php. Symfony2 a besoin que nous enregistrions tous les bundles utilisés par l’application. Bous pourrez également remarquer que certains bundles sont seulement enregistrés dans les environnements dev ou test. Charger ces bundles dans l’environnement de production prod apporterait des calculs supplémentaires pour des fonctionnalités qui ne seraient pas nécessaires. Le code suivant montre comment notre BloggerBlogBundle a été enregistré

// app/AppKernel.php
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
        // ..
            new Blogger\BlogBundle\BloggerBlogBundle(),
        );
        // ..

        return $bundles;
    }

    // ..
}

Les routes¶

Le routage du bundle a été importé dans le principal fichier de routage de l’application, situé dans app/config/routing.yml.

# app/config/routing.yml
BloggerBlogBundle:
    resource: "@BloggerBlogBundle/Resources/config/routing.yml"
    prefix:   /

L’option prefix nous permet d’associer le routage entier du BloggerBlogBundle avec un préfixe. Dans notre cas, nous avons opté pour utiliser le chemin par défaut, qui est /. Si par exemple vous vouliez que toutes les routes soient préfixées par /blogger, vous pouvez changer le préfixe pour prefix: /blogger.

Structure par défaut¶

L’architecture de répertoire par défaut du bundle a été créé dans le répertoirre src. Cela commence par le répertoire Blogger qui est associée à l’espace de nom Blogger dans lequel nous avons crée notre bundle. Dans ce répertoire se trouve le répertoire BlogBundle qui contient le bundle. Le contenu de ce dossier va être détaillé à mesure que nous avancerons dans ce tutoriel. Si vous êtes familier avec l’architecture MVC, certain des noms de répertoires doivent parler d’eux même.

Routage¶

Le fichier de routage du BloggerBlogBundle situé dans src/Blogger/BlogBundle/Resources/config/routing.yml contient les règles de routage par défaut

# src/Blogger/BlogBundle/Resources/config/routing.yml
BloggerBlogBundle_homepage:
    pattern:  /hello/{name}
    defaults: { _controller: BloggerBlogBundle:Default:index }

Le routage est composé d’un motif et de paramètres par défaut. Le motif est comparé à l’URL, les paramètres désignent quel contrôleur exécuter lorsque la route est éligible. Dans le motif /hello/{name}, le substitut {name} va correspondre à n’importe quelle type de valeur car rien de spécifique n’a été précisé. Cette route ne précise également aucune culture, format ou méthode HTTP. Comme aucune méthode HTTP n’est précisée, les requêtes de type GET, POST, PUT ou autre sont éligibiles lors de la comparaison du motif.

Si une adresse valide tous les critères précisés par une route, alors elle sera exécutée par le contrôleur décrit dans l’option _controller. Cette option contient le nom logique du contrôleur qui permet à Symfony2 de l’associer à un fichier spécifique. L’exemple ci-dessus va conduire à l’exécution de l’action index du contrôleur Default situé dans le fichier src/Blogger/BlogBundle/Controller/DefaultController.php.

Le contrôleur¶

Le contrôleur dans cet exemple est très simple. La classe``DefaultController`` étend la classe Controller qui propose des méthodes utiles telles que la méthode render utilisée ci dessous. Comme notre route définit un substitut, il est passé comme argument à notre action sous le nom $name. L’action ne fait rien de plus qu’appeler la méthode render en lui précisant d’utiliser le fichier template index.html.twig situé dans le dossier de vues (Views/) du contrôleur Default de BloggerBlogBundle pour l’affichage. Le format du nom de template est bundle:controlleur:template. Dans notre cas il s’agit de BloggerBlogBundle:Default:index.html.twig, qui associe le template index.html.twig, dans le fichier de vues Default du BloggerBlogBundle, ou physiquement au fichier src/Blogger/BlogBundle/Resources/views/Default/index.html.twig. Un tel format de nommage pour les template permet de référer à des bundles depuis n’importe où dans l’application, ou même dans un autre bundle. Nous verrons cela plus tard dans le chapitre.

Nous passons également la variable $name au template via le paramètre array fourni à la méthode render.

<?php
// src/Blogger/BlogBundle/Controller/DefaultController.php

namespace Blogger\BlogBundle\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;

class DefaultController extends Controller
{
    public function indexAction($name)
    {
        return $this->render('BloggerBlogBundle:Default:index.html.twig', array('name' => $name));
    }
}

Le template (la vue)¶

Comme vous pouvez le voir, le template est très simple. Il affiche Hello, suivi de l’argument name qui a été passé en paramètre par le contrôleur.

{# src/Blogger/BlogBundle/Resources/views/Default/index.html.twig #}
Hello {{ name }}!

Template principal - Niveau 1¶

Commençons par créer le bloc de base du template pour Symblog. Nous avons pour cela besoin de 2 fichiers, le template et son fichier CSS associé. Comme Symfony2 supporte l’HTML5 nous allons également nous en servir.

<!-- app/Resources/views/base.html.twig -->
<!DOCTYPE html>
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html"; charset=utf-8" />
        <title>{% block title %}symblog{% endblock %} - symblog</title>
        <!--[if lt IE 9]>
            <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
        <![endif]-->
        {% block stylesheets %}
            <link href='http://fonts.googleapis.com/css?family=Irish+Grover' rel='stylesheet' type='text/css'>
            <link href='http://fonts.googleapis.com/css?family=La+Belle+Aurore' rel='stylesheet' type='text/css'>
            <link href="{{ asset('css/screen.css') }}" type="text/css" rel="stylesheet" />
        {% endblock %}
        <link rel="shortcut icon" href="{{ asset('favicon.ico') }}" />
    </head>
    <body>

        <section id="wrapper">
            <header id="header">
                <div class="top">
                    {% block navigation %}
                        <nav>
                            <ul class="navigation">
                                <li><a href="#">Home</a></li>
                                <li><a href="#">About</a></li>
                                <li><a href="#">Contact</a></li>
                            </ul>
                        </nav>
                    {% endblock %}
                </div>

                <hgroup>
                    <h2>{% block blog_title %}<a href="#">symblog</a>{% endblock %}</h2>
                    <h3>{% block blog_tagline %}<a href="#">creating a blog in Symfony2</a>{% endblock %}</h3>
                </hgroup>
            </header>

            <section class="main-col">
                {% block body %}{% endblock %}
            </section>
            <aside class="sidebar">
                {% block sidebar %}{% endblock %}
            </aside>

            <div id="footer">
                {% block footer %}
                    Symfony2 blog tutorial - created by <a href="https://github.com/dsyph3r">dsyph3r</a>
                {% endblock %}
            </div>
        </section>

        {% block javascripts %}{% endblock %}
    </body>
</html>

Ce template met en place la structure principale de notre site de blogging. La plupart du fichier est composé de HTML, avec d’étranges commandes Twig. C’est à ces directives Twig que nous allons nous intéresser maintenant.

Commençons pour nous intéresser à la partie HEAD du document. Regardons la balise title:

<title>{% block title %}symblog{% endblock %} - symblog</title>

La première chose que vous aller remarquer est l’étrange tag {%. Ce ni du HTML, ni du PHP non plus. Il s’agit d’un des 3 tags de Twig. Ce tag signifie Fais quelque chose. Il est utilisé pour executer des blocs de code tels que les structures de contrôle, et pour définir des blocs. Une liste complète des structures de contrôle est disponible dans la documentation de Twig. Le bloc Twig que nous avons défini dans le titre fait 2 choses; Il crée un identificateur de block nommé title, et lui fournit une valeur de contenu par défaut entre les directives block et endblock. En définissant un bloc, nous pouvons nous servir du modèle d’héritage de Twig. Par exemple, sur une page qui sert à afficher un article, on peut souhaiter que le titre de la page reflète le titre de l’article. Cela peut être réalisé en étendant le template et en surchargeant le bloc title.

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

{% block title %}The blog title goes here{% endblock %}

Dans l’exemple ci dessus, nous avons étendu le template de base de l’application qui définissait initialement le bloc title. Vous pourrez remarquer que le format de template utilisé dans la directive extends ne contient ni la partie Bundles ni la partie Controlleur que nous avons évoqués précédemment: souvenez vous du format bundle:controller:template. En ne précisant ni le Bundle ni le Controlleur, on spécifie l’usage des templates au niveau de l’application, c’est à dire ceux situés dans app/Resources/views/.

Ensuite nous avons défini un autre bloc de titre et avons mis dedans du contenu, dans le cas présent le titre du blog. Comme le template parent a déjà défini un block title, il est remplacé par le nouveau. Le titre serait désormais ‘The blog title goes here - symblog’. Cette fonctionnalité proposée par Twig va être largement utilisée lors de la création de templates.

Dans le bloc de la feuille de style, nous avons introduit le tag Twig suivant, {{, qui signifie Dis quelque chose.

<link href="{{ asset('css/screen.css') }}" type="text/css" rel="stylesheet" />

Ce tag est utilisé pour afficher la valeur d’une variable ou d’une expression. Dans l’exemple ci-dessus, il affiche la valeur de la fonction asset, qui nous fournit une manière portable de faire le lien avec les fichiers manipulés par l’application, tels que les fichiers CSS, JavaScript et les images.

Le tag {{ peut également être combiné avec des filtres pour manipuler la sortie avant son affichage.

{{ blog.created|date("d-m-Y") }}

Pour une liste complète des filtres, se référer à la documentation de Twig.

Le dernier tag de Twig, que nous n’avons pas vu dans les templates, est le tag de commentaires {#. Son usage est le suivant :

{# The quick brown fox jumps over the lazy dog #}

Il n’y a pas d’autre concept introduit dans ce template. Il fournit la structure principale, prête à être personnalisée selon nos besoins.

Ensuite, il est temps d’ajouter du style. Créez une feuille de style dans web/css/screen.css et ajoutez le contenu suivant. Cela va ajouter du style pour le template principal.

html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,img,ins,kbd,q,s,samp,small,strike,strong,sub,sup,tt,var,b,u,i,center,dl,dt,dd,ol,ul,li,fieldset,form,label,legend,table,caption,tbody,tfoot,thead,tr,th,td,article,aside,canvas,details,embed,figure,figcaption,footer,header,hgroup,menu,nav,output,ruby,section,summary,time,mark,audio,video{border:0;font-size:100%;font:inherit;vertical-align:baseline;margin:0;padding:0}article,aside,details,figcaption,figure,footer,header,hgroup,menu,nav,section{display:block}body{line-height:1}ol,ul{list-style:none}blockquote,q{quotes:none}blockquote:before,blockquote:after,q:before,q:after{content:none}table{border-collapse:collapse;border-spacing:0}

body { line-height: 1;font-family: Arial, Helvetica, sans-serif;font-size: 12px; width: 100%; height: 100%; color: #000; font-size: 14px; }
.clear { clear: both; }

#wrapper { margin: 10px auto; width: 1000px; }
#wrapper a { text-decoration: none; color: #F48A00; }
#wrapper span.highlight { color: #F48A00; }

#header { border-bottom: 1px solid #ccc; margin-bottom: 20px; }
#header .top { border-bottom: 1px solid #ccc; margin-bottom: 10px; }
#header ul.navigation { list-style: none; text-align: right; }
#header .navigation li { display: inline }
#header .navigation li a { display: inline-block; padding: 10px 15px; border-left: 1px solid #ccc; }
#header h2 { font-family: 'Irish Grover', cursive; font-size: 92px; text-align: center; line-height: 110px; }
#header h2 a { color: #000; }
#header h3 { text-align: center; font-family: 'La Belle Aurore', cursive; font-size: 24px; margin-bottom: 20px; font-weight: normal; }

.main-col { width: 700px; display: inline-block; float: left; border-right: 1px solid #ccc; padding: 20px; margin-bottom: 20px; }
.sidebar { width: 239px; padding: 10px; display: inline-block; }

.main-col a { color: #F48A00; }
.main-col h1,
.main-col h2
    { line-height: 1.2em; font-size: 32px; margin-bottom: 10px; font-weight: normal; color: #F48A00; }
.main-col p { line-height: 1.5em; margin-bottom: 20px; }

#footer { border-top: 1px solid #ccc; clear: both; text-align: center; padding: 10px; color: #aaa; }

Template du Bundle - Niveau 2¶

Nous allons maintenant avancer vers la création de la présentation pour le bundle Blog. Créez un fichier dans src/Blogger/BlogBundle/Resources/views/layout.html.twig et ajoutez-y le contenu suivant :

{# src/Blogger/BlogBundle/Resources/views/layout.html.twig #}
{% extends '::base.html.twig' %}

{% block sidebar %}
    Sidebar content
{% endblock %}

A première vue, ce template peut sembler un peu simple, mais sa simplicité est sa force. Tout d’abord, il étend le template de base de l’application que nous avons créé précédemment. Ensuite, il remplace le bloc de la barre latérale avec un contenu factice. Comme la barre latérale va être présente dans toutes les pages de notre blog, il est logique de réaliser la personnalisation à ce niveau là. Vous pourriez demander pourquoi nous ne faisons pas la personnalisation dans le fichier de base de l’application, car il est également présent dans toutes les pages. C’est simple, l’application ne connait rien à propos d’un bundle et cele ne devrait jamais être le cas. Le bundle devrait contenir toutes ses fonctionnalités et afficher la barre latérale fait partie d’une de ces fonctionnalitées. Ok, dans ce cas pourquoi ne plaçons nous pas la barre latérale dans chacune des pages de template ? C’est à nouveau très simple, car il faudrait dupliquer la barre latérale à chaque fois que nous voudrions ajouter une page. Plus loin ce template du second étage va nous donner de la flexibilité pour ajouter de la personnalisation pour des besoins futurs et tous les templates enfants en hériteront. Par exemple, nous pourrions vouloir afficher le pied de page sur toutes les pages, et ce serait l’endroit idéal pour faire ceci.

Template de page - Niveau 3¶

Nous sommes enfin prêt pour la disposition du contrôleur. Ces agencements vont régulièrement être liés à des actions du contrôleur, par exemple l’action show va avoir un template show.

Commençons par créer le contrôleur pour la page d’accueil et son template. Comme c’est la première page que nous allons créer, nous allons avoir besoin de créer le contrôleur. Créez le contrôleur dans src/Blogger/BlogBundle/Controller/PageController.php et ajoutez-y le code suivant:

<?php
// src/Blogger/BlogBundle/Controller/PageController.php

namespace Blogger\BlogBundle\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;

class PageController extends Controller
{
    public function indexAction()
    {
        return $this->render('BloggerBlogBundle:Page:index.html.twig');
    }
}

Maintenant nous allons créer le template pour cette action. Comme vous pouvez le voir dans ce contrôleur Page, nous allons afficher le template index. Créez le template dans src/Blogger/BlogBundle/Resources/views/Page/index.html.twig

{# src/Blogger/BlogBundle/Resources/views/Page/index.html.twig #}
{% extends 'BloggerBlogBundle::layout.html.twig' %}

{% block body %}
    Blog homepage
{% endblock %}

Cela présente le format de template final que nous pouvons spécifier. Dans cet exemple, le template BloggerBlogBundle::layout.html.twig est étendu là où la partie Controlleur du nom du template est omise. En excluant la partie Controlleur, nous précisons l’utilisation au niveau du bundle du template créé dans src/Blogger/BlogBundle/Resources/views/layout.html.twig.

Maintenant ajoutons une route pour notre page d’accueil. Mettez à jour la configuration de routage du bundle situé dans src/Blogger/BlogBundle/Resources/config/routing.yml.

# src/Blogger/BlogBundle/Resources/config/routing.yml
BloggerBlogBundle_homepage:
    pattern:  /
    defaults: { _controller: BloggerBlogBundle:Page:index }
    requirements:
        _method:  GET

Finalement, nous devons supprimer la route par défaut pour l’écran d’accueil de Symfony2. Supprimez la route _welcome en haut du fichier de routage de dev, situé dans le fichier app/config/routing_dev.yml.

Nous sommes désormais prêt à voir notre template pour le blog. Rendez vous avec votre navigateur à l’adresse http://symblog.dev/app_dev.php/.

Vous devriez désormais voir l’agencement de base du blog, avec le contenu principal du blog, et la barre latérale qui reflète lec blocs que nous avons surchargés dans les templates adéquats.