Advanced htmx: hx-push-url and hx-replace-url
So So we're going to start off season 2 with a big one, h x push URL. And, actually, I'll just include h x replace URL because it's kinda just a subset. They're very similar, but I'll explain it a little bit, but just include these together. So both are accessing your URL bar. So they're part of the bigger sort of HTMLX browser controls.
Lazarus:They let you sort of tap into what your browser can do. We talked about this a little bit with HX boost which, you know, turns all your links, your regular links, into AJAX links and then swaps out the body. So push URL seems kind of simple. Right? This so h x boost will will replace the URL up the top, so that does something similar.
Lazarus:H x push URL lets you push anything up to your URL bar. So as you load something, you load something in, and then you can just, along with that, give the browser as if this was a link, you know, as if this was something that you had clicked, it just pushes a new URL up to the URL bar. And h x push URL accepts either true or false. And the reason you do false you know, everything's false by default. Nothing's getting pushed to the URL if you don't choose to.
Lazarus:But it is inherited from above. So if you put h x x push URL at the top, the top equals true, then it will push the URL for all your h x gets. So if you then want to put that at the top of your in the, you know, the top of your DOM tree, you can then put false to turn that off for different things. But, usually, you're just gonna put it on sort of a single thing and set it to true. So if you use true, it will replace the URL in the u r with the URL that's in your request.
Lazarus:So h x get equals whatever that URL is, it will put that in there. You can also, instead of putting true, you can specify a specific URL to use. So if it say, it doesn't match the h x get for whatever reason, you can just do an h x push URL. So let's say you go to /account. Right?
Lazarus:You're just you're you're on the account page, and you want to have a click that shows you all the details of a certain part of the account. So you can add h x push URL equals slash account slash details. So now when you click to show more about those account details, it is putting up in the URL bar that account details, but it's doing more than just putting it up in the URL bar. It's also it's taking a full snapshot of your DOM before you click that, so that you can now press the back button and go back, and you'll go back to just slash account, and you'll also go back to your DOM state before. So it's really tapping into that browser history.
Lazarus:This solves one of the major problems with changing your page through AJAX. So you all probably experienced this. You have a page that uses AJAX, you're updating things, you're changing things, You you make a little change, and and you you go you do something, and you want to go back. You've like, you sort of are thinking of this as like, well, I've made a change. I want to go to the previous page.
Lazarus:You press the back button, and it goes back to the page you were at 20 pages ago because you were actually only in one page ever. You were in that same place. So this h x push URL really solves that problem, of the back button by taking the snapshot of your DOM and adding it to your browser history. The previous state is right there. And the reason I think we can include replace URL in the same, it does the same thing, but rather than creating a snapshot and just adding it like a stack onto the browser history, it replaces your current history item.
Lazarus:So you lose the previous state, but if you were to refresh or something your new state stays in the same place. But we'll come back to that refresh in a minute. So there's some very powerful browser controls here, and I think this is sort of an essential kind of, building block of htmx. So, you know, kind of gets top billing for season 2. Now, the reason that this was not included in the basics, it sounds kind of basic, right?
Lazarus:You can just kind of like it's in the simple, just true false, or you put a URL and you push it. Everyone loves their back buttons. Everybody wants to be able to do this. This is a nice thing. So this could this would have been a basic, and I almost actually recorded it and had to delete it because there's there's a gotcha.
Lazarus:Consider the example. You have loaded a partial to the page, right? So this will just use the account and then the account slash details again. So you've clicked the account details. You've done h x push URL for account slash details.
Lazarus:That's all good. So it loads that partial. The partial is just a little bit of HTML that has the details in it. You can use the back button, you go back to the regular account. You can use the forward button, you go back to account details.
Lazarus:We're all good. Everything's good. What happens when you're on account slash details and you refresh the page? So first thought is this route is meant to just return partial HTML. So you refresh the page, you're just going to get partial HTML.
Lazarus:You're going to lose your whole page. You're just going to get that little snippet that's part of the details, right? That's the default behavior. So if you just consider it as a simple thing and you just start using it, you're going to get into this problem. You're going to refresh the page.
Lazarus:Things are going to disappear. It's going to look really weird. It's going to be bad. If you send someone that URL, check out the account details page. Just gonna get an HTML snippet.
Lazarus:Right? That's how we're doing this. That's how HTMLX is working. We're taking these snippets and we're putting them in different places in the page. So you have to account for this.
Lazarus:That's why this is in the advanced section. You have to account for this on the server side. You have to have conditional responses for that URL. So if it comes from an HTMLX request, like whatever it was that initially populated, that slash account slash details, you have to return the partial. If it came from a non h tmx request, just a regular server request, which is what happens when you refresh the page or when you send someone a link, It just loads the page as a standard page, right?
Lazarus:It's not an AJAX request, it's not an HTMLX request. Then you need to show the full page, you need to show the account details, but also you need to show the account, you need to show the app, you need to load everything. So there's a conditional thing in there. It's the same route and based on the headers. So there's probably some different options in how to do this, but I think the most straightforward step 1 would be to look at the request headers.
Lazarus:HTMLX always sends a header along with it if it's an AJAX request, which is header, HX request. There's other ways to check for AJAX. You know, all these different back end systems have their own way of kind of pulling in and deciding how to handle the request, but request headers are important. If you can access you can always access them. So if you access with whatever back end you're using, you know, request header hx dash request, If that is there, then you branch and you show the whole page.
Lazarus:You return the whole page, including the account details. If that's I'm sorry. If that's there, you do not show that, you just show the partial. If h x request is there, you're getting a partial. If that's not there, then you show the whole page with everything, including the details.
Lazarus:Right? So that way, if you send that link, it will pull the whole page with the details and everything. However, if you're already on the account page and you just click to show the details, it's going to load just that partial. So that's the trickiness. That's the gotcha.
Lazarus:So push URL and replace URL, you need to consider it in both of these cases. They're very similar. Push URL pushes it onto the stack, so you have that nice browser history. Replace URL replaces your current browser history with that stack. So but that's how you do it.
Lazarus:So that way you can deal with both the back button and the refresh if you handle that on the server side and have that conditional, changing of returning the whole page or returning the partial based on where the request came from. So that's a checks push URL and a checks replace URL. We're gonna go through every single advanced attribute we can this season, and hopefully have some fun along the way.
