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

@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)
transition How the screen comes in and goes out: the theme's by default (see Transitions)
content A Markdown resource, or a folder of them for a path ending in {*name} (see Markdown screens)

@ScreenRoute.notFound() marks the screen of unknown addresses (see Filters, guards and errors).

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.

@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)

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).

// 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:

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

See also