beamingHistoryis a collection ofBeamLocations.pop()goes back from stack ("inside" the currentBeamLocation)- Back button should appear only when there are >1 page in the stack of current
BeamLocation.
- Usage: Navigates to a specific
BeamLocation. - Syntax:
context.beamTo(MyBeamLocation()); - Description: Use this to navigate to a new location, defined by a
BeamLocationobject. - Navigator Equivalent:
Navigator.of(context).push(MaterialPageRoute(builder: (context) => MyPage()));
- 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');
- 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();
- Usage: Checks if it’s possible to beam back.
- Syntax:
context.canBeamBack; - Description: Returns
trueif there are locations in the history stack to go back to.
- Usage: Accesses the current BeamLocation.
- Syntax:
context.currentBeamLocation; - Description: Provides access to the current location properties.
- Usage: Accesses the stack of pages in the current BeamLocation.
- Syntax:
context.currentPages; - Description: Returns a list of
BeamPageobjects in the current location.
- Usage: Updates the current location with new properties.
- Syntax:
context.updateCurrentLocation(MyBeamLocation()); - Description: Useful for modifying properties of the current location.
- 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()));
- 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()));
- 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
popUntilcan be used for similar behavior but not exactly the same.
- 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'));
Path parameters are dynamic segments of the URL that can change based on the specific item or page you're referring to.
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:
Path parameters are dynamic segments of the URL that can change based on the specific item or page you're referring to.
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 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 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},
);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.
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.
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: ...,
)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.