TP n°9 - Interface dynamique en Javascript, API, AJAX

Consultez les routes mises en œuvre par api-platform, avec symfony console debug:router.

Vous voyez apparaître différentes routes derrière le chemin _api_/pastes/ correspondant aux opérations CRUD supportées par notre API :

• « get »
• « get collection »
• « post »
• « put »
• « patch »
• « delete »

On va s’intéresser à la consultation de la liste des Pastes de l’application.

Dans l’API de l’application, la collection des entités Paste est disponible sur le chemin d’accès à la ressource /api/pastes via une requête GET.

On peut ainsi utiliser le client curl en ligne de commande, par exemple, pour y accéder sous forme de représentation JSON-LD :

curl -X GET "http://localhost:8000/api/pastes" -H  "accept: application/ld+json"

{
  "@context": "/api/contexts/Paste",
  "@id": "/api/pastes",
  "@type": "hydra:Collection",
  "hydra:totalItems": 2,
  "hydra:member": [
    {
      "@id": "/api/pastes/5",
      "@type": "Paste",
      "id": 5,
      "content": "I am the blue US president",
      "created": "2018-01-01T00:00:00+00:00"
    },
    {
      "@id": "/api/pastes/6",
      "@type": "Paste",
      "id": 6,
      "content": "I am the red US president",
      "created": "2018-01-01T00:00:00+00:00"
    }
  ]
}

JSON-LD est un format d’encodage de données sémantiques basé sur JSON. Il permet d’embarquer des méta-informations permettant d’exploiter les données de façon plus fine qu’un format JSON basique. C’est l’un des formats standards de l’approche Web des données / Web Sémantique, supportant le modèle RDF.

Le format JSON-LD (JSON for Linking Data) est documenté sur https://json-ld.org/.

On peut utiliser cURL en ligne de commande, pour tester l’API, comme dans les exemples de cette section.

Si on ne dispose pas de cURL, on peut aussi utiliser une extension du navigateur générant des requêtes REST.

Mais de façon beaucoup plus pratique, api-platform intègre une interface Web dynamique permettant d’expérimenter avec l’API, basée sur Swagger/OpenAPI. C’est un client codé en JavaScript, directement accessible depuis la page de documentation intégrée dans http://localhost:8000/api/ (bouton « Try it out »).

On peut donc aller bien au-delà de la simple consultation, par exemple pour générer des requêtes CRUD de création de nouveaux Pastes via un POST. Encore un exemple avec le client curl en ligne de commande :

curl -X 'POST' \
  'http://localhost:8000/api/pastes' \
  -H 'accept: application/ld+json' \
  -H 'Content-Type: application/ld+json' \
  -d '{
  "content": "I am the US president",
  "created": "2023-10-23T14:29:33.383Z"
}'

Le code de réponse HTTP sera 201 Created (ce code est spécifiquement fait pour confirmer cette création, et faisant partie des codes dans la gamme 2xx il confirme que ça c’est bien passé).

Par convention, il sera complété par l’en-tête location qui pointera sur la nouvelle ressource créée : location: /api/pastes/13

La réponse transmise par le serveur affichera, au format JSON LD (comme demandé via l’en-tête accept de la requête) :

{
  "@context":"/api/contexts\Paste",
  "@id":"/api/pastes/8",
  "@type":"Paste",
  "id":8,
  "content":"I am the US president",
  "created":"2023-10-23T14:29:33+00:00"
}

Procédez aux étapes suivantes :

1. dans src/Controller/ProjectController.php, modifiez la méthode new() existante, pour ajouter le code bidon suivant.

   Attention à bien placer les différents blocs dans le bon ordre, comme ci-dessous

   use App\Entity\Todo;
   
   //...
   
       #[Route('/new', name: 'app_project_new', methods: ['GET', 'POST'])]
       public function new(Request $request, EntityManagerInterface $entityManager): Response
       {
           // 1) création d'un projet en mémoire
           $project = new Project();
   
           // 2) ajout de sous-entités
           // code bidon - c'est juste fait pour qu'un Project ait des todos
           // sinon, ça ne sert pas à grand chose
           $todo1 = new Todo();
           $todo1->setTitle('todo1');
           $project->getTodos()->add($todo1);
           $todo2 = new Todo();
           $todo2->setTitle('todo2');
           $project->getTodos()->add($todo2);
           // fin du code bidon
   
           // 3) création d'un formulaire d'affichage du projet
           //    et de ses sous-tâches
           $form = $this->createForm(ProjectType::class, $project);
           $form->handleRequest($request);
   
           if ($form->isSubmitted() && $form->isValid()) {
               $entityManager->persist($project);
               $entityManager->flush();
   
               return $this->redirectToRoute('app_project_index', [], Response::HTTP_SEE_OTHER);
           }
   
           return $this->render('project/new.html.twig', [
               'project' => $project,
               'form' => $form,
           ]);
       }
   

   Dès qu’un projet est créé, en support de l’affichage du formulaire de création, il comportera deux sous-tâches de test.

2. modifiez la méthode ProjectType::buildForm (dans src/Form/ProjectType.php) pour gérer l’intégration dans le formulaire de modification d’un projet, de sous-formulaires pour ses sous-tâches.

   Vous devrez peut-être adapter le code ci-dessous :

   use Symfony\Component\Form\Extension\Core\Type\CollectionType;
   //...
       public function buildForm(FormBuilderInterface $builder, array $options)
       {
           $builder
               ->add('title')
               ->add('description')
               ->add('todos', CollectionType::class, [
                   'entry_type' => TodoType::class,
                   'entry_options' => [
                       'label' => false,
                       //'task_is_new' => true,
                       'display_project' => false
                   ]
               ])
               ;
       }
   

   Vous voyez ici comment on intègre un nouvel élément au formulaire, pour gérer la collection des sous-tâches de l’attribut todos des Project.

   Au lieu d’une gestion d’un champ de saisie mono-valuée, comme pour le titre du projet (title), il s’agit ici d’un objet Symfony gérant une collection (CollectionType). Chaque élément de la collection sera géré par un sous-formulaire de type TodoType (il existe déjà, et est utilisé pour la création des tâches).

   Dans entry_options, on passe les options nécessaires à TodoType, dont notre option display_project qui signale que le champ du projet ne doit pas être affiché dans TodoType::buildForm. Selon vos choix d’implémentation des séances précédentes, vous devrez peut-être adapter les valeurs du tableau entry_options (ajout d’une valeur par défaut pour task_is_new, par exemple).

3. Vérifiez que le formulaire de création de nouveau projet s’affiche, et permet d’y voir les deux sous-tâches « bidon ».

Il faut maintenant adapter le code du gabarit associé, pour intégrer la dimension dynamique du formulaire HTML.

Dans le gabarit templates/project/_form.html.twig existant, on va modifier le formulaire de création de nouveau projet pour embarquer des sous-formulaires pour chacune des tâches.

Procédez aux étapes suivantes :

1. Modifiez templates/project/new.html.twig pour ajouter un gabarit de base intermédiaire, qui sera spécifique aux formulaires de création ou de modification des projets, qui pourra intégrer le code Javascript :

   {# Removed: extends 'base.html.twig' #}
   {% extends 'project/project_form_base.html.twig' %}
   
   {% block title %}New Project{% endblock %}
   ...
   

2. Modifiez de même templates/project/edit.html.twig

3. Ajoutez le nouveau gabarit templates/project/project_form_base.html.twig :

   {% extends 'base.html.twig' %}
   
   {% block custompage_script %}
      /* Chargement de JQuery depuis un CDN
         <script
               src="https://code.jquery.com/jquery-3.6.0.js"
               integrity="sha256-H+K7U5CnXl1h5ywQfKtSj8PCmoN9aaq30gDh27Xc0jk="
               crossorigin="anonymous"></script>
        */
      <script>
   
        /* Ici se trouvera le code JQuery nécessaire aux formulaires dynamiques */
   
      </script>
   {% endblock %} {# custompage_script #}
   
   

   Le bloc custompage_script existait dans le gabarit de base base.html.twig, prêt à être surchargé pour l’ajout de code javascript dans les pages de l’application. C’est ce qu’on va faire dans quelques instants.

4. Modifiez le gabarit de formulaire project/_form.html.twig qui est inclus dans les deux gabarits new et edit, afin d’y lister explicitement tous les attributs, du projet, et de ses sous-tâches.

   {{ form_start(form) }}
   
       {{ form_errors(form) }}
   
       <div class="row">
           <div class="col">
               {{ form_row(form.title) }}
               {{ form_row(form.description) }}
           </div>
           <div class="col">
   
               {% dump form.todos %}
   
               <h3>Tasks</h3>
               <ul class="todos">
                    {# form_row(form.todos) #}
                    {# passer en revue chaque todo existante pour afficher ses champs #}
                    {% for todo in form.todos %}
                           <li>{{ form_row(todo) }}</li>
                    {% endfor %}
                </ul>
   
           </div>
       </div>
   
       <button class="btn btn-primary">{{ button_label|default('Save') }}</button>
   
   {{ form_end(form) }}
   

   Cela suppose que le formulaire qui sera transmis à ce gabarit ne contiendra pas uniquement des données du modèle pour le projet, mais aussi pour ses sous-tâches. Cela devrait fonctionner puisqu’on a ajouté des données « bidon » ci-dessus, quand on a modifié ProjectController::new.

5. Testez que l’affichage du formulaire fonctionne bien quand on invoque la page de création d’un nouveau projet. Le formulaire doit afficher les données « bidon » qu’on a ajouté dans la création du formulaire, pour des tâches « todo1 » et « todo2 », via deux jeux de champs de saisie pour ces tâches.
6. Observez dans la barre d’outils Symfony la structure des formulaires transmis, le format des objets Collection gérant les sous-tâches instances de Todo.
7. Observez, avec l’inspecteur des outils de développement du navigateur, la structure des sous-formulaires dans l’arbre DOM.

Il reste maintenant à mettre en place le fonctionnement dynamique du formulaire pour supporter la saisie d’un nombre quelconque de tâches, et non deux sous-tâches « bidons ».

Lisez la section Allowing « new » Tags with the « Prototype » de la documentation Symfony, qui explique le principe de fonctionnement du formulaire dynamique qu’on va mettre en œuvre.

Procédez aux étapes suivantes, en parallèle de votre lecture :

1. Modifiez la méthode ProjectType::buildForm (dans src/Form/ProjectType.php) pour autoriser l’ajout de nouveaux sous-formulaires pour la Collection todos si elle doit s’agrandir dynamiquement. Ajoutez l’option allow_add, pour obtenir ce qui suit :

   public function buildForm(FormBuilderInterface $builder, array $options)
   {
       $builder
           ->add('title')
           ->add('description')
           ->add('todos', CollectionType::class, [
               'entry_type' => TodoType::class,
               'entry_options' => [
                   'label' => false,
                   //'task_is_new' => true,
                   'display_project' => false
               ],
               'allow_add' => true,
               // 'by_reference' => false,
               // 'allow_delete' => true,
           ])
           ;
   }
   

2. Modifiez en parallèle le gabarit project/_form.html.twig pour y ajouter un « prototype » de nouveau formulaire, dont l’objectif sera d’être prêt à être utilisé par du code Javascript.

   Modifiez la balise <ul> de la liste des sous-formulaires.

   Le code Twig doit passer de :

   <h3>Tasks</h3>
   <ul class="todos">
       {# form_row(form.todos) #}
       {# passer en revue chaque todo existante pour afficher ses champs #}
       {% for todo in form.todos %}
   

   à :

   <h3>Tasks</h3>
   <ul class="todos" data-prototype="{{ form_widget(form.todos.vars.prototype)|e('html_attr') }}">
       {# form_row(form.todos) #}
       {# passer en revue chaque todo existante pour afficher ses champs #}
       {% for todo in form.todos %}
   

   On insère ainsi, dans un attribut data-prototype, qu’on place ainsi dans l’en-tête de la liste dans le <ul>, un prototype de formulaire généré par Symfony (form.todos.vars.prototype) du fait de l’option allow_add. On l’encode sous forme d’attribut d’une balise HTML, pour ne pas casser le HTML, avec le filtre Twig e('html_attr').

3. Testez le fonctionnement de l’affichage du formulaire de création de nouveau projet, et vérifiez que le <ul> contenant les tâches contient bien une valeur (assez longue) générée pour l’attribut data-prototype, quand on examine le code HTML dans l’inspecteur des outils du développeur Web.

   Cette valeur est un peu absconse à première vue.

   En fait, elle correspond à une version « prête à l’emploi » d’un code HTML de sous-formulaire, qui contient deux couples champs de saisie et labels, pour les attributs title, completed, etc. des sous-tâches. En voici une version indentée, donc plus lisible :

   <div id="project_todos___name__">
     <div class="mb-3">
       <label for="project_todos___name___title" class="form-label">Title</label>
       <input type="text" id="project_todos___name___title"
              name="project[todos][__name__][title]" maxlength="255"
              class="form-control" />
     </div>
   </div>
   

   Inutile d’en comprendre tous les détails. Le code Javascript fourni ci-dessous saura quoi en faire.

4. Ajoutez enfin un bouton qui servira à déclencher l’ajout d’une nouvelle tâche, juste après la liste à puces <ul>...</ul> :

     {% for todo in form.todos %}
       <li>{{ form_row(todo) }}</li>
     {% endfor %}
   </ul>
   <button type="button" class="add_item_link" data-collection-holder-class="todos">Add a task</button>
   

Maintenant, il ne reste plus qu’à coder le Javascript correspondant.

Procédez aux étapes suivantes :

1. On va modifier le gabarit de base project/project_form_base.html.twig. Dans le bloc custompage_script Twig, dans les balises <script>, on ajoute le code JQuery suivant :

   var $collectionHolder;
   
   jQuery(document).ready(function() {
    // Get the ul that holds the collection of todos
    $collectionHolder = $('ul.todos');
   
    // count the current items in the ul/li we have (e.g. 2), use that as the new
    // index when inserting a new item (e.g. 2)
    $collectionHolder.data('index', $collectionHolder.find('li').length);
   
    $('button.add_item_link').on('click', function(e) {
        // add a new todo form (see next code block)
        addTodoForm($collectionHolder);
    });
   });
   
   function addTodoForm($collectionHolder) {
       // Get the data-prototype explained earlier
       var prototype = $collectionHolder.data('prototype');
   
       // get the new index
       var index = $collectionHolder.data('index');
   
       var newForm = prototype;
       // You need this only if you didn't set 'label' => false in your todos field in ProjectType
       // Replace '__name__label__' in the prototype's HTML to
       // instead be a number based on how many items we have
       // newForm = newForm.replace(/__name__label__/g, index);
   
       // Replace '__name__' in the prototype's HTML to
       // instead be a number based on how many items we have
       newForm = newForm.replace(/__name__/g, index);
   
       // increase the index with one for the next item
       $collectionHolder.data('index', index + 1);
   
       // Display the form in the page in an li, before the "Add a task" link li
       var $newFormLi = $('<li></li>').append(newForm);
       $collectionHolder.append($newFormLi);
   }
   

   Ce code peut sembler un peu compliqué, mais il est en fait relativement simple, pourvu qu’on ait compris le principe de la phase précédente où on a embarqué dans le formulaire HTML l’attribut data-prototype, tel que généré par Symfony.

   addTodoForm() va convertir ce prototype en code HTML, qui sera ajouté dans le DOM du formulaire, pour faire apparaître au bon endroit les sous-champs d’ajout d’une tâche, en remplaçant les identifiants des différentes balises des formulaires, là où le prototype contenait __name__.

   Référez-vous si besoin à la documentation Symfony qui explique bien les détails de ce code.

2. Testez le fonctionnement du bouton « Ajouter une tâche », pour vérifier que l’ajout d’un sous-formulaire est opérationnel. Vérifiez dans le DOM, via l’inspecteur des outils de développement du navigateur, que les sous-formulaires sont ajoutés dynamiquement comme on le souhaite (de la même façon que lorsqu’ils sont déjà présents pour les tâches « bidon »).

Vous avez ici un exemple de la façon dont un réflexe Javascript sait modifier dynamiquement le contenu d’une page, pour changer à la demande le contenu d’un formulaire. La structure du formulaire, préparée à l’avance dans le prototype, généré par le serveur, n’est pas complètement construite par le code Javascript. Le formulaire reste sous un contrôle assez important du code Symfony.

Procédez aux modifications suivantes :

1. Ajoutez dans la classe de formulaire des Projets, une option supplémentaire (allow_delete) permettant d’autoriser la suppression des sous-formulaires :

   public function buildForm(FormBuilderInterface $builder, array $options)
       {
           $builder
               ->add('todos', CollectionType::class, array(
                   ...
                   'allow_delete' => true,
               ));
           ;
       }
   

2. Modifiez le code JQuery correspondant pour ajouter des liens de suppression de sous-formulaires de saisie de tâches, grâce à une nouvelle fonction addTodoFormDeleteLink( ) :

   1. insérez le code correspondant qui modifie tous les <li> des tâches, dans le formulaire existant :

      var $collectionHolder;
      
      jQuery(document).ready(function() {
          // Get the ul that holds the collection of todos
          $collectionHolder = $('ul.todos');
      
          // NEW here :
          //add a delete link to all of the existing task form li elements
          $collectionHolder.find('li').each(function() {
              addTodoFormDeleteLink($(this));
          });
          // END NEW
      
          //...
      

   2. puis ajoutez, presque à la fin de la fonction addTodoForm(), l’appel nouvelle fonction :

      function addTodoForm($collectionHolder, $newLinkLi) {
          //...
      
          // Display the form in the page in an li, before the "Add a task" link li
          var $newFormLi = $('<li></li>').append(newForm);
      
          // NEW here :
          // add a delete link to the new form
          addTodoFormDeleteLink($newFormLi);
          // END NEW
      
          $collectionHolder.append($newFormLi);
      }
      

   3. et enfin, ajoutez la fonction addTodoFormDeleteLink( ) :

      // NEW here :
      function addTodoFormDeleteLink($todoFormLi) {
          var $removeFormButton = $('<button type="button">Delete this task</button>');
          $todoFormLi.append($removeFormButton);
      
          $removeFormButton.on('click', function(e) {
              // remove the li for the todo form
              $todoFormLi.remove();
          });
      }
      // END NEW
      
      

3. Testez le fonctionnement des liens de suppression et leur impact sur le DOM de la page.

Lors des mises à jour des données, à la validation des formulaires de modification des projets, on s’attend à ce que les modifications sur les données des projets soient sauvées, mais aussi les ajouts, modifications ou suppressions des données de leurs tâches, venant des sous-formulaires Todo embarqués dynamiquement dans le formulaire.

Si les formulaires fonctionnent correctement, les méthodes new et edit du contrôleur ProjectController reçoivent les bonnes données, lors des requêtes POST.

Contrôlez que les données transmises dans les formulaires sont cohérentes, après des ajouts ou suppressions de sous-formulaires de Todos :

1. dans le Profiler de la barre d’outils Symfony, vous allez examiner les requêtes POST (antérieures à la redirection, en cas de succès) en remontant dans l’historique des requêtes.
2. les données soumises dans une requête POST sont visibles dans le menu Forms : il doit y avoir le bon nombre de sous formulaires des todos dans la hiérarchie :
   • project
   • title
   • description
   • todos, qui contient bien une collection de tâches :
     • 1
     • 2
     • …
3. si le formulaire a été accepté sans problème, vérifiez les requêtes transmises à la base de données par Doctrine, suite aux traitements du formulaire (valide), dans le menu « Doctrine ».

Si le formulaire fonctionnait correctement, des requêtes INSERT, UPDATE ou DELETE devraient être faites dans la base de données, dans la table todos, pour gérer l’ajout, la modification ou la suppression des sous-tâches des projets.

Or normalement, à ce stade, les données ne sont pas sauvegardées correctement. Seule la table des projets est toujours gérée.

On va corriger le code pour s’assurer de la bonne sauvegarde.

L’ajout d’une sous-tâche devrait afficher une erreur 500 du type « A new entity was found through the relationship ’App\Entity\Project#todos’ that was not configured to cascade persist operations for entity »

Notez que l’erreur se produit dans l’appel à $entityManager->flush();, soit au niveau de la tentative de génération des requêtes à envoyer à la base de données, dans Doctrine.

1. Procédez à l’examen des données des formulaires, comme indiqué ci-dessus. Il doit bien y avoir le bon nombre de sous-tâches dans les sous-formulaires todos.

2. Examinez le message d’erreur complet, qui propose une solution pour remédier au problème.

   L’explication du problème qu’on vient de résoudre est donnée dans la documentation, dans la « bloc » « Doctrine: Cascading Relations and saving the « Inverse » side » de https://symfony.com/doc/current/form/form_collections.html#allowing-new-tags-with-the-prototype.

   Dans la gestion de la soumission du formulaire, le code gérant l’ajout des données des formulaires dans les entités en mémoire est invoqué dans $form->isValid() : cela invoque Project:addTodo() pour chaque sous-formulaire des todos.

   Examinez Project:addTodo(), et remarquez le code :

   if (!$this->todos->contains($todo)) {
       $this->todos->add($todo);
       $todo->setProject($this);
   }
   

   • on ajoute le nouveau todo dans la collection des todos de ce projet,
   • puis on met à jour le pointeur inverse, du Todo vers son Project.

   De nouvelles entités sont donc présentes en mémoire dans App\Entity\Project#todos, comme nous l’indique Doctrine dans le message d’erreur.

   Mais si on examine le code traitant les données du formulaire dans le contrôleur (entre $form->isValid() et l’endoit où se produit l’erreur : $entityManager->flush();), on peut vérifier quelles sont les données qui doivent être sauvegardées, puisqu’elles sont « marquées » comme telles avec l’appel à $entityManager->persist($project);. Seul le projet est marqué.

   Comme indiqué dans la proposition de correction du message d’erreur, soit on devrait écrire une boucle pour appeler persist( ) explicitement pour chaque élément de $project->getTodos(), soit ce persist() doit procéder « en cascade », en parcourant l’arbre des données liées depuis l’instance de $project, ce qui sera fait à condition d’avoir déclaré l’attribut todos de Project avec cascade={"persist"}.

   Ou bien, =. L’annotation est beaucoup plus pratique, dans ce cas. Consultez la documentation doctrine pour plus de détails.

3. Procédez aux modifications suggérées en ajoutant cascade: ['persist'] dans l’attribut Doctrine ORM\OneToMany de Project:todos dans src/Entity/Project.php :

   #[ORM\OneToMany(mappedBy: 'project', targetEntity: Todo::class, cascade: ['persist'])]
   private Collection $todos;
   
   

Vérifiez que cela fonctionne correctement maintenant, en revenant dans le Profiler sur la requête POST, et en examinant les requêtes.

Y a-t-il les INSERT INTO todos attendus ? Cela doit maintenant fonctionner.

Maintenant que l’ajout fonctionne, vérifions la suppression.