Skip to content

Web

Web apps differ from mobile in ways that affect navigation: pages can be opened directly by URL, the user can refresh at any time, and the browser has its own back and forward buttons. Playx Navigation has features for each.

Setup

Call this before runApp for path URLs (no #) and so that push is reflected in the browser URL:

void main() {
  PlayxNavigation.setupWeb();            // usePathUrlStrategy: true, optionURLReflectsImperativeAPIs: true
  runApp(const MyApp());
}

It does nothing outside the web.

extra does not survive a refresh

state.extra is not part of the URL. After a refresh, a typed or shared URL, or a deep link, it is null. Treat it as an optional shortcut and load by id when it is missing.

class JobDetailsController with PlayxPageLifecycle {
  JobDetailsController({required this.id, Job? job}) : job = Rxn(job);
  final int id;
  final Rxn<Job> job;

  @override
  Future<void> onPageEnter(GoRouterState state) async {
    job.value ??= await repository.getJob(id);
  }
}

controller: (context, state) => JobDetailsController(
  id: state.intPathParam('id')!,
  job: state.extraAs<Job>(),     // typed, never throws, null when missing
),

state.extraAs<T>(), state.intPathParam(name) and state.intQueryParam(name) never throw. To keep extra across browser back and forward, give GoRouter an extraCodec.

Validate ids before the page is built with a binding's redirect so a bad URL never builds a half-empty page.

Back to the parent

After a refresh or deep link there may be nothing to pop, so Flutter's automatic AppBar back button is missing. PlayxNavigation.back() pops when it can and otherwise goes to the page's parent: from a job's details to the jobs list, even when the details page was opened directly.

The parent is found in this order:

  1. The route's parentLocation, if it returns a value.
  2. The nearest shorter path that matches a route: /jobs/5/edit -> /jobs/5 -> /jobs.

The automatic parent never falls back to /, so tab roots such as /jobs have no parent unless you set one.

// Nested or path-shaped routes need nothing extra:
PlayxRoute(path: '/jobs', builder: ..., routes: [
  PlayxRoute(path: ':id', builder: ...),          // /jobs/5 -> back -> /jobs
]),

// When the path doesn't contain the parent, say where to go:
PlayxRoute(
  path: '/job/:id',
  parentLocation: (state) => '/jobs',
  builder: ...,
),
PlayxRoute(
  path: '/edit-job/:id',
  parentLocation: (state) => '/jobs/${state.pathParameters['id']}',
  builder: ...,
),

PlayxBackButton

AppBar(
  leading: PlayxNavigation.canGoBack ? const PlayxBackButton() : null,
  title: const Text('Job details'),
)

PlayxBackButton calls back(). It renders nothing when canGoBack is false, and accepts onPressed (called first, e.g. to save a draft) and color.

API Purpose
PlayxNavigation.back() Pop, or go to the parent. Returns false if neither is possible.
PlayxNavigation.canGoBack Whether back() can do something.
PlayxNavigation.parentLocation The location back() goes to when there is nothing to pop.
PlayxNavigation.popOrGo(location) Pop, or go to a specific fallback.
PlayxNavigation.popUntil(location, orGo: true) Pop back to a page, or go there if it isn't in the stack.

popUntil

Return to a page deeper in history, for example back to the jobs list after a create flow:

PlayxNavigation.popUntil('/jobs');                  // false if '/jobs' isn't in the stack
PlayxNavigation.popUntil('/jobs', orGo: true);      // goes to '/jobs' if it isn't
PlayxNavigation.popUntilNamed('jobs', orGo: true);

Pages above the target receive onHidden / onExit and the target receives onReEnter. Details in the navigation API.

Browser back and forward

The browser's buttons behave like pop and push: the page that was left gets onExit, the page revealed gets onReEnter, and going forward creates a new page with onEnter.

Refresh

A refresh restarts the app: onInitApp runs again, and the pages for the URL behave like a deep link. Only the visible page enters; pages behind it are pending until they are shown. Controllers and extra from before the refresh are gone, so rebuild state from the URL.

Browser tab titles

PlayxNavigationBuilder(pageTitle: PlayxPageTitle(...)) keeps the tab title in sync with the current page, using the labels you declared for breadcrumbs. See Breadcrumbs and page titles.

Breadcrumbs are derived from the route tree, so they are correct after a refresh or a deep link. See Breadcrumbs and page titles.