qlevar_router 0.3.2 qlevar_router: ^0.3.2 copied to clipboard
Manage you project Routes. Create nested routes. Simply navigation without context to your pages. Change only one sub widget in your page when navigating to new route.
Qlevar Router (QR) Show Demo #
With Navigator2.0 Manage your project routes and create nested routes. Update only one widget in your page when navigating to new route. Simply navigation without context to your page.
There are cases when we need to change the route of the application without changing the entire page and without lossing the state of the current page simplly i want to update a part in it with a new route (common case is bottom navigation bar, sidebar in a dashboard, etc). That was so hard to accomplish in flutter unit now. With this package you can do this Nested Routing - Widget Update.
The clever way to Route in your projects.
Using #
Installing #
Use this package as a library
- Depend on it
Add this to your package's pubspec.yaml file:
dependencies:
qlevar_router:
Install it You can install packages from the command line:
with Flutter:
flutter pub get
Import it Now in your Dart code, you can use:
import 'package:qlevar_router/qlevar_router.dart';
Configuration #
To use this package you must first use the Router with the MaterialApp
or CupertinoApp
. and give the package router and parser to the app.
MaterialApp.router(
routerDelegate: QR.router(routes),
routeInformationParser: QR.routeParser())
routes
are the list of QRoute that represent the routes for your project.
The path of the route should start with /
.
InitRoute #
As default the initRoute is /
, if you want to change it you need to give the new value to the initRoute
in the router method
MaterialApp.router(
routerDelegate: QR.router(AppRoutes().routes, initRoute: '/dashboard'),
routeInformationParser: QR.routeParser(),
);
Nested Routing - Widget Update #
To use the nested routing:
- simply define the children for a route with QRoute or QRouteBuilder
QRoute(
name: 'Items',
path: '/items',
page: (child) => ItemsScreen(child),
children: [
QRoute(
name: 'Items Details',
path: '/details',
page: (c) => ItemDetailsScreen()),
QRoute(
name: 'Add Items',
path: '/new',
page: (c) => AddItemScreen())
-
then a router for this children will be created and you get this router in the page property of the parent The child parameter of page property for the route
Items
-
Then you can place it wherever you like in your page
class ItemsScreen extends StatelessWidget {
final QRouter routerChild;
ItemsScreen(this.routerChild);
final database = Get.find<Database>();
@override
Widget build(BuildContext context) {
return SingleChildScrollView(
child: Column(
children: [
// ...
// any code or widgets you want
// ...
routerChild,
],
),
);
}
}
and leave the rest for the package.
now when you navigate from /items/new
to /item/details
only the ItemDetailsScreen
widget will be replaced with AddItemScreen
and any other widget in your ItemsScreen
will be the same
Context-less Navigation #
No more need for context when you want to navigate. if you need to route to new page simply
// white the path to the page
QR.to('/dashboard/items');
// OR
// Here the path of the route is '/dashboard/items/:itemId' and the QRoute.name = 'Item Page'
// and the result is '/dashboard/items/3'
QR.toName('Item Page', params:{'itemId':3})
and QR is clever enough to know with Router
he should update.
want to go back
QR.back();
Params #
send params with your route and receive them in the next page.
you can set the params as:
- route component:
QRoute(path: '/:orderId',page: (child) => OrderDetails()),
// and this receive it in your page
final orderId = QR.params['orderId'].toString()
- or als query param
QR.replace('/dashboard/items/details?itemName=${e.name}&numbers=[2,6,7]')
// and this receive it in your page
final itemName = QR.params['itemName'].toString()
final numbers = QR.params['numbers']
Redirecting #
you can redirect to new page whenever a page is called using the redirectGuard
.
The redirectGuard
give the current path als parameter and takes the new path to redirect to.
or it takes null
so the page can be accessed.
QRoute(
path: '/dashboard',
redirectGuard: (path)=> AuthService().isLoggedIn? null: '/login' )
Not found page #
you can set your custom not found pag to show it whenever page was not found, or a default one will be set.
Note: the route to the not found page must be /notfound
.
Classes #
QRoute #
-
name: The name of the route
-
path: The path of this route
-
page: The page to show, a normal widget. It give the child router to place it in the parent page where it needed when the route has no children it give null.
-
onInit: a function to do what you need before initializing the route.
-
onDispose: a function to do what you need before disposing the route. for example
onInit
andonDispose
are very useful to use with Getx.QRoute( name: 'Items Details', path: '/details', onInit: () =>Get.put(ItemsController), onDispose: () => Get.delete<ItemsController>(), page: (c) => ItemDetailsScreen())
-
redirectGuard: a method to redirect to new page. it gives the called path and takes the new path to navigate to, give it null when you don't want to redirect.
-
children: the children of this route
-
Example
QRoute(
name: 'Dashboard',
path: '/dashboard',
page: (childRouter) => DashboardScreen(childRouter),
redirectGuard: (path)=> AuthService().isLoggedIn? null: '/login',
children: [
QRoute(
name: 'Dashboard Main',
path: '/',
page: (child) => DashboardContent()),
QRoute(
name: 'Items',
path: '/items',
page: (child) => ItemsScreen(child),
children: [
QRoute(
name: 'Items Details',
path: '/details',
page: (child) => ItemDetailsScreen())
]),
]),
- InitRoute: Set the initialize route for this route when it has children. This value will not be used if the route has no children. The child will be created but the path will not be changed. in the example when the route
/Item
called theItemsScreen
page will be created and the child will beItemDetailsScreen
but the path will stay/items
not/items/details
QRoute(
name: 'Items',
path: '/items',
initRoute:'/details', // This child will be created when the path is '/items'
page: (child) => ItemsScreen(child),
children: [
QRoute(
name: 'Items Details',
path: '/details',
page: (c) => ItemDetailsScreen()),
QRoute(
name: 'Add Items',
path: '/new',
page: (c) => AddItemScreen())
QRouteBuilder #
When you work on a large project the router class will start to get too big and messy and here when QRouteBuilder
come to help.
Split the the router to multiple files and call them from the root router or as child to another page.
See OrdersRoutes
class in example routes.dart
// Define the sub router.
class OrdersRoutes extends QRouteBuilder {
static String orders = 'Orders';
static String ordersMain = 'Orders Main';
static String ordersDetails = 'Orders Details';
@override
QRoute createRoute() => QRoute(
name: orders,
path: '/orders',
page: (child) => OrdersScreen(child),
children: [
QRoute(
name: ordersDetails,
path: '/:orderId',
page: (child) => OrderDetails()),
]);
}
// Link it to the root route or as child to another page
final routes = <QRouteBase>[
QRoute(
name: dashboard,
path: '/dashboard',
page: (childRouter) => DashboardScreen(childRouter),
children: [
QRoute(
name: dashboardMain,
path: '/',
page: (child) => DashboardContent()),
OrdersRoutes(), // Here is the call
])
);
QR #
- to(String path, NavigationType: navigate to new path, call this method from anywhere and QR is clever enough to know which router he should update.
- toName(String name, Map<String,dynamic> params, NavigationMode mode): Navigation to new route by the name, just give the name of the route and the params to add to the route and QR will build the path and navigate to it for you.
- back(): navigate back to a previous page.
- history: list of string for the paths that has been called.
- params: Map<String,dynamic> contains the params for the current route.
- currentRoute: The information for the current route.
- fullPath: the full path of the current route.
- params: Map<String,dynamic> contains the params for the current route.
NavigationType #
Define how you want the navigation to react.
- Push: place the new page on the top of the stack.
- Pop: remove the page on the top of the stack.
- ReplaceAll: remove all page from the stack and place this on on the top.
- ReplaceLast: replace the last page with this page.
- PopUntilOrPush: Pop all page unit you get this page in the stack if the page doesn't exist in the stack push in on the top This is the default type to navigation.