Route controllers and views¶
The simplest way to give a page state: declare the controller type on the route. The package
creates one controller per page visit, runs its lifecycle hooks, and disposes it. Views read it
like GetX's GetView<T>. No binding class is needed (but a binding can be added too).
Declaring a controller¶
PlayxRoute<JobDetailsController>(
path: ':id',
controller: (context, state) => JobDetailsController(
jobId: state.intPathParam('id')!,
job: state.extraAs<Job>(), // null on web refresh / deep link
),
disposeController: (controller) => controller.onClose(), // optional
builder: (context, state) => const JobDetailsView(),
)
PlayxShellBranch<T> accepts the same controller / disposeController parameters.
- The factory runs when the page is entered, after every
onInitAppfinished. The controller is stored in the page's scope underTand exists before the first build. disposeControllerruns when the page exits (afteronPageExit).- Two stacked pages of the same route each get their own controller.
Controller lifecycle hooks¶
Mix in PlayxPageLifecycle to react to the page's lifecycle from the controller itself. The onPage*
names do not clash with GetxController's onInit / onReady / onClose.
class JobsController extends GetxController with PlayxPageLifecycle {
@override
Future<void> onPageEnter(GoRouterState state) async => loadFirstPage();
@override
void onPageHidden() => tourController.dismissTour();
@override
void onPageReEnter(GoRouterState? state, bool wasPoppedAndReentered) {
if (pagingController.itemList?.isNotEmpty ?? false) {
tourController.startTour(checkRoute: false);
}
}
@override
void onPageExit() => saveScrollPosition();
}
All hooks may be sync or async. While onPageEnter runs, the page shows its loading state
(Page configuration), so the view only builds once the data is loaded
(unless the route uses waitForBinding: false).
Order¶
For a route with both a binding and a controller:
enter: create controller -> registerController -> binding.onEnter -> onPageEnter -> content builds
hidden: binding.onHidden -> onPageHidden
reEnter: binding.onReEnter -> onPageReEnter
exit: binding.onExit -> onPageExit -> unregisterController -> disposeController
- The controller is created before
binding.onEnter, so the binding can callPlayxScope.of(context).get<T>(). - Callbacks never overlap, and exit waits for a running enter.
- Replace or a path-parameter change disposes the old controller before the new one is created.
- A page behind a deep link gets its controller when it is first shown. Until then it shows its
loading widget, even with
waitForBinding: false. - If the factory or
onPageEnterthrows, the route'serrorBuilderis shown.retrycreates a fresh controller.
PlayxView<T>¶
PlayxView<T> gets the page's controller and passes it to buildView:
class JobsView extends PlayxView<JobsController> {
const JobsView({super.key});
@override
Widget buildView(BuildContext context, JobsController controller) {
return Scaffold(
body: const BuildJobsList(), // a child view in another file
floatingActionButton: FloatingActionButton(onPressed: controller.refresh),
);
}
}
Child widgets in separate files work the same way. Any widget below the page resolves the same page's controller:
class BuildJobsList extends PlayxView<JobsController> {
const BuildJobsList({super.key});
@override
Widget buildView(BuildContext context, JobsController controller) =>
ListView(children: [for (final job in controller.jobs) BuildJobItem(job: job)]);
}
class BuildJobItem extends PlayxView<JobsController> {
const BuildJobItem({super.key, required this.job});
final Job job;
@override
Widget buildView(BuildContext context, JobsController controller) => ListTile(
title: Text(job.title),
trailing: IconButton(
icon: const Icon(Icons.delete),
onPressed: () => controller.delete(job), // closures are safe
),
);
}
Plain widgets can use the context extension:
final controller = context.controller<JobsController>(); // throws a clear StateError if missing
final maybe = context.maybeController<JobsController>(); // null if missing
constconstructors and callbacks are safe: the controller is resolved from the context on every build and passed in. A widget instance never stores it.- A view can ask for a base type:
PlayxView<JobFormController>works on bothPlayxRoute<CreateJobController>andPlayxRoute<EditJobController>. - In a
shellBuilderorinitBuilderthe controller may not exist yet; usemaybeController<T>(). - Dialogs and bottom sheets need
PlayxScopeProvider.
Lookup order¶
- The page's scope: a route controller, or a value a binding stored with
PlayxScope.of(context).put, including values of a subtype. PlayxPageConfig.findController: letsPlayxViewfind controllers a binding registered in an external registry. See GetX and other registries.
So PlayxView also works with plain bindings:
class JobsBinding extends PlayxBinding {
@override
Future<void> onEnter(BuildContext context, GoRouterState state) async {
PlayxScope.of(context).put(JobsController(), dispose: (c) => c.onClose());
}
}
Migrating from GetView<T>¶
| Before (GetX) | After |
|---|---|
class X extends GetView<T> |
class X extends PlayxView<T> |
Widget build(BuildContext context) |
Widget buildView(BuildContext context, T controller) |
body uses controller |
unchanged |
Get.find<T>() in a widget |
context.controller<T>() |
binding Get.put / Get.delete |
PlayxRoute<T>(controller:, disposeController:), or keep the binding |
binding onHidden / onReEnter using Get.find |
PlayxPageLifecycle hooks on the controller, or keep them in the binding |