diff --git a/core/utils.py b/core/utils.py index 6b72bde8..2f56cebf 100644 --- a/core/utils.py +++ b/core/utils.py @@ -13,40 +13,20 @@ # # -from dataclasses import dataclass from datetime import date, timedelta # Image utils from io import BytesIO -from typing import Any import PIL from django.conf import settings from django.core.files.base import ContentFile -from django.forms import BaseForm from django.http import HttpRequest -from django.template.loader import render_to_string -from django.utils.html import SafeString from django.utils.timezone import localdate from PIL import ExifTags from PIL.Image import Image, Resampling -@dataclass -class FormFragmentTemplateData[T: BaseForm]: - """Dataclass used to pre-render form fragments""" - - form: T - template: str - context: dict[str, Any] - - def render(self, request: HttpRequest) -> SafeString: - # Request is needed for csrf_tokens - return render_to_string( - self.template, context={"form": self.form, **self.context}, request=request - ) - - def get_start_of_semester(today: date | None = None) -> date: """Return the date of the start of the semester of the given date. If no date is given, return the start date of the current semester. diff --git a/core/views/mixins.py b/core/views/mixins.py index e5b445d6..2a18955c 100644 --- a/core/views/mixins.py +++ b/core/views/mixins.py @@ -1,8 +1,14 @@ -from typing import ClassVar +import copy +import inspect +from typing import Any, ClassVar, LiteralString, Protocol, Unpack from django.conf import settings from django.core.exceptions import ImproperlyConfigured +from django.http import HttpRequest, HttpResponse +from django.template.loader import render_to_string +from django.utils.safestring import SafeString from django.views import View +from django.views.generic.base import ContextMixin, TemplateResponseMixin class TabedViewMixin(View): @@ -71,3 +77,152 @@ class AllowFragment: def get_context_data(self, **kwargs): kwargs["is_fragment"] = self.request.headers.get("HX-Request", False) return super().get_context_data(**kwargs) + + +class FragmentRenderer(Protocol): + def __call__( + self, request: HttpRequest, **kwargs: Unpack[dict[str, Any]] + ) -> SafeString: ... + + +class FragmentMixin(TemplateResponseMixin, ContextMixin): + """Make a view buildable as a fragment that can be embedded in a template. + + Most fragments are used in two different ways : + - in the request/response cycle, like any regular view + - in templates, where the rendering is done in another view + + This mixin aims to simplify the initial fragment rendering. + The rendered fragment will then be able to re-render itself + through the request/response cycle if it uses HTMX. + + !!!Example + ```python + class MyFragment(FragmentMixin, FormView): + template_name = "app/fragment.jinja" + form_class = MyForm + success_url = reverse_lazy("foo:bar") + + # in another view : + def some_view(request): + fragment = MyFragment.as_fragment() + return render( + request, + "app/template.jinja", + context={"fragment": fragment(request) + } + + # in urls.py + urlpatterns = [ + path("foo/view", some_view), + path("foo/fragment", MyFragment.as_view()), + ] + ``` + """ + + reload_on_redirect: bool = False + """If True, this fragment will trigger a full page reload on redirect.""" + + @classmethod + def as_fragment(cls, **initkwargs) -> FragmentRenderer: + # the following code is heavily inspired from the base View.as_view method + for key in initkwargs: + if not hasattr(cls, key): + raise TypeError( + "%s() received an invalid keyword %r. as_view " + "only accepts arguments that are already " + "attributes of the class." % (cls.__name__, key) + ) + + def fragment(request: HttpRequest, **kwargs) -> SafeString: + self = cls(**initkwargs) + # any POST action on the fragment will be dealt by the fragment itself. + # So, if the view that is rendering this fragment is in a POST context, + # let's pretend anyway it's a GET, in order to be sure the fragment + # won't try to do any POST action (like form validation) on initial render. + self.request = copy.copy(request) + self.request.method = "GET" + self.kwargs = kwargs + return self.render_fragment(request, **kwargs) + + fragment.__doc__ = cls.__doc__ + fragment.__module__ = cls.__module__ + return fragment + + def render_fragment(self, request, **kwargs) -> SafeString: + return render_to_string( + self.get_template_names(), + context=self.get_context_data(**kwargs), + request=request, + ) + + def dispatch(self, *args, **kwargs): + res: HttpResponse = super().dispatch(*args, **kwargs) + if 300 <= res.status_code < 400 and self.reload_on_redirect: + # HTMX doesn't care about redirection codes (because why not), + # so we must transform the redirection code into a 200. + res.status_code = 200 + res.headers["HX-Redirect"] = res["Location"] + return res + + +class UseFragmentsMixin(ContextMixin): + """Mark a view as using fragments. + + This mixin is not mandatory + (you may as well render manually your fragments in the `get_context_data` method). + However, the interface of this class bring some distinction + between fragments and other context data, which may + reduce boilerplate. + + !!!Example + ```python + class FooFragment(FragmentMixin, FormView): ... + + class BarFragment(FragmentMixin, FormView): ... + + class AdminFragment(FragmentMixin, FormView): ... + + class MyView(UseFragmentsMixin, TemplateView) + template_name = "app/view.jinja" + fragments = { + "foo": FooFragment + "bar": BarFragment(template_name="some_template.jinja") + } + fragments_data = { + "foo": {"some": "data"} # this will be passed to the FooFragment renderer + } + + def get_fragments(self): + res = super().get_fragments() + if self.request.user.is_superuser: + res["admin_fragment"] = AdminFragment + return res + ``` + """ + + fragments: dict[LiteralString, type[FragmentMixin] | FragmentRenderer] | None = None + fragment_data: dict[LiteralString, dict[LiteralString, Any]] | None = None + + def get_fragments(self) -> dict[str, type[FragmentMixin] | FragmentRenderer]: + return self.fragments if self.fragments is not None else {} + + def get_fragment_data(self) -> dict[str, dict[str, Any]]: + """Return eventual data used to initialize the fragments.""" + return self.fragment_data if self.fragment_data is not None else {} + + def get_fragment_context_data(self) -> dict[str, SafeString]: + """Return the rendered fragments as context data.""" + res = {} + data = self.get_fragment_data() + for name, fragment in self.get_fragments().items(): + is_cls = inspect.isclass(fragment) and issubclass(fragment, FragmentMixin) + _fragment = fragment.as_fragment() if is_cls else fragment + fragment_data = data.get(name, {}) + res[name] = _fragment(self.request, **fragment_data) + return res + + def get_context_data(self, **kwargs): + kwargs = super().get_context_data(**kwargs) + kwargs.update(self.get_fragment_context_data()) + return kwargs diff --git a/core/views/user.py b/core/views/user.py index cd27cbba..cd8fd55b 100644 --- a/core/views/user.py +++ b/core/views/user.py @@ -41,6 +41,7 @@ from django.template.loader import render_to_string from django.template.response import TemplateResponse from django.urls import reverse, reverse_lazy from django.utils.decorators import method_decorator +from django.utils.safestring import SafeString from django.utils.translation import gettext as _ from django.views.generic import ( CreateView, @@ -63,8 +64,9 @@ from core.views.forms import ( UserGroupsForm, UserProfileForm, ) -from core.views.mixins import QuickNotifMixin, TabedViewMixin +from core.views.mixins import QuickNotifMixin, TabedViewMixin, UseFragmentsMixin from counter.models import Counter, Refilling, Selling +from counter.views.student_card import StudentCardFormFragment from eboutic.models import Invoice from subscription.models import Subscription from trombi.views import UserTrombiForm @@ -508,7 +510,7 @@ class UserClubView(UserTabsMixin, CanViewMixin, DetailView): current_tab = "clubs" -class UserPreferencesView(UserTabsMixin, CanEditMixin, UpdateView): +class UserPreferencesView(UserTabsMixin, UseFragmentsMixin, CanEditMixin, UpdateView): """Edit a user's preferences.""" model = User @@ -526,17 +528,18 @@ class UserPreferencesView(UserTabsMixin, CanEditMixin, UpdateView): kwargs.update({"instance": pref}) return kwargs + def get_fragment_context_data(self) -> dict[str, SafeString]: + res = super().get_fragment_context_data() + if hasattr(self.object, "customer"): + res["student_card_fragment"] = StudentCardFormFragment.as_fragment()( + self.request, customer=self.object.customer + ) + return res + def get_context_data(self, **kwargs): kwargs = super().get_context_data(**kwargs) - if not hasattr(self.object, "trombi_user"): kwargs["trombi_form"] = UserTrombiForm() - if hasattr(self.object, "customer"): - from counter.views.student_card import StudentCardFormView - - kwargs["student_card_fragment"] = StudentCardFormView.get_template_data( - self.object.customer - ).render(self.request) return kwargs diff --git a/counter/urls.py b/counter/urls.py index 04757aa1..67c7d950 100644 --- a/counter/urls.py +++ b/counter/urls.py @@ -56,7 +56,7 @@ from counter.views.home import ( CounterMain, ) from counter.views.invoice import InvoiceCallView -from counter.views.student_card import StudentCardDeleteView, StudentCardFormView +from counter.views.student_card import StudentCardDeleteView, StudentCardFormFragment urlpatterns = [ path("/", CounterMain.as_view(), name="details"), @@ -83,7 +83,7 @@ urlpatterns = [ path("eticket//pdf/", EticketPDFView.as_view(), name="eticket_pdf"), path( "customer//card/add/", - StudentCardFormView.as_view(), + StudentCardFormFragment.as_view(), name="add_student_card", ), path( diff --git a/counter/views/click.py b/counter/views/click.py index a44e841f..4da38643 100644 --- a/counter/views/click.py +++ b/counter/views/click.py @@ -26,7 +26,8 @@ from django.forms import ( ) from django.http import Http404 from django.shortcuts import get_object_or_404, redirect, resolve_url -from django.urls import reverse_lazy +from django.urls import reverse +from django.utils.safestring import SafeString from django.utils.translation import gettext_lazy as _ from django.views.generic import FormView from django.views.generic.detail import SingleObjectMixin @@ -34,7 +35,7 @@ from ninja.main import HttpRequest from core.auth.mixins import CanViewMixin from core.models import User -from core.utils import FormFragmentTemplateData +from core.views.mixins import FragmentMixin, UseFragmentsMixin from counter.forms import RefillForm from counter.models import ( Counter, @@ -45,7 +46,7 @@ from counter.models import ( ) from counter.utils import is_logged_in_counter from counter.views.mixins import CounterTabsMixin -from counter.views.student_card import StudentCardFormView +from counter.views.student_card import StudentCardFormFragment def get_operator(request: HttpRequest, counter: Counter, customer: Customer) -> User: @@ -163,7 +164,9 @@ BasketForm = formset_factory( ) -class CounterClick(CounterTabsMixin, CanViewMixin, SingleObjectMixin, FormView): +class CounterClick( + CounterTabsMixin, UseFragmentsMixin, CanViewMixin, SingleObjectMixin, FormView +): """The click view This is a detail view not to have to worry about loading the counter Everything is made by hand in the post method. @@ -304,6 +307,18 @@ class CounterClick(CounterTabsMixin, CanViewMixin, SingleObjectMixin, FormView): def get_success_url(self): return resolve_url(self.object) + def get_fragment_context_data(self) -> dict[str, SafeString]: + res = super().get_fragment_context_data() + if self.object.type == "BAR": + res["student_card_fragment"] = StudentCardFormFragment.as_fragment()( + self.request, customer=self.customer + ) + if self.object.can_refill(): + res["refilling_fragment"] = RefillingCreateView.as_fragment()( + self.request, customer=self.customer + ) + return res + def get_context_data(self, **kwargs): """Add customer to the context.""" kwargs = super().get_context_data(**kwargs) @@ -321,39 +336,15 @@ class CounterClick(CounterTabsMixin, CanViewMixin, SingleObjectMixin, FormView): kwargs["form_errors"] = [ list(field_error.values()) for field_error in kwargs["form"].errors ] - if self.object.type == "BAR": - kwargs["student_card_fragment"] = StudentCardFormView.get_template_data( - self.customer - ).render(self.request) - - if self.object.can_refill(): - kwargs["refilling_fragment"] = RefillingCreateView.get_template_data( - self.customer - ).render(self.request) - return kwargs -class RefillingCreateView(FormView): +class RefillingCreateView(FragmentMixin, FormView): """This is a fragment only view which integrates with counter_click.jinja""" form_class = RefillForm template_name = "counter/fragments/create_refill.jinja" - @classmethod - def get_template_data( - cls, customer: Customer, *, form_instance: form_class | None = None - ) -> FormFragmentTemplateData[form_class]: - return FormFragmentTemplateData( - form=form_instance if form_instance else cls.form_class(), - template=cls.template_name, - context={ - "action": reverse_lazy( - "counter:refilling_create", kwargs={"customer_id": customer.pk} - ), - }, - ) - def dispatch(self, request, *args, **kwargs): self.customer: Customer = get_object_or_404(Customer, pk=kwargs["customer_id"]) if not self.customer.can_buy: @@ -373,6 +364,10 @@ class RefillingCreateView(FormView): return super().dispatch(request, *args, **kwargs) + def render_fragment(self, request, **kwargs) -> SafeString: + self.customer = kwargs.pop("customer") + return super().render_fragment(request, **kwargs) + def form_valid(self, form): res = super().form_valid(form) form.clean() @@ -383,10 +378,11 @@ class RefillingCreateView(FormView): return res def get_context_data(self, **kwargs): - context = super().get_context_data(**kwargs) - data = self.get_template_data(self.customer, form_instance=context["form"]) - context.update(data.context) - return context + kwargs = super().get_context_data(**kwargs) + kwargs["action"] = reverse( + "counter:refilling_create", kwargs={"customer_id": self.customer.pk} + ) + return kwargs def get_success_url(self, **kwargs): return self.request.path diff --git a/counter/views/student_card.py b/counter/views/student_card.py index 6e2a3358..9aef2e11 100644 --- a/counter/views/student_card.py +++ b/counter/views/student_card.py @@ -13,16 +13,16 @@ # # - from django.core.exceptions import PermissionDenied from django.http import Http404, HttpRequest, HttpResponse from django.shortcuts import get_object_or_404 from django.urls import reverse +from django.utils.safestring import SafeString from django.utils.translation import gettext as _ from django.views.generic.edit import DeleteView, FormView from core.auth.mixins import can_edit -from core.utils import FormFragmentTemplateData +from core.views.mixins import FragmentMixin from counter.forms import StudentCardForm from counter.models import Customer, StudentCard from counter.utils import is_logged_in_counter @@ -62,28 +62,12 @@ class StudentCardDeleteView(DeleteView): ) -class StudentCardFormView(FormView): - """Add a new student card. This is a fragment view !""" +class StudentCardFormFragment(FragmentMixin, FormView): + """Add a new student card.""" form_class = StudentCardForm template_name = "counter/fragments/create_student_card.jinja" - @classmethod - def get_template_data( - cls, customer: Customer, *, form_instance: form_class | None = None - ) -> FormFragmentTemplateData[form_class]: - """Get necessary data to pre-render the fragment""" - return FormFragmentTemplateData( - form=form_instance if form_instance else cls.form_class(), - template=cls.template_name, - context={ - "action": reverse( - "counter:add_student_card", kwargs={"customer_id": customer.pk} - ), - "customer": customer, - }, - ) - def dispatch(self, request: HttpRequest, *args, **kwargs): self.customer = get_object_or_404( Customer.objects.select_related("student_card"), pk=kwargs["customer_id"] @@ -96,6 +80,10 @@ class StudentCardFormView(FormView): return super().dispatch(request, *args, **kwargs) + def render_fragment(self, request, **kwargs) -> SafeString: + self.customer = kwargs.pop("customer") + return super().render_fragment(request, **kwargs) + def form_valid(self, form: StudentCardForm) -> HttpResponse: data = form.clean() StudentCard.objects.update_or_create( @@ -104,10 +92,12 @@ class StudentCardFormView(FormView): return super().form_valid(form) def get_context_data(self, **kwargs): - context = super().get_context_data(**kwargs) - data = self.get_template_data(self.customer, form_instance=context["form"]) - context.update(data.context) - return context + return super().get_context_data(**kwargs) | { + "action": reverse( + "counter:add_student_card", kwargs={"customer_id": self.customer.pk} + ), + "customer": self.customer, + } def get_success_url(self, **kwargs): return self.request.path diff --git a/docs/reference/core/mixins.md b/docs/reference/core/mixins.md new file mode 100644 index 00000000..d08c1ee8 --- /dev/null +++ b/docs/reference/core/mixins.md @@ -0,0 +1,10 @@ +::: core.views.mixins + handler: python + options: + heading_level: 3 + members: + - TabedViewMixin + - QuickNotifMixin + - AllowFragment + - FragmentMixin + - UseFragmentsMixin \ No newline at end of file diff --git a/docs/tutorial/fragments.md b/docs/tutorial/fragments.md index 007d4c0d..bcb85909 100644 --- a/docs/tutorial/fragments.md +++ b/docs/tutorial/fragments.md @@ -1,40 +1,356 @@ -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. +## Qu'est-ce qu'un fragment -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. +Une application web django traditionnelle suit en général +le schéma suivant : -Pour remédier à cela, il existe le mixin [AllowFragment][core.views.AllowFragment]. +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 -Une fois ajouté à une vue Django, il ajoute le boolean `is_fragment` dans les -templates jinja. Sa valeur est `True` uniquement si HTMX envoie la requête. -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. +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. -Exemple d'utilisation d'une vue avec fragment: +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 +
+ {% csrf_token %} + {{ 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 %} +
+ {% csrf_token %} + {{ 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 +
+ {% csrf_token %} + {{ form }} + +
+ ``` + +=== "`app/fragment/update_foo.jinja`" + + ```html+jinja +
+ {% csrf_token %} + {{ form }} + +
+ ``` + +=== "`app/foo.jinja`" + + ```html+jinja + {% extends "core/base.html" %} + + {% block content %} +

{% trans %}Update current foo{% endtrans %}

+ {{ update_fragment }} + +

{% trans %}Create new foo{% endtrans %}

+ {{ 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 import AllowFragment +from core.views.mixins import UseFragmentsMixin -class FragmentView(AllowFragment, TemplateView): - template_name = "my_template.jinja" + +class FooCompositeFormView(UseFragmentsMixin, TemplateView): + fragments = { + "create_fragment": FooCreateFragment, + "update_fragment": FooUpdateFragment + } + fragment_data = { + "update_fragment": {"foo": 4} + } + template_name = "app/foo.jinja" ``` -Exemple de template (`my_template.jinja`) -```jinja -{% if is_fragment %} - {% extends "core/base_fragment.jinja" %} -{% else %} - {% extends "core/base.jinja" %} -{% endif %} +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 -{% block title %} - {% trans %}My view with a fragment{% endtrans %} -{% endblock %} +class FooCompositeFormView(UseFragmentsMixin, TemplateView): + fragments = { + "create_fragment": FooCreateFragment + } + template_name = "app/foo.jinja" -{% block content %} -

{% trans %}This will be a fragment when is_fragment is True{% endtrans %} -{% endblock %} + 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) + } ``` + + diff --git a/mkdocs.yml b/mkdocs.yml index 73758b9d..4dfe67dc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -66,7 +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 + - Les fragments: tutorial/fragments.md - Etransactions: tutorial/etransaction.md - How-to: - L'ORM de Django: howto/querysets.md @@ -94,6 +94,7 @@ nav: - reference/core/models.md - Champs de modèle: reference/core/model_fields.md - reference/core/views.md + - reference/core/mixins.md - reference/core/schemas.md - reference/core/auth.md - counter: