TP n° 4 - HTML (et/ou Twig) en autonomie - Début du mini-projet

Table des matières

Objectif de cette séquence

Cette séance vise à découvrir, en autonomie, les langages HTML (et/ou Twig), qui vont nous servir pour la construction des pages des interfaces Web des applications.

Nous allons aussi débuter le mini-projet, pour les étudiants interessés.

Vous poursuivrez cette dévouverte, en autonomie, d’ici les prochaines séances de TP.

Étape 1 : Auto-apprentissage des langages HTML et Twig

Nous allons maintenant passer à l’étude des deux principaux langages qui vont nous servir à fabriquer, du côté du serveur, les pages Web qui seront transmises au navigateur.

Les éléments que vous allez apprendre dans cette séquence ne sont pas toujours très complexes, mais vous seront utiles pour les TP ou le mini-projet.

Consacrez le temps nécessaire à cet apprentissage, qui s’avérera très utile pour la suite.

Étape 1-a : HTML autonomie (1h)

Vous allez commencer par l’apprentissage de HTML, le langage bien connu qui permet au navigateur de présenter les données à l’utilisateur.

À ce stade, l’objectif n’est pas de vous demander d’acquérir une connaissance très détaillée de HTML.

Les étudiants ayant déjà une connaissance minimale d’HTML peuvent passer directement à l’étape suivante.

Vous allez apprendre les rudiments d’HTML afin de pouvoir entamer tout prochainement le travail sur les grandes lignes des pages d’une application Web.

Vous aurez surtout besoin de comprendre les éléments structurant le contenu des pages dans cette première approche.

Très bientôt, vous commencerez en effet votre projet par l’implémentation de pages qui seront assez minimalistes, afin de réaliser un prototype fonctionnel. Puis vous raffinerez les détails du contenu pendant les séances suivantes, quand vous intégrerez plus d’éléments de présentation, une fois que nous aurons abordé CSS, par exemple.

Il n’est donc pas utile d’apprendre tous les détails d’HTML dès maintenant.

En fait, une grande partie des apprentissages d’HTML sont faits d’imitation des solutions trouvées sur d’autre sites, en se référant à la documentation (ou aux spécifications) lorsqu’on souhaite en savoir plus. Et nous n’avons pas l’ambition de faire de vous des experts de Web design non-plus.

Effectuez maintenant le tutoriel en ligne HTML5 Tutorial de W3Schools pendant maximum 1h. Vous pouvez arréter ce tutoriel à la partie sur les « iframe ».

Étape 1-b : Twig en autonomie (45’)

Vous allez maintenant découvrir Twig le langage qui permet de concevoir des gabarits.

La plupart du temps, on ne générera pas des pages HTML directement, mais on s’appuiera sur des gabarits pour ce faire. Twig permet de concevoir des gabarits qui sont des modèles de pages, dans lesquels on pourra injecter des données.

Nous allons étudier Twig plus en détail dans le prochain cours, mais il est utile d’avoir quelques notions sur la syntaxe et le rôle des éléments de base constituant les gabarits.

  1. Consultez la documentation de Symfony, qui décrit l’utilisation des gabarits (templates, en anglais) « Creating and Using Templates ».
  2. Prenez ensuite le temps de lire le début de la documentation TWig pour les concepteurs de gabarits, afin de mieux étayer votre utilisation pratique.

Mini-Projet (optionnel)

Cette section s’adresse aux étudiants intéressés par le mini-projet.

Elle vise à initier les éléments techniques nécessaire au mini-projet, afin de vous guider correctement au démarrage.

Étape proj-1 : Création du projet Symfony d’agence de voyages pour Couettes et cafés

Vous allez commencer le projet, pour mettre en place la base d’une application représentative des fonctionnalités d’un site Web d’e-commerce classique, en partant des spécifications d’un cahier des charges fourni.

Ce site Web correspondra aux besoins fictifs d’une agence de réservation de séjours de courte durée en « couette et café »1 pour des voyageurs, et portera sur trois grands modules fonctionnels :

  • un site public « front-office » destiné aux clients de l’agence. Il comporte les deux premiers modules :
    • celui destiné aux propriétaires (authentifiés) qui souhaitent déposer une annonce de location pour leur couette et café;
    • celui destiné aux clients qui souhaitent faire une réservation parmi les annonces de couette et café disponibles. La « vitrine » publique, des annonces disponible pour des visiteurs anonymes sera un sous-ensemble de ce module, et un sous-ensemble d’autres fonctionnalités deviendra disponibles une fois que ces clients s’authentifieront;
  • une portion du site de type « back-office », réservée au personnel de l’agence, permettant de gérer les réservations, notamment pour la validation des paiements, et tout autres besoins spéciaux en cas de problèmes.

Votre projet sera réalisé en partant d’un squelette d’application Symfony standard, en intégrant petit-à-petit des fonctionnalités correspondant à ce qui sera abordé dans chaque séquence de cours, et en s’inspirant du code de l’application fil-rouge ToDo qui sera fourni en parallèle, en séances de TP.

Le cahier des charges fourni couvre un large spectre fonctionnel. Aussi il ne sera probablement pas réaliste de mettre en œuvre toutes les fonctionnalités indiquées.

Nous allons vous fournir un guide de mise en œuvre permettant de mesurer votre avancement dans le projet, pour que chacun puisse avancer à son rythme, tout en mesurant son pourcentage d’avancement par rapport aux éléments requis pour l’évaluation. Le but n’est pas d’aboutir coûte que coûte à un résultat de qualité professionnelle, mais de pratiquer sur un cas concret au fur et à mesure des apprentissages.

Chaque projet sera original et propre à son/ses auteur(s). Toute tentative de plagiat fera l’objet d’une sanction d’ordre disciplinaire.

Étape proj-1-a : Prise de connaissance du cahier des charges de l’application

  1. Lisez le Cahier des charges de l’application de site Web d’agence de voyage.
  2. Avez-vous bien compris la différence entre les modules du front-office et le back-office de l’application ?

Étape proj-1-b : Initialisation du répertoire de travail du projet

  1. Créez un nouveau répertoire pour y sauvegarder le travail sur votre projet, par exemple dans ~/CSC4101/proj-agvoy/ :

    mkdir $HOME/CSC4101/proj-agvoy/
    

    Si vous prévoyez de travailler en binôme, effectuez cette opération sur un seul des comptes des membres du binôme, pour le travail que vous allez effectuer pendant la durée de cette séance de TP.
    Pour la suite, vous synchroniserez votre travail avec l’autre compte du 2ème membre du binôme, pour assurer que chacun ait une copie de tous les éléments, avant d’entamer le travail hors-présentiel.

  2. À l’intérieur, récupérez une copie du squelette d’application Symfony :
   cd $HOME/CSC4101/proj-agvoy/

# symfony new agvoy-app --version=5.4 --webapp
# symfony composer create-project symfony/skeleton /vagrant/agvoy-app 5.4.*

symfony composer create-project symfony/website-skeleton agvoy-app "5.4.*"

Un projet Symfony est créé dans le répertoire $HOME/CSC4101/proj-agvoy/agvoy-app, dans lequel vous allez travailler pour la suite.

Chargez ensuite le code du projet dans votre IDE.

Étape proj-1-c : Tests de l’application de base

Testez le lancement de l’application avec bin/console server:run comme déjà étudié pour l’application ToDo.

Consultez la page d’accueil fournie, et notez les ressources documentaires proposées, que vous pourrez aller lire d’ici les prochaines séances de TP.

Le module web-server de Symfony permettant de tester avec server:run est installable, comme on l’a vu dans la séance précédente, avec :

symfony composer require symfony/web-server-bundle "^4.4" --dev

Nous vous suggérons de tracer une liste de choses à faire pour le mini-projet, comme de lire ces documentations, et de tenir cette liste à jour, par exemple dans un fichier TODO.txt présent dans le répertoire du code de votre projet.

Notez également, dans ce fichier, les URL des supports de TP, et les n° des étapes auxquelles vous avez rencontré les consignes concernant ces choses à faire.

Pensez à ajouter dans cette liste la documentation Symfony à aller lire, comme indiqué ci-dessus…

Étape proj-1-d : Initialisation du repo Git

Nous vous incitons maintenant à initialiser un référentiel pour le code de votre projet, en utilisant Git, soit en ligne de commande, soit via l’IDE.

Dans un premier temps, un git init suffit, et quelques git add, dans le référentiel Git local au projet.

Cette étape nécessite bien-entendu une connaissance de Git (normalement acquise dans une majorité de projets de première année). Il n’est pas forcément trop tard pour vous y mettre pour de bon, même si cet apprentissage est supposé maîtrisé. Cependant, vous n’êtes pas obligés d’en passer par là, car ce n’est pas un acquis d’apprentissage du présent cours.

Utiliser Git offrira deux aventages principaux :

  • permettre de récupérer un état précédent opérationnel, en cas de fausse manipulations (retour aux commits de la séquence précédente)
  • permettre de collaborer avec un éventuel binôme, et de mesurer la contribution respective de chacun au moment de l’évaluation.

Étape proj-2 : Génération des premières entités du modèle de données

L’objectif de cette étape est de commencer la conception et la mise en œuvre des premières entités du modèle des données.

Vous allez commencer la génération du code PHP qui permettra de gérer, avec Doctrine, les premières entités nécesaires au stockage dans la base de données pour l’application.

Pour commencer, prenez le temps d’analyser le cahier des charges pour déterminer les premières entités sur lesquelles vous allez faire la mise en œuvre des premières pages.

Vous n’aurez pas assez de cette première séquence du projet pour générer toutes les entités du modèle issues du cahier des charges.

Commencez par une analyse large, mais par une réalisation minimale, pour avancer par incréments au long du projet.

La méthodologie que nous vous conseillons d’adopter est :

  1. ajout au modèle de données de quelques entités fortement liées (sans être exhaustif sur leurs propriétés)
  2. ajout de données de test minimales à charger en base de données
  3. réalisation de premières interfaces de consultation de ces données
  4. raffinement des propriétés à gérer pour ces premières entités
  5. itération pour d’autres entités, en ajoutant au fil de l’eau des associations entre entités anciennes et nouvelles

Définition des entités

Vous aurez besoin de nombreuses entités dans le modèle des données de l’application, qui serviront à gérer les différentes fonctions.

L’analyse du cahier des charges devrait vous amener à dégager une liste d’entités suivantes :

Region
une zone géographique dans laquelle l’agence opère. Cela permet de présenter les Couette et Cafés disponibles.
Owner
propriétaire d’une chambre qui souhaite la louer en Couette et Café
Room
Couette et café disponible chez un propriétaire, pour la location, réservable par des clients
UnavailablePeriod
période où les réservations ne sont pas possibles
Client
utilisateur enregistré qui peut réserver des Couette et Cafés
Reservation
Réservation d’un Couette et Café par un client. Elle sera validée en fin de processus par un paiement auprès de l’agence
Comment
appréciation enregistrée par un client en fin de séjour, et publiée sur le site, pour que les futurs clients puissent avoir des infos avant de réserver

Nous vous suggérons de respecter le nommage suggéré ici, afin de faciliter les interactions avec l’équipe enseignante : si chaque projet utilise une nomenclature différente, le travail pour vous aider dans votre projet sera d’autant plus compliqué.

Vous utiliserez les assistants pour générer le modèle pour Doctrine. Avant de vous lancer, précisez bien les attributs que vous souhaitez utiliser.

Propriétés des entités du modèle

Voici une première liste d’attributs mono-valués pour toutes ces entités :

  • Region
    Nom attribut Type Contraintes Commentaire
    name string notnull  
    presentation text nullable on simplifie avec un texte brut
    country string (2 caract.) nullable code du pays si pas à cheval

    Plus tard on pourrait envisager une arborescence de régions, sous-régions, etc. Pour l’instant, pas utile

  • Owner
    Nom attribut Type Contraintes Commentaire
    firstname string nullable  
    familyName string notnull  
    address text nullable on simplifie : du texte au lieu de choses compliquées
    country string (2 caract.) notnull code du pays - cf. CountryType
  • Room
    Nom attribut Type Contraintes Commentaire
    summary      
    description      
    capacity      
    superficy      
    price      
    address      

Associations entre entités

Ensuite il y aura des liens à définir entre entités, résultant en des attributs multi-valués :

  • Owner (1) — (0..n) Room : OneToMany

    un Couette et café n’a qu’un seul propriétaire

  • Room (0..n) — (1..n) Region : ManyToMany

    un Couette et Café peut apparaître dans différentes régions touristiques, au choix du propriétaire

On affinera le modèle ultérieurement, pour couvrir ce qui concerne les clients et leurs réservations, mais il y a déjà du travail pour réaliser les pages de l’application relatives à ces premières entités.

Pour l’instant, il est préférable d’éviter de gérer des attributs complexes comme les dates ou les intervales de dates, qui peuvent présenter quelques difficultés de mise en œuvre.

Plus tard, au fur et à mesure de la construction de l’application, vous ajouterez des fonctionnalités plus avancées et pourrez réutiliser les assistants de génération de code (makers) pour ajouter de nouvelles entités, ou de nouveaux attributs aux entités.

Passez à la mise en œuvre.

Étape proj2-a : Mise en œuvre

Vous allez maintenant pouvoir procéder aux étapes suivantes :

  1. Générer le code PHP des entités avec l’assistant make:entity

    Vous allez déjà pouvoir générer les premières entités avec l’assistant make:entity, y compris pour les relations entre entités, puis tester quelques interactions simples (en lecture seule pour commencer) sur des données de tests.

    Pour mémoire, l’assistant make:entity a été introduit dans le TP n°1 et est documenté dans « Databases and the Doctrine ORM ».

  2. Regénérer la base de données avec Doctrine

    • configurer l’utilisation de la base SQLite
    • créer la base
    • créer le schéma

    On utilise les outils doctrine:database:create, doctrine:schema:create, etc. qui ont également été introduits dans le TP n°1.

Étape proj2-b : Chargement de données de tests

On peut ensuite ajouter du code permettant de charger des données de test avec le module de Fixtures (également introduit dans le premier TP), pour tester que toutes les entités sont gérées, ainsi que leurs associations en base de données.

Pour cela, il faut ajouter le module dans le projet :

composer require --dev orm-fixtures

Ensuite, on écrit le chargement des données comme pour les exemples vus sur ToDo ou Mini-Allociné.

Pour la gestion des associations entre entités, on pourra utiliser des références, telles qu’elles sont documentées dans la documentation du module DoctrineFixturesBundle.

Par exemple, pour l’ajout d’un Couette et café présent dans la région ile-de-france, on peut utiliser :

class AppFixtures extends Fixture
{
    // définit un nom de référence pour une instance de Region
    public const IDF_REGION_REFERENCE = 'idf-region';

    public function load(ObjectManager $manager)
    {
    //...

    $region = new Region();
    $region->setCountry("FR");
    $region->setName("Ile de France");
    $region->setPresentation("La région française capitale");
    $manager->persist($region);

    $manager->flush();
    // Une fois l'instance de Region sauvée en base de données,
    // elle dispose d'un identifiant généré par Doctrine, et peut
    // donc être sauvegardée comme future référence.
    $this->addReference(self::IDF_REGION_REFERENCE, $region);

    // ...

    $room = new Room();
    $room->setSummary("Beau poulailler ancien à Évry");
    $room->setDescription("très joli espace sur paille");
    //$room->addRegion($region);
    // On peut plutôt faire une référence explicite à la référence
    // enregistrée précédamment, ce qui permet d'éviter de se
    // tromper d'instance de Region :
    $room->addRegion($this->getReference(self::IDF_REGION_REFERENCE));     
    $manager->persist($room);

    $manager->flush();

    //...
    }

    //...
}

Une fois que les données sont présentes en base de données, on peut éventuellement ajouter des outils de consultation en ligne de commande, avec make:command (référez-vous encore un fois au TP 1) ou directement via des interfaces Web, tel qu’indiqué ci-dessous.

Étape proj-3 : Création des première pages en consultation

L’objectif de cette étape est d’ajouter les premières vues en consultation des entités qui ont été ajoutées au modèle.

Avant de créer les premières pages de consultation, il est important de réfléchir à la conception du « plan de routage » envisagé pour l’ensemble de l’application.

Conception du routage

Vous n’allez pas pouvoir concevoir, dès maintenant, toutes les routes de l’application, mais il est important d’imaginer assez tôt ce à quoi les routes peuvent ressembler au final.

En effet, on utilisera autant que possible les assistants générateurs de code de Symfony qui vont produire des fichiers automatiquement, et autant éviter si c’est possible des conflits de nommage des répertoires ou des fichiers source générés. Cela facilitera les opérations de renommage éventuellement nécessaires.

Cette section présente quelques éléments qui seront revus ultérieurement quand on avancera dans la réalisation des formulaires et des contrôleurs CRUD.

Lisez cette section, mais ne cherchez pas dès maintenant à ajouter les contrôleurs CRUD. On s’intéresse pour l’instant à des pages en simple consultation. La suite viendra dans quelques semaines, quand nous aurons étudié la théorie derrière les actions en modification, et les formulaires.

  • Routes en consultation pour Room

    Examinons les fonctions de consultation d’un Couette et Café, qu’on va devoir mettre en œuvre. On souhaite distinguer la consultation faite par le propriétaire (qui consulte l’historique, et pointe vers des fonctions de modification), de celle faite par le client, qui verra moins d’informations, et ne peut qu’enregistrer une nouvelle réservation.

    On peut donc souhaiter disposer de plusieurs routes distinctes pour deux fonctions séparées, pour l’entité Room qui gère les Couette et Cafés dans notre modèle de données :

    • public_room_show pour la consultation par les clients
    • room_show pour la version du propriétaire.
  • Routes CRUD pour Room

    Dans l’exemple de nommage des routes de consultation ci-dessus, on a choisi de nommer room_show la version du propriétaire, car cela ressemble à d’autres noms de routes pour les actions CRUD : room_new, room_edit, room_delete souvent utilisées dans les applications Symfony.

    D’ailleurs, nous serons amenés à utiliser dans quelques semaines, un assistant de Symfony qui nous servira à générer facilement le code supportant des opérations de gestion en modification des entités. Cela générera pour nous les nombreux gabarits, et chemins de routes.

    Examinons donc ce qu’on obtiendra au final pour la création, suppression, édition ou suppression des Couette et cafés, qui est destinée à être effectuée par les propriétaires.

    Le contrôleur CRUD généré par l’assistant pour Room génèrera des routes selon le schéma suivant, sans surprise :

    Nom de route Chemin
    room_index /room/list/
    room_new /room/new
    room_show /room/{id}
    room_edit /room/{id}/edit
    room_delete /room/{id}

    Cela s’accompagnera de gabarits Twig stockés dans templates/room/.

  • Renommage des routes CRUD

    On pourrait préférer modifier les chemins, par exemple pour structurer tous les chemins des routes spécifique au propriétaire avec un préfixe commun /owner. Ainsi pour les propriétaires ces routes CRUD pour Room pourraient devenir :

    room_index /owner/room/list/
    room_new /owner/room/new
    room_show /owner/room/{id}
    room_edit /owner/room/{id}/edit
    room_delete /owner/room/{id}

    De façon similaire, pour les régions, on pourra générer un CRUD pour les salariés de l’agence, pour l’entité Region, mais qui soit accessible uniquement pour le backoffice. On en renommera donc les chemins pour les préfixer par /backoffice. Au final cela donnerait :

    region_index /backoffice/region/list/
    region_new /backoffice/region/new
    region_show /backoffice/region/{id}
    region_edit /backoffice/region/{id}/edit
    region_delete /backoffice/region/{id}

    Attention cependant : de tels renommage sont parfois longs et fastidieux à opérer (Eclipse peut nous y aider, mais c’est souvent source d’erreurs). Malheureusement, les générateurs Symfony ne permettent pas de « customiser » les noms de routes ou les préfixes de chemins…

    Dans tous les cas, mieux vaut avoir un peu anticipé à l’avance pour éviter des renommages chaotiques ultérieurs.

    Ces éléments étant posés, on peut passer à la génération des premières pages, au bon endroit dans notre plan de routage.

Étape 4-a : Génération des pages en consultation

Après ces considérations, passons maintenant à la pratique.

Vous allez générer le code la consultation des premières entités, comme par exemple :

  • la consultation d’une liste d’annonces de Couette et cafés présents dans une région donnée;
  • la consultation d’une annonce d’un Couette et Café particulier.

Nous vous incitons à utiliser pour cela make:controller, comme cela a été vu dans la séance de TP n°3.

Une fois le code généré, vous travaillerez sur le contenu des pages, dans les premiers gabarits Twig.

Vous pourrez mettre ainsi en place, pour chaque module du site, une structure de pages standard, donc des gabarits Twig de base.

Inspirez-vous de ce qui est fait pour l’application fil-rouge ToDo.

Auto-évaluation

À l’issue de cette séquence de travaux pratiques, vous avez des connaissances minimales des langages HTML et TWIG.

Vous pouvez commencer à programmer des pages HTML simples.

Vous savez programmer des algorithmes simples pour intégrer des données dans des modèles de pages, via les gabarits Twig.

Pour le projet, vous avez initié le répertoire de votre projet, et avez commencé à noter la liste de choses à faire dans le fichier TODO.txt, en relation avec les étapes de ce support de TP.

Ensuite

Vous poursuivrez le travail entrepris, dans cette séance.

pour les étudiants choisssant de ne pas faire le mini-projet
vous poursuivez l’étude de Twig en autonomie pendant 1h d’ici la prochaine séance de TP
pour les étudiants choissant de faire le mini-projet
vous poursuivez les étapes indiquées (en les traçant dans votre TODO.txt) pour avancer dans le projet, pendant encore 2h30, environs, en travail autonome.

Notes de bas de page:

1

chambre d’hôtes, en anglais bed and breakfast

Auteur: Olivier Berger (TSP)

Created: 2022-08-25 Thu 08:41

Validate