winzik/docs/ide/tutorial.md

88 lines
6.5 KiB
Markdown

# Interactive tutorial
The IDE teaches itself: an **interactive tutorial** walks you through its tools on a real Symfony project, step by step.
A guide panel explains each step and a **ghost mouse** (an extra pointer drawn over the IDE, never your real cursor) flies to the
button, tab or window to look at, lights it and shows where to click.
## Start it
- **Help > Symfony tutorial**;
- the **Welcome** screen, section **Learn**: "Learn the IDE with a Symfony project";
- Search Everywhere (double Shift): "Symfony tutorial";
- the link at the top of the [documentation's index](index.md).
When you make a **new Symfony project** (New Project > Web site > Symfony) the IDE offers the tutorial once, right after it opens:
**Start the Symfony tutorial**, **Later**, or tick **Don't offer it again**. That choice belongs to you, not to the project; undo it in
**Settings > Offer the Symfony tutorial after a new Symfony project**. The tutorial stays in the Help menu anyway.
Starting it asks whether to **create the test project** (a fresh Symfony skeleton with the web app packages, made in Docker like New
Project, in your projects folder under `symfony-tutorial`) or to **use the open Symfony project**. An existing test project is reused.
## The panel
- **Contents**: chapters and steps with a tick on the done ones; click a step to jump to it.
- The step's text: what to do, why, what to look at, tips and shortcuts.
- **Previous** / **Next** (or `Alt+Shift+Left` / `Alt+Shift+Right`).
- **Do it for me**: the IDE does the step through its own commands (opens the window, creates the controller...), so you can follow.
- **Show me**: the ghost mouse replays where to look and click, with a spotlight and a pulse. Nothing is clicked for real.
- Drag the panel by its title, collapse it with the small arrow, close it with the cross. **Restart the tutorial** forgets the progress.
## One step, one precise action
Every step points at the **real control** you must use, inside the tool windows (the Run button of the Console form, "+" of the Doctrine
window, the blue **Apply** button of a dialog, "Refresh from the API" of the HTTP Client...), says exactly what to click or type and where, why,
and what you should see afterwards. Long procedures are split (create an entity = open the dialog, name it, add a field, choose its type, show
the change, apply).
- **Show me** first **opens** the window or dialog the step needs, waits until the control is on screen, scrolls it into view, then flies the ghost
to it with a spotlight and a click ripple. The control is looked up again at every frame while the ghost moves; the panel steps aside so that it
never hides the control. If the control cannot be found the panel says so.
- The tutorial **verifies the real result** before it ticks a step and moves on: the file exists (`src/Controller/HomeController.php`,
`src/Entity/Product.php`), the route is declared in the controller (the routes panel), the migration file appeared, the database check says the
schema matches, the HTTP request got a 2xx answer, the field you typed contains what was asked.
- If you do something else (close a window, open another one), the panel shows a note: **press Show me**, the IDE reopens what is needed and
points at it again. You can always press **Next**.
Your progress is remembered **per project**: close the IDE and come back, the tutorial resumes where you left.
## The chapters
0. The IDE tour: project tree, editor, tool windows, Re-index, Search Everywhere, the Doc button.
1. Run the site ([Run](run.md), [Docker](docker.md)).
2. The **New… hub** (Alt+N), the [Symfony console](symfony-console.md), a controller ([command wizards](command-wizards.md)), the controller routes panel and
completion with automatic import.
3. Twig templates and the [Twig preview](twig-preview.md) ("Layout + CSS").
4. [CSS](css-editor.md) and [Bootstrap](bootstrap.md) editors.
5. [Doctrine](doctrine.md) entities and the diagram.
6. The [.env editor](dotenv.md) and its DSN builder.
7. The database **schema check** (status bar badge, banner, "Fix everything") and migrations.
8. The [Database](database.md) window: tables, SQL console, visual SQL builder.
9. DQL in a repository.
10. [Symfony forms](symfony-forms.md).
11. Validation and 12. Security ([validation and security](validation-security.md)).
13. [Events](symfony-events.md) and [Messenger](messenger.md).
14. Installing [API Platform](api-platform.md) (New… > Install API Platform), the [HTTP client](http-client.md), OpenAPI of the local site and "Refresh from the API".
15. [Tests](tests.md) and coverage.
16. Translations.
17. [Scripts](scripts.md) and the [Security audit](security-audit.md).
18. Where to go next: the documentation, the [Board](board.md), [Git](git.md).
## Languages
The panel's buttons and titles are translated in the 14 languages of the IDE. The **texts of the steps** exist in English and French:
the other languages show the English text. The panel's own messages (control not found, how to come back) are in all 14.
## For authors of other tutorials
A tutorial is data: `ide/ui/js/tutorial/symfony-steps.js` (chapters, steps, targets, what a step waits for, "Do it for me" commands) walked by
the engine `tour.js`. Targets are `data-tour="name"` attributes on the IDE's elements, **including the controls inside the tool windows and dialogs**
(`tool-<id>` for the tool window buttons; a dialog button gets one with `tour: 'name'` in `dialog({ buttons })`). A step may have:
`before` (commands that open the window or dialog when the target is not on screen), `ready` (what must be visible before the ghost moves),
`ghost` (the route: `[{ target, click }]`), `back` (what to do when the user went elsewhere) and a `wait` that checks the real result:
`{exists: path}`, `{check: 'route:<controller file>' | 'migration' | 'schema-ok' | 'http-2xx' | 'visible:<target>' | 'text:<selector>~<regex>'}`,
`{value: {target, match}}` (a field the user types into), `{click: target}`, `{tool}`, `{action}`, `{opened}`, `{saved}`. "Do it for me" commands add
`{click: target}` and `{fill: {target, value}}`. A test checks that every target, command, precondition and wait of a tutorial exists in the UI code.
To try the whole path in the real IDE on a Symfony project (a copy of yours), on a virtual screen: `games/ide/tools/ui-tour-check.sh <project> <out dir> <step id>...`
(one screenshot per step, with where the ghost points). The steps that need Docker (the running site, MariaDB, API Platform's HTTP answers) are not
exercised by that container: try them on your computer.