We are not fond of big Javascript frameworks at NLP Cloud. NLP Cloud is an API based on spaCy and HuggingFace transformers in order to propose Named Entity Recognition (NER), sentiment analysis, text classification, summarization, and much more. Our backoffice is very simple. Users can retrieve their API token, upload their custom spaCy models, upgrade their plan, send support messages… Nothing too complex so we didn’t feel the need for Vue.js or React.js for that. We then used this very cool combination of htmx and Django.
Let me show you how it works and tell you more about the advantages of this solution.
What is htmx and why use it?
htmx is the successor of intercooler.js. The concept behind these 2 projects is that you can do all sorts of advanced things like AJAX, CSS transitions, websockets, etc. with HTML only (meaning without writing a single line of Javascript). And the lib is very lite (9kB only).
Another very interesting thing is that, when doing asynchronous calls to your backend, htmx does not expect a JSON response but an HTML fragment response. So basically, contrary to Vue.js or React.js, your frontend does not have to deal with JSON data, but simply replaces some parts of the DOM with HTML fragments already rendered on the server side. So it allows you to 100% leverage your good old backend framework (templates, sessions, authentication, etc.) instead of turning it into a headless framework that only returns JSON. The idea is that the overhead of an HTML fragment compared to JSON is negligible during an HTTP request.
So, to sum up, here is why htmx is interesting when building a single page application (SPA):
- No Javascript to write
- Excellent backend frameworks like Django, Ruby On Rails, Laravel… can be fully utilized
- Very small library (9kB) compared to the Vue or React frameworks
- No preprocessing needed (Webpack, Babel, etc.) which makes the development experience much nicer
Installation
Installing htmx is just about loading the script like this in your HTML <head>:
<script src="https://unpkg.com/htmx.org@1.2.1"></script>
I won’t go into the details of Django’s installation here as this article essentially focuses on htmx.
Load Content Asynchronously
The most important thing when creating an SPA is that you want everything to load asynchronously. For example, when clicking a menu entry to open a new page, you don’t want the whole webpage to reload, but only the content that changes. Here is how to do that.
Let’s say our site is made up of 2 pages:
- The token page showing the user his API token
- The support page basically showing the support email to the user
We also want to display a loading bar while the new page is loading.
Frontend
On the frontend side, you would create a menu with 2 entries. And clicking an entry would show the loading bar and change the content of the page without reloading the whole page.
<progress id="content-loader" class="htmx-indicator" max="100"></progress>
<aside>
<ul>
<li><a hx-get="/token" hx-push-url="true"
hx-target="#content" hx-swap="innerHTML"
hx-indicator="#content-loader">Token</a></li>
<li><a hx-get="/support"
hx-push-url="true" hx-target="#content" hx-swap="innerHTML"
hx-indicator="#content-loader">Support</a></li>
</ul>
</aside>
<div id="content">Hello and welcome to NLP Cloud!</div>
In the example above the loader is the <progress> element. It is hidden by default thanks to its class htmx-indicator. When a user clicks one of the 2 menu entries, it makes the loader visible thanks to hx-indicator="#content-loader".
When a user clicks the token menu entry, it performs a GET asynchronous call to the Django token url thanks to hx-get="/token". Django returns and HTML fragment that htmx puts in <div id="content"></div> thanks to hx-target="#content" hx-swap="innerHTML".
Same thing for the support menu entry.
Even if the page did not reload, we still want to update the URL in the browser in order to help the user understand where he is. That’s why we use hx-push-url="true".
As you can see we now have an SPA that is using HTML fragments behind the hood rather than JSON, with a mere 9kB lib, and only a couple of directives.
Backend
Of course the above does not work without the Django backend.
Here’s your urls.py:
from django.urls import path
from . import views
urlpatterns = [
path('', views.index, name='index'),
path('token', views.token, name='token'),
path('support', views.support, name='support'),
]
Now your views.py:
def index(request):
return render(request, 'backoffice/index.html')
def token(request):
api_token = 'fake_token'
return render(request, 'backoffice/token.html', {'token': api_token})
def support(request):
return render(request, 'backoffice/support.html')
And last of all, in a templates/backoffice directory add the following templates.
index.html (i.e. basically the code we wrote above, but with Django url template tags):
<!DOCTYPE html>
<html>
<head>
<script src="https://unpkg.com/htmx.org@1.2.1"></script>
</head>
<body>
<progress id="content-loader" class="htmx-indicator" max="100"></progress>
<aside>
<ul>
<li><a hx-get="{% url 'home' %}"
hx-push-url="true" hx-target="#content" hx-swap="innerHTML"
hx-indicator="#content-loader">Home</a></li>
<li><a hx-get="{% url 'token' %}" hx-push-url="true"
hx-target="#content" hx-swap="innerHTML"
hx-indicator="#content-loader">Token</a></li>
</ul>
</aside>
<div id="content">Hello and welcome to NLP Cloud!</div>
<body>
</html>
token.html:
Here is your API token: {{ token }}
support.html:
For support questions, please contact support@nlpcloud.io
As you can see, all this is pure Django code using routing and templating as usual. No need of an API and Django Rest Framework here.
Allow Manual Page Reloading
The problem with the above is that if a user manually reloads the token or the support page, he will only end up with the HTML fragment instead of the whole HTML page.
The solution, on the Django side, is to render 2 different templates depending on whether the request is coming from htmx or not.
Here is how you could do it.
In your views.py you need to check whether the HTTP_HX_REQUEST header was passed in the request. If it was, it means this is a request from htmx and in that case you can show the HTML fragment only. If it was not, you need to render the full page.
def index(request):
return render(request, 'backoffice/index.html')
def token(request):
if request.META.get("HTTP_HX_REQUEST") != 'true':
return render(request, 'backoffice/token_full.html', {'token': api_token})
return render(request, 'backoffice/token.html', {'token': api_token})
def support(request):
if request.META.get("HTTP_HX_REQUEST") != 'true':
return render(request, 'backoffice/support_full.html')
return render(request, 'backoffice/support.html')
Now in your index.html template you want to use blocks in order for the index page to be extended by all the other pages:
<!DOCTYPE html>
<html>
<head>
<script src="https://unpkg.com/htmx.org@1.2.1"></script>
</head>
<body>
<progress id="content-loader" class="htmx-indicator" max="100"></progress>
<aside>
<ul>
<li><a hx-get="{% url 'home' %}"
hx-push-url="true" hx-target="#content" hx-swap="innerHTML"
hx-indicator="#content-loader">Home</a></li>
<li><a hx-get="{% url 'token' %}" hx-push-url="true"
hx-target="#content" hx-swap="innerHTML"
hx-indicator="#content-loader">Token</a></li>
</ul>
</aside>
<div id="content">{% block content %}{% endblock %}</div>
<body>
</html>
Your token.html template is the same as before but now you need to add a second template called token_full.html in case the page is manually reloaded:
{% extends "home/index.html" %}
{% block content %}
{% include "home/token.html" %}
{% endblock %}
Same for support.html, add a support_full.html file:
{% extends "home/index.html" %}
{% block content %}
{% include "home/support.html" %}
{% endblock %}
We are basically extending the index.html template in order to build the full page all at once on the server side.
This is a small hack but this is not very complex, and a middleware can even be created for the occasion in order to make things even simpler.
What Else?
We only scratched the surface of htmx. This library (or framework?) includes tons of usefull other features like:
- You can use the HTTP verb you want for your requests. Use
hx-getforGET,hx-postforPOST, etc. - You can use polling, websockets, and server side events, in order to listen to events coming from the server
- You can use only a part of the HTML fragment returned by the server (
hx-select) - You can leverage CSS transitions
- You can easily work with forms and file uploads
- You can use htmx’s hyperscript, which is a pseudo Javascript language that can easily be embedded in HTML tags for advanced usage
Conclusion
I’m very enthusiast about this htmx lib as you can see, and I do hope more and more people will realize they don’t necessarily need a huge JS framework for their project.
For the moment I’ve only integrated htmx into small codebases in production, but I’m pretty sure that htmx fits into large projects too. So far it’s been easy to maintain, lightweight, and its seamless integration with backend frameworks like Django is a must!
If some of you use htmx in production, I’d love to hear your feebacks too!