Skip to content

Commit 8c8466c

Browse files
atscottatscott
committed
docs(router): Clarify how to clear secondary routes
The example for clearing secondary outlets currently only works because the named outlet appears at the root of the application's route config. If developers follow this example with an outlet that is not at the root level, they will not be able to close the outlet. This commit updates the example to provide a more robust way of clearing the outlet from the activated outlet component as well as providing a warning about how the commands are applied. Lastly, there is a small bit of guidance provided for developers who might want to explore the ability to close an outlet from any location in the app, without needing to be aware of the activated route. An example of this can be found here: https://stackblitz.com/edit/close-outlet-from-anywhere resolves angular#13523
1 parent d7665fd commit 8c8466c

2 files changed

Lines changed: 27 additions & 4 deletions

File tree

‎aio/content/examples/router/src/app/compose-message/compose-message.component.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
// #docregion
2-
import { Component, HostBinding } from '@angular/core';
3-
import { Router } from '@angular/router';
2+
import {Component} from '@angular/core';
3+
import {ActivatedRoute, Router} from '@angular/router';
44

55
@Component({
66
selector: 'app-compose-message',
@@ -12,7 +12,7 @@ export class ComposeMessageComponent {
1212
message: string;
1313
sending = false;
1414

15-
constructor(private router: Router) {}
15+
constructor(private router: Router, private route: ActivatedRoute) {}
1616

1717
send() {
1818
this.sending = true;
@@ -32,7 +32,7 @@ export class ComposeMessageComponent {
3232
closePopup() {
3333
// Providing a `null` value to the named outlet
3434
// clears the contents of the named outlet
35-
this.router.navigate([{ outlets: { popup: null }}]);
35+
this.router.navigate([{outlets: {popup: null}}], {relativeTo: this.route.parent});
3636
}
3737
// #enddocregion closePopup
3838
}

‎aio/content/guide/router-tutorial-toh.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1884,6 +1884,29 @@ This time, the value of `'popup'` is `null`.
18841884
That's not a route, but it is a legitimate value.
18851885
Setting the popup `RouterOutlet` to `null` clears the outlet and removes the secondary popup route from the current URL.
18861886

1887+
<div class="alert is-critical">
1888+
1889+
**Note:** All commands in the array passed to `Router.navigate()` target a _specific segment_ in the `UrlTree`.
1890+
We specify the parent of the `ActivatedRoute` as the `relativeTo` option because we want to remove `'popup'` from the segment which holds its reference.
1891+
It's important to always be aware of which segments the commands will be applied to.
1892+
1893+
</div>
1894+
1895+
<div class="alert is-helpful">
1896+
1897+
When `relativeTo` is not provided to the `Router.navigate()` method, the commands are processed starting at the root.
1898+
We could omit the `relativeTo` option in this particular example because the `'popup'` outlet appears at the root level of the configuration.
1899+
1900+
</div>
1901+
1902+
<div class="alert is-helpful">
1903+
1904+
If you want to close an outlet which appears at any segment depth, you could accomplish
1905+
this by creating a `UrlTree` from the current URL, recursively clearing segment `children` matching the outlet name, and finally
1906+
calling `Router.navigateByUrl()` with the `root` segment of the current `UrlTree`.
1907+
1908+
</div>
1909+
18871910
{@a guards}
18881911

18891912
{@a milestone-5-route-guards}

0 commit comments

Comments
 (0)