Flutter Beamer Cheat Sheet

flutter_beamer_cheat_sheet.md

Flutter Beamer Navigation Cheat Sheet

Dont forget:

• beamingHistory is a collection of BeamLocations.
• pop() goes back from stack ("inside" the current BeamLocation)
• Back button should appear only when there are >1 page in the stack of current BeamLocation.

1. Beamer.of(context).beamTo

• Usage: Navigates to a specific BeamLocation.
• Syntax: context.beamTo(MyBeamLocation());
• Description: Use this to navigate to a new location, defined by a BeamLocation object.
• Navigator Equivalent: Navigator.of(context).push(MaterialPageRoute(builder: (context) => MyPage()));

2. Beamer.of(context).beamToNamed

• Usage: Navigates to a named route.
• Syntax: context.beamToNamed('/my-route');
• Description: Ideal for navigating using route names as strings.
• Navigator Equivalent: Navigator.of(context).pushNamed('/my-route');

3. Beamer.of(context).beamBack

• Usage: Navigates back in the Beamer's history stack.
• Syntax: context.beamBack();
• Description: Use this to go back to the previous location.
• Navigator Equivalent: Navigator.of(context).pop();

4. Beamer.of(context).canBeamBack

• Usage: Checks if it’s possible to beam back.
• Syntax: context.canBeamBack;
• Description: Returns true if there are locations in the history stack to go back to.

5. Beamer.of(context).currentBeamLocation

• Usage: Accesses the current BeamLocation.
• Syntax: context.currentBeamLocation;
• Description: Provides access to the current location properties.

6. Beamer.of(context).currentPages

• Usage: Accesses the stack of pages in the current BeamLocation.
• Syntax: context.currentPages;
• Description: Returns a list of BeamPage objects in the current location.

7. Beamer.of(context).updateCurrentLocation

• Usage: Updates the current location with new properties.
• Syntax: context.updateCurrentLocation(MyBeamLocation());
• Description: Useful for modifying properties of the current location.

8. Beamer.of(context).beamToReplacementNamed

• Usage: Replaces the current location with a new one.
• Syntax: context.beamToReplacementNamed('/my-route');
• Description: Similar to beamToNamed, but replaces the current location in the stack.
• Navigator Equivalent: Navigator.of(context).pushReplacement(MaterialPageRoute(builder: (context) => MyPage()));

9. Beamer.of(context).beamToReplacement

• Usage: Replaces the current location with a new one.
• Syntax: context.beamToReplacement(MyBeamLocation());
• Description: Similar to beamTo, but replaces the current location in the stack.
• Navigator Equivalent: Navigator.of(context).pushReplacement(MaterialPageRoute(builder: (context) => MyPage()));

10. Beamer.of(context).popBeamLocation

• Usage: Pops the top-most location in the stack.
• Syntax: context.popBeamLocation();
• Description: Used to remove the top location from the history stack.
• Navigator Equivalent: No direct equivalent. Navigator's popUntil can be used for similar behavior but not exactly the same.

11. Beamer.of(context).popToNamed

• Usage: Pops routes until a route with a certain name.
• Syntax: context.popToNamed('/my-route');
• Description: Useful for popping multiple routes until a specific named route is reached.
• Navigator Equivalent: Navigator.of(context).popUntil(ModalRoute.withName('/my-route'));

Beamer Parameters Cheat Sheet

Path Parameters

Path parameters are dynamic segments of the URL that can change based on the specific item or page you're referring to.

Example

class ProductLocation extends BeamLocation {
  @override
  List<String> get pathPatterns => ['/product/:productId'];

  @override
  List<BeamPage> buildPages(BuildContext context, BeamState state) {
    final productId = state.pathParameters['productId'];
    return [
      BeamPage(
        key: ValueKey('product-$productId'),
        child: ProductPage(productId: productId),
      ),
    ];
  }
}

Certainly! Here's a cheat sheet in markdown format explaining how to use path parameters, query parameters, and object parameters in Beamer, with examples:

Beamer Cheat Sheet: Parameters

Path Parameters

Path parameters are dynamic segments of the URL that can change based on the specific item or page you're referring to.

Example

class ProductLocation extends BeamLocation {
  @override
  List<String> get pathPatterns => ['/product/:productId'];

  @override
  List<BeamPage> buildPages(BuildContext context, BeamState state) {
    final productId = state.pathParameters['productId'];
    return [
      BeamPage(
        key: ValueKey('product-$productId'),
        child: ProductPage(productId: productId),
      ),
    ];
  }
}

In this example, if you navigate to /product/42, the productId will be '42'.

Usage:

Beamer.of(context).beamToNamed('/product/123');

Query Parameters

Query parameters are a set of key-value pairs in the URL, typically used for filtering or sorting data.

class SearchLocation extends BeamLocation {
  @override
  List<String> get pathPatterns => ['/search'];

  @override
  List<BeamPage> buildPages(BuildContext context, BeamState state) {
    final query = state.queryParameters['query'];
    return [
      BeamPage(
        key: ValueKey('search'),
        child: SearchPage(query: query),
      ),
    ];
  }
}

Usage:

Beamer.of(context).beamToNamed('/search?query=shoes');

Or, use a function that builds a query URL from a Map:

String buildRouteWithQuery(String baseRoute, Map<String, dynamic> queryParams) {
  final uri = Uri.parse(baseRoute);
  final newUri = uri.replace(queryParameters: queryParams);
  return newUri.toString();
}

var queryMap = {'query': 'beamer', 'page': '1', 'other': 'othervalue' };
Beamer.of(context).beamToNamed(buildRouteWithQuery('/search', queryMap));

Object Parameters

Object parameters allow passing complex data objects through navigation.

class UserProfileLocation extends BeamLocation {
  @override
  List<String> get pathPatterns => ['/user-profile'];

  @override
  List<BeamPage> buildPages(BuildContext context, BeamState state) {
    final user = state.data['user'] as User;
    return [
      BeamPage(
        key: ValueKey('user-profile'),
        child: UserProfilePage(user: user),
      ),
    ];
  }
}

Usage:

Beamer.of(context).beamToNamed(
  '/user-profile',
  data: {'user': currentUser},
);

---

Manipulating BeamHistory

To manipulate the history, you can access beamDelegate.beamHistory. However, keep in mind that direct manipulation of the beamHistory is not recommended. Instead, use the provided methods by the delegate to navigate, pop, or replace routes which indirectly affects the history.

Examples of History Manipulation

Clearing the history:

To clear the navigation history (e.g., after a user logs out):

beamerDelegate.beamHistory.clear();
beamerDelegate.beamToNamed('/');

This clears the history and beams to the root location, effectively resetting the navigation stack.

Custom Back Navigation:

To implement custom behavior when the user presses the back button, you might listen to WillPopScope and manually manipulate the history:

WillPopScope(
  onWillPop: () async {
    if (customCondition) {
      // Perform custom navigation, e.g., popping multiple pages
      beamerDelegate.beamHistory.removeLast();
      beamerDelegate.update(
        configuration: RouteInformation(location: beamerDelegate.currentBeamLocation.state.uri.toString()),
      );
      return false; // Prevents default pop action
    }
    return true; // Allows default pop action
  },
  child: ...,
)

Navigating Without Adding to History:

If you want to navigate to a new screen without adding it to the history (similar to replacing the current route), you can use the beamReplace method:

beamerDelegate.beamReplace(
  location: NewLocation(),
);

This replaces the current location in the history with a new one.

Object Parameters cannot use with state.data but you can use with direct data

class UserProfileLocation extends BeamLocation {
  @override
  List<String> get pathPatterns => ['/user-profile'];

  @override
  List<BeamPage> buildPages(BuildContext context, BeamState state) {
    final user = data['user'] as User;
    return [
      BeamPage(
        key: ValueKey('user-profile'),
        child: UserProfilePage(user: user),
      ),
    ];
  }
}

Ref: slovnicki/beamer#436