Bina Kedai Satu Produk Dengan Rangka Kerja Python Django dan Htmx

Ini adalah siri pertama daripada dua bahagian menggunakan Django, htmx dan Stripe untuk mencipta tapak web e-dagang satu produk. Dalam bahagian ini, kami akan memulakan projek Django kami dan menyepadukannya dengan htmx.

Dalam bahagian kedua, kami akan mengendalikan pesanan dengan Stripe.

Mari kita pergi!

Mengapa Django, htmx dan Stripe?

Kami akan menggunakan Django, htmx dan Stripe untuk membuat tapak web kami kerana:

• Django ialah rangka kerja web Python dengan sistem ORM, templat dan penghalaan yang hebat. Ia mempunyai beberapa ciri terus dari kotak (seperti pengesahan) dan berbilang pakej sumber terbuka tersedia dalam talian. Kami akan menggunakan Django untuk membina tapak web.
• htmx ialah perpustakaan JavaScript yang memberikan tapak web anda rasa moden hanya dengan menggunakan atribut html — anda sebenarnya tidak perlu menulis sebarang JavaScript (walaupun anda boleh, sudah tentu). Kami akan menggunakan htmx untuk memberikan sedikit interaktiviti pada halaman kami.
• Stripe ialah platform pembayaran dengan API yang hebat — ia mengendalikan pembayaran dan maklumat kad kredit. Ia juga disepadukan dengan baik dengan Google dan Apple Pay. Kami akan menggunakan Stripe untuk memudahkan pembayaran produk.

Begini cara produk akhir akan berfungsi:

• Seorang pengguna pergi ke tapak web kami dan dapat melihat beberapa maklumat tentang produk kami, termasuk harga dan penerangannya.
• Sebaik sahaja pengguna mengklik butang "beli", mereka diubah hala ke sesi pembayaran Stripe.
• Jika pembayaran berjaya, mereka akan dialihkan ke laman web kami sekali lagi. Kami menyimpan maklumat pesanan mereka dan menghantar e-mel pengesahan kepada pelanggan dan semua pengguna kakitangan untuk memberitahu mereka tentang pembelian baru-baru ini.

Sekarang mari kita konfigurasikan projek Django kami, buat paparan awal dan bina borang pembelian dengan htmx.

Konfigurasikan Projek Django Python Anda

Untuk menyediakan projek kami, kami perlu mencipta persekitaran maya, mengaktifkannya dan memasang pakej yang diperlukan. Kami kemudiannya boleh mencipta projek Django dan apl Django kami.

Cipta Persekitaran Maya

Mari kita mulakan dengan mencipta persekitaran maya, supaya kita boleh mengasingkan kebergantungan kita:

python -m venv .venv

Begini cara kami mengaktifkannya pada Linux/Mac:

source .venv/bin/activate

Dan pada Windows:

.venv\Scripts\activate

Pasang Pakej yang Diperlukan

Dalam persekitaran maya kami yang diaktifkan, kami memerlukan beberapa pakej untuk membuat ini berfungsi:

pip install django stripe django-htmx python-dotenv

Di sini, kami telah memasang:

• Django
• Jalur untuk berfungsi dengan API jalur.
• django-htmx, yang menyediakan beberapa fungsi pembantu untuk berfungsi dengan htmx.
• python-dotenv untuk memuatkan pembolehubah persekitaran daripada fail .env.

Buat Projek Django

Dalam direktori yang sama dengan persekitaran maya kami, mari buat projek Django yang dipanggil ecommerce_site:

django-admin startproject ecommerce_site .

Di Django, amalan yang baik untuk mempunyai kod yang dianjurkan oleh satu atau lebih "apl". Setiap apl ialah pakej yang melakukan sesuatu secara khusus. Projek boleh mempunyai berbilang apl, tetapi untuk kedai mudah ini, kami hanya boleh mempunyai satu apl yang mempunyai kebanyakan kod — paparan, borang dan model untuk platform e-dagang kami. Mari buat dan panggilnya e-dagang:

python manage.py startapp ecommerce

Dan tambahkan apl ini pada INSTALLED_APPS kami dalam ecommerce_site/settings.py:

# ecommerce_site/settings.py

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

Jika anda menghadapi masalah dengan persediaan ini, lihat produk akhir. Pada peringkat ini, struktur fail anda sepatutnya kelihatan seperti ini:

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

Cipta Templat

Sekarang projek kami telah dikonfigurasikan, kami perlu membuat beberapa reka letak asas. Dalam direktori templat, tambahkan fail base.html — templat yang akan diwarisi oleh semua templat lain. Tambahkan htmx untuk interaksi pengguna, mvp.css untuk penggayaan asas dan mesej yang dijana Django pada templat:

<!-- 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>

Buat templat home.html dalam direktori templat yang sama, untuk paparan laman utama kami. Ia harus memanjangkan base.html dan hanya mengisi bahagian kandungannya.

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

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

Dalam templat ini, kami telah memasukkan templat product.html. product.html akan memberikan beberapa butiran tentang produk kami dan imej pemegang tempat. Mari buat dalam direktori templat yang sama:

<!-- 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>

Buat Paparan Rumah

Dalam e-dagang/views.py, kami akan mencipta paparan yang akan memaparkan templat rumah:

# ecommerce/views.py

from django.shortcuts import render

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

Dan tambahkannya pada urlpatterns dalam 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
]

Kini kita boleh menjalankan pelayan dengan:

python manage.py runserver

Jika anda melompat ke http://127.0.0.1:8000 dalam penyemak imbas anda, anda sepatutnya melihat sesuatu seperti ini:

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>