mirror of
https://github.com/ae-utbm/sith.git
synced 2025-11-04 02:53:06 +00:00
357 lines
10 KiB
Markdown
357 lines
10 KiB
Markdown
## Qu'est-ce qu'un fragment
|
|
|
|
Une application web django traditionnelle suit en général
|
|
le schéma suivant :
|
|
|
|
1. l'utilisateur envoie une requête au serveur
|
|
2. le serveur renvoie une page HTML,
|
|
qui contient en général des liens et/ou des formulaires
|
|
3. lorsque l'utilisateur clique sur un lien ou valide
|
|
un formulaire, on retourne à l'étape 1
|
|
|
|
C'est un processus qui marche, mais qui est lourd :
|
|
générer une page entière demande du travail au serveur
|
|
et effectuer le rendu de cette page en demande également
|
|
beaucoup au client.
|
|
Or, des temps de chargement plus longs et des
|
|
rechargements complets de page peuvent nuire
|
|
à l'expérience utilisateur, en particulier
|
|
lorsqu'ils interviennent lors d'opérations simples.
|
|
|
|
Pour éviter ce genre de rechargement complet,
|
|
on peut utiliser AlpineJS pour rendre la page
|
|
interactive et effectuer des appels à l'API.
|
|
Cette technique fonctionne particulièrement bien
|
|
lorsqu'on veut afficher des objets ou des listes
|
|
d'objets de manière dynamique.
|
|
|
|
En revanche, elle est moins efficace pour certaines
|
|
opérations, telles que la validation de formulaire.
|
|
En effet, valider un formulaire demande beaucoup
|
|
de travail de nettoyage des données et d'affichage
|
|
des messages d'erreur appropriés.
|
|
Or, tout ce travail existe déjà dans django.
|
|
|
|
On veut donc, dans ces cas-là, ne pas demander
|
|
toute une page HTML au serveur, mais uniquement
|
|
une toute petite partie, que l'on utilisera
|
|
pour remplacer la partie qui correspond sur la page actuelle.
|
|
Ce sont des fragments.
|
|
|
|
|
|
## HTMX
|
|
|
|
Toutes les fonctionnalités d'interaction avec les
|
|
fragments, côté client, s'appuient sur la librairie htmx.
|
|
|
|
L'usage qui en est fait est en général assez simple
|
|
et ressemblera souvent à ça :
|
|
|
|
```html+jinja
|
|
<form
|
|
hx-trigger="submit" {# Lorsque le formulaire est validé... #}
|
|
hx-post="{{ url("foo:bar") }}" {# ...envoie une requête POST vers l'url donnée... #}
|
|
hx-swap="outerHTML" {# ...et remplace tout l'html du formulaire par le contenu de la réponse HTTP #}
|
|
>
|
|
{% csrf_token %}
|
|
{{ form }}
|
|
<input type="submit" value="{% trans %}Go{% endtrans %}"/>
|
|
</form>
|
|
```
|
|
|
|
C'est la majorité de ce que vous avez besoin de savoir
|
|
pour utiliser HTMX sur le site.
|
|
|
|
Bien entendu, ce n'est pas tout, il y a d'autres
|
|
options et certaines subtilités, mais pour ça,
|
|
consultez [la doc officielle d'HTMX](https://htmx.org/docs/).
|
|
|
|
## La surcouche du site
|
|
|
|
Pour faciliter et standardiser l'intégration d'HTMX
|
|
dans la base de code du site AE,
|
|
nous avons créé certains mixins à utiliser
|
|
dans les vues basées sur des classes.
|
|
|
|
### [AllowFragment][core.views.mixins.AllowFragment]
|
|
|
|
`AllowFragment` est extrêmement simple dans son
|
|
concept : il met à disposition la variable `is_fragment`,
|
|
qui permet de savoir si la vue est appelée par HTMX,
|
|
ou si elle provient d'un autre contexte.
|
|
|
|
Grâce à ça, on peut écrire des vues qui
|
|
fonctionnent dans les deux contextes.
|
|
|
|
Par exemple, supposons que nous avons
|
|
une `EditView` très simple, contenant
|
|
uniquement un formulaire.
|
|
On peut écrire la vue et le template de la manière
|
|
suivante :
|
|
|
|
=== "`views.py`"
|
|
|
|
```python
|
|
from django.views.generic import UpdateView
|
|
|
|
|
|
class FooUpdateView(UpdateView):
|
|
model = Foo
|
|
fields = ["foo", "bar"]
|
|
pk_url_kwarg = "foo_id"
|
|
template_name = "app/foo.jinja"
|
|
```
|
|
|
|
=== "`app/foo.jinja`"
|
|
|
|
```html+jinja
|
|
{% if is_fragment %}
|
|
{% extends "core/base_fragment.jinja" %}
|
|
{% else %}
|
|
{% extends "core/base.jinja" %}
|
|
{% endif %}
|
|
|
|
{% block content %}
|
|
<form hx-trigger="submit" hx-swap="outerHTML">
|
|
{% csrf_token %}
|
|
{{ form }}
|
|
<input type="submit" value="{% trans %}Go{% endtrans %}"/>
|
|
</form>
|
|
{% endblock %}
|
|
```
|
|
|
|
Lors du chargement initial de la page, le template
|
|
entier sera rendu, mais lors de la soumission du formulaire,
|
|
seul le fragment html de ce dernier sera changé.
|
|
|
|
### [FragmentMixin][core.views.mixins.FragmentMixin]
|
|
|
|
Il arrive des situations où le résultat que l'on
|
|
veut accomplir est plus complexe.
|
|
Dans ces situations, pouvoir décomposer une vue
|
|
en plusieurs vues de fragment permet de ne plus
|
|
raisonner en termes de condition, mais en termes
|
|
de composition : on n'a pas un seul template
|
|
qui peut changer les situations, on a plusieurs
|
|
templates que l'on injecte dans un template principal.
|
|
|
|
Supposons, par exemple, que nous n'avons plus un,
|
|
mais deux formulaires à afficher sur la page.
|
|
Dans ce cas, nous pouvons créer deux templates,
|
|
qui seront alors injectés.
|
|
|
|
=== "`urls.py`"
|
|
|
|
```python
|
|
from django.urls import path
|
|
|
|
from app import views
|
|
|
|
urlpatterns = [
|
|
path("", FooCompositeView.as_view(), name="main"),
|
|
path("create/", FooUpdateFragment.as_view(), name="update_foo"),
|
|
path("update/", FooCreateFragment.as_view(), name="create_foo"),
|
|
]
|
|
```
|
|
|
|
=== "`view.py`"
|
|
|
|
```python
|
|
from django.views.generic import CreateView, UpdateView, TemplateView
|
|
from core.views.mixins import FragmentMixin
|
|
|
|
|
|
class FooCreateFragment(FragmentMixin, CreateView):
|
|
model = Foo
|
|
fields = ["foo", "bar"]
|
|
template_name = "app/fragments/create_foo.jinja"
|
|
|
|
|
|
class FooUpdateFragment(FragmentMixin, UpdateView):
|
|
model = Foo
|
|
fields = ["foo", "bar"]
|
|
pk_url_kwarg = "foo_id"
|
|
template_name = "app/fragments/update_foo.jinja"
|
|
|
|
|
|
class FooCompositeFormView(TemplateView):
|
|
template_name = "app/foo.jinja"
|
|
|
|
def get_context_data(**kwargs):
|
|
return super().get_context_data(**kwargs) | {
|
|
"create_fragment": FooCreateFragment.as_fragment()(),
|
|
"update_fragment": FooUpdateFragment.as_fragment()(foo_id=1)
|
|
}
|
|
```
|
|
|
|
=== "`app/fragment/create_foo.jinja`"
|
|
|
|
```html+jinja
|
|
<form
|
|
hx-trigger="submit"
|
|
hx-post="{{ url("app:create_foo") }}"
|
|
hx-swap="outerHTML"
|
|
>
|
|
{% csrf_token %}
|
|
{{ form }}
|
|
<input type="submit" value="{% trans %}Create{% endtrans %}"/>
|
|
</form>
|
|
```
|
|
|
|
=== "`app/fragment/update_foo.jinja`"
|
|
|
|
```html+jinja
|
|
<form
|
|
hx-trigger="submit"
|
|
hx-post="{{ url("app:update_foo") }}"
|
|
hx-swap="outerHTML"
|
|
>
|
|
{% csrf_token %}
|
|
{{ form }}
|
|
<input type="submit" value="{% trans %}Update{% endtrans %}"/>
|
|
</form>
|
|
```
|
|
|
|
=== "`app/foo.jinja`"
|
|
|
|
```html+jinja
|
|
{% extends "core/base.html" %}
|
|
|
|
{% block content %}
|
|
<h2>{% trans %}Update current foo{% endtrans %}</h2>
|
|
{{ update_fragment }}
|
|
|
|
<h2>{% trans %}Create new foo{% endtrans %}</h2>
|
|
{{ create_fragment }}
|
|
{% endblock %}
|
|
```
|
|
|
|
Le résultat consistera en l'affichage d'une page
|
|
contenant deux formulaires.
|
|
Le rendu des fragments n'est pas effectué
|
|
par `FooCompositeView`, mais par les vues
|
|
des fragments elles-mêmes, en sautant
|
|
les méthodes `dispatch` et `get`/`post` de ces dernières.
|
|
À chaque validation de formulaire, la requête
|
|
sera envoyée à la vue responsable du fragment,
|
|
qui se comportera alors comme une vue normale.
|
|
|
|
#### La méthode `as_fragment`
|
|
|
|
Il est à noter que l'instantiation d'un fragment
|
|
se fait en deux étapes :
|
|
|
|
- on commence par instantier la vue en tant que renderer.
|
|
- on appelle le renderer en lui-même
|
|
|
|
Ce qui donne la syntaxe `Fragment.as_fragment()()`.
|
|
|
|
Cette conception est une manière de se rapprocher
|
|
le plus possible de l'interface déjà existante
|
|
pour la méthode `as_view` des vues.
|
|
La méthode `as_fragment` prend en argument les mêmes
|
|
paramètres que `as_view`.
|
|
|
|
Par exemple, supposons que nous voulons rajouter
|
|
des variables de contexte lors du rendu du fragment.
|
|
On peut écrire ça ainsi :
|
|
|
|
```python
|
|
fragment = Fragment.as_fragment(extra_context={"foo": "bar"})()
|
|
```
|
|
|
|
#### Personnaliser le rendu
|
|
|
|
En plus de la personnalisation permise par
|
|
`as_fragment`, on peut surcharger la méthode
|
|
`render_fragment` pour accomplir des actions
|
|
spécifiques, et ce uniquement lorsqu'on effectue
|
|
le rendu du fragment.
|
|
|
|
Supposons qu'on veuille manipuler un entier
|
|
dans la vue et que, lorsqu'on est en train
|
|
de faire le rendu du template, on veuille augmenter
|
|
la valeur de cet entier (c'est juste pour l'exemple).
|
|
On peut écrire ça ainsi :
|
|
|
|
```python
|
|
from django.views.generic import CreateView
|
|
from core.views.mixins import FragmentMixin
|
|
|
|
|
|
class FooCreateFragment(FragmentMixin, CreateView):
|
|
model = Foo
|
|
fields = ["foo", "bar"]
|
|
template_name = "app/fragments/create_foo.jinja"
|
|
|
|
def render_fragment(self, request, **kwargs):
|
|
if "foo" in kwargs:
|
|
kwargs["foo"] += 2
|
|
return super().render_fragment(request, **kwargs)
|
|
```
|
|
|
|
Et on effectuera le rendu du fragment de la manière suivante :
|
|
|
|
```python
|
|
FooCreateFragment.as_fragment()(foo=4)
|
|
```
|
|
|
|
### [UseFragmentsMixin][core.views.mixins.UseFragmentsMixin]
|
|
|
|
Lorsqu'on a plusieurs fragments, il est parfois
|
|
plus aisé des les aggréger au sein de la vue
|
|
principale en utilisant `UseFragmentsMixin`.
|
|
|
|
Elle permet de marquer de manière plus explicite
|
|
la séparation entre les fragments et le reste du contexte.
|
|
|
|
Reprenons `FooUpdateFragment` et la version modifiée
|
|
de `FooCreateFragment`.
|
|
`FooCompositeView` peut être réécrite ainsi :
|
|
|
|
```python
|
|
from django.views.generic import TemplateView
|
|
from core.views.mixins import UseFragmentsMixin
|
|
|
|
|
|
class FooCompositeFormView(UseFragmentsMixin, TemplateView):
|
|
fragments = {
|
|
"create_fragment": FooCreateFragment,
|
|
"update_fragment": FooUpdateFragment
|
|
}
|
|
fragment_data = {
|
|
"update_fragment": {"foo": 4}
|
|
}
|
|
template_name = "app/foo.jinja"
|
|
```
|
|
|
|
Le résultat sera alors strictement le même.
|
|
|
|
Pour personnaliser le rendu de tous les fragments,
|
|
on peut également surcharger la méthode
|
|
`get_fragment_context_data`.
|
|
Cette méthode remplit les mêmes objectifs
|
|
que `get_context_data`, mais uniquement pour les fragments.
|
|
Il s'agit simplement d'un utilitaire pour séparer les responsabilités.
|
|
|
|
```python
|
|
from django.views.generic import TemplateView
|
|
from core.views.mixins import UseFragmentsMixin
|
|
|
|
|
|
class FooCompositeFormView(UseFragmentsMixin, TemplateView):
|
|
fragments = {
|
|
"create_fragment": FooCreateFragment
|
|
}
|
|
template_name = "app/foo.jinja"
|
|
|
|
def get_fragment_context_data(self):
|
|
# let's render the update fragment here
|
|
# instead of using the class variables
|
|
return super().get_fragment_context_data() | {
|
|
"create_fragment": FooUpdateFragment.as_fragment()(foo=4)
|
|
}
|
|
```
|
|
|
|
|