Scopes¶
Every page with a binding or controller gets a PlayxScope: one per page visit, from onEnter
to onExit. It solves the classic problem of stacked pages (details/1 over details/2, or edit
over create sharing a JobFormController) overwriting or deleting each other's controllers.
It works with any state management (GetX, Bloc, Provider, ChangeNotifier, plain classes).
Getting the scope¶
final scope = PlayxScope.of(context); // throws a StateError if there is none
final maybe = PlayxScope.maybeOf(context); // null outside a page with a binding or controller
context can be the context passed to a binding callback, or any context inside the page's widget
tree. In binding callbacks the same scope is returned in onEnter, onHidden, onReEnter and
onExit. The scope is disposed right after onExit completes.
API¶
| Member | Purpose |
|---|---|
id |
A unique, never reused id for this page visit. Use it as a GetX tag, a family key, ... |
put<T>(value, {dispose}) |
Store an object in the page. dispose(value) runs when the scope ends. |
get<T>() / maybeGet<T>() / has<T>() |
Read it. Exact type first, then the first stored value that is T. |
onDispose(callback) |
Run cleanup after onExit completes (reverse registration order). |
state |
This page's GoRouterState. |
binding |
The binding the scope belongs to. |
pageState, isActive, isDisposed |
This page's lifecycle state. |
binding.currentState is shared by every page using the binding; scope.pageState belongs to one page.
Storing again under the same type replaces the value for lookups; the earlier value's dispose
still runs when the scope ends. Calling put or onDispose after the scope is disposed throws a
StateError. Errors thrown by disposers are reported and the remaining disposers still run.
Patterns¶
Lifecycle methods with the scope id as a tag (GetX)¶
class JobDetailsBinding extends PlayxBinding {
@override
Future<void> onEnter(BuildContext context, GoRouterState state) async {
Get.put(
JobDetailsController(id: state.intPathParam('id')!, job: state.extraAs<Job>()),
tag: PlayxScope.of(context).id,
);
}
@override
Future<void> onHidden(BuildContext context) async =>
Get.find<JobDetailsController>(tag: PlayxScope.of(context).id).pauseUpdates();
@override
Future<void> onReEnter(BuildContext context, GoRouterState? state, bool popped) async =>
Get.find<JobDetailsController>(tag: PlayxScope.of(context).id).resumeUpdates();
@override
Future<void> onExit(BuildContext context) async =>
Get.delete<JobDetailsController>(tag: PlayxScope.of(context).id);
}
// In the page:
final controller = Get.find<JobDetailsController>(tag: PlayxScope.of(context).id);
Cleanup registered in onEnter¶
onExit is optional, so cleanup can be attached where the controller is created:
@override
Future<void> onEnter(BuildContext context, GoRouterState state) async {
final scope = PlayxScope.of(context);
Get.put(JobDetailsController(), tag: scope.id);
scope.onDispose(() => Get.delete<JobDetailsController>(tag: scope.id));
}
Keep the controller in the scope (no global registry)¶
@override
Future<void> onEnter(BuildContext context, GoRouterState state) async {
PlayxScope.of(context).put(
JobDetailsController(id: state.intPathParam('id')!),
dispose: (controller) => controller.onClose(),
);
}
// In the page, in onHidden / onReEnter / onExit, or in widgets:
final controller = PlayxScope.of(context).get<JobDetailsController>();
// or: context.controller<JobDetailsController>()
See Route controllers and views for the declarative version of this.
Shared (unscoped) resources¶
binding.activeScopes lists the pages currently using the binding. A page leaves the list before
its onExit runs, so this only cleans up when no other page needs the resource:
@override
Future<void> onExit(BuildContext context) async {
if (activeScopes.isEmpty) Get.delete<JobsController>();
}
Dialogs and bottom sheets¶
Dialogs and sheets are shown above the page's widget tree. Pass the scope down with
PlayxScopeProvider: