Beamer Documentation

To ensure users return to their exact previous location after a restart, follow this pattern:

1. Track Locations

Maintain a navigation state provider that stores:

• booksLocation: The last known location within the Books tab.
• articlesLocation: The last known location within the Articles tab.
• lastLocation: The overall last known location of the app.

2. Listen to Route Changes

In your root BeamerDelegate, define a routeListener function. This function should be called every time the app location changes, updating the navigation state provider and persisting the values to a repository (e.g., using shared preferences).

3. Restore State on Startup

When the app restarts, read the persisted locations from your provider. Because nested BeamerDelegates must reside within a State class to function correctly with Flutter's lifecycle, pass these locations into the State via a constructor.

Beamer supports nested navigation by placing Beamer widgets anywhere in the widget tree. This is useful for scenarios like bottom navigation bars where the navigation state of the content area should be independent of the bar itself.

When using multiple Beamers, BeamerDelegate has specific properties to manage parent-child synchronization:

• initializeFromParent: (Default true) If true, the child BeamerDelegate initializes its BeamStack from the parent's configuration.
• updateFromParent: (Default true) If true, the child listens to the parent's configuration updates.
• updateParent: Allows the child to update the parent (e.g., to sync beamingHistory for the BeamerBackButtonDispatcher).

class HomeScreen extends StatelessWidget {
  final _beamerKey = GlobalKey<BeamerState>();
  final _routerDelegate = BeamerDelegate(
    stackBuilder: BeamerStackBuilder(
      beamStacks: [
        BooksStack(),
        ArticlesStack(),
      ],
    ),
  );

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Beamer(
        key: _beamerKey,
        routerDelegate: _routerDelegate,
      ),
      bottomNavigationBar: BottomNavigationBarWidget(beamerKey: _beamerKey),
    );
  }
}

Beamer uses BeamStacks to architecturally separate different parts of an application (e.g., a BooksStack for book-related pages and an ArticlesStack for article-related pages).

A BeamStack is an abstract class that manages a specific stack of pages. It has three primary responsibilities:

1. pathPatterns: Defines which URIs the stack can handle.
2. buildPages: Defines how to construct the List<BeamPage> for the Navigator based on the current state.
3. state: Maintains a state object that links the path patterns to the page construction.

BeamState is a built-in state implementation that provides access to URI attributes like pathParameters and queryParameters.

class BooksStack extends BeamStack<BeamState> {
  @override
  List<Pattern> get pathPatterns => ['/books/:bookId'];

  @override
  List<BeamPage> buildPages(BuildContext context, BeamState state) {
    final pages = [const BeamPage(key: ValueKey('home'), child: HomeScreen())];
    
    if (state.uri.pathSegments.contains('books')) {
      pages.add(const BeamPage(key: ValueKey('books'), child: BooksScreen()));
    }

    final String? bookIdParameter = state.pathParameters['bookId'];
    if (bookIdParameter != null) {
      pages.add(BeamPage(
        key: ValueKey('book-$bookIdParameter'),
        title: 'Book #$bookIdParameter',
        child: BookDetailsScreen(bookId: int.tryParse(bookIdParameter)),
      ));
    }
    return pages;
  }
}

To integrate Beamer, use the .router constructor of your MaterialApp (or similar widget). You must provide a BeamerParser for the routeInformationParser and a BeamerDelegate for the routerDelegate.

There are three ways to configure the stackBuilder in BeamerDelegate:

1. Custom Function: A manual function that returns a BeamStack based on RouteInformation.
2. BeamerStackBuilder: Automatically selects a BeamStack from a provided list based on pathPatterns.
3. RoutesStackBuilder: A simplified approach using a map of routes, which removes the need for custom BeamStack classes but offers less customization.

// Option 1: Custom stackBuilder function
final routerDelegate = BeamerDelegate(
  stackBuilder: (routeInformation, _) {
    if (routeInformation.uri.path.contains('books')) {
      return BooksStack(routeInformation);
    }
    return HomeStack(routeInformation);
  },
);

// Option 2: Using BeamerStackBuilder with a list
final routerDelegate = BeamerDelegate(
  stackBuilder: BeamerStackBuilder(
    beamStacks: [
      HomeStack(),
      BooksStack(),
    ],
  ),
);

// Option 3: Using RoutesStackBuilder with a map
final routerDelegate = BeamerDelegate(
  stackBuilder: RoutesStackBuilder(
    routes: {
      '/': (context, state, data) => HomeScreen(),
      '/books': (context, state, data) => BooksScreen(),
      '/books/:bookId': (context, state, data) =>
        BookDetailsScreen(bookId: state.pathParameters['bookId']),
    },
  ),
);

// Integration into MaterialApp
@override
Widget build(BuildContext context) {
  return MaterialApp.router(
    routerDelegate: routerDelegate,
    routeInformationParser: BeamerParser(),
    backButtonDispatcher: BeamerBackButtonDispatcher(delegate: routerDelegate),
  );
}