Optionally update URLs on Frame navigation and stream responses

[bfitch]

Adds the ability for Turbo Frames to update the URL on link navigation and in response to form submissions. Also, enables updating the URL in Turbo Stream responses.

Frame Navigation

If a frame has a link with the data attribute data-turbo-history, when clicked, it will update window.location via pushState or replaceState. For example:

<turbo-frame id="history">
  <a href="/messages" data-turbo-history>Show Messages</a>
</turbo-frame>

will update the url to /messages.

You can also manually override the URL to whatever value you may need:

<turbo-frame id="history">
 <a href="/messages" data-turbo-history-url="/special-messages">Show messages</a>
</turbo-frame>

updates the url to /special-messages.

To update the URL with replaceState, add "replace" as the attribute value:

<turbo-frame id="history">
  <a href="/messages" data-turbo-history="replace">History frame</a>
</turbo-frame>

replaces the current url with /messages.

Frame Form Submission

The same data attributes can be added to form elements. URLs will either match the form's action attribute or any redirect URLs from the server:

<turbo-frame>
  <form action="/messages" method="post" data-turbo-history>
    <input type="submit">
  </form>
</turbo-frame>

will update the URL to /messages. Or if the server redirects, for example to /messages/3, the redirected URL will be displayed instead.

Note: URL's can also be updated by forms and links outside frames that render into frame elements with data-turbo-frame="<frame_id>".

Stream Rendering

The same data attributes can be used to update the URL in response to <turbo-stream> responses:

<turbo-stream action="prepend" target="messages" data-turbo-history-url="/messages/2>
  <template>Message 2</template>
</turbo-stream>

appends message 2 to the messages list and updates the URL to messages/2.

---

Prior Issues and Discussion

• Push state and updating URLs with Turbo Frames #50
• https://discuss.hotwire.dev/t/sidebar-or-navigation-bar-with-hotwire-turbo/1740/13
• https://discuss.hotwire.dev/t/routing-in-a-modal-interface/2071
• https://discuss.hotwire.dev/t/turbo-frames-with-browser-destination-url-replacement/1552/7
• https://discuss.hotwire.dev/t/search-as-you-type-with-turbo/2232/9
• https://discuss.hotwire.dev/t/how-to-change-current-url/1846

[bfitch]

@seanpdoyle Any thoughts on this PR? I know you and the team are all busy and I have no expectation that this would be merged in as is without discussion, but I'm curious to hear what you think.

• Does this feature fit with the team's goals for Hotwire?
• Are there any concerns about this implementation?

I'm open to any changes you might want to make, both technically and as a feature, to get this merged in (if you think it's valuable, of course).

Thanks for your hard work on this library 🙏

[seanpdoyle]

Does this feature fit with the team's goals for Hotwire?

As I understand it: Yes, this is something we've discussed and are intent on supporting in some form.

Are there any concerns about this implementation?

We're still not sure what the surface area of this "API" should be, and what is the best way for consumers to interact with it.

I'm not sure whether or not there will ever be support for changing the URL with <turbo-stream> updates, but the <turbo-frame> use case feels appropriate.

There are also some additional considerations that somewhat straddle the framework-application divide that still need to be hashed out: what happens when you refresh the page after a turbo-frame drives the URL? What happens when you navigate with back/forward? Does a turbo-frame-powered navigation update that URL's Snapshot cache? My gut tells me that those are mostly application-level concerns, but I'm not sure if there are sufficient framework level hooks to support those circumstances.

In the short term, I think that turbo:frame-render or turbo:frame-load events (#59) will enable consumers to wire up their own versions of this (like pushing to the history stack like you've done here). I suspect that will ship in some form in the next beta release.

Any built-in support for this will likely require that FrameElement and FrameController drive frames with Visit and Navigator instances, and that will require some internal re-structuring work.

[bfitch]

Thanks @seanpdoyle.

what happens when you refresh the page after a turbo-frame drives the URL?

It initiates a full page reload for that URL/route. So, if you refresh on /messages/2/edit it will return a full page HTML response (application layout and the messages/edit template).

What happens when you navigate with back/forward?

Right now, same as above.

Does a turbo-frame-powered navigation update that URL's Snapshot cache?

That is a great question and one I was hoping someone on the core team could help me think about and implement. TBH, I don't fully understand the full logic around snapshots/visits and caching. If this could hook into Turbo Drive's snapshot functionality, that would be awesome.

My gut tells me that those are mostly application-level concerns

That's my feeling as well. For example, previously (before some changes to the turbo accept request headers, I believe) I was able to avoid a full layout re-render by including:

layout -> { turbo_frame_request? ? false : "application" }

in my ApplicationController. That made navigating by forward/back button very similar to "normal" frame navigation.

---

The main reason I want to update the URL with frame/stream navigation is so I can synchronize as much of the browser UI state with the server as possible, while also performing the minimum amount of DOM manipulation. Basically to make Hotwire feel as good as the best SPAs.

For example, in this view:

I want to capture:

• the text "ank" in the search field, providing an active filter for the messages list
• that message 43 ("slank") is highlighted/selected in the sidebar
• Message 43 is being edited with a form in the main content area
• Message 43's attributes are displayed in the form

Ideally, I can navigate to this UI state with one server request and one DOM update from a turbo frame navigation (by clicking on the message in the sidebar). But, crucially, I can also render this state from a "normal" server side rendered template, by following an external link or refreshing the browser, etc.

In my experience so far, having the URL capture as much of the UI state as possible has been an extremely powerful pattern for allowing Hotwire to update the page with the minimal amount of changes, while also not breaking normal server rendering, and providing a user experience as snappy and smooth as the best SPA's.

Anyway, all that is to say, I'm really motivated to continue pushing this forward and to see how far Hotwire can take this paradigm. Exciting times.

[aviflombaum]

I'm a fan of this functionality. It's going to get implemented as extensions/plugins anyway and I think it has a valid use-case. @bfitch example of a still document-centric interface that has multiple independent frames but where one functions as a main frame where you'd want navigating it to update pushState makes total sense. I think the HTML attribute data-turbo-history is a fine metadata attribute to add to enable this functionality. Happy to help if needed.

[seanpdoyle]

Maybe declaring data-turbo-action on the frame element or the form/link driving it would be a more appropriate data attribute interface, since that's already supported for page-level links.

Conceptually, top level navigations default to data-turbo-action="advance", and frames default to data-turbo-action="replace" (since they don't have a history of their own). To support this, we'd likely have to make the Navigator frame-aware, and retain references of the frame elements that push onto the applications History stack.

[bfitch]

Maybe declaring data-turbo-action on the frame element or the form/link driving it would be a more appropriate data attribute interface, since that's already supported for page-level links.

That sounds like a good option to me @seanpdoyle. So, with that attribute interface:

<turbo-frame id="suff" data-turbo-action>
  <a href="/messages">Show Messages</a>
</turbo-frame>

would render messages into the fram and update the url to /messages?

I assume this approach could also handle form submissions/redirects and we could still make it work with forms and links outside frames that render into frame elements with data-turbo-frame="<frame_id>?

To support this, we'd likely have to make the Navigator frame-aware, and retain references of the frame elements that push onto the applications History stack.

I hope this wouldn't be a huge lift to implement, but that sounds exactly right to me. Unifying navigation across pages and visits and frame navigation sounds like the right direction.

[aviflombaum]

Love that @bfitch - I would probably break it into 2 - first implement the attribute then allow it to actually specify target. If we get consensus that this would be desired behavior I'm happy to pair with someone on implementing it based on the already very good work submitted in this PR.

[perlun]

@bfitch Thanks for your effort on this one. 🙏 We're currently trying it out in our app. (I built a custom version of the dist based on your branch for now.)

One thing that would be nice would be to get the PR rebased on top of the latest release. Right now, it's based on beta 4 (if I get it right) and we're hitting some issues which I think is fixed in beta 5 (the Turbo-Frame header is missing on the first form submission but present on subsequent ones - I'm hoping this is #86, #110 or #166 we're seeing).

Can it be done? 😇

[MACscr]

this is definitely one of my top needs as well.

[trsteel88]

Has there been any progress on this @bfitch or @seanpdoyle? This looks like it would be really helpful.

I have a turbo frame which filters results and I need the URL to update so a user can copy and paste that filter (or see the updated results if they navigate their history).

I played around with using Turbo.visit(). However, this always resets the page back to the top which means the user has to scroll back down after filtering.

[tomek1024]

I would very welcome this feature

[kstratis]

This one looks super helpful!
Any updates at all...?

cc @bfitch @seanpdoyle

[seanpdoyle]

I've opened #398 as an alternative, based off of #167 (comment).

[aviflombaum]

Awesome!!!

[pySilver]

If anyone is looking for a workaround to manage history from stream response, check this one: #792