Preload extension: hx-boost, no side effects, HX-Preloaded header, form support, tests and JSDocs

[marisst]

Major update of the preload extension.

• Hx-boost element preloading with correct request headers
  • Currently <a href="link" hx-boost="true" preload>Link</a> will be preloaded using XML request without HX-Request headers.
  • Hoverer, when user clicks on the link, a request with HX-Request and HX-Boosted headers is sent, and the cached request may not be used by the browser resulting in double loading.
  • This update includes changes fixing this issue and also allowing to preload <form method="get" target="/link" hx-boost="true" preload> with HX-Request.
  • Issues addressed:
    • Am I doing something wrong or is the preload extension asking the server for pages without the necessary headers? #89
    • Preloaded Pages Not Boosted with htmx Preload Extension #107
    • Preload extension preloads URLs but navigating there loads the data again #108
    • Headers defined with hx-headers not sent with preload #116
• No side-effects e.g. like visible loading indicators while preloading data
  • Currently if an element is preloaded based on hx-get attribute, the preload will cause loading indicators to show up
  • With this change it is not the case anymore. HTMX.ajax() is used only to generate the xhr request (incl. headers), which is manipulated in htmx:beforeRequest and sent without executing HTMX callbacks.
  • Issues addressed:
    • Bug: loading elements shown when using preload and laoding-states extensions #78
    • Preload: stopping event propagation when priming a cache?  #90
    • Preload Ext adds loading styles to loaded elements #110
    • preloaded places htmx-request class on body #115
  • Overlapping PR:
    • Do not emit htmx events when preloading requests #91
• HX-Preload header
  • Currently server cannot distinct between preload and regular requests
  • With this change, a HX-Preload header is added to all preload requests
  • Issues addressed:
    • Proposal for preload specific header #114
  • Overlapping PR:
    • preload: added a "hx-preload" header to hx-get and href requests #61
• Form element smart preloading with alternated values
  • Currently <form hx-get="/link" preload> will preload the form with as-is values whenever user clicks or hovers (if preload="mouseover") on any of the forms elements.
  • However, if user clicks or hovers over <input type="radio">, <input type="checkbox"> or <select> elements, it is more likely that the value of those elements will be changed first and then the form submitted.
  • This update includes smarter preloading of these three input elements, sending preload request with the alternated values. Additionally, <form method="get" target="/link" preload> will also be preloaded. Elements other than radio buttons, checkboxes, select elements and submit buttons are not triggering form preloading.
  • Issue addressed: Ajax sending parameters htmx#105
• Tests
  • Currently extension doesn't have any tests
  • Added 39 tests covering current and added functionality
  • Two issues were found and fixed during this process
    • <button hx-get="/link" hx-ext="preload" preload>Button</button> is not preloaded in current version, but it is preloaded with the change. The reason is that the extension currently does not consider the element in which the extension is registered among the pool of nodes it initializes.
    • touchstart event listener was added to node as an alternative to mousedown and mouseover events for touchscreens, but it was not working because the correct node.preloadState was not set when calling load(node)
• JSDocs and improved code readability
  • JSDocs added to all functions
  • Code reorganized in top-down manner. Currently the main part of the code is on the bottom and the least important utility functions are on top, making it hard to read it. I replaced const funct = function(){} with function funct() {} declarations, which allow to change the order.
  • The node.preloadState values are currently confusing. PAUSE is used for when node is initialized, READY for when data is loading and DONE for when loading is complete. I have renamed PAUSE to READY, READY to LOADING and kept DONE. I also added a new state TIMEOUT used to check that user hovers over an element for at least 100ms before it starts loading.
• preload="always" documentation and config flexibility
  • added documentation for preload="always" property
  • enabled use of preload="always", currently it can only be used together with preload mode e.g. preload="always mousedown"

Documentation is updated in a corresponding pull request in the main xtmx repository. bigskysoftware/htmx#3001

[netlify]

✅ Deploy Preview for htmx-extensions canceled.

Name	Link
🔨 Latest commit	0e4802c
🔍 Latest deploy log	https://app.netlify.com/sites/htmx-extensions/deploys/674aff2182188500089f3873

[untitaker]

this patch is working great for me in combination with hx-boost. essentially it "just works" while the main branch version doesn't. however, the loading indicator is visible when pages are being preloaded.

[ALameLlama]

Looks greats so far but +1 on the indicators, I don't believe these should be visible for preloads.

[marisst]

@untitaker and @ALameLlama, thank you for reviewing my pull request. I agree with you. I implemented a change which prevents loading indicators to be shown while preloading nodes. I have also added a "HX-Preload": "true" header to all preload requests.

[yoonthegoon]

EDIT:

ALameLlama helped pointing out I was missing Cache-Control from my response headers. All is good 😌

---

I hate to be the bearer of bad news, but I'm still getting two requests and the latter not being cached.
I attached screenshots on two browsers I've tested on.
I'm on macOS 15.0 24A335 arm64.

I suspect it's due to the additional HX-Preloaded header, as that's the only difference between the two requests.

GET /blog/inquit-incepta HTTP/1.1
Host: 127.0.0.1:3000
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:132.0) Gecko/20100101 Firefox/132.0
Accept: */*
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate, br, zstd
HX-Request: true
HX-Current-URL: http://127.0.0.1:3000/blog
HX-Boosted: true
- HX-Preloaded: true
Sec-GPC: 1
Connection: keep-alive
Referer: http://127.0.0.1:3000/blog
Sec-Fetch-Dest: empty
Sec-Fetch-Mode: cors
Sec-Fetch-Site: same-origin
DNT: 1
Priority: u=0

Unfortunately, I wasn't able to modify your code to try removing the added header without breaking the way the script functioned.
I'll see if I can try again on a different operating system when I get the chance.

I left both screenshots filtered just to show other requests were being cached.

Zen Browser
1.0.1-a.19 (Firefox 132.0.1) (aarch64)

Safari
Version 18.0 (20619.1.26.31.6)

[ALameLlama]

What do your response headers look like? I have a feeling you're missing the Cache-Control.

https://htmx.org/extensions/preload/

Preloaded responses will only be cached in the browser if the response headers allow it. For example, the response header Cache-Control: private, max-age=60 allows the browser to cache the response, whereas Cache-Control: no-cache prevents it.

The new request header HX-Preloaded shouldn't have any effect on it. just give the BE more information about what triggered the request.

[yoonthegoon]

Oof I'm silly. I just added the Cache-Control header and it's all good now. (I blame axum and askama_axum for making adding that in so difficult :P )

Here was my old response headers.

HTTP/1.1 200 OK
content-type: text/html; charset=utf-8
content-length: 5740
- date: Thu, 21 Nov 2024 04:22:51 GMT
+ date: Thu, 21 Nov 2024 04:22:52 GMT

Also I tried the preload.js in 6944833 (where the request headers are exactly the same) and I still wasn't caching the second, so that clearly wasn't it.

[marisst]

It would be great to get somebody review this pull request. Merging it would allow us to close 10 issues, which is a lot given there are only roughly 30 issues reported in this repository.

@Telroshan seems that the most recent PRs in the repo have been reviewed by you. Have you had a chance or are you planning to look at this one? Do you have any worries about it? If helpful, we can connect.

The author of the original preload extension is @benpate bigskysoftware/htmx#273, and it was approved by @1cg. Maybe we can get some inputs from the original authors if they are still active in this repo?

[Telroshan]

Hey @marisst , first of all thanks for your work. Life's currently a bit hectic so I haven't had the chance yet to sit down and review this PR as it should be. Can't guarantee a date that I'll look into it, but I hope to do it in the upcoming weeks.
I know this can be frustrating, but rest assured that we'll get there eventually!