Skip to content

Update reference doc for router guards and resolvers #38079

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
jbogarthyde wants to merge 1 commit into from
Closed

Update reference doc for router guards and resolvers #38079

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 86 additions & 23 deletions packages/router/src/interfaces.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,12 @@ import {UrlSegment, UrlTree} from './url_tree';
* @description
*
* Interface that a class can implement to be a guard deciding if a route can be activated.
* If all guards return `true`, navigation will continue. If any guard returns `false`,
* navigation will be cancelled. If any guard returns a `UrlTree`, current navigation will
* be cancelled and a new navigation will be kicked off to the `UrlTree` returned from the
* guard.
* If all guards return `true`, navigation continues. If any guard returns `false`,
* navigation is cancelled. If any guard returns a `UrlTree`, the current navigation
* is cancelled and a new navigation begins to the `UrlTree` returned from the guard.
*
* The following example implements a `CanActivate` function that checks whether the
* current user has permission to activate the requested route.
*
* ```
* class UserToken {}
Expand All @@ -41,7 +43,12 @@ import {UrlSegment, UrlTree} from './url_tree';
* return this.permissions.canActivate(this.currentUser, route.params.id);
* }
* }
* ```
*
* Here, the defined guard function is provided as part of the `Route` object
* in the router configuration:
*
* ```
* @NgModule({
* imports: [
* RouterModule.forRoot([
Expand All @@ -57,7 +64,7 @@ import {UrlSegment, UrlTree} from './url_tree';
* class AppModule {}
* ```
*
* You can alternatively provide a function with the `canActivate` signature:
* You can alternatively provide an in-line function with the `canActivate` signature:
*
* ```
* @NgModule({
Expand Down Expand Up @@ -94,10 +101,12 @@ export type CanActivateFn = (route: ActivatedRouteSnapshot, state: RouterStateSn
* @description
*
* Interface that a class can implement to be a guard deciding if a child route can be activated.
* If all guards return `true`, navigation will continue. If any guard returns `false`,
* navigation will be cancelled. If any guard returns a `UrlTree`, current navigation will
* be cancelled and a new navigation will be kicked off to the `UrlTree` returned from the
* guard.
* If all guards return `true`, navigation continues. If any guard returns `false`,
* navigation is cancelled. If any guard returns a `UrlTree`, current navigation
* is cancelled and a new navigation begins to the `UrlTree` returned from the guard.
*
* The following example implements a `CanActivateChild` function that checks whether the
* current user has permission to activate the requested child route.
*
* ```
* class UserToken {}
Expand All @@ -118,7 +127,12 @@ export type CanActivateFn = (route: ActivatedRouteSnapshot, state: RouterStateSn
* return this.permissions.canActivate(this.currentUser, route.params.id);
* }
* }
* ```
*
* Here, the defined guard function is provided as part of the `Route` object
* in the router configuration:
*
* ```
* @NgModule({
* imports: [
* RouterModule.forRoot([
Expand All @@ -139,7 +153,7 @@ export type CanActivateFn = (route: ActivatedRouteSnapshot, state: RouterStateSn
* class AppModule {}
* ```
*
* You can alternatively provide a function with the `canActivateChild` signature:
* You can alternatively provide an in-line function with the `canActivateChild` signature:
*
* ```
* @NgModule({
Expand Down Expand Up @@ -181,10 +195,12 @@ export type CanActivateChildFn = (childRoute: ActivatedRouteSnapshot, state: Rou
* @description
*
* Interface that a class can implement to be a guard deciding if a route can be deactivated.
* If all guards return `true`, navigation will continue. If any guard returns `false`,
* navigation will be cancelled. If any guard returns a `UrlTree`, current navigation will
* be cancelled and a new navigation will be kicked off to the `UrlTree` returned from the
* guard.
* If all guards return `true`, navigation continues. If any guard returns `false`,
* navigation is cancelled. If any guard returns a `UrlTree`, current navigation
* is cancelled and a new navigation begins to the `UrlTree` returned from the guard.
*
* The following example implements a `CanDeactivate` function that checks whether the
* current user has permission to deactivate the requested route.
*
* ```
* class UserToken {}
Expand All @@ -193,6 +209,12 @@ export type CanActivateChildFn = (childRoute: ActivatedRouteSnapshot, state: Rou
* return true;
* }
* }
* ```
*
* Here, the defined guard function is provided as part of the `Route` object
* in the router configuration:
*
* ```
*
* @Injectable()
* class CanDeactivateTeam implements CanDeactivate<TeamComponent> {
Expand Down Expand Up @@ -223,7 +245,7 @@ export type CanActivateChildFn = (childRoute: ActivatedRouteSnapshot, state: Rou
* class AppModule {}
* ```
*
* You can alternatively provide a function with the `canDeactivate` signature:
* You can alternatively provide an in-line function with the `canDeactivate` signature:
*
* ```
* @NgModule({
Expand Down Expand Up @@ -266,8 +288,11 @@ export type CanDeactivateFn<T> =
*
* Interface that classes can implement to be a data provider.
* A data provider class can be used with the router to resolve data during navigation.
* The interface defines a `resolve()` method that will be invoked when the navigation starts.
* The router will then wait for the data to be resolved before the route is finally activated.
* The interface defines a `resolve()` method that is invoked when the navigation starts.
* The router waits for the data to be resolved before the route is finally activated.
*
* The following example implements a `resolve()` method that retrieves the data
* needed to activate the requested route.
*
* ```
* @Injectable({ providedIn: 'root' })
Expand All @@ -281,7 +306,13 @@ export type CanDeactivateFn<T> =
* return this.service.getHero(route.paramMap.get('id'));
* }
* }
* ```
*
* Here, the defined `resolve()` function is provided as part of the `Route` object
* in the router configuration:
*
* ```

* @NgModule({
* imports: [
* RouterModule.forRoot([
Expand All @@ -299,7 +330,7 @@ export type CanDeactivateFn<T> =
* export class AppRoutingModule {}
* ```
*
* You can alternatively provide a function with the `resolve` signature:
* You can alternatively provide an in-line function with the `resolve()` signature:
*
* ```
* export const myHero: Hero = {
Expand Down Expand Up @@ -328,6 +359,29 @@ export type CanDeactivateFn<T> =
* export class AppModule {}
* ```
*
* @usageNotes
*
* When both guard and resolvers are specified, the resolvers are not executed until
* all guards have run and succeeded.
* For example, consider the following route configuration:
*
* ```
* {
* path: 'base'
* canActivate: [BaseGuard],
* resolve: {data: BaseDataResolver}
* children: [
* {
* path: 'child',
* guards: [ChildGuard],
* component: ChildComponent,
* resolve: {childData: ChildDataResolver}
* }
* ]
* }
* ```
* The order of execution is: BaseGuard, ChildGuard, BaseDataResolver, ChildDataResolver.
*
* @publicApi
*/
export interface Resolve<T> {
Expand All @@ -339,10 +393,13 @@ export interface Resolve<T> {
* @description
*
* Interface that a class can implement to be a guard deciding if children can be loaded.
* If all guards return `true`, navigation will continue. If any guard returns `false`,
* navigation will be cancelled. If any guard returns a `UrlTree`, current navigation will
* be cancelled and a new navigation will be kicked off to the `UrlTree` returned from the
* guard.
* If all guards return `true`, navigation continues. If any guard returns `false`,
* navigation is cancelled. If any guard returns a `UrlTree`, current navigation
* is cancelled and a new navigation starts to the `UrlTree` returned from the guard.
*
* The following example implements a `CanLoad` function that decides whether the
* current user has permission to load requested child routes.
*
*
* ```
* class UserToken {}
Expand All @@ -360,6 +417,12 @@ export interface Resolve<T> {
* return this.permissions.canLoadChildren(this.currentUser, route, segments);
* }
* }
* ```
*
* Here, the defined guard function is provided as part of the `Route` object
* in the router configuration:
*
* ```
*
* @NgModule({
* imports: [
Expand All @@ -377,7 +440,7 @@ export interface Resolve<T> {
* class AppModule {}
* ```
*
* You can alternatively provide a function with the `canLoad` signature:
* You can alternatively provide an in-line function with the `canLoad` signature:
*
* ```
* @NgModule({
Expand Down