Routemaster

Because routesBuilder in RoutemasterDelegate provides a BuildContext, you can use state management (like Provider) to return different RouteMap instances based on application state (e.g., whether a user is logged in).

MaterialApp.router(
  routerDelegate: RoutemasterDelegate(
    routesBuilder: (context) {
      final appState = Provider.of<AppState>(context);
      return appState.isLoggedIn ? loggedInMap : loggedOutMap;
    },
  ),
  routeInformationParser: RoutemasterParser(),
);

To use Routemaster, integrate it into your MaterialApp.router by providing a RoutemasterDelegate with a routesBuilder and a RoutemasterParser. The routesBuilder takes a BuildContext and returns a RouteMap containing your application's route definitions.

MaterialApp.router(
  routerDelegate: RoutemasterDelegate(
    routesBuilder: (context) => RouteMap(routes: {
      '/': (routeData) => MaterialPage(child: PageOne()),
      '/two': (routeData) => MaterialPage(child: PageTwo()),
    }),
  ),
  routeInformationParser: RoutemasterParser(),
)

To change the image displayed during the app's launch on iOS, you can use one of two methods:

1. Direct File Replacement: Replace the existing image files located in the example/book_store/ios/Runner/Assets.xcassets/LaunchImage.imageset/ directory with your own assets.
2. Xcode Interface:
   • Open the iOS workspace using open ios/Runner.xcworkspace.
   • In the Xcode Project Navigator, navigate to Runner/Assets.xcassets.
   • Drag and drop your desired images into the asset catalog to replace the launch screen assets.

While Hero animations work automatically on the top-level navigator, you must wrap any PageStackNavigator used in a child navigator with a HeroControllerScope to enable them.

HeroControllerScope(
  controller: MaterialApp.createMaterialHeroController(),
  child: PageStackNavigator(
    stack: pageStack,
  )
)

To change the launch screen image for the iOS version of your application, you can use one of two methods:

1. Direct File Replacement: Replace the existing image files directly within the example/simple_example/ios/Runner/Assets.xcassets/LaunchImage.imageset/ directory with your own assets.
2. Xcode Interface:
   • Open the iOS workspace using open ios/Runner.xcworkspace.
   • In the Xcode Project Navigator, navigate to Runner/Assets.xcassets.
   • Drag and drop your desired images into the asset catalog to replace the old ones.

You can control access to routes by returning different widgets or Redirect objects based on logic (e.g., authentication status).

• Show a 404/Custom page: Return a different widget (like NotFound()) if validation fails. This does not change the URL.
• Redirect (URL change): Return Redirect('/path') to change the current URL to a new one.
• Redirect (No URL change): Return a different widget (like CustomNoAccessPage()) to show a specific view without changing the URL.
• Route Redirection: Use Redirect('/path') within a route definition to map one path to another.

// Redirecting a route
'/one': (routeData) => MaterialPage(child: PageOne()),
'/two': (routeData) => Redirect('/one'),

// Guarded route with Redirect
'/protected-route': (route) => 
    canUserAccessPage()
      ? MaterialPage(child: ProtectedPage())
      : Redirect('/no-access'),

You can retrieve information about the current route using RouteData.of(context). This provides access to the full path, path parameters, and query parameters.

RouteData.of(context).path; // Full path: '/product/123?query=param'
RouteData.of(context).pathParameters; // Map: {'id': '123'}
RouteData.of(context).queryParameters; // Map: {'query': 'param'}

Query parameters (e.g., ?query=hello) are automatically parsed and accessible via the queryParameters map in the RouteData object.

// Path '/search?query=hello' results in SearchPage(query: 'hello')
RouteMap(routes: {
  '/search': (route) => MaterialPage(
        child: SearchPage(query: route.queryParameters['query']),
      ),
})

Extend RoutemasterObserver to listen to navigation events. RoutemasterObserver extends NavigatorObserver and receives all nested Navigator events. You can override didPop for standard navigator events or didChangeRoute for Routemaster-specific route data changes.

class MyObserver extends RoutemasterObserver {
  @override
  void didPop(Route route, Route? previousRoute) {
    print('Popped a route');
  }

  @override
  void didChangeRoute(RouteData routeData, Page page) {
    print('New route: ${routeData.path}');
  }
}

// Register in MaterialApp.router
routerDelegate: RoutemasterDelegate(
  observers: [MyObserver()],
  routesBuilder: (_) => routeMap,
),

Use Routemaster.of(context) to perform navigation from within a widget tree. You can use .push() to add a new route to the stack or .replace() to swap the current route. Paths can be absolute (starting with /) or relative.

// Absolute paths
Routemaster.of(context).push('/absolute-path');
Routemaster.of(context).replace('/absolute-path');

// Relative paths
Routemaster.of(context).push('relative-path');
Routemaster.of(context).replace('relative-path');

Define a fallback page for any URL that does not match your RouteMap by using the onUnknownRoute property in RouteMap.

RouteMap(
    onUnknownRoute: (route, context) {
        return MaterialPage(child: NotFoundPage());
    },
    routes: {
        '/': (_) => MaterialPage(child: HomePage()),
    },
)