go_router_plus
go_router_plus copied to clipboard
:office: Building blocks screens, access control and refresh notifiers base on Go Router
Go Router Plus
Go Router is an awesome easy-to-use and production ready package for creating routes, handling navigation, deep and dynamic links but in large apps have a lot of screens, states and auth logics, it's hard to manage routes, redirect and refresh router logics.
This package try to solve problems above by adding screen pattern, common redirect logics and chain redirect/refresh listenable.
Installation
Run the command bellow to install this package:
flutter pub add go_router_plus
After install pub package, now you can import it:
import 'package:go_router_plus/go_router_plus.dart';
Creating screens
Screen represent for route of your application, the purpose of
it is separate GoRoute
factory logics out of GoRouter
factory for
easy-to-read and maintaining.
/// lib/screens/my_first_screen.dart
import 'package:go_router_plus/go_router_plus.dart';
import 'package:go_router/go_router.dart'
class MyFirstScreen extends Screen {
@override
Widget build(BuildContext context, GoRouterState state) {
return Text('Hello world');
}
@override
String get routeName => 'my_first_screen';
@override
String get routePath => '/my-first-screen';
}
All of your screens must be extends an abstraction class Screen
providing by this package.
The following methods, getters need to implements:
- Method
build(BuildContext context, GoRouterState state)
must be redeclare return type toWidget
orPage<void>
, in common case you should useWidget
but if you want to control the transition of screen you should usePage<void>
. - Getter
routeName
declare route name of the screen must be unique. - Getter
routePath
declare route path of the screen.
Mark screen as an initial screen
To setup initial path (the first screen user will see) in traditional way, we will set initialPath
argument of GoRouter
factory but when using this package you need to create the screen implements InitialScreen
interface instead.
class LoginScreen extends Screen implements InitialScreen {
///......
}
Mark screen as an error screen
As you know, GoRouter
factory offer we an errorBuilder
argument to handling error (e.g route not found) but when using this package you need to create the screen implements ErrorScreen
interface instead.
class MyErrorScreen extends Screen implements ErrorScreen {
@override
Widget build(BuildContext context, GoRouterState state) {
return Text(state.error);
}
///......
}
Nested navigation
ShellRoute was added since go router v5
provides a way to wrap all sub-routes with a UI shell. Under the hood, GoRouter places a Navigator
in the widget tree, which is used to display matching sub-routes, you can use this feature by
extends ShellScreen
class:
class MyShellScreen extends ShellScreen {
@override
List<ScreenBase> subScreens() {
return [
ScreenA(),
ScreenB(),
];
}
}
Creating router with screens
Now you got the screen pattern concept, let creating Go Router:
final router = createGoRouter(
screens: [
LoginScreen(),
MyFirstScreen(),
MyErrorScreen(),
],
);
createGoRouter
factory function providing by this package.
Redirector
Redirector
will handles redirection logics of all routes.
You can setup one or many redirectors via redirectors
argument of createGoRouter
factory function:
final router = createGoRouter(
screens: [
LoginScreen(),
MyFirstScreen(),
MyErrorScreen(),
],
redirectors: [
AuthRedirector(
state: LoggedInStateProvider(),
guestRedirectPath: '/login',
userRedirectPath: '/home-page',
),
ScreenRedirector(),
],
);
Authentication redirection
Authentication redirection is the most of common logic of the whole app
so it provided out of the box by this package via AuthRedirector
.
To use this builtin feature, you need to create a class implements the LoggedInState
interface:
class LoggedInStateProvider implements LoggedInState {
bool _loggedIn = false;
@override
bool get loggedIn => _loggedIn;
set loggedIn(bool value) {
_loggedIn = value;
}
}
It's a simple interface need you implements loggedIn
getter,
this getter return true
when user has been logged in otherwise
user's guest (not logged in).
And you need to marks guest and user screens of you app by using UserScreen
and GuestScreen
interfaces:
class LoginScreen extends Screen implements GuestScreen {
@override
String get routePath => '/login';
///...
}
class HomeScreen extends Screen implements UserScreen {
@override
String get routePath => '/home';
///...
}
In example above, we have two screen, one for guest (login screen) and one for
user (home screen). When user is NOT logged in he/she will be redirect
to login screen otherwise he/she will redirect to home screen, to handling
this scenario, we need to add AuthRedirector
with the setting bellow:
final router = createGoRouter(
screens: [
LoginScreen(),
HomeScreen(),
],
redirectors: [
AuthRedirector(
state: LoggedInStateProvider(),
guestRedirectPath: '/login',
userRedirectPath: '/home',
),
],
);
Now everytime user access to screens implements UserScreen
interface but
he/she's NOT logged in will be redirect to login screen and if they access to
screens implements GuestScreen
interface but logged in will be redirect to home screen.
Screen redirection
It's a builtin feature to support screens have a custom redirect
logic (e.g: access control by app states, user roles).
Screens want to build custom redirect logic should be implements RedirectAware
:
class VipScreen extends Screen implements UserScreen, RedirectAware {
@override
FutureOr<String?> redirect(BuildContext context, GoRouterState state) {
/// final currentUser = ....
return !currentUser.isVip ? '/home' : null;
}
}
Like origin redirection,
redirect
method above return null in case current user's VIP type so user can stay
in this screen, on the other hand normal user will be redirect to home screen.
And to activate this feature pass ScreenRedirector
instance to redirectors
argument of factory function:
final router = createGoRouter(
screens: [
LoginScreen(),
HomeScreen(),
VipScreen(),
],
redirectors: [
ScreenRedirector(),
AuthRedirector(
state: LoggedInStateProvider(),
guestRedirectPath: '/login',
userRedirectPath: '/home',
),
],
);
Creating custom redirector
In some cases, you may want to control redirection logics for common screens like AuthRedirector
or ScreenRedirector
above
(e.g: add an interface to marks some screens only admin user can access).
abstract class AdminScreen {}
class ManageUserScreen extends Screen implements AdminScreen {
///...
}
class AdminRedirector implements RestrictRedirector {
@override
bool shouldRedirect(Screen screen) {
return screen is AdminScreen;
}
@override
FutureOr<String?> redirect(BuildContext context, GoRouterState state) {
/// final currentUser = ....
return !currentUser.isAdmin ? '/home' : null;
}
}
In the example above, we have add the AdminScreen
interface use to marks screens for admin user only,
if user's not permit will be redirect to home screen.
AdminRedirector
implements RestrictRedirector
interface only execute redirect
method when
shouldRedirect
method return true otherwise it'll skip. In this case, shouldRedirect
method
only return true
when current screen implements AdminScreen
.
The final step is add custom redirector to redirectors
argument of factory function
final router = createGoRouter(
screens: [
ManageUserScreen(),
],
redirectors: [
AdminRedirector(),
///...
],
);
Refresh notifiers
Refresh listenable is a builtin feature of GoRouter to re-invoke redirection logics but it only accept one listenable and we need to implements all of re-invoke logics in one place.
With this package you can add more than one listenable to re-invoke redirection logics so you can separate logics to easy control, readable and independent to each others.
Pass one or more listenable instance to refreshNotifiers
argument of factory function:
class AuthService with ChangeNotifier implements LoggedInState {
bool _loggedIn = true;
@override
bool loggedIn() => _loggedIn;
void logout() {
_loggedIn = false;
notifyListeners();
}
}
class PromotionService with ChangeNotifer {
void activate() {
///....
notifyListeners();
}
}
final authService = AuthService();
final router = createGoRouter(
screens: [
ManageUserScreen(),
],
redirectors: [
AuthRedirector(
state: authService,
guestRedirectPath: '/login',
userRedirectPath: '/home',
),
///...
],
refreshNotifiers: [
authService,
PromotionService(),
/// GoRouterRefreshStream(...),
]
);
In the example above, AuthService
class's a refresh notifier and implements LoggedInState
interface
to providing state of current user's logged-in or guest. When user logout AuthRedirector
will invoke
and redirect he/she to login screen. In the other hand, promotion service will invoke redirection logic
when activate promotion (e.g: move user to promotion screen).