element with two special Alpine.js attributes on
it.
1. The x-data attribute: which defines a data property named "open"
with a value of true. You can think of data properties like local
variables in your HTML.
2. The x-show attribute: which says "only show this element if the
value of the "open" data property is true."
Combined these initialize the element with "open" to true, which
results in it being shown on the page.
Now let's look at the close button:
This markup does a variable assignment based on the "click" event. In
English, it says "when the button is clicked, set the value of the
"open" property to false."
Finally, there's the message itself, which resides in the outer
. Its visibility will be determined by the visibility of its
parent.
Press the little "x" to close this message...
Putting this together: the page loads, "open" is set to true, and the
notification shows up. Then you click the close button, "open"
becomes false and the whole thing disappears.
This is the core way that Alpine works: you define some dynamic
content in terms of "local" variables, and then wire up events that
manipulate those variables. Alpine attributes can set an element's
visiblity, change class lists, set content, add transitions, and
more. Working this way makes a lot of tasks simpler!
Also, because most logic in Alpine is configured by HTML attributes,
you can do quite a lot and never even write a line of JavaScript.
This simplifies things dramatically.
Integrating Alpine.js and Django
Alright, so Alpine is pretty cool. But how does it work with Django?
The quick answer is: exactly like it works with anything else.
Because Alpine lives predominantly in HTML it can work seamlessly
with Django--and indeed any server-rendered template system. All you
have to do is make sure that it's imported somewhere in your Django
template with something like this:
And you're off to the races! This will feel very familiar to Django
developers who haven't started using things like NPM and Webpack. You
can adopt Alpine without worrying about all that other stuff.
Finally, since most Alpine logic happens client-side there's really
nothing specific required to make Alpine and Django work together on
the backend. The Django bits become more important when you start
making AJAX requests and integrating with your sever.
Which brings us to our next example...
Talking to your Django backend without a full-page reload with HTMX
After interactive interfaces, the next-most-common use of JavaScript
is talking to your back end without full-page reloads--what we called
making AJAX requests above. Most of these workflows follow a similar
pattern--the user does something (e.g. clicks a button), a request is
made to the back end, and the front end updates itself based on the
response. On-page pagination, partial and auto-saving, and infinite
scroll are all examples of this type of thing.
Choosing your AJAX tool
To do AJAX--as with other things--you've got loads of options.
Historically, you might have used jQuery's $.ajax() function. These
days, JavaScript's fetch, or the axios library are more common. All
of these are perfectly fine choices.
Once again, choosing the right tool can be a complicated set of
tradeoffs--many of which will depend on the size of your project and
the experience and preferences of the people building it. Fetch is (
mostly) natively supported in browsers, which means it can be used
with no dependencies. Axios provides a friendlier API (you can kind
of think of it like requests for JavaScript). Both fetch and axios
play nicely with JavaScript frameworks--including React and Vue but
also low-JS frameworks like Alpine.
So with that out of the way, we'll now say: HTMX is our recommended
way to do AJAX in a Django project.
What is HTMX?
Don't feel bad if you haven't heard of HTMX--I hadn't until 2021. But
in the last 12 months, HTMX taken the Django community by storm.
There were three different talks on HTMX at the 2021 DjangoCon (here,
here, and here) and it also got a shout-out in my talk on "Modern
Javascript and Django".
Modern JS graph Slide
The author's worldview of integrating Django and JavaScript. In
short, go for "designed" low-JS using things like HTMX and Alpine
(this post), or "hybrid" high-JS with something like React (part 4 of
this series).
HTMX operates similarly to Alpine, in that it's implemented primarily
by attaching attributes to your HTML markup. But where Alpine focuses
on client-side state and operations, HTMX focuses on interaction with
your server.
The core workflow of HTMX is: make a request to the server and swap
the response into the page. At first this sounds a lot like every
other AJAX workflow, but there's a key difference: the response is
returned (and rendered) as HTML.
This little detail results in a complete paradigm shift for how you
do AJAX with Django. You no longer have to worry about JSON
serialization, Django Rest Framework, or anything like that. Instead,
your "APIs" are completely normal Django template views that return
HTML. Splash in a little HTMX and presto-change-o, you have an AJAX
app!
HTMX is a game-changer for the low-JS world in Django. To do it
justice would require an entire standalone post--perhaps the next
article in this series. But here's a quick example that should give
you the basics.
An HTMX example with Django Forms
So let's say we want to build a little contact form. And for the
purposes of our example, we'll assume that you can contact us about
anything except chimeras. Chimeras are the mortal enemies of the
Pegasus!
Chimera Image
Pegasus vs Chimera. Image from Marc Camelbeke
Our Django form class for this might look something like this:
class ContactForm(forms.Form):
subject = forms.CharField(max_length=100)
message = forms.CharField(widget=forms.Textarea({'rows': 3}),
help_text='You can message me about anything you want. '
'Except chimeras. I hate chimeras.')
sender = forms.EmailField()
def clean_message(self):
# Accept any message, unless it contains the word 'chimera'
message = self.cleaned_data['message']
if 'chimera' in message.lower():
raise forms.ValidationError('What did I tell you about chimeras?!')
return message
Now, in a typical Django architecture you'd stick this form in
template, serve it with a view, and process the form submission as a
POST request (typically handled by the same view)--as outlined in the
Django docs here. The form submission is processed as a full-page
load in the browser, and the response is rendered as a new page. This
is Django 101.
But what if we wanted to submit the form asynchronously--without doing
a full page reload? An asynchronous workflow can have several
benefits: it's a smoother user experience, allows the form to be
embedded anywhere on a page, and sends less data over the wire.
First, a demo! Fill in the form below. For bonus points, see what
happens if you try to use "chimera" in the message field.
Get in touch!
Subject
[ ]
Message
[ ]
[ ]
[ ]
You can message me about anything you want. Except chimeras, who are
my sworn enemy.
Sender
[ ]
[Submit]
Smooth, right?
Typically an AJAX workflow like this involves a fair amount of
JavaScript and breaking outside of Django forms. You might serialize
the data with JSON, build the UI in a JavaScript framework like
React, and submit it to a Django Rest Framework endpoint.
What's remarkable this particular example (which uses HTMX) is that:
1. It is 100% backed by standard Django views and forms.
2. It doesn't require writing a single line of JavaScript code.
Let's look at how it works.
First the definition of the form:
Our contact form template, in HTMX
Notice how familiar this looks! It's almost exactly like any other
Django form inside a template. The only difference is that instead of
using the standard "method" and "action" fields on the