The navigation/client-side story

[josevalim]

This issue describes the steps we need to take to improve the navigation story with LiveView. For example, if you have a LiveView with three tabs and you want to change the URL when the user clicks on those tabs. Or, if you are navigating a table, you want to paginate or order it and annotate where in the table you are.

Ideally, we want to keep those as regular links, especially since the initial LiveView render is meant to be indexed, used for SEO, and what not. This proposal does keep the links as is, all you need to do is to add a new attribute called phx-live-route=true (or phx-route or something else to be determined).

When the link is clicked and phx-live-route is set, we will submit the link HREF to the root LiveView through WebSockets. The root LiveView will run the path against the router and act accordingly:

1. If it points to the same LiveView as the one currently running, we will call handle_params(params, socket)

2. If it points to the another LiveView, will transition to it and mount it

3. If it does not point to a LiveView, we will emit an error from the server and let the event go through in the browser, effectively clicking the link

In order to implement this, we need the following changes:

1. On disconnected mount, we need to store the phoenix router in the static session

2. On connected mount, we will send the full browser URL. path_parameters will no longer be passed as part of the session. Instead we will pass them alongside the parsed query string to the optional handle_params/2 callback, which should be invoked after mount and before render. handle_params/2 should be called on both connected and disconnected mount.

3. For future route matching, we need to store both the phoenix router and the current host in the socket (since the link may be a relative link and the router can match on hosts)

FAQ

Q: What if there are two LiveViews at the root?

A: We will provide a mechanism to specify which one of the two is the root.

Q: What if there are two routes pointing to the same LiveView?

A: We said "If it points to the same LiveView as the one currently running" but we need to specify what the same LiveView means. Is it the same name? Is it the same route? Is it the same session? I would say the same name is fine, at least for a starting point, but we need to keep in mind that the same LiveView can be mounted with different session keys or even the same session keys have changed.

[hubertlepicki]

I think this is way more reasonable than the original proposal and will save programmers trouble when using this model. One question, however:

If it points to the another LiveView, will transition to it and mount it

I suppose this means leaving everything outside LiveView intact? As in, I have a web site that has a sidebar, header etc, and LiveView root mounted in the main page content. The only item that would change is the main page content, right? If I wanted to transition everything, I would put everything into a LiveView. I am okay with that just checking how it'll work.

[josevalim]

I suppose this means leaving everything outside LiveView intact?

Yes!

--

*José Valimwww.plataformatec.com.br <http://www.plataformatec.com.br/>Founder and Director of R&D*

[hubertlepicki]

❤️

[chrismccord]

Closed via #239

Q: What if there are two LiveViews at the root?

The first one that appears in the DOM wins

We will provide a mechanism to specify which one of the two is the root.

no longer planned

Q: What if there are two routes pointing to the same LiveView?

This is now handled properly since we use path based routing and look up the route information. See the live_redirect docs for examples. Thanks everyone!