
# Screens and routes

`@ScreenRoute` makes a widget class a screen, opened at its path. The screen reads its values (path variables, query parameters, an object passed along) from `context.route`, and the generator writes a constant for each screen, so code opens it with `BookPageRoute.to(isbn: ...)` instead of a string.

## Why

An address written as a string in twenty places breaks silently when a path changes. Here the path is declared once, on the screen; the generator writes typed keys and a typed `to(...)`, and a query parameter is converted (and checked) before the screen opens, not in `build`.

## Example

```dart
@ScreenRoute(
  '/catalog/books/{isbn}',
  title: 'Book',
  params: {'page': int},
  extra: BookSummary,
)
class BookPage extends StatelessWidget {
  const BookPage({super.key});

  @override
  Widget build(BuildContext context) {
    final route = context.route;
    final isbn = route.get(BookPageRoute.isbn);        // String
    final page = route.get(BookPageRoute.page) ?? 1;   // int?
    final summary = route.get(BookPageRoute.extra);    // BookSummary?
    return Text('${summary?.title ?? isbn}, page $page');
  }
}
```

## @ScreenRoute

| Argument | Meaning |
|---|---|
| `path` | Spring's path pattern, written in full |
| `title` | The browser tab, the screen reader, the search result. `#{key}` is a message key (`#{book.title}`) |
| `name` | The route's name; the class name in kebab case by default (`BookPage` is `book-page`) |
| `params` | The query parameters the screen reads, with their types. They are converted by the `ConversionService` when the screen opens, so `?page=abc` shows the error screen instead of failing in `build` |
| `extra` | The type of an object passed along, not in the address. It is lost on a reload or a deep link, so it is always optional |
| `shell` | The shell the screen opens in when its path is under none of its branches; usually left out |
| `branch` | The branch the screen opens in, by its path, when its own path is not under it (see [Shells](shells.md)) |
| `transition` | How the screen comes in and goes out: the theme's by default (see [Transitions](transitions.md)) |
| `content` | A Markdown resource, or a folder of them for a path ending in `{*name}` (see [Markdown screens](markdown-screens.md)) |

`@ScreenRoute.notFound()` marks the screen of unknown addresses (see [Filters, guards and errors](filters-and-guards.md)).

## Path patterns

The patterns are the web starter's:

| Pattern | Matches | Value |
|---|---|---|
| `/catalog/books/{isbn}` | one segment | `isbn` |
| `/orders/{id:\d+}` | one segment that matches the regular expression | `id` |
| `/docs/{*path}` | the rest of the address, at the end only | `path`, with its leading `/` (`/core/beans`) |

An address with a `/` at its end (`/docs/beans/`) is the address without it, as static hosts send a folder's address that way.

## @RouteInfo

`@RouteInfo` describes a screen beyond navigation: its search result and link preview, and whether a link from outside opens it. It sits next to `@ScreenRoute`, like springdoc's `@Operation` next to `@GetMapping`.

```dart
@ScreenRoute('/', title: 'NEON Books')
@RouteInfo(description: 'The bookshop of the NEON district.', image: 'resources:images/og.png')
class HomePage extends StatelessWidget { ... }

@ScreenRoute('/checkout')
@RouteInfo(index: false, link: false)
class CheckoutPage extends StatelessWidget { ... }
```

| Argument | Default | Meaning |
|---|---|---|
| `description` | none | The text under the title in a search result and a link preview; `#{key}` is a message key |
| `image` | none | The preview picture (`resources:images/book.png`) |
| `index` | `true` | `false`: search engines may not list the page (`noindex`, not in the sitemap) |
| `paths` | none | Addresses of a screen with path variables, which the build cannot know (`['/catalog/books/978-0']`), for the pages for search engines |
| `link` | `true` | Whether a link from outside the app (a deep link) opens the screen |

## Reading the route: context.route

The widget reads its route from `context.route`, the `RouteTemplate` bound to its own screen (a screen under another one still sees its own values), and rebuilds when its parameters change. In `State.initState`, use `RouteTemplate.read(context)`, which does not rebuild.

| `context.route` | |
|---|---|
| `get(BookPageRoute.isbn)` | A typed value: a path variable, a parameter, the extra object |
| `pathVariable('isbn')`, `param<int>('page')`, `params<String>('tag')`, `extra<T>()` | The same by name |
| `uri`, `pattern`, `name`, `matches('/catalog/**')` | The address and the route |
| `stack`, `branch`, `canPop`, `changes` | The screens under each other, the shell's branch, whether `pop` closes one, a stream of navigations |
| `content` | The Markdown resource of the route, if any |
| `language`, `switchLanguage('ja')` | The current language and a switch (see [Languages](languages.md)) |

Outside widgets, inject the `RouteTemplate` bean: it reads the screen on top.

## Opening a screen

For each screen the generator writes an extension with its constants: `BookPageRoute.pattern`, `BookPageRoute.routeName`, a key per value (`isbn`, `page`, `extra`), and `to(...)` with the values as parameters (path variables required, the rest optional).

```dart
// The app's state becomes this screen, with the screens of its path below.
context.route.go(BookPageRoute.to(isbn: '978-0441013593', page: 2));

// On top, waiting for a result.
final paid = await context.route.push<bool>(CheckoutPageRoute.to());

// Back with a result.
context.route.pop(true);

// The same screen with other parameters (?page=3), without a new screen.
context.route.replaceParams({'page': 3});
```

| Method | Meaning |
|---|---|
| `go(location, {pathVariables, params, extra, transition})` | Makes the location the app's state: its screen with the screens of its path below it, in its shell's branch (the other branches kept) |
| `push<T>(location, {...})` | Opens the location on top and completes with what that screen is popped with, `null` when it is closed otherwise |
| `pop([result])` | Closes the screen on top with a result; `false` when there is nothing to close |
| `replaceParams(params)` | Replaces the query parameters of the screen without opening a new one |

`go` and `push` also take a string: an address (`'/catalog?page=2'`), or a pattern with `pathVariables:`; `params:` and `extra:` add values, and `transition:` replaces the screen's transition for this navigation.

Another address of the same route (`/books/1` to `/books/2`) keeps the screen: its state, its scroll and the shell around it stay, and it rebuilds with the new address and variables.

## Where the app starts

The app starts at the address the platform gives (the browser's bar, a deep link). When it gives none (`/`), `spring.flutter.navigation.initial` names the first screen, and `spring.flutter.navigation.redirects` sends addresses elsewhere:

```yaml
spring:
  flutter:
    navigation:
      initial: /catalog
      redirects:
        "[/home]": /catalog     # a path as a key is written in brackets
```

## See also

- [Shells and tabs](shells.md)
- [Routes in Dart configuration](dart-configuration.md)
- [All properties](properties.md)
- [Path patterns of the web starter](../spring-boot-starter-web/controllers/request-mapping.md)
