Dmitrii Filippov | daf0ec9 | 2020-03-17 11:27:28 +0100 | [diff] [blame] | 1 | /** |
| 2 | * @license |
Ben Rohlfs | 94fcbbc | 2022-05-27 10:45:03 +0200 | [diff] [blame] | 3 | * Copyright 2017 Google LLC |
| 4 | * SPDX-License-Identifier: Apache-2.0 |
Dmitrii Filippov | daf0ec9 | 2020-03-17 11:27:28 +0100 | [diff] [blame] | 5 | */ |
Ben Rohlfs | 77c489a | 2022-09-21 14:25:56 +0200 | [diff] [blame] | 6 | import {define} from '../../../models/dependency'; |
Wyatt Allen | 797480f | 2017-06-08 09:20:46 -0700 | [diff] [blame] | 7 | |
Ben Rohlfs | 77c489a | 2022-09-21 14:25:56 +0200 | [diff] [blame] | 8 | export const navigationToken = define<NavigationService>('navigation'); |
| 9 | |
| 10 | export interface NavigationService { |
| 11 | /** |
| 12 | * This is similar to letting the browser navigate to this URL when the user |
Ben Rohlfs | 90b2b7d | 2024-03-13 08:42:32 +0100 | [diff] [blame] | 13 | * clicks it, or to just calling `window.location.assign()` directly. |
| 14 | * |
| 15 | * CAUTION: You should actually use `window.location.assign()` directly for |
| 16 | * URLs that are not handled by gr-router. Otherwise we will call |
| 17 | * `pushState()` and then `window.location.reload()` from the router, which |
| 18 | * will break the browser's back button. |
Ben Rohlfs | 77c489a | 2022-09-21 14:25:56 +0200 | [diff] [blame] | 19 | * |
| 20 | * This adds a new entry to the browser location history. Consier using |
| 21 | * `replaceUrl()`, if you want to avoid that. |
| 22 | * |
| 23 | * page.show() eventually just calls `window.history.pushState()`. |
| 24 | */ |
| 25 | setUrl(url: string): void; |
| 26 | |
| 27 | /** |
| 28 | * Navigate to this URL, but replace the current URL in the history instead of |
| 29 | * adding a new one (which is what `setUrl()` would do). |
| 30 | * |
Ben Rohlfs | 90b2b7d | 2024-03-13 08:42:32 +0100 | [diff] [blame] | 31 | * CAUTION: You should actually use `window.location.replace()` directly for |
| 32 | * URLs that are not handled by gr-router. Otherwise we will call |
| 33 | * `replaceState()` and then `window.location.reload()` from the router, which |
| 34 | * will break the browser's back button. |
| 35 | * |
Ben Rohlfs | 77c489a | 2022-09-21 14:25:56 +0200 | [diff] [blame] | 36 | * page.redirect() eventually just calls `window.history.replaceState()`. |
| 37 | */ |
| 38 | replaceUrl(url: string): void; |
Ben Rohlfs | f665736 | 2023-04-12 14:01:35 +0200 | [diff] [blame] | 39 | |
| 40 | /** |
| 41 | * You can ask the router to block all navigation to other pages for a while, |
| 42 | * e.g. while there are unsaved comments. You must make sure to call |
| 43 | * `releaseNavigation()` with the same string shortly after to unblock the |
| 44 | * router. |
| 45 | * |
| 46 | * The provided reason must be non-empty. |
| 47 | */ |
| 48 | blockNavigation(reason: string): void; |
| 49 | |
| 50 | /** |
| 51 | * See `blockNavigation()`. |
| 52 | * |
| 53 | * This API is not counting. If you block navigation with the same reason |
| 54 | * multiple times, then one release call will unblock. |
| 55 | */ |
| 56 | releaseNavigation(reason: string): void; |
Ben Rohlfs | 77c489a | 2022-09-21 14:25:56 +0200 | [diff] [blame] | 57 | } |