winzik/docs/ide/fr/tutorial.md

88 lines
7.3 KiB
Markdown

# Tutoriel interactif
L'IDE s'explique lui-même : un **tutoriel interactif** vous fait parcourir ses outils sur un vrai projet Symfony, pas à pas.
Un panneau guide explique chaque étape et une **souris fantôme** (un pointeur supplémentaire dessiné sur l'IDE, jamais votre vrai curseur)
vole jusqu'au bouton, à l'onglet ou à la fenêtre à regarder, l'éclaire et montre où cliquer.
## Le démarrer
- **Aide > Symfony tutorial** ;
- l'écran d'**accueil**, section **Apprendre** : « Apprendre l'IDE avec un projet Symfony » ;
- Search Everywhere (double Maj) : « Symfony tutorial » ;
- le lien en haut de l'[index de la documentation](index.md).
Quand vous créez un **nouveau projet Symfony** (Nouveau projet > Site web > Symfony), l'IDE propose le tutoriel une seule fois, dès son
ouverture : **Démarrer le tutoriel Symfony**, **Plus tard**, ou cochez **Ne plus me le proposer**. Ce choix est le vôtre, pas celui du projet ;
annulez-le dans **Réglages > Proposer le tutoriel Symfony après un nouveau projet Symfony**. Le tutoriel reste de toute façon dans le menu Aide.
Au démarrage, l'IDE demande s'il faut **créer le projet de test** (un squelette Symfony neuf avec les paquets web app, fait dans Docker comme
Nouveau projet, dans votre dossier de projets sous `symfony-tutorial`) ou **utiliser le projet Symfony ouvert**. Un projet de test existant est réutilisé.
## Le panneau
- **Table des matières** : chapitres et étapes, avec une coche sur celles qui sont faites ; cliquez une étape pour y aller.
- Le texte de l'étape : quoi faire, pourquoi, quoi regarder, astuces et raccourcis.
- **Précédent** / **Suivant** (ou `Alt+Maj+Gauche` / `Alt+Maj+Droite`).
- **Fais-le pour moi** : l'IDE réalise l'étape avec ses propres commandes (ouvre la fenêtre, crée le contrôleur...), pour que vous suiviez.
- **Montre-moi** : la souris fantôme rejoue où regarder et cliquer, avec un halo et une pulsation. Rien n'est cliqué pour de vrai.
- Déplacez le panneau par son titre, repliez-le avec la petite flèche, fermez-le avec la croix. **Recommencer le tutoriel** efface la progression.
## Une étape, une action précise
Chaque étape désigne le **vrai contrôle** à utiliser, dans les fenêtres d'outils (le bouton Run du formulaire de la Console, le « + » de la fenêtre
Doctrine, le bouton bleu **Apply** d'un dialogue, « Refresh from the API » du client HTTP...), dit exactement quoi cliquer ou taper et où, pourquoi,
et ce que vous devez voir ensuite. Les longues procédures sont découpées (créer une entité = ouvrir le dialogue, la nommer, ajouter un champ, choisir
son type, voir le changement, appliquer).
- **Montre-moi** commence par **ouvrir** la fenêtre ou le dialogue dont l'étape a besoin, attend que le contrôle soit à l'écran, le fait défiler dans la
vue, puis envoie le fantôme dessus avec un halo et une ondulation de clic. Le contrôle est recherché à nouveau à chaque image pendant que le fantôme
bouge ; le panneau se pousse pour ne jamais le cacher. Si le contrôle est introuvable, le panneau le dit.
- Le tutoriel **vérifie le résultat réel** avant de cocher une étape et d'avancer : le fichier existe (`src/Controller/HomeController.php`,
`src/Entity/Product.php`), la route est déclarée dans le contrôleur (panneau des routes), le fichier de migration est apparu, la vérification de la
base dit que le schéma correspond, la requête HTTP a reçu une réponse 2xx, le champ que vous tapez contient ce qui est demandé.
- Si vous faites autre chose (fermer une fenêtre, en ouvrir une autre), le panneau affiche une note : **appuyez sur Montre-moi**, l'IDE rouvre ce
qu'il faut et le désigne à nouveau. Vous pouvez toujours appuyer sur **Suivant**.
Votre progression est mémorisée **par projet** : fermez l'IDE et revenez, le tutoriel reprend où vous l'aviez laissé.
## Les chapitres
0. La visite de l'IDE : arbre du projet, éditeur, fenêtres d'outils, ré-indexation, Search Everywhere, bouton Doc.
1. Lancer le site ([Lancer](run.md), [Docker](docker.md)).
2. Le **hub Nouveau…** (Alt+N), la [console Symfony](symfony-console.md), un contrôleur ([assistants de commandes](command-wizards.md)), le panneau des routes du contrôleur et la complétion avec import automatique.
3. Templates Twig et [aperçu Twig](twig-preview.md) (« Layout + CSS »).
4. Éditeurs [CSS](css-editor.md) et [Bootstrap](bootstrap.md).
5. Entités [Doctrine](doctrine.md) et diagramme.
6. L'[éditeur .env](dotenv.md) et son constructeur de DSN.
7. La **vérification du schéma** de la base (badge de la barre d'état, bandeau, « Fix everything ») et les migrations.
8. La fenêtre [Database](database.md) : tables, console SQL, constructeur SQL visuel.
9. DQL dans un repository.
10. [Formulaires Symfony](symfony-forms.md).
11. Validation et 12. Sécurité ([validation et sécurité](validation-security.md)).
13. [Événements](symfony-events.md) et [Messenger](messenger.md).
14. Installer [API Platform](api-platform.md) (Nouveau… > Install API Platform), le [client HTTP](http-client.md), l'OpenAPI du site local et « Refresh from the API ».
15. [Tests](tests.md) et couverture.
16. Traductions.
17. [Scripts](scripts.md) et [audit de sécurité](security-audit.md).
18. Pour aller plus loin : la documentation, le [Tableau](board.md), [Git](git.md).
## Langues
Les boutons et titres du panneau sont traduits dans les 14 langues de l'IDE. Les **textes des étapes** existent en anglais et en français :
les autres langues affichent le texte anglais. Les messages du panneau lui-même (contrôle introuvable, comment revenir) existent dans les 14.
## Pour les auteurs d'autres tutoriels
Un tutoriel est une donnée : `ide/ui/js/tutorial/symfony-steps.js` (chapitres, étapes, cibles, ce qu'une étape attend, commandes de
« Fais-le pour moi ») parcourue par le moteur `tour.js`. Les cibles sont des attributs `data-tour="nom"` sur les éléments de l'IDE
**y compris les contrôles à l'intérieur des fenêtres et des dialogues** (`tool-<id>` pour les boutons des fenêtres d'outils ; un bouton de dialogue en
reçoit un avec `tour: 'nom'` dans `dialog({ buttons })`). Une étape peut avoir : `before` (commandes qui ouvrent la fenêtre ou le dialogue quand la
cible n'est pas à l'écran), `ready` (ce qui doit être visible avant que le fantôme bouge), `ghost` (le trajet : `[{ target, click }]`), `back` (que
faire quand l'utilisateur est parti ailleurs) et un `wait` qui vérifie le résultat réel : `{exists: chemin}`, `{check: 'route:<fichier du contrôleur>' |
'migration' | 'schema-ok' | 'http-2xx' | 'visible:<cible>' | 'text:<sélecteur>~<regex>'}`, `{value: {target, match}}` (un champ où l'utilisateur tape),
`{click: cible}`, `{tool}`, `{action}`, `{opened}`, `{saved}`. Les commandes de « Fais-le pour moi » ajoutent `{click: cible}` et
`{fill: {target, value}}`. Un test vérifie que chaque cible, commande, précondition et attente d'un tutoriel existent dans le code de l'IDE.
Pour essayer tout le parcours dans l'IDE réel sur un projet Symfony (une copie du vôtre), sur un écran virtuel :
`games/ide/tools/ui-tour-check.sh <projet> <dossier de sortie> <id d'étape>...` (une capture par étape, avec l'endroit désigné par le fantôme). Les étapes qui
demandent Docker (le site qui tourne, MariaDB, les réponses HTTP d'API Platform) ne sont pas exercées par ce conteneur : essayez-les sur votre ordinateur.