[docs] High-level Routing, Navigation and URL overview #76888

Dosant · 2020-09-07T15:47:54Z

Summary

Preview

This pr adds a page that gives a high-level overview of available tools and explains common approaches for handling routing, browser navigation and URL in Kibana.

Such guide is something we were asked for in one of the latest surveys

elasticmachine · 2020-09-07T17:26:44Z

Pinging @elastic/kibana-app-arch (Team:AppArch)

elasticmachine · 2020-09-07T17:26:45Z

Pinging @elastic/kibana-platform (Team:Platform)

pgayvallet

Overall this is a great addition to the documentation.

Some comments, mostly on the fact that the basePath handling seems to have been forgotten in the examples.

docs/developer/best-practices/navigation.asciidoc

Dosant · 2020-09-08T11:08:22Z

Thanks @pgayvallet, I made edits with your suggestions 👍

pgayvallet

Thanks for the changes. LGTM

streamich

LGTM

docs/developer/best-practices/navigation.asciidoc

streamich · 2020-09-10T10:18:49Z

docs/developer/best-practices/navigation.asciidoc

+
+[source,js]
+----
+window.location.href = core.http.basePath.prepend(`/dashboard/my-dashboard`); // (try to avoid this)


For some reason this code block has almost no syntax highlighting:

I wonder if it is how our website is set up or does it has to do with [source,js].

Great example, but I was initially confused because you say "using native browser apis" but part of the example is using core apis.

What if we had the "Deep linking into Kibana Apps" section first, so the user is introduced to the core api core.http.basePath.prepend and what it does and that it should only be used if there isn't a url generator available?

Then you can follow up with this section and I think the user may understand that you are focusing on the window.location.href part of the line.

Could then even write it as:

const discoverUrl = discoverUrlGenerator.createUrl({filters, timeRange}); // Avoid this, as it will cause a full page reload. window.location.href = discoverUrl;

Which focuses in on which is the part to avoid.

docs/developer/best-practices/navigation.asciidoc

streamich · 2020-09-10T10:53:08Z

docs/developer/best-practices/navigation.asciidoc

+----
+
+
+As it would be too much boilerplate to do this for each {kib} link in your app, there is a handy HOC that helps with it: 


Maybe we should not mention RedirectAppLinks in this doc as it is a hack to easily make legacy Kibana URLs work. Or mention that it is a hack and you should not be using it.

It seems we are missing a good way to navigate across Kibana apps, we need a component where one specifies an app and path:

<KbnLink app={'discover'} to={'/foo/bar'}> Click me! </KbnLink>

Maybe in kibana_react we could put a component that can do both, navigate within Kibana app:

import { Link } from 'src/plugins/kibana_react/public'; <Link to={'/foo/bar'} />

and across apps if app prop is specified:

<Link app={'discover'} to={'/foo/bar'} />

I agree that component would makes sense.

RedirectAppLinks still worth a mention. Some places don't have React wired up and you need to make sure your non React links are nested into that component.

Maybe we should not mention RedirectAppLinks in this doc as it is a hack to easily make legacy Kibana URLs work. Or mention that it is a hack and you should not be using it.

Late reply, but RedirectAppLinks is, AFAIK, not a hack, and the current preferred approach. See #58751 for more context and the whole discussion about the various options. The issue is still open for proposals for possible alternative to match other uses cases (the KbnLink was one of them, so I'm totally in favor of adding that though, see #58751 (comment))

docs/developer/best-practices/navigation.asciidoc

stacey-gammon

So much ❤️ for these doc additions!! Thanks @Dosant!

Few nitpicky comments, but overall, LGTM!

docs/developer/best-practices/navigation.asciidoc

stacey-gammon · 2020-09-10T17:10:27Z

docs/developer/best-practices/navigation.asciidoc

+
+[source,js]
+----
+window.location.href = core.http.basePath.prepend(`/dashboard/my-dashboard`); // (try to avoid this)


Great example, but I was initially confused because you say "using native browser apis" but part of the example is using core apis.

What if we had the "Deep linking into Kibana Apps" section first, so the user is introduced to the core api core.http.basePath.prepend and what it does and that it should only be used if there isn't a url generator available?

Then you can follow up with this section and I think the user may understand that you are focusing on the window.location.href part of the line.

Could then even write it as:

const discoverUrl = discoverUrlGenerator.createUrl({filters, timeRange}); // Avoid this, as it will cause a full page reload. window.location.href = discoverUrl;

Which focuses in on which is the part to avoid.

docs/developer/best-practices/navigation.asciidoc

stacey-gammon · 2020-09-10T17:31:16Z

docs/developer/best-practices/navigation.asciidoc

+**When you should consider using state syncing utils:**
+
+* You want to sync your application state with URL in similar manner Analyze group applications do.
+* You want to follow platform's <<history-and-location, working with browser history and location best practices>> out of the box. 


I don't follow this one. I don't see State Syncing utils, or the _a and _g format used in any of the documentation links for ScopedHistory:

https://github.com/elastic/kibana/blob/master/docs/development/core/public/kibana-plugin-core-public.appmountparameters.history.md

https://github.com/elastic/kibana/blob/master/test/plugin_functional/plugins/core_plugin_a/public/application.tsx#L120

https://github.com/elastic/kibana/blob/master/docs/development/core/public/kibana-plugin-core-public.scopedhistory.md

So seems like I can use ScopedHistory without using any state syncing utils directly? Or am I missing something?

So seems like I can use ScopedHistory without using any state syncing utils directly?

Exactly!

ScopedHistory is a core's wrapper around browser's navigation and history apis.

Whenever you want to use window.location or window.history, you should consider using core's ScopeHistory instead. (for example, reading / writing query params, updating path, etc..)

You can use it for listening to location changes. You can't do it with native apis. (Native api's are limited and support only popState or hashChange)

You should initialize your app's react router with it.

And you should initialize state state syncing utils with it! So inside state syncing utils are using core's history instance, instead of browser's api's directly

stacey-gammon · 2020-09-10T17:34:04Z

src/plugins/kibana_utils/docs/state_sync/README.md

+
+- You want to sync your application state with URL in similar manner analyze applications do that.
+- You want to follow platform's <<history-and-location, working with browser history and location best practices>> out of the box.
+- You want to support `state:storeInSessionStore` escape hatch for URL overflowing out of the box.


So state:storeInSessionStore relies on _a and _g parameters in the URL?

No, not really.

When using state syncing utils (with kbnUrlStateStorage to be precise) you can configure your state to be synced to any query key. You can also set it up to sync only hash into URL. This is covered in docs of stateSync, which is linked from this general guide: https://github.com/elastic/kibana/blob/master/src/plugins/kibana_utils/docs/state_sync/storages/kbn_url_storage.md#setting-url-format-option

cjcenizal

Thanks so much for writing this up! I read through the preview, but wasn't as thorough as I could have been. I did find one formatting error.

docs/developer/best-practices/navigation.asciidoc

kibanamachine · 2020-09-15T11:44:54Z

💚 Build Succeeded

continuous-integration/kibana-ci/pull-request
Commit: 1e55aa5

Build metrics

distributable file count

id	value	diff	baseline
default	45548	+1	45547
oss	27225	+1	27224
total		+2

History

💚 Build #74129 succeeded 01f3354
💚 Build #74123 succeeded 9ac8bda

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

Dosant added 2 commits September 7, 2020 17:46

overview around navigation

664e09b

update

ccf7ed1

Dosant added docs Feature:New Platform Feature:StateManagement release_note:skip Skip the PR/issue when compiling release notes Team:AppArch Team:Core Core services & architecture: plugins, logging, config, saved objects, http, ES client, i18n, etc v7.10.0 v8.0.0 labels Sep 7, 2020

wip

9c8272d

Dosant changed the title ~~overview around navigation~~ [docs] Routing, Navigation and URL guide Sep 7, 2020

Dosant changed the title ~~[docs] Routing, Navigation and URL guide~~ [docs] High-level Routing, Navigation and URL overview Sep 7, 2020

Dosant added 2 commits September 7, 2020 18:41

improve

cb40bfd

fix

7c9676e

Dosant marked this pull request as ready for review September 7, 2020 17:26

Dosant requested a review from a team as a code owner September 7, 2020 17:26

Dosant requested review from stacey-gammon and a team September 7, 2020 17:26

pgayvallet reviewed Sep 8, 2020

View reviewed changes

Dosant added 2 commits September 8, 2020 12:31

Merge branch 'master' of github.com:elastic/kibana into docs/url

cc6d767

@pgayvallet review

1ca84bc

fix

3505bed

Dosant requested a review from pgayvallet September 8, 2020 13:02

pgayvallet approved these changes Sep 10, 2020

View reviewed changes

streamich approved these changes Sep 10, 2020

View reviewed changes

Dosant added 2 commits September 10, 2020 15:53

Merge branch 'master' of github.com:elastic/kibana into docs/url

37d9c4e

improve

6d4dd05

stacey-gammon reviewed Sep 10, 2020

View reviewed changes

Dosant added 4 commits September 14, 2020 14:29

Merge branch 'master' of github.com:elastic/kibana into docs/url

a64e376

@stacey-gammon suggestions

8e32bfa

improve TOC

9ac8bda

fix broken URL

01f3354

This was referenced Sep 14, 2020

[Meta] Developer Url & linking documentation & guidelines #69806

Closed

Plugin URLs should be part of the plugin's contract #66682

Open

cjcenizal reviewed Sep 14, 2020

View reviewed changes

docs/developer/best-practices/navigation.asciidoc Show resolved Hide resolved

Dosant added 2 commits September 15, 2020 11:58

Merge branch 'master' of github.com:elastic/kibana into docs/url

99bd668

fix formatting

1e55aa5

Dosant merged commit ba4d4a9 into elastic:master Sep 15, 2020

Dosant added a commit to Dosant/kibana that referenced this pull request Sep 15, 2020

[docs] High-level Routing, Navigation and URL overview (elastic#76888)

07a8c1a

Dosant mentioned this pull request Sep 15, 2020

[7.x] [docs] High-level Routing, Navigation and URL overview (#76888) #77468

Merged

Dosant added a commit that referenced this pull request Sep 15, 2020

[docs] High-level Routing, Navigation and URL overview (#76888) (#77468)

02a40a6

Dosant mentioned this pull request Sep 29, 2020

Update documentation for kibana_react #72432

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs] High-level Routing, Navigation and URL overview #76888

[docs] High-level Routing, Navigation and URL overview #76888

Dosant commented Sep 7, 2020 •

edited

Loading

elasticmachine commented Sep 7, 2020

elasticmachine commented Sep 7, 2020

pgayvallet left a comment

Dosant commented Sep 8, 2020

pgayvallet left a comment

streamich left a comment

streamich Sep 10, 2020 •

edited

Loading

stacey-gammon Sep 10, 2020

streamich Sep 10, 2020

streamich Sep 10, 2020 •

edited

Loading

Dosant Sep 10, 2020 •

edited

Loading

pgayvallet Sep 16, 2020 •

edited

Loading

stacey-gammon left a comment

stacey-gammon Sep 10, 2020

stacey-gammon Sep 10, 2020

Dosant Sep 14, 2020

stacey-gammon Sep 10, 2020

Dosant Sep 14, 2020

cjcenizal left a comment

kibanamachine commented Sep 15, 2020

		----


		As it would be too much boilerplate to do this for each {kib} link in your app, there is a handy HOC that helps with it:

[docs] High-level Routing, Navigation and URL overview #76888

[docs] High-level Routing, Navigation and URL overview #76888

Conversation

Dosant commented Sep 7, 2020 • edited Loading

Summary

elasticmachine commented Sep 7, 2020

elasticmachine commented Sep 7, 2020

pgayvallet left a comment

Choose a reason for hiding this comment

Dosant commented Sep 8, 2020

pgayvallet left a comment

Choose a reason for hiding this comment

streamich left a comment

Choose a reason for hiding this comment

streamich Sep 10, 2020 • edited Loading

Choose a reason for hiding this comment

stacey-gammon Sep 10, 2020

Choose a reason for hiding this comment

streamich Sep 10, 2020

Choose a reason for hiding this comment

streamich Sep 10, 2020 • edited Loading

Choose a reason for hiding this comment

Dosant Sep 10, 2020 • edited Loading

Choose a reason for hiding this comment

pgayvallet Sep 16, 2020 • edited Loading

Choose a reason for hiding this comment

stacey-gammon left a comment

Choose a reason for hiding this comment

stacey-gammon Sep 10, 2020

Choose a reason for hiding this comment

stacey-gammon Sep 10, 2020

Choose a reason for hiding this comment

Dosant Sep 14, 2020

Choose a reason for hiding this comment

stacey-gammon Sep 10, 2020

Choose a reason for hiding this comment

Dosant Sep 14, 2020

Choose a reason for hiding this comment

cjcenizal left a comment

Choose a reason for hiding this comment

kibanamachine commented Sep 15, 2020

💚 Build Succeeded

Build metrics

distributable file count

History

Dosant commented Sep 7, 2020 •

edited

Loading

streamich Sep 10, 2020 •

edited

Loading

streamich Sep 10, 2020 •

edited

Loading

Dosant Sep 10, 2020 •

edited

Loading

pgayvallet Sep 16, 2020 •

edited

Loading