88 lines
6.5 KiB
Markdown
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.
|