Guards of routes
A guard keeps the user from screens of the app until something holds. There are two kinds:
- A gate keeps the user from the whole app, such as an onboarding that the user has to finish first, terms to accept, or a sign-in in an app that nobody uses without an account. The built-in gates are that of
onboardingandsign_in.gateofsign_in. - A guard that stands for a condition keeps the user only from the routes that ask for the condition, such as the screens that need an account. The built-in one is
sign_in.hasAccount. Conditions of routes describes it.
A module declares a guard as data of the router role, next to its routes. Whichever module provides the router then asks the guards of every module the same way, and the other modules of the app know nothing of them.
A gate over the whole app
A module declares a guard as a RouteGuard of smf_contracts:
| Part of a guard | What it is |
|---|---|
name | The name of the guard in its module. The full name is <module id>.<name>, such as terms.accepted. |
allows | A function of the app that returns a ValueListenable<bool>: whether the guard allows, which notifies its listeners when that changes. |
redirectTo | The target of the guard: a route of the module, which the router shows while the guard does not allow. |
stage | When the app asks the guard among the guards of its kind: GuardStage.welcome or GuardStage.identity. Every guard has one. See the order of the guards. |
resumes | Whether the router brings the user back to where they were once the guard allows again. It is true unless the guard says otherwise. See where the user comes back to. |
condition | The condition that the guard stands for. A guard without one is a gate. |
The target and the routes below it are the flow of the guard, the screens that the user may see while the guard does not allow. While a gate does not allow, the router shows the target in place of every location outside the flow, of whichever module.
The target is a top-level route of the module that needs no values and is outside the main navigation, which a gate keeps the user out of. No route of the flow can start the app, and none of them asks for a condition.
The app calls the function of a guard once, when its router first asks the guards, which is after bootstrap(). From then on it reads the value whenever it asks. So the value is known without waiting: a guard that depends on something saved on the device takes it in bootstrap(), as a restorer of the preferences does. The value changes outside the build of a frame, such as in the handler of a tap, because the router navigates when it changes.
What the user sees
A feature terms keeps the user at /terms until the terms are accepted. The app starts on /home:
The screen of the flow only changes what the guard reads. It navigates nowhere: the router leaves the flow.
The flow is closed
The routes of a flow show only while a guard with that flow does not allow. The flow is over once the guard allows, and every other guard of the module with the same target allows too. From then on the router shows the screen that the app starts on in place of each location of the flow, whether go(), push(), replace() or the platform asks for it. Such a push() completes with null. While another gate does not allow, the router shows the target of that gate instead.
So no code navigates into the flow of a gate, and that includes the module of the guard: it changes what the guard reads, and the router shows the target. A link to /onboarding in an app whose onboarding is finished opens the screen that the app starts on.
A guard that stands for a condition is the exception. While it does not allow and every gate does, the routes of its flow show like any route, so a screen may open its target, and a link to one of them opens it over the screen that the app starts on; see the flow of such a guard.
The order of the guards
The app asks its gates first, and then its guards that stand for a condition. It asks the guards of each kind by their stage, then in the order of the modules, then as their module declares them.
| Stage | What it is for |
|---|---|
GuardStage.welcome | What a new user goes through on the first launch, before the app asks who the user is, such as an onboarding. |
GuardStage.identity | What asks who the user is, such as a sign-in. |
The app asks the guards of an earlier stage first, whatever the order of the modules. The guard of onboarding has the stage welcome, and the two guards of sign_in the stage identity. So the onboarding comes before the sign-in, whichever of the two modules was named first, and neither module names the other to place its guard.
The first gate that does not allow decides, for every route, and no later guard is asked. That is why the flows of the gates show one after another. Only when every gate allows does the app ask the guards that stand for a condition.
A module cannot add a stage. A guard that is neither of the two takes the stage that its flow belongs to: welcome if the flow needs to know nothing of the user, as that of a consent or of a required update, and identity if it needs to know who the user is, as that of a subscription. The order of the modules then places it among the guards of that stage. So the app may ask such a guard before the guard that asks who the user is, and it allows while it cannot tell who the user is.
In the app, the stage shows only in the order of routeGuards.
What every router does
Before it shows a location, a router asks the guards about it. That holds for the location the app starts on, for each location that go(), push() or replace() is asked to show, and for each location that the platform gives the router.
| The location | What the router does |
|---|---|
| A gate keeps the user from it. | It shows the target of the gate in its place, as go() to the target does. The target takes the whole stack, and the stacks of every branch of the main navigation. Such a push() completes with null at once. |
| It is in a flow that is over. | It shows the screen that the app starts on in place of the stack. Such a push() completes with null at once. |
| It asks for a condition that does not hold. | It opens the target of the guard of that condition over the page that the user is on, and the request waits; see Conditions of routes. |
| It is a page of the flow of a guard that stands for a condition, and a link asks for it, with no page of the app below it. | It opens that page over the screen that the app starts on, so that back leads into the app; see the flow of the guard. |
In the first two cases the router never builds the screen of the location that was asked for, and the listeners of the screen never hear of it. In the third it shows that screen once the condition holds.
When a guard starts or stops allowing, the router tells the role of the pages that the user can get back to, and does what the role answers. It shows a location in place of its whole stack, closes the pages on top that have to leave, or leaves everything as it is.
The target of a gate takes the pages of every branch of the main navigation, since a gate keeps the user from those pages. That holds whenever the gate allows again: also in the turn in which it stopped allowing, as when code signs one user out and the next one in, and while the transition to its target is on its way. Each branch is then back on its destination.
Where the user comes back to
The role remembers one location for the user to come back to, and it remembers one only for a gate:
| What happened | What the role remembers | Where the user lands once the gates allow |
|---|---|---|
| The user or the platform asked for a location that a gate kept them from. | That location. A later one replaces an earlier one, so a link that arrives while the flow is shown wins. | The remembered location. |
| A gate that brings the user back stopped allowing while the user was in the app, and nothing was remembered yet. | The location below the pages that pushes showed, such as the tab that those pages were opened from. When pushes showed every page, the screen that the app starts on. | The remembered location. |
| A guard that does not bring the user back stopped allowing. | Nothing. It also forgets what it remembered, for whichever gate. | A location that was asked for since then, or else the screen that the app starts on. |
| A gate started allowing with nothing remembered, as in an app that the platform opened on a location of the flow. | Nothing. | The screen that the app starts on. |
The role never remembers a location in the flow of a guard: once that guard allows, its flow is over. Once the router has shown the remembered location, the role forgets it. It also forgets it when the user moves on, which is when the router asks about a location that no gate keeps the user from and that is outside every flow, or in one that is over.
A guard brings the user back unless it says otherwise, with resumes: false. The guard of the onboarding brings the user back: a user who asked to see the onboarding again comes back to the screen they were on. The guards of sign_in say otherwise. After a sign-out, the next user comes neither to the screen that the last one was on nor to a link that the last one followed. A location that is asked for after such a guard stopped, while it does not allow, is still remembered, so the user comes to a link that arrives then.
The role looks at the guards each time the router asks about a location or tells it that a guard notified. It takes a guard to have stopped when the guard does not allow and allowed at the look before. So a guard that does not allow from the first launch has not stopped, and the location that the app is opened with is shown after the flows of a first launch. A guard that stops and allows again between two looks, such as one that does not notify, is not seen to stop, and the role forgets nothing then.
What a screen does
A screen never closes itself, and never navigates, after it changed what a guard reads. The router has done both by then.
That goes for a screen of a flow that made its guard allow, as after a sign-in. It also goes for a page that asks for a condition and ends it itself, as a screen of an account does with its sign-out.
A pop() after the change closes the page that is on top by then. After a sign-in that is the page that the user asked for, and a push() that waited for it completes with null. After a sign-out it is the page below the one that the router closed, which may be the main navigation of the app. A go() after the change takes the place of what the router showed.
What the role generates
In an app whose modules declare guards, the template of the router role adds to lib/core/router/app_router.dart:
routeGuards | The guards of the app, in the order the app asks them. Each is a RouteGuard of the app, a class that the role generates into that file. It is not the class of smf_contracts with the same name, with which a module declares the guard. |
redirectOf(routeName) | The location that the guards show when the router is asked for a route, or null when they let the user see it. |
flowIsOver(routeName) | Whether the route is in the flow of a guard and every guard with that flow allows. |
guardChanges | A Listenable that notifies when a guard starts or stops allowing. |
GuardedNavigation | The class through which a router asks the guards, with asked and changed, and the classes of its answers: ShowInstead, ShowOver, ShowNothing and ClosePages. It keeps the remembered location. |
A guard of the app has its full name, its allows, its target as redirectTo, and the full names of the routes of its flow. It has resumes: false when it does not bring the user back, and a guard that stands for a condition has the routes that ask for it. This is the list of an app with onboarding and sign_in:
final List<RouteGuard> routeGuards = [
RouteGuard(
'onboarding.firstRun',
allows: guard0.onboardingCompleted(),
redirectTo: const OnboardingOnboardingLocation(),
flow: const {'onboarding.onboarding'},
),
RouteGuard(
'sign_in.gate',
allows: guard1.signInAllowsApp(),
redirectTo: const SignInSignInLocation(),
flow: const {'sign_in.signIn', 'sign_in.signUp', 'sign_in.resetPassword'},
resumes: false,
),
RouteGuard(
'sign_in.hasAccount',
allows: guard1.signInHasAccount(),
redirectTo: const SignInSignInLocation(),
flow: const {'sign_in.signIn', 'sign_in.signUp', 'sign_in.resetPassword'},
resumes: false,
routes: const {'sign_in.account'},
),
];
The two gates come first, by their stages, and the guard that stands for a condition after them. The two guards of sign_in show the same target, so they have one flow, which is over once both allow.
The class decides what a router does about the guards, and the memory of the gates is in it, written once. A module that provides the router only asks and does what it is answered. So routers that ask alike show the user the same pages at the same time. One thing is up to the router: whether it can close on its own a page that replace() showed in place of a page that no push showed, which changes the location that the role remembers below such a page. An app without guards gets none of this code.
Rules
| Rule | What it requires |
|---|---|
router.guards | The guards of a module have valid names and functions of the app. Each shows a top-level route of the module that needs no values, is outside the main navigation, and has no start candidate in its flow. A guard that stands for a condition is the only one of its module for it, and the module requires or provides the role of the condition. |
router.guard_functions | The function of every guard is a top-level function of its file that takes no arguments and returns a ValueListenable<bool>. |
router.guards_asked | In an app with guards, the files of the module that provides the router create a GuardedNavigation, read guardChanges, and name the answers ShowOver and ClosePages. |
The first is checked before an app is generated, and the other two by the contract harness. The last one keeps a router that knows nothing of the guards out of an app with a module that needs them. It does not tell whether a router does what the guards answer: only a running app shows that, and SMF's CI checks it there with every router that SMF has. See Contributing.
smf create also refuses a --start in the flow of a guard, since the app shows the flow until the guard allows, and then the screen that it starts on.
Next
- Conditions of routes describes a guard that keeps the user only from some routes.
- Navigation describes the guards from the side of the app.
- Write a feature module declares the guard of this page.
- Ask the guards in a router shows how a router asks the guards, and
go_routerhow go_router does.