Skip to content

Commit

Permalink
[docs] Adds paragraphs on inter-app navigation with application servi…
Browse files Browse the repository at this point in the history
  • Loading branch information
TinaHeiligers authored Apr 5, 2022
1 parent 735b4c9 commit 3bb27f2
Show file tree
Hide file tree
Showing 3 changed files with 47 additions and 1 deletion.
22 changes: 22 additions & 0 deletions dev_docs/key_concepts/navigation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,10 @@ To navigate between different Kibana apps without a page reload there are APIs i
* [core.application.navigateToApp](https://github.com/elastic/kibana/blob/main/docs/development/core/public/kibana-plugin-core-public.applicationstart.navigatetoapp.md)
* [core.application.navigateToUrl](https://github.com/elastic/kibana/blob/main/docs/development/core/public/kibana-plugin-core-public.applicationstart.navigatetourl.md)

Both methods offer customization such as opening the target in a new page, with an `options` parameter. All the options are optional be default.
* [core.application.navigateToApp options](https://github.com/elastic/kibana/blob/main/docs/development/core/public/kibana-plugin-core-public.navigatetoappoptions.md)
* [core.application.navigateToUrl options](https://github.com/elastic/kibana/blob/main/docs/development/core/public/kibana-plugin-core-public.navigatetourloptions.md)

*Rendering a link to a different app on its own would also cause a full page reload:*

```jsx
Expand Down Expand Up @@ -124,6 +128,24 @@ const MyApp = () =>
</RedirectAppLinks>
```

NOTE: There may be cases where you need a full page reload. While rare and should be avoided, rather than implement your own navigation,
you can use the `navigateToUrl` `forceRedirect` option.

```tsx
const MyForcedPageReloadLink = () =>
<a
href={urlToSomeSpecialApp}
onClick={(e) => {
e.preventDefault();
core.application.navigateToUrl('someSpecialApp', { forceRedirect: true });
}}
>
Go to Some Special App
</a>;
```

If you also need to bypass the default onAppLeave behavior, you can set the `skipUnload` option to `true`. This option is also available in `navigateToApp`.

## Setting up internal app routing

It is very common for Kibana apps to use React and React Router.
Expand Down
25 changes: 24 additions & 1 deletion docs/developer/best-practices/navigation.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -85,11 +85,15 @@ const urlToADashboard = core.http.basePath.prepend(`/dashboard/my-dashboard`);
window.location.href = urlToADashboard;
----

To navigate between different {kib} apps without a page reload there are APIs in `core`:
To navigate between different {kib} apps without a page reload (by default) there are APIs in `core`:

* {kib-repo}tree/{branch}/docs/development/core/public/kibana-plugin-core-public.applicationstart.navigatetoapp.md[core.application.navigateToApp]
* {kib-repo}tree/{branch}/docs/development/core/public/kibana-plugin-core-public.applicationstart.navigatetourl.md[core.application.navigateToUrl]

Both methods offer customization such as opening the target in a new page, with an `options` parameter. All the options are optional be default.
* {kib-repo}tree/{branch}/docs/development/core/public/kibana-plugin-core-public.navigatetoappoptions.md[core.application.navigateToApp options]
* {kib-repo}tree/{branch}/docs/development/core/public/kibana-plugin-core-public.navigatetourloptions.md[core.application.navigateToUrl options]

*Rendering a link to a different {kib} app on its own would also cause a full page reload:*

[source,typescript jsx]
Expand Down Expand Up @@ -128,6 +132,25 @@ const MyApp = () =>
</RedirectAppLinks>
----

NOTE: There may be cases where you need a full page reload. While rare and should be avoided, rather than implement your own navigation,
you can use the `navigateToUrl` `forceRedirect` option.

[source,typescript jsx]
----
const MyForcedPageReloadLink = () =>
<a
href={urlToSomeSpecialApp}
onClick={(e) => {
e.preventDefault();
core.application.navigateToUrl('someSpecialApp', { forceRedirect: true });
}}
>
Go to Some Special App
</a>;
----

If you also need to bypass the default onAppLeave behavior, you can set the `skipUnload` option to `true`. This option is also available in `navigateToApp`.

[[routing]]
=== Setting up internal app routing

Expand Down
1 change: 1 addition & 0 deletions src/core/public/application/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -821,6 +821,7 @@ export interface ApplicationStart {
* ```
*
* @param url - an absolute URL, an absolute path or a relative path, to navigate to.
* @param options - navigation options
*/
navigateToUrl(url: string, options?: NavigateToUrlOptions): Promise<void>;
/**
Expand Down

0 comments on commit 3bb27f2

Please sign in to comment.