Add documentation for htmx

core/views/__init__.py

@@ -327,6 +327,8 @@ class DetailFormView(SingleObjectMixin, FormView):
 
 
 class AllowFragment:
+    """Add `is_fragment` to templates. It's only True if the request is emitted by htmx"""
+
     def get_context_data(self, **kwargs):
         kwargs["is_fragment"] = self.request.headers.get("HX-Request", False)
         return super().get_context_data(**kwargs)

docs/explanation/technos.md

@@ -200,6 +200,19 @@ Grâce à son architecture, il est extrêmement
 bien adapté pour un usage dans un site multipage.
 C'est une technologie simple et puissante qui se veut comme le jQuery du web moderne.
 
+### Htmx
+
+[Site officiel](https://htmx.org/)
+
+En plus de AlpineJS, l’interactivité sur le site est augmenté via Htmx.
+C'est une librairie js qui s'utilise également au moyen d'attributs HTML à
+ajouter directement dans les templates.
+
+Son principe est de remplacer certains éléments du html par un fragment de
+HTML renvoyé par le serveur backend. Cela se mari très bien avec le
+fonctionnement de django et en particulier de ses formulaires afin d'éviter
+de doubler le travail pour la vérification des données.
+
 ### Sass
 
 [Site officiel](https://sass-lang.com/)

docs/reference/stock/models.md

@@ -1 +0,0 @@
-::: stock.models

docs/reference/stock/views.md

@@ -1 +0,0 @@
-::: stock.views

docs/tutorial/fragments.md

@@ -0,0 +1,12 @@
+Pour utiliser HTMX, on a besoin de renvoyer des fragments depuis le backend.
+Le truc, c'est que tout est optimisé pour utiliser `base.jinja` qui est assez gros.
+
+Dans beaucoup de scénario, on veut pouvoir renvoyer soit la vue complète, soit
+juste le fragment. En particulier quand on utilise l'attribut `hx-history` de htmx.
+
+Pour remédier à cela, il existe le mixin [AllowFragment][core.views.AllowFragment].
+
+Une fois ajouté à une vue Django, il ajoute le boolean `is_fragment` dans les
+templates jinja. Sa valeur est `True` uniquement si HTMX envoi la requette.
+Il est ensuite très simple de faire un if/else pour hériter de
+`core/base_fragment.jinja` au lieu de `core/base.jinja` dans cette situation.

mkdocs.yml

@@ -66,6 +66,7 @@ nav:
     - Structure du projet: tutorial/structure.md
     - Gestion des permissions: tutorial/perms.md
     - Gestion des groupes: tutorial/groups.md
+    - Créer des fragments: tutorial/fragments.md
     - Etransactions: tutorial/etransaction.md
   - How-to:
     - L'ORM de Django: howto/querysets.md