TodoMVC using HTMX, Hyperscript and Python Flask
This post evaluates HTMX, a simple framework that uses attributes to enhance HTML with SPA behaviours. Instead of a full-blown javascript framework, it progressively enhances plain HTML to build capabilities. Better articles have been written on why.
We will focus on IF it helps bring SPA-like behaviour intuitively without JavaScript fatigue.
We are going to use TodoMVC as a reference implementation, which has a simple spec and various implementations to compare frontend frameworks, which are predominantly in Javascript/Typescript.
To begin with, I just took the todo-mvc template and modified it progressively to add features with care taken to preserve the original HTML. We use simple requests/responses and return HTML fragments as views to the front end, and HTMX takes care of patching them into the DOM where we target it. No page refreshes are needed, hence the SPA behaviour minus the gluttony of javascript frameworks and the associated build-the-world tooling they bring.
This involved splitting the HTML into small templates, which we can return as
fragments from our server. The TODOMVC app has key components of an <input/>
to capture new TODOS and an unordered list of list items <li/> to represent
them. The <li/> themselves are CRUD enabled, which allows them to be
edited/deleted.
Fetching new todos is as simple as using an attribute hx-get and pointing to your endpoint, which returns plain HTML.
<ul class="todo-list" hx-get="/todos" hx-trigger="load"></ul>
Easy to read and understand. On a load of the element, get a list of todos from /todos, which returns,
<li>TODO1</li>
<li>TODO2</li>which is automatically spliced into our todolist <ul> as children
<!-- ASSEMBLED DOM -->
<ul class="todo-list" hx-get="/todos" hx-trigger="load">
<li>TODO1</li>
<li>TODO2</li>
</ul>Enhancing <li/> items to support Read, Update, Delete involves decorating them
with attributes as so,
- Read - Render the value of the todo in the template tag {{ todo.label }}
- Update - On exiting the input box on blur or on pressing enter (2 triggers), call POST to update the todo
- Delete - on delete link clicked, issue DELETE and will remove the list element automatically on success.
- Toggle between edit mode - This one was tricky as the mode switch happens in
CSS by changing the class name. We track the state of the editmode on the
server and return the whole
<li/>element on dblclick. This felt unnecessary. Later, with hyperscript, I will show how easy it is to implement this on the client side.
<li id="list-item-{{todo.id}}"
class="{{"completed" if todo.status}} {{"editing" if todo.editMode}} {{"notEditing" if not todo.editMode }}"
hx-get="/editTodo/{{todo.id}}"
hx-trigger="dblclick"
hx-swap="outerHTML" hx-target="this"> <!-- TOGGLE EDIT MODE -->
<div class="view">
<input class="toggle" type="checkbox" {{'checked' if todo.status}}
hx-post="/toggleStatus/{{ todo.id }}"
hx-swap="outerHTML"
hx-target="#list-item-{{todo.id}}"> <!-- TOGGLE TODO STATUS -->
<label><span id="todo-label" >{{ todo.label }} <!-- READ: FETCH AND DISPLAY TODO STATUS --></span></label>
<button class="destroy" hx-delete="/deleteTodo/{{todo.id}}"><!-- DELETE TODO --></button>
</div>
<input name="edit-todo" class="edit" value="{{ todo.label }}"
hx-trigger="keyup[keyCode==13], blur"
hx-post="/updateTodo/{{ todo.id }}" > <!-- UPDATE TODO -->
</li>Behind the scenes - Server Side
A brief note on the server side implemented here in Python using Flask, a minimal web server. There is nothing much to be noted here. The server can be anything that can serve plain HTML. The prototype’s logic surrounding the todo state management is implemented in a simple Python style with templates serving the results. The todos and the editor state are tracked in session cookies (default flask implementation). This is a deviation from the TODOMVC specification, which requests it to be stored in local storage. This idea of where the state should be held is a good decision point in choosing HTMX.
Example of how state is defined and implementation of clear completed feature which clears all todos that are status complete (True)
@dataclass
class Todo:
id: str
label: str
status: bool
editMode: bool
@dataclass
class State:
currentStatusFilter: str
hideSection: bool
tobeCompletedCount: int
clearCompleted: bool
selectedIndex: typing.Union[int, None]
@app.route("/clearCompleted", methods=['POST'])
def clearCompleted():
currentState, todos = getState()
clearedTodos = [todo for todo in todos if not todo.status]
updateState(currentState, clearedTodos)
return getTodos("All")
The full implementation can be found in app.py.
Hyperscript
My initial attempt was to get away as much as I could without using any JavaScript, but there are a few features that scripting can solve elegantly. Luckily, HTMX is well paired with a scripting language called Hyperscript from the same creator, and it is bliss. It takes after hypertalk of natural language programming fame.
Here is what it looks like when you need to clear the input after adding a todo.
on htmx:afterRequest if event.detail.successful then set my.value to ''
Redoing the dblclick to toggle the .editing class turns into
<label _="on dblclick toggle .editing on #list-item-{{todo.id}}"></label>
That and a simple mutation observer script to keep track of length of changed list items covers what we need.
on mutation of anything from .todo-list
if length of <.todo-list li/> == 0 then add .hidden to .main then add .hidden to .footer
The nice thing about hyperscript is it’s declarative feel and it’s first class natural language approach to reference and manipulate DOM elements. Improves readability.
Key takeaways
-
For certain kinds of applications, plain old HTML served and patched into the DOM is a sufficient approach to deliver a SPA like experience without the bloat of full-fledged JS frameworks and associated builds and maintenance overhead
-
Taking an incremental evaluate/tackle approach to features in a web app goes a long way in keeping the application responsive and lightweight.
-
Serving plain old HTML allows flexibility on server-side frameworks. It also helps with keeping the logic close to the origin state.
-
HTMX encourages thinking about static vs interactive parts of an app and brings in only what is necessary to handle the interactive parts.
-
Following a declarative approach builds on the strength of HTML. The readability helps with the long-term maintenance of the solution.
Demo
https://todomvc-app-htmx.fly.dev/