blob: 3d21e07d92c24112d108c93e263efb5cfedf7bcb [file] [log] [blame]
Dmitrii Filippovdaf0ec92020-03-17 11:27:28 +01001/**
2 * @license
Ben Rohlfs94fcbbc2022-05-27 10:45:03 +02003 * Copyright 2017 Google LLC
4 * SPDX-License-Identifier: Apache-2.0
Dmitrii Filippovdaf0ec92020-03-17 11:27:28 +01005 */
Ben Rohlfs77c489a2022-09-21 14:25:56 +02006import {define} from '../../../models/dependency';
Wyatt Allen797480f2017-06-08 09:20:46 -07007
Ben Rohlfs77c489a2022-09-21 14:25:56 +02008export const navigationToken = define<NavigationService>('navigation');
9
10export interface NavigationService {
11 /**
12 * This is similar to letting the browser navigate to this URL when the user
Ben Rohlfs90b2b7d2024-03-13 08:42:32 +010013 * 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 Rohlfs77c489a2022-09-21 14:25:56 +020019 *
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 Rohlfs90b2b7d2024-03-13 08:42:32 +010031 * 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 Rohlfs77c489a2022-09-21 14:25:56 +020036 * page.redirect() eventually just calls `window.history.replaceState()`.
37 */
38 replaceUrl(url: string): void;
Ben Rohlfsf6657362023-04-12 14:01:35 +020039
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 Rohlfs77c489a2022-09-21 14:25:56 +020057}