Skip to content

F
Front-End
Unverified Commit 6a434ab9 authored by Ian Hickson's avatar Ian Hickson Committed by GitHub
Browse files
Options

Fix grammar and writing style for some of the Router documentation (#68513)

parent dcc8ced8
Hide whitespace changes
Inline Side-by-side
Showing with 101 additions and 109 deletions
packages/flutter/lib/src/widgets/router.dart
View file @ 6a434ab9
......@@ -27,9 +27,11 @@ import 'navigator.dart';
/// these information and navigates accordingly.
///
/// The latter case should only happen in a web application where the [Router]
/// reports route change back to web engine.
/// reports route changes back to web engine.
class RouteInformation {
/// Creates a route information.
/// Creates a route information object.
///
/// The arguments may be null.
const RouteInformation({this.location, this.state});
/// The location of the application.
......@@ -42,15 +44,16 @@ class RouteInformation {
/// The state of the application in the [location].
///
/// The app can have different states even in the same location. For example
/// the text inside a [TextField] or the scroll position in a [ScrollView],
/// these widget states can be stored in the [state].
/// The app can have different states even in the same location. For example,
/// the text inside a [TextField] or the scroll position in a [ScrollView].
/// These widget states can be stored in the [state].
///
/// It's only used in the web application currently. In a web application,
/// this property is stored into browser history entry when the [Router]
/// report this route information back to the web engine through the
/// [PlatformRouteInformationProvider], so we can get the url along with state
/// back when the user click the forward or backward buttons.
/// Currently, this information is only used by Flutter on the web:
/// the data is stored in the browser history entry when the
/// [Router] reports this route information back to the web engine
/// through the [PlatformRouteInformationProvider]. The information
/// is then passed back, along with the [location], when the user
/// clicks the back or forward buttons.
///
/// The state must be serializable.
final Object? state;
......@@ -64,31 +67,29 @@ class RouteInformation {
/// button), parses route information into data of type `T`, and then converts
/// that data into [Page] objects that it passes to a [Navigator].
///
/// Additionally, every single part of that previous sentence can be overridden
/// and configured as desired.
/// Each part of this process can be overridden and configured as desired.
///
/// The [routeInformationProvider] can be overridden to change how the name of
/// the route is obtained. the [RouteInformationProvider.value] when the
/// [Router] is first created is used as the initial route, and subsequent
/// notifications from the [RouteInformationProvider] to its listeners are
/// treated as notifications that the route information has changed.
/// the route is obtained. The [RouteInformationProvider.value] is used as the
/// initial route when the [Router] is first created. Subsequent notifications
/// from the [RouteInformationProvider] to its listeners are treated as
/// notifications that the route information has changed.
///
/// The [backButtonDispatcher] can be overridden to change how back button
/// notifications are received. This must be a [BackButtonDispatcher], which is
/// an object where callbacks can be registered, and which can be chained
/// so that back button presses are delegated to subsidiary routers. The
/// callbacks are invoked to indicate that the user is trying to close the
/// current route (by pressing the system back button); the [Router] ensures
/// that when this callback is invoked, the message is passed to the
/// [routerDelegate] and its result is provided back to the
/// [backButtonDispatcher]. Some platforms don't have back buttons and on those
/// platforms it is completely normal that this notification is never sent. The
/// common [backButtonDispatcher] for root router is an instance of
/// [RootBackButtonDispatcher], which uses a [WidgetsBindingObserver] to listen
/// to the `popRoute` notifications from [SystemChannels.navigation]. A
/// common alternative is [ChildBackButtonDispatcher], which must be provided
/// the [BackButtonDispatcher] of its ancestor [Router] (available via
/// [Router.of]).
/// an object where callbacks can be registered, and which can be chained so
/// that back button presses are delegated to subsidiary routers. The callbacks
/// are invoked to indicate that the user is trying to close the current route
/// (by pressing the system back button); the [Router] ensures that when this
/// callback is invoked, the message is passed to the [routerDelegate] and its
/// result is provided back to the [backButtonDispatcher]. Some platforms don't
/// have back buttons (e.g. iOS and desktop platforms); on those platforms this
/// notification is never sent. Typically, the [backButtonDispatcher] for the
/// root router is an instance of [RootBackButtonDispatcher], which uses a
/// [WidgetsBindingObserver] to listen to the `popRoute` notifications from
/// [SystemChannels.navigation]. Nested [Router]s typically use a
/// [ChildBackButtonDispatcher], which must be provided the
/// [BackButtonDispatcher] of its ancestor [Router] (available via [Router.of]).
///
/// The [routeInformationParser] can be overridden to change how names obtained
/// from the [routeInformationProvider] are interpreted. It must implement the
......@@ -160,7 +161,9 @@ class RouteInformation {
/// its needs.
///
/// An application might have no [Router] widgets if it has only one "screen",
/// or if the facilities provided by [Navigator] are sufficient.
/// or if the facilities provided by [Navigator] are sufficient. This is common
/// for desktop applications, where subsidiary "screens" are represented using
/// different windows rather than changing the active interface.
///
/// A particularly elaborate application might have multiple [Router] widgets,
/// in a tree configuration, with the first handling the entire route parsing
......@@ -172,68 +175,63 @@ class RouteInformation {
///
/// ## URL updates for web applications
///
/// In the web platform, it is important to keeps the URL up to date with the
/// app state. This ensures the browser constructs its history entry
/// correctly so that its forward and backward buttons continue to work.
///
/// If the [routeInformationProvider] is a [PlatformRouteInformationProvider]
/// and a app state change leads to [Router] rebuilds, the [Router] will detect
/// such a event and retrieve the new route information from the
/// [RouterDelegate.currentConfiguration] and the
/// [RouteInformationParser.restoreRouteInformation]. If the location in the
/// new route information is different from the current location, the router
/// sends the new route information to the engine through the
/// [PlatformRouteInformationProvider.routerReportsNewRouteInformation].
/// In the web platform, keeping the URL in the browser's location bar up to
/// date with the application state ensures that the browser constructs its
/// history entry correctly, allowing its back and forward buttons to function
/// as the user expects.
///
/// By Providing implementations of these two methods in the subclasses and using
/// the [PlatformRouteInformationProvider], you can enable the [Router] widget to
/// update the URL in the browser automatically.
/// If an app state change leads to the [Router] rebuilding, the [Router] will
/// retrieve the new route information from the [routerDelegate]'s
/// [RouterDelegate.currentConfiguration] method and the
/// [routeInformationParser]'s [RouteInformationParser.restoreRouteInformation]
/// method. If the location in the new route information is different from the
/// current location, the router sends the new route information to the
/// [routeInformationProvider]'s
/// [RouteInformationProvider.routerReportsNewRouteInformation] method. That
/// method as implemented in [PlatformRouteInformationProvider] uses
/// [SystemNavigator.routeInformationUpdated] to notify the engine, and through
/// that the browser, of the new URL.
///
/// You can force the [Router] to report the new route information back to the
/// engine even if the [RouteInformation.location] has not changed. By calling
/// the [Router.navigate], the [Router] will be forced to report the route
/// information back to the engine after running the callback. This is useful
/// when you want to support the browser backward and forward buttons without
/// changing the URL. For example, the scroll position of a scroll view may be
/// saved in the [RouteInformation.state]. If you use the [Router.navigate] to
/// update the scroll position, the browser will create a new history entry with
/// the [RouteInformation.state] that stores the new scroll position. when the
/// users click the backward button, the browser will go back to previous scroll
/// position without changing the url bar.
/// One can force the [Router] to report new route information to the
/// [routeInformationProvider] (and thus the browser) even if the
/// [RouteInformation.location] has not changed by calling the [Router.navigate]
/// method with a callback that performs the state change. This allows one to
/// support the browser's back and forward buttons without changing the URL. For
/// example, the scroll position of a scroll view may be saved in the
/// [RouteInformation.state]. Using [Router.navigate] to update the scroll
/// position causes the browser to create a new history entry with the
/// [RouteInformation.state] that stores this new scroll position. When the user
/// clicks the back button, the app will go back to the previous scroll position
/// without changing the URL in the location bar.
///
/// You can also force the [Router] to ignore a one time route information
/// update by providing a one time app state update in a callback and pass it
/// into the [Router.neglect]. The [Router] will not report any route
/// information even if it detects location change as a result of running the
/// callback. This is particularly useful when you don't want the browser to
/// create a browser history entry for this app state update.
/// One can also force the [Router] to ignore application state changes by
/// making those changes during a callback passed to [Router.neglect]. The
/// [Router] will not report any route information even if it detects location
/// change as a result of running the callback.
///
/// You can also choose to opt out of URL updates entirely. Simply ignore the
/// [RouterDelegate.currentConfiguration] and the
/// [RouteInformationParser.restoreRouteInformation] without providing the
/// implementations will prevent the [Router] from reporting the URL back to the
/// web engine. This is not recommended in general, but You may decide to opt
/// out in these cases:
/// To opt out of URL updates entirely, pass null for [routeInformationProvider]
/// and [routeInformationParser]. This is not recommended in general, but may be
/// appropriate in the following cases:
///
/// * If you are not writing a web application.
/// * The application does not target the web platform.
///
/// * If you have multiple router widgets in your app, then only one router
/// widget should update the URL (Usually the top-most one created by the
/// [WidgetsApp.router]/[MaterialApp.router]/[CupertinoApp.router]).
/// * There are multiple router widgets in the application. Only one [Router]
/// widget should update the URL (typically the top-most one created by the
/// [WidgetsApp.router], [MaterialApp.router], or [CupertinoApp.router]).
///
/// * If your app does not care about the in-app navigation using the browser's
/// forward and backward buttons.
/// * The application does not need to implemenent in-app navigation using the
/// browser's back and forward buttons.
///
/// Otherwise, we strongly recommend implementing the
/// [RouterDelegate.currentConfiguration] and the
/// [RouteInformationParser.restoreRouteInformation] to provide optimal
/// user experience in the web application.
/// In other cases, it is strongly recommended to implement the
/// [RouterDelegate.currentConfiguration] and
/// [RouteInformationParser.restoreRouteInformation] APIs to provide an optimal
/// user experience when running on the web platform.
class Router<T> extends StatefulWidget {
/// Creates a router.
///
/// The [routeInformationProvider] and [routeInformationParser] can be null if this
/// router does not depend on route information. A common example is a sub router
/// that builds its content completely relies on the app state.
/// that builds its content completely based on the app state.
///
/// If the [routeInformationProvider] is not null, the [routeInformationParser] must
/// also not be null.
......@@ -247,8 +245,8 @@ class Router<T> extends StatefulWidget {
this.backButtonDispatcher,
}) : assert(
(routeInformationProvider == null) == (routeInformationParser == null),
'You must provide both routeInformationProvider and routeInformationParser '
'if this router parses route information. Otheriwse, they should both '
'Both routeInformationProvider and routeInformationParser must be provided '
'if this router parses route information. Otherwise, they should both '
'be null.'
),
assert(routerDelegate != null),
......@@ -282,8 +280,8 @@ class Router<T> extends StatefulWidget {
/// builds a navigating widget for the [Router].
///
/// It is also the primary respondent for the [backButtonDispatcher]. The
/// [Router] relies on the [RouterDelegate.popRoute] to handles the back
/// button intends.
/// [Router] relies on [RouterDelegate.popRoute] to handle the back
/// button.
///
/// If the [RouterDelegate.currentConfiguration] returns a non-null object,
/// this [Router] will opt for URL updates.
......@@ -297,11 +295,9 @@ class Router<T> extends StatefulWidget {
/// Retrieves the immediate [Router] ancestor from the given context.
///
/// Use this method when you need to access the delegates in the [Router].
/// For example, you need to access the [backButtonDispatcher] of the parent
/// router to create a [ChildBackButtonDispatcher] for a nested router.
/// Another use case may be updating the value in [routeInformationProvider]
/// to navigate to a new route.
/// This method provides access to the delegates in the [Router]. For example,
/// this can be used to access the [backButtonDispatcher] of the parent router
/// when creating a [ChildBackButtonDispatcher] for a nested [Router].
static Router<dynamic>? of(BuildContext context, {bool nullOk = false}) {
final _RouterScope? scope = context.dependOnInheritedWidgetOfExactType<_RouterScope>();
assert(() {
......@@ -1011,13 +1007,11 @@ abstract class RouteInformationParser<T> {
/// Restore the route information from the given configuration.
///
/// This is not required if you do not opt for the route information reporting
/// , which is used for updating browser history for the web application. If
/// you decides to opt in, you must also overrides this method to return a
/// route information.
/// This may return null, in which case the browser history will not be updated.
/// See [Router]'s documentation for details.
///
/// In practice, the [parseRouteInformation] method must produce an equivalent
/// configuration when passed this method's return value
/// The [parseRouteInformation] method must produce an equivalent
/// configuration when passed this method's return value.
RouteInformation? restoreRouteInformation(T configuration) => null;
}
......@@ -1025,21 +1019,21 @@ abstract class RouteInformationParser<T> {
/// navigating widget.
///
/// This delegate is the core piece of the [Router] widget. It responds to
/// push route and pop route intent from the engine and notifies the [Router]
/// to rebuild. It also act as a builder for the [Router] widget and builds a
/// push route and pop route intents from the engine and notifies the [Router]
/// to rebuild. It also acts as a builder for the [Router] widget and builds a
/// navigating widget, typically a [Navigator], when the [Router] widget
/// builds.
///
/// When engine pushes a new route, the route information is parsed by the
/// When the engine pushes a new route, the route information is parsed by the
/// [RouteInformationParser] to produce a configuration of type T. The router
/// delegate receives the configuration through [setInitialRoutePath] or
/// [setNewRoutePath] to configure itself and builds the latest navigating
/// widget upon asked.
/// widget when asked ([build]).
///
/// When implementing subclass, consider defining a listenable app state to be
/// used for building the navigating widget. The router delegate should update
/// the app state accordingly and notify the listener know the app state has
/// changed when it receive route related engine intents (e.g.
/// When implementing subclasses, consider defining a [Listenable] app state object to be
/// used for building the navigating widget. The router delegate would update
/// the app state accordingly and notify its own listeners when the app state has
/// changed and when it receive route related engine intents (e.g.
/// [setNewRoutePath], [setInitialRoutePath], or [popRoute]).
///
/// All subclass must implement [setNewRoutePath], [popRoute], and [build].
......
packages/flutter/test/widgets/router_test.dart
View file @ 6a434ab9
......@@ -155,9 +155,8 @@ void main() {
} on AssertionError catch(e) {
expect(
e.message,
'You must provide both routeInformationProvider and '
'routeInformationParser if this router parses route information. '
'Otheriwse, they should both be null.'
'Both routeInformationProvider and routeInformationParser must be provided if this router '
'parses route information. Otherwise, they should both be null.'
);
}
});
......@@ -175,9 +174,8 @@ void main() {
} on AssertionError catch(e) {
expect(
e.message,
'You must provide both routeInformationProvider and '
'routeInformationParser if this router parses route information. '
'Otheriwse, they should both be null.'
'Both routeInformationProvider and routeInformationParser must be provided if this router '
'parses route information. Otherwise, they should both be null.'
);
}
});
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

HIAST - GitLab