Créez une boutique mono-produit avec le framework Python Django et Htmx

Il s'agit de la première d'une série en deux parties utilisant Django, htmx et Stripe pour créer un site Web de commerce électronique mono-produit. Dans cette partie, nous allons démarrer notre projet Django et l'intégrer avec htmx.

Dans la deuxième partie, nous traiterons les commandes avec Stripe.

Allons-y !

Pourquoi Django, HTML et Stripe ?

Nous utiliserons Django, htmx et Stripe pour créer notre site Web car :

• Django est un framework Web Python avec un excellent système ORM, de modèles et de routage. Il possède quelques fonctionnalités prêtes à l'emploi (comme l'authentification) et plusieurs packages open source disponibles en ligne. Nous utiliserons Django pour créer le site Web.
• htmx est une bibliothèque JavaScript qui donne à votre site Web une impression de modernité simplement en utilisant des attributs HTML — vous n'avez pas réellement besoin d'écrire du JavaScript (même si vous le pouvez, bien sûr). Nous utiliserons htmx pour donner un peu d'interactivité à notre page.
• Stripe est une plateforme de paiement dotée d'une excellente API : elle gère les paiements et les informations de carte de crédit. Il s'intègre également parfaitement à Google et Apple Pay. Nous utiliserons Stripe pour faciliter les paiements des produits.

Voici comment le produit final fonctionnera :

• Un utilisateur accède à notre site Web et peut voir certaines informations sur notre produit, y compris son prix et sa description.
• Une fois que l'utilisateur clique sur le bouton « acheter », il est redirigé vers la session de paiement de Stripe.
• Si le paiement réussit, ils sont à nouveau redirigés vers notre site Internet. Nous enregistrons les informations de leur commande et envoyons un e-mail de confirmation au client et à tous les utilisateurs du personnel pour les informer de l'achat récent.

Configurons maintenant notre projet Django, créons les vues initiales et construisons le formulaire d'achat avec htmx.

Configurez votre projet Django Python

Pour mettre en place notre projet, nous devons créer un environnement virtuel, l'activer et installer les packages requis. Nous pouvons ensuite créer notre projet Django et notre application Django.

Créer un environnement virtuel

Commençons par créer un environnement virtuel, afin de pouvoir isoler nos dépendances :

python -m venv .venv

Voici comment nous l'activons sur Linux/Mac :

source .venv/bin/activate

Et sous Windows :

.venv\Scripts\activate

Installez les packages requis

Au sein de notre environnement virtuel activé, nous avons besoin de quelques packages pour que cela fonctionne :

pip install django stripe django-htmx python-dotenv

Ici, nous avons installé :

• Django
• Stripe pour travailler avec l'API Stripe.
• django-htmx, qui fournit des fonctionnalités d'aide pour travailler avec htmx.
• python-dotenv pour charger les variables d'environnement à partir des fichiers .env.

Créer le projet Django

Dans le même répertoire que notre environnement virtuel, créons un projet Django appelé ecommerce_site :

django-admin startproject ecommerce_site .

Dans Django, c'est une bonne pratique d'avoir du code organisé par une ou plusieurs "applications". Chaque application est un package qui fait quelque chose en particulier. Un projet peut avoir plusieurs applications, mais pour cette simple boutique, nous ne pouvons avoir qu'une seule application qui contiendra la majeure partie du code : les vues, les formulaires et les modèles de notre plateforme de commerce électronique. Créons-le et appelons-le ecommerce :

python manage.py startapp ecommerce

Et ajoutez cette application à nos INSTALLED_APPS dans ecommerce_site/settings.py :

# ecommerce_site/settings.py

INSTALLED_APPS = [
    # ... the default django apps
    "ecommerce", # ⬅️ new
]

Si vous rencontrez des problèmes avec cette configuration, consultez le produit final. À ce stade, la structure de votre fichier devrait ressembler à ceci :

ecommerce_site/
├── .venv/  # ⬅️ the virtual environment
├── ecommerce_site/ # ⬅️ the django project configuration
│   ├── __init__.py
│   ├── asgi.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── ecommerce/ # ⬅️ our app setup
│     ├── templates/
│   ├── __init__.py
│   ├── admin.py
│   ├── apps.py
│   ├── models.py
│   ├── tests.py
│   └── views.py
└── manage.py

Créer les modèles

Maintenant que notre projet est configuré, nous devons créer des mises en page de base. Dans le répertoire des modèles, ajoutez un fichier base.html — le modèle dont tous les autres modèles hériteront. Ajoutez htmx pour l'interaction utilisateur, mvp.css pour le style de base et les messages générés par Django au modèle :

<!-- ecommerce/templates/base.html -->

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>One-Product E-commerce Site</title>

    <!-- include htmx ⬇️ -->
    <script
      src="https://unpkg.com/htmx.org@1.9.11"
      integrity="sha384-0gxUXCCR8yv9FM2b+U3FDbsKthCI66oH5IA9fHppQq9DDMHuMauqq1ZHBpJxQ0J0"
      crossorigin="anonymous"
    ></script>

    <!-- include mvp.css ⬇️ -->
    <link rel="stylesheet" href="https://unpkg.com/mvp.css" />
  </head>
  <body hx-headers='{"X-CSRFToken": "{{ csrf_token }}"}' hx-boost="true">
    <header>
      <h1>One-Product E-commerce Site</h1>
    </header>
    <main>
      <section>
        {% if messages %} {% for message in messages %}
        <p><mark>{{ message }}</mark></p>
        {% endfor %} {% endif %}
      </section>
      {% block content %} {% endblock %}
    </main>
  </body>
</html>

Créez un modèle home.html dans le même répertoire templates, pour notre vue d'accueil. Il devrait étendre le fichier base.html et remplir simplement sa section de contenu.

<!-- ecommerce/templates/home.html -->

{% extends "base.html" %} {% block content %}
<section>{% include "product.html" %}</section>
{% endblock %}

Dans ce modèle, nous avons inclus le modèle product.html. product.html affichera quelques détails sur notre produit et une image d'espace réservé. Créons-le dans le même répertoire templates :

<!-- ecommerce/templates/product.html -->
<form>
  <img src="https://picsum.photos/id/30/400/250" alt="mug" />
  <h3>mug<sup>on sale!</sup></h3>
  <p>mugs are great - you can drink coffee on them!</p>
  <p><strong>5€</strong></p>
  <button type="submit" id="submit-btn">Buy</button>
</form>

Créer la vue d'accueil

Dans ecommerce/views.py, nous allons créer la vue qui affichera le modèle d'accueil :

# ecommerce/views.py

from django.shortcuts import render

def home(request):
    return render(request, 'home.html')

Et ajoutez-le aux modèles d'URL dans ecommerce_site/urls.py :

# ecommerce_site/urls.py

from django.contrib import admin
from django.urls import path
from ecommerce import views # ⬅️ new

urlpatterns = [
    path("admin/", admin.site.urls),
    path("", views.home, name="home"), # ⬅️ new
]

Maintenant, nous pouvons exécuter le serveur avec :

python manage.py runserver

Si vous accédez à http://127.0.0.1:8000 dans votre navigateur, vous devriez voir quelque chose comme ceci :

It might feel like overkill to add a dedicated product.html template instead of just the product details in the home.html template, but product.html will be useful for the htmx integration.

Add the Form and Use Htmx

Great! We now have a view that looks good. However, it doesn’t do much yet. We'll add a form and set up the logic to process our product purchase. Here’s what we want to do:

1. Allow the user to select how many products (mugs) they want to buy.
2. When the user clicks “Buy”, make a POST request to a different view called purchase in the backend using hx-post.
3. In that view, validate the form and wait for 2 seconds to simulate the Stripe integration (we'll cover this in the second part of this guide).
4. Replace the form content with the purchase view response.
5. While the order is processing, show a loading message and disable the “Buy” button, so that the user doesn’t accidentally make multiple orders.

Let's go step by step.

1: Add a Quantity Order Form

Let’s first create and add a simple order form to our view allowing a user to select the number of mugs they want. In ecommerce/forms.py, add the following code:

# ecommerce/forms.py

from django import forms

class OrderForm(forms.Form):
        quantity = forms.IntegerField(min_value=1, max_value=10, initial=1)

In ecommerce/views.py, we can initialize the form in the home view:

# ecommerce/views.py

from ecommerce.forms import OrderForm # ⬅️ new

def home(request):
    form = OrderForm() # ⬅️ new - initialize the form
    return render(request, "home.html", {"form": form}) # ⬅️ new - pass the form to the template

And render it in the template:

<!-- ecommerce/templates/product.html -->

<form method="post">
  <!-- Same product details as before, hidden for simplicity -->

  <!-- render the form fields ⬇️ -->
  {{ form }}

  <!-- the same submit button as before ⬇️ -->
  <button type="submit" id="submit-btn">Buy</button>
</form>

2: Make a POST Request To a Different View

When the user clicks "Buy", we want to process the corresponding POST request in a dedicated view to separate the different logic of our application. We will use htmx to make this request. In the same ecommerce/templates/product.html template, let's extend the form attributes:

<!-- ecommerce/templates/product.html -->

<!-- add the hx-post html attribute ⬇️ -->
<form method="post" hx-post="{% url 'purchase' %}">
  <!-- Same product details as before, hidden for simplicity -->

  {{ form }}
  <button type="submit" id="submit-btn">Buy</button>
</form>

With this attribute, htmx will make a POST request to the purchase endpoint and stop the page from reloading completely. Now we just need to add the endpoint.

3: Create the Purchase View

The purchase view can be relatively simple for now:

# ecommerce/views.py
import time # ⬅️ new

# new purchase POST request view ⬇️
@require_POST
def purchase(request):
    form = OrderForm(request.POST)
    if form.is_valid():
        quantity = form.cleaned_data["quantity"]
        # TODO - add stripe integration to process the order
        # for now, just wait for 2 seconds to simulate the processing
        time.sleep(2)
    return render(request, "product.html", {"form": form})

In this view, we validate the form, extract the quantity from the cleaned data, and simulate Stripe order processing. In the end, we return the same template (product.html). We also need to add the view to the urlpatterns:

# ecommerce_site/urls.py

# ... same imports as before

urlpatterns = [
    path("admin/", admin.site.urls),
    path("", views.home, name="home"),
    path("purchase", views.purchase, name="purchase"),  # ⬅️ new
]

We now need to tell htmx what to do with this response.

4: Replace the Form Content With the Purchase View Response

Htmx has a hx-swap attribute which replaces targeted content on the current page with a request's response.
In our case, since the purchase view returns the same template, we want to swap its main element — the

<!-- ecommerce/templates/product.html -->

<!-- add the hx-swap html attribute ⬇️ -->
<form method="post" hx-post="{% url 'purchase' %}" hx-swap="outerHTML">
  <!-- Same product details as before, hidden for simplicity -->

  {{ form }}
  <button type="submit" id="submit-btn">Buy</button>
</form>

<!-- ecommerce/templates/product.html -->

<!-- add the hx-disabled-elt html attribute ⬇️ -->
<form
  method="post"
  hx-post="{% url 'purchase' %}"
  hx-swap="outerHTML"
  hx-disabled-elt="#submit-btn"
>
  <!-- Same product details as before, hidden for simplicity -->

  {{ form }}
  <button type="submit" id="submit-btn">Buy</button>

  <!-- add a loading message with the htmx-indicator class ⬇️ -->
  <p class="htmx-indicator"><small>Getting your mug ready...</small></p>
</form>