route_manager

Description:

route manager

This package provides an advanced but easy-to-use implementation of "Navigator 2.0" to manage navigation and routing on every platform. It supports url changes on web, deeplinking on mobile and nested routes.
Features #
This package contains:

RouteManager


The RouteManager is responsible of creating and storing the RouteDelegate, the InformationParser and the CustomTransitionDelegate to manage routing such as pushing and popping pages.

RouteInfo


It is a class used to set the route name, the route child widget to display when the path is pointing to this route, and eventually a function to map query from arguments can be provided.


InitialRouteInfo

It is a class that contains info about the initial route. It is used to set the initial route name (that defaults to "/" if not specified) and eventually a method to specify a path to use as redirect if a condition is not met.


RouteManagerWillPopScope



It is a widget to override the popRoute event handler and to handle the pop action such as when tapping the physical back button on Android devices. It's similar to WillPopScope widget used with Navigator. Note that to block swipe gesture to go back on iOS you must use the allowSwipeToPopOnIOS property in RouteManager constructor.

RouterManager


It's a widget to use in the widget tree to create a nested route, and it is initialised with a RouteManager parameter.
Getting started #
To get started, simply install the package adding the dependency
Usage #
Check the usage paragraph according to your needs.
RouteInfo #
This class contains info about a route. It is used to set the route name, the route child widget to display when the path is pointing to this route, and eventually a function to map query from arguments can be provided. Furthermore, if requiredAuthentication is set to true (default to false), the authenticationWrapper widget specified in the RouteManager constructor will be used as wrapper for the routeWidget.
var routeInfo = RouteInfo(
name: "/home",
requiresAuthentication: false,
routeWidget: (args) => HomeScreen(),
);
copied to clipboard
To manage routes pushing directly widgets instead of using names, you can use the TypedRouteInfo class. It's similar to RouteInfo, but required explicitally setting the type of the Widget that will be pushed in the navigation stack.
var routeInfo = TypedRouteInfo(
name: "/home",
requiresAuthentication: false,
type: HomeScreen,
routeWidget: (args) => HomeScreen(),
);
copied to clipboard
InitialRouteInfo #
This class contains info about the initial route. It is used to set the route name and eventually a method to specify a path to use as redirect if a condition is not met.
var initialRouteInfo = InitialRouteInfo(
initialRouteName: "/",
redirectToPath: (context) {
// Verify a condition to redirect the user to another page instead of the root
if (user.isAdmin) {
return "/admin";
}
return null;
}
);
copied to clipboard
RouteManager #
RouteManager manage routing for a custom route. The app can have multiple route managers, but at least one to be used as the root router in MaterialApp.
The RouteManager is responsible of creating and storing the RouteDelegate, the InformationParser and the CustomTransitionDelegate to manage routing such as pushing and popping pages.
It must be used to initialize the routing system. To use it in the root MaterialApp routing, instantiate the MaterialApp with the MaterialApp.router constructor and then pass the created RouteDelegate and InformationParser, as shown in the following example.
final routeManager = RouteManager(
routesInfo: // Must be provided to specify all the possibile Route pages
[
RouteInfo(name: "/", routeWidget: (args) => SplashScreen()),
RouteInfo(name: "/home", routeWidget: (args) => HomeScreen()),
TypedRouteInfo(name: "/test", routeWidget: (args) => TestScreen(), type: TestScreen),
],
initialRouteInfo: InitialRouteInfo(
initialRouteName: "/home",
redirectToPath: (context) {
if (user.isAdmin) {
return "/admin";
}
return null;
}
), // Optional, to specify an custom initial route if different from "/" and eventually a path to redirect the user if he should not see the initial route (i.e. for specific roles after authenticating)
defaultRouteWidget: Text("404"), // Optional, to specify a custom widget to show if no route widget is find for a specified name
basePath: "/app", // Optionally, used on web to match a custom base href in the index.html file, if different from "/"
evaluateEnabledRoute: (path) => true, // Optional, to add some logic for a specific path to eventually block access to that page. It can be used, for example to avoid entering some page for non-admin users.
allowSwipeToPopOnIOS: true, // Optional, if it's _false_, the default swipe gesture to pop page on iOS is blocked
enableTransitionAnimation;: true, // Boolean value to specify if route transitions will be executed without animations
authenticationWrapper: (child) => Container(child: child), // Optional, you can specify a widget to use as authentication wrapper for the routes that are defined as `requiresAuthentication` in the `routesInfo` list.
onGenerateNavigatorContext: (context) {}, /// Optional, this method can be used to access the navigator context
);

@override
Widget build(BuildContext context) {
return MaterialApp.router(
routeInformationParser: routeManager.informationParser,
routerDelegate: routeManager.routerDelegate,
);
}
copied to clipboard
RouteManagerWillPopScope #
To override the popRoute handler of RouteDelegate, and handle the pop action event for a scecific page (such as when tapping the physical back button on Android devices), you can use the RouteManagerWillPopScope widget, in the same way you could use the WillPopScope widget when working with Navigator.
return RouteManagerWillPopScope(
child: child,
// The method to call _before_ the pop action is effectively taken.
// If the callback returns a Future that resolves to false, the enclosing route will not be popped.
onWillPop: _onWillPop,
);
copied to clipboard
RouterManager #
To use another RouteManager in app, the RouterManager widget can be similarly used as shown in the following code. This is helpful to handle nested routes. Consider that only the RouteManager provided in the MaterialApp has the ability to change the url on web platform.
final routeManager = RouteManager(routesInfo: [
RouteInfo(name: "/home", routeWidget: (args) => Container()),
]);

@override
Widget build(BuildContext context) {
return RouterManager(
routeManager: routeManager,
);
}
copied to clipboard
RouteDelegate #
The RouteDelegate instance to push/pop pages can be accessed by calling:
final routerDelegate = RouterManager.of(context);
copied to clipboard
In this way you can find the nearest RouterManager ancestor in the widget tree. If you have nested RouteDelegate, for example when using the RouterManager widget, you can access the root RouteManager instance as follows.
final rootRouterDelegate = RouterManager.of(context, rootNavigator: true);
copied to clipboard
It is also possible to access the router delegate as follows (even if not recommended):
final routeManager = RouteManager(
[...]
);
var routerDelegate = routeManager.routerDelegate;
copied to clipboard
Note that you need the context to use the route delegate. If you want to use it outside a widget with context, you should take care on your own to store an application's global context, or to share the RouteManager instance globally in the project to access it everywhere. This behaviour is discouraged and so there is no out-of-the-box implementation for it.
Router Delegate methods

Push a new page in the stack with name. Optionally, a [Map] argument can be passed to be processed by the routeWidget builder as specified in the routesInfo list provided to the RouteManager. You can eventually await for a result popped by the pushed route.

var result = await RouteManager.of(context).pushNamed<bool>("/home", arguments: {"title": "Hello World"});
copied to clipboard

Push a new page in the stack as a Widget. You can eventually await for a result popped by the pushed route.

var result = await RouteManager.of(context).push<bool>(TestScreen());
copied to clipboard

Pop a page from the stack. You can eventually return a value to the completer that pushed the page (see push or pushNamed APIs)

var poppedPage = await RouteManager.of(context).pop(value: true);
copied to clipboard

Pop the last page in the stack and push a new one with name

RouteManager.of(context).pushReplacementNamed("/home", arguments: {'test': true});
copied to clipboard

Pop the last page in the stack and push a new one as a widget

RouteManager.of(context).pushReplacement(TestScreen());
copied to clipboard

Pop all the pages in the stack and push the root page

RouteManager.of(context).popAll();
copied to clipboard

Pop to the last page with specified name in the stack

RouteManager.of(context).popTo("/home");
copied to clipboard

Show dialog

RouteManager.of(context).showDialog(builder: (context) => Dialog(child: Text("Hello world")));
copied to clipboard

Show modal (either full screen or not, and eventually draggable)

RouteManager.of(context).showModal(builder: (context) => Scaffold(body: Text("Hello world")));
copied to clipboard
Additional information #
This package is mantained by the Competence Center Flutter of Mobilesoft Srl.