TL;DR
htmx can be quite useful, especially for python devs with not enough time to learn javascript frameworks but who needs an alternative to tools like streamlit.
The “hypermedia systems” book quite a good read, I recommend reading it.
My code discussed in this blog post very closely resembles the code in the “hypermedia systems” book, but is built up progressively, to make it easier to follow along the book when stepping through the chapters. I only cover parts I found essential though. But maybe my template is helpful to follow if you want to add components important to you.
Links to things
- the book “hypermedia systems”: https://hypermedia.systems
- the book’s github repo: https://github.com/bigskysoftware/contact-app
- my github repo I refer to here: https://github.com/eschmidt42/htmx-experiments
What is htmx?
It is a tool introduced in the book “hypermedia systems”. It’s a small javascript library you can install with little overhead, it extends HTML tags with attributes so you can use GET, POST, PUT and DELETE methods with various triggers, leading to new pages or replaces small pieces of the current one. There is also a small DELETE example below to illustrate the htmx capabilities.
The code in the “hypermedia systems” book
Starting to read the “hypermedia systems” book, I saw they provided code, hence I naturally wanted to implement it while reading along. Building something myself I find very helpful in actually understand it. But I quickly found that the code examples assumed presence of other, not discussed, code. Darn it! But I saw the authors referred to a github repo they have prepared, yay! Quickly jumping over there and cloning the repo I did find a working app, more yay! (how often do I find broken code …)
However, looking into the repo, trying to understand what I need to look at for the book in order to understand the mechanics, I found a bunch of javascript files, various html templates with htmx pieces I’ve not yet heard of in the book and I also couldn’t easily discern what code is necessary for the functionalities I’ve read about so far. This surprised me, I got the impression that the usage of htmx should be relatively easy, what is going on? Is the htmx business actually much more difficult than expected?
To find out I decided, instead of trying to understand the repo as is, to start from scratch, take a broom and clear out everything that is javascript and htmx and successively built it up, so plain file diffs can be used to understand the changes, limiting the added ideas to a minimum, following the chapters. Crossing fingers, hoping this decision will not lead me down unseen rabbit holes.
Turns out it in this case it was actually a sensible approach. The result of this ab intio journey is the main point of this blog post and can be found just after the following htmx teaser. 🙂
htmx teaser
To illustrate a very neat aspect of htmx let’s look at one code example to send a DELETE request, which is not supported by HTML for some reason, see the book for more :).
What htmx allows you to do is the following
<!-- apps/web2/templates/edit.html -->
<button
hx-delete="/contacts/{{ contact.id }}"
hx-target="body">
Delete Contact
</button>
In this example the button tag gets added a hx-delete method that will make the click event on the button send a DELETE HTTP request to /contacts/{{ contact.id }}. The curly braces part is jinja2 templating, essentially only contains some id. The hx-target defines what is to be replaced by the HTML that is returned from the backend. This can be different things, here it’s "body".
The backend, using flask, then looks something like
# apps/web2/app.py
@app.route("/contacts/<contact_id>", methods=["DELETE"])
def contacts_delete(contact_id=0):
...
So only a route needs to be specified with the method DELETE and that will call the function def contacts_delete. This function is the one that returns HTML that will replace the target "body".
Mapping of chapters to code / app versions
Building the “Contact.app” app in the book up from scratch resulted in five versions of the app.
The first is in the directory `apps/web1`. It contains the most basic version of Contact.app, only flask, html (with jinja2 templating) and the needed css.
apps/web2 is the first version of the app containing htmx. It introduced boosting of links & forms for efficiency, the usage of DELETE, the validation of input on client and server side and paging.
apps/web3 adds some htmx features for user convenience like active search, lazy loading and inline / bulk delete.
apps/web4 adds the management of a long running process, e.g. data download, really just to show that it is possible.
apps/web5 also demonstrates something for the sake of it :P, the addition of a json data api. So the state of the app can be changed, e.g. via curl requests, leading to changes on the client side / frontend.
The chapters / sections are mapped to the above folders as follows:
- “A Web 1.0 application” ->
apps/web1– vanilla html app - “Htmx Patterns” ->
apps/web2– adds boosting, DELETE, validation, paging - “More Htmx Patterns” ->
apps/web3– adds active search, lazy loading, inline / bulk delete - “A Dynamic Archive UI” ->
apps/web4– adds data download management - “JSON Data APIs” ->
apps/web5– adds json data api
Final words
I hope this progressive build-up of the “Contact.app” from the book “hypermedia systems” is of help to you.
In the next blog post something with fasthtml may be coming up. What could it be? What could it possibly be? So hard to guess! Such uncertainty. 😀
So long and happy coding!
Datamuncher 