HTMX media-type?

[huuff]

I'm surprised there's no HTMX media-type. Requests made by HTMX could have this media-type (maybe Accept: text/html+htmx?) so the backend could better disambiguate between pure HTML requests (larger-grained, full pages, for clients without js enabled) and HTMX ones (finer-grained, returning only parts of the page). This would also help with progressive enhancement.

Is this a strange idea?

[nickchomey]

Html fragments are FAR from an htmx innovation... As far as I'm aware, this is the original basis of AJAX, largely served by jQuery for a long time

[nickchomey]

What is it that you're trying to solve for here...? Such headers don't exist, yet htmx works fine... And, is there something stopping you from just adding such headers if it is something that you think you need?

[huuff]

I suppose you mean the media-type does not exist since HX-Trigger does exist...

And in fact, there's nothing stopping me from adding the media-type myself, I already thought about setting Accep: text/html+htmx using htmx:configRequest but wanted to share the idea to see what people would think about it.

Media type has always been used to disambiguate representations in the back-end via content negotiation, so I think that would have more support than disambiguating by an arbitrary header (such as HX-Trigger) .

The "Hypermedia Systems" example is the following: given a path /contacts that returns a list of contacts, we want to offer a different representation depending on whether the request is for a part of the screen (such as an embedded representation from HTMX) or the whole screen. (such as the user entering /contacts in the address bar). This is the Flask code:

@app.route("/contacts")
def contacts():
    search = request.args.get("q")
    if search is not None:
        contacts_set = Contact.search(search)
        if request.headers.get('HX-Trigger') == 'search':
          return render_template("rows.html", contacts=contacts_set) (1)
    else:
        contacts_set = Contact.all()
    return render_template("index.html", contacts=contacts_set)

I've ported it to Spring + Kotlin since I'm not familiar with Python nor flask:

    @GetMapping("/contacts")
    fun contacts(
        @RequestParam(name="q") search: String?,
        @RequestHeader("HX-Trigger") trigger: String?,
        model: Model,
    ): String {
        if (search != null) {
            model.addAttribute("contacts", contacts.search(search))

            if (trigger == "search") {
                return "rows.html"
            }
        } else {
            model.addAttribute("contacts", contacts.all())
        }

        return "index.html"
    }

This feels a bit uncomfortable to me. Both representations are dispatched by the same method. For this simple example, building the response is pretty simple, but in a larger application, the model for the full page might be much bigger than the partial one, and thus require more code to build. Spring framework has a pretty easy way to do content negotiation based on the Accept header which would simplify it greatly given a specific media type:

   @GetMapping("/contacts", produces = ["text/html"])
    fun contactsFull(
        @RequestParam(name="q") search: String?,
        model: Model,
    ): String {
        if (search != null) {
            model.addAttribute("contacts", contacts.search(search))
        } else {
            model.addAttribute("contacts", contacts.all())
        }

        return "index.html"
    }
    
    @GetMapping("/contacts", produces = ["text/html+htmx"])
    fun contactsPartial(
        @RequestParam(name="q") search: String?,
        model: Model,
    ): String {
        if (search != null) {
            model.addAttribute("contacts", contacts.search(search))
        } else {
            model.addAttribute("contacts", contacts.all())
        }

        return "rows.html"
    }

This would better allow evolving separating both representations independently and better separate the concerns. Now, I'm pretty sure the Spring framework (and others) should have some way to disambiguate by the value of the header, but I still think content negotiation by the accept header is usually more readily available...

On the other hand, I think using the HX-Trigger header for this gives an affordance you might not need (checking the value of the header). In this case, the representation the client wants is a partial list of contacts (an <ul> with a few <li> elements) and this can perfectly match the definition of the resource at the backend, so whether you want to embed it in the front-end (the #search element or otherwise) shouldn't really matter any more than the fact that you want to embed it.

[nickchomey]

It seems to me that this isn't something that should be baked into htmx, whatsoever.

Each application - both front end and backend - is unique and should handle full page vs fragment rendering in whatever way is appropriate.

The basic example in the book is one way of doing it. Your example looks fine as well (though I think you meant to get rid of the if statements in the two endpoints...). There's plenty of other ways of doing it, with and without headers, with single and separate functions etc... You could just as easily use separate endpoints instead of an htmx header (contacts-all, contacts-search, contact, etc...).

And the beauty of htmx is that all approaches are welcome and compatible.

Ps, keep in mind that there are surely plenty of use cases within an htmx application to request a full page rather than a framework. So html+htmx wouldn't work in that case for identifying fragment endpoints.

Pps this essay might also be useful for you as you seem to be trying to be prescriptive, whereas htmx is VERY agnostic about how anyone implements any of this. https://htmx.org/essays/hypermedia-on-whatever-youd-like/

[huuff]

Ps, keep in mind that there are surely plenty of use cases within an htmx application to request a full page rather than a framework. So html+htmx wouldn't work in that case for identifying fragment endpoints.

This is a fair point I didn't consider.

Pps this essay might also be useful for you as you seem to be trying to be prescriptive, whereas htmx is VERY agnostic about how anyone implements any of this. https://htmx.org/essays/hypermedia-on-whatever-youd-like/

That's a great essay! Thank you for suggesting it!

In the end, I just found out that htmx always adds the HX-Request: true header in all of its requests. This meets my needs perfectly so I'm using that. Still, I think we could benefit from a specification of a media-type for HTML fragments, but that's outside of the scope of htmx.

[nickchomey]

Glad to have been helpful and that you found a solution for your application.

[alexpetros]

Some more discussion of the content type here: #1229