Bindings and lifecycle¶
A PlayxBinding attaches logic to a route. Every page that shows a route with a binding runs the
binding's callbacks at well-defined moments.
class JobsBinding extends PlayxBinding {
@override Future<void> onInitApp() async {} // once, at boot
@override FutureOr<String?> redirect(BuildContext c, GoRouterState s) => null; // before the page is built
@override Future<void> onEnter(BuildContext c, GoRouterState s) async {} // required
@override Future<void> onHidden(BuildContext c) async {}
@override Future<void> onReEnter(BuildContext c, GoRouterState? s, bool popped) async {}
@override Future<void> onExit(BuildContext c) async {}
@override String? breadcrumb(BuildContext c, GoRouterState s) => null; // see Breadcrumbs
}
Only onEnter is required. context is the page's own context. PlayxScope.of(context) returns the
page's scope in every callback, including onExit.
The callbacks¶
| Callback | When | Typical use |
|---|---|---|
onInitApp() |
Once per binding, during boot, before any page enters. | Register repositories, datasources, services. |
redirect(context, state) |
Before the route is built, when it is the destination (not for child routes). Return a location to redirect or null. |
Validate parameters (/jobs/abc). |
onEnter(context, state) |
The page is shown for the first time. | Load data, create controllers. |
onHidden(context) |
Another page covers this one (push, tab switch) but it stays in the stack. | Pause timers, dismiss tours. |
onReEnter(context, state, wasPoppedAndReentered) |
The page becomes visible again after being hidden. | Refresh, resume. |
onExit(context) |
The page is removed from the tree. | Dispose resources. |
wasPoppedAndReentered is true when the pages above it were removed (pop, popUntil,
go to a parent, resetting a branch), and false when it comes back through a branch switch.
Order¶
onExit is always preceded by onHidden unless the page was never entered or is replaced in
place (see below).
Guarantees¶
These hold for every navigation, so bindings can rely on them.
- One lifecycle per page, not per route.
details/1pushed overdetails/2are two pages; the first receivesonHiddenand lateronReEnter. The same applies when a single binding instance is shared by several routes. - Callbacks never overlap. For one page they run strictly in order. Leaving a page while
onEnteris still running queuesonHidden/onExituntil it finishes, so cleanup always runs after setup. - Leaving before entering. On one navigation, every
onHiddenstarts before anyonEnter/onReEnter. onExitfollows the exit animation. When a page is popped, the revealed page getsonReEnterimmediately; the popped page getsonHiddenimmediately andonExitonce it is removed from the tree.onEnterwaits foronInitApp. No page enters before every binding'sonInitAppfinished. If boot fails the page is not entered (it shows the error handling).- Replace and parameter changes start a new lifecycle.
PlayxNavigation.offAndTo(...), or going from/item/1to/item/2, ends the old page's lifecycle (onExitcompletes) before the new page'sonEnterstarts, andonEnterreceives the new parameters. Query-only changes do not restart it. - Deep links and preloaded branches are pending. A page mounted behind the visible page (the
parent of a deep-linked child, or a
preload: trueshell branch) hasPlayxPageState.pending. It receivesonEnter(notonReEnter) when it is first shown. - A failed
onEnteris not entered. If it throws or times out, noonHidden/onReEnter/onExitruns for that page. Nothing is left half-initialized. - Only router navigation counts. Dialogs, bottom sheets and routes pushed with
Navigator.push(outside go_router) do not hide the page underneath.
Shell routes¶
Branch A (Home) <-> Branch B (Products)
1. Enter Home home.onEnter
2. Switch to Products home.onHidden, products.onEnter
3. Switch back products.onHidden, home.onReEnter(popped: false)
Parent -> child (push and pop)
1. Enter list list.onEnter
2. Push details list.onHidden, details.onEnter
3. Pop details details.onHidden, list.onReEnter(popped: true), details.onExit
4. Navigate away list.onHidden, list.onExit
Scenario table¶
Shell with products -> details and favorites -> details branches, plus a top-level
/details/:id route:
| Navigation | Events |
|---|---|
| Products, push details | products.onHidden, details.onEnter |
| Pop details | details.onHidden, products.onReEnter(popped: true), details.onExit |
| Favorites details, switch to the products tab | favDetails.onHidden, products.onReEnter(popped: false) |
| Switch back to favorites | products.onHidden, favDetails.onReEnter(popped: false) |
Push top-level /details/1 from anywhere, then pop |
origin.onHidden, details.onEnter, then details.onHidden, origin.onReEnter(popped: true), details.onExit |
go('/products/details/7') from favorites details |
favDetails.onHidden, details.onEnter (favorites details stays alive in its branch) |
Deep link to /products/details/1, then pop |
details.onEnter, then products.onEnter (not re-enter) |
goBranch(i, initialLocation: true) with details open |
details.onHidden, products.onReEnter(popped: true), details.onExit |
go('/login') (outside the shell) |
onExit once for every page that was entered, in every branch |
Page state¶
binding.currentState (a PlayxPageState?) reflects the page's phase: pending, enter,
reEnter, hidden, exit. It is shared by every page using the binding, so for several live
pages prefer PlayxScope.of(context).pageState.
Sharing a binding between live pages¶
One binding instance can back several pages that are alive at the same time (the same route
stacked, or one instance used for several routes). Each page still gets its own onEnter /
onExit, so one page's onExit can run while another page of that binding is active, and for
different routes the new page's onEnter can run before the old page's onExit. Keep per-page state
in the page's scope, or check binding.activeScopes:
@override
Future<void> onExit(BuildContext context) async {
// activeScopes no longer contains this page here.
if (activeScopes.isEmpty) Get.delete<JobsController>();
}
Binding registry¶
final binding = PlayxNavigation.findBinding<JobsBinding>(); // throws if not found
final maybe = PlayxNavigation.findBindingOrNull<JobsBinding>();
final all = PlayxNavigation.bindings; // unmodifiable
Bindings are collected from the route tree during boot, including nested and shell routes.
Binding redirect¶
redirect validates before the page is built, which is better than navigating away from
onEnter (the page would still be built with missing data):
@override
FutureOr<String?> redirect(BuildContext context, GoRouterState state) =>
state.intPathParam('id') == null ? '/jobs' : null;
It runs after the route's guards and before the route's own redirect, and only when the
binding's own route is the destination. See Guards and redirects.