Context Navigation

← Previous Ticket
Next Ticket →

#36044 closed Cleanup/optimization (wontfix)

Reusable form templates example lead to a TemplateDoesNotExist error

Reported by:	Guillaume LEBRETON	Owned by:	Guillaume LEBRETON
Component:	Documentation	Version:	5.1
Severity:	Normal	Keywords:
Cc:	Guillaume LEBRETON, David Smith	Triage Stage:	Accepted
Has patch:	yes	Needs documentation:	no
Needs tests:	no	Patch needs improvement:	yes
Easy pickings:	no	UI/UX:	no

Description

Following the docs https://docs.djangoproject.com/en/5.1/topics/forms/#reusable-form-templates, i tried to set a a form template.

settings.py

#...
#...

from django.forms.renderers import TemplatesSetting


class CustomFormRenderer(TemplatesSetting):
    form_template_name = "form_snippet.html"


FORM_RENDERER = "django_bug.settings.CustomFormRenderer"

models.py

from django.db import models

class Car(models.Model):
    name = models.CharField(max_length=100)

forms.py

from cars.models import Car
from django import forms


class CarForm(forms.ModelForm):
    class Meta:
        model = Car
        fields = '__all__'

views.py

from django.views.generic import CreateView

from cars.forms import CarForm
from cars.models import Car


class CarCreateView(CreateView):
    model = Car
    form_class = CarForm

template/cars/car_form.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>

This is form:

{{ form }}

</body>
</html>

template/form_snippet.html

{% for field in form %}
    <div class="fieldWrapper">
        wrapper from snippet
        {{ field.errors }}
        {{ field.label_tag }} {{ field }}
    </div>
{% endfor %}

and then:

TemplateDoesNotExist at /create_car/

django/forms/errors/list/default.html

Request Method: 	GET
Request URL: 	http://localhost:8000/create_car/
Django Version: 	5.1.4
Exception Type: 	TemplateDoesNotExist
Exception Value: 	

django/forms/errors/list/default.html

So either i missed a step but maybe the doc example is not very clear, or the example should be modified because inheriting from DjangoTemplates
instead of TemplateSettings made the example work out of the box:

from django.forms.renderers import DjangoTemplates


class CustomFormRenderer(DjangoTemplates):
    form_template_name = "form_snippet.html"


FORM_RENDERER = "django_bug.settings.CustomFormRenderer"

I tried the search engine issue but didn't find any related ones. Can i propose an update to the docs ?

Change History (14)

comment:1 by Asfand Yar Khan, 10 months ago

Yes it does work with DjangoTemplates , I am not sure but can someone confirm if this is just a document change ?

Last edited 10 months ago by Asfand Yar Khan (previous) (diff)

comment:2 by Tim Graham, 10 months ago

I'm inclined to think you probably didn't configure TemplatesSetting as documented. i.e. "Using this renderer requires you to make sure the form templates your project needs can be located."

I'm unsure if modifying the example would improve it since what works "out of the box" for one project may not work for another.

comment:3 by Asfand Yar Khan, 10 months ago

Thanks, works after configuring TemplatesSetting.

comment:4 by Asfand Yar Khan, 10 months ago

Resolution:	→ invalid
Status:	new → closed

comment:5 by Guillaume LEBRETON, 10 months ago

Resolution:	invalid
Status:	closed → new

You're right, i didn't configure TemplateSetting, because in the doc paragraph https://docs.djangoproject.com/en/5.1/topics/forms/#reusable-form-templates, there's no mention of any prior conffiguration needed. It says you have to configure a form renderer, and in the link there's 3 different form renderers: https://docs.djangoproject.com/en/5.1/ref/settings/#form-renderer, but somehow the one that doesn't need configuration is not used in the example.

Let me summarize how a user would use the doc, here is the actual situation:

You create a new django project, without any customization
You create a form view
You copy paste snippets from https://docs.djangoproject.com/en/5.1/topics/forms/#reusable-form-templates
You have an error about missing templates
You click on https://docs.djangoproject.com/en/5.1/ref/settings/#std-setting-FORM_RENDERER
You click on https://docs.djangoproject.com/en/5.1/ref/forms/renderers/#django.forms.renderers.TemplatesSetting
Put django.forms in installed apps

Scratch your head about where to put this snippet

import django

django.__path__[0] + "/forms/templates"  # or '/forms/jinja2'

Realize that this one was not necessary for the example, and profit, the example is working

Now, with having DjangoTemplates instead of TemplatesSetting:

You create a new django project, without any customization
You create a form view
You copy paste snippets from https://docs.djangoproject.com/en/5.1/topics/forms/#reusable-form-templates
It's working, and you can start have customized form templates.

So maybe i missed a point and i hope you will tell me before closing the ticket, but as an end user of the documentation it seems for me unecessary complicated. With DjangoTemplates you go straight to the point, and you can re-use form templates, just as the docs sections says

comment:6 by Sarah Boyce, 10 months ago

Cc:	David Smith added

https://docs.djangoproject.com/en/5.1/ref/forms/renderers/#django.forms.renderers.DjangoTemplates

If you want to render templates with customizations from your TEMPLATES setting, such as context processors for example, use the TemplatesSetting renderer.

I think the above might be why customized renderers inherit from TemplatesSetting.
Occasionally in examples we have a comment like # ... to indicate something is incomplete/partial for the example. So perhaps a comment or having it inherit from DjangoTemplates is an idea.

I'd quite like to hear David's opinion here

comment:7 by Sarah Boyce, 10 months ago

Type:	Uncategorized → Cleanup/optimization

comment:8 by Sarah Boyce, 10 months ago

Triage Stage:	Unreviewed → Accepted

Tentatively accepting

comment:9 by Guillaume LEBRETON, 10 months ago

Has patch:	set
Owner:	set to Guillaume LEBRETON
Status:	new → assigned

comment:10 by Guillaume LEBRETON, 10 months ago

https://github.com/django/django/pull/18999

comment:11 by Sarah Boyce, 10 months ago

Patch needs improvement:	set

comment:12 by Sarah Boyce, 9 months ago

Resolution:	→ wontfix
Status:	assigned → closed

Following a discussion on the pull request, we have decided to leave the docs as they are.
Thank you all for the discussion

comment:13 by Kevin Renskers, 7 months ago

I ran into the exact same problem: when following the docs on https://docs.djangoproject.com/en/5.1/topics/forms/#reusable-form-templates with a standard Django project, created by the startproject command, you get a TemplateDoesNotExist error.

And no, I didn't have TemplatesSetting configured, since the default project settings don't do that. And this is not mentioned at https://docs.djangoproject.com/en/5.1/topics/forms/#reusable-form-templates at all. So I find it a bit strange that this issue got closed without any changes to the docs at all. Can the documentation at least tell users that they need to add django.forms to their INSTALLED_APPS for this to work?

I'm unsure if modifying the example would improve it since what works "out of the box" for one project may not work for another.

The example on https://docs.djangoproject.com/en/5.1/topics/forms/#reusable-form-templates results in an error by default, with a standard Django project as created by the startproject command. It's a pretty bad user experience when you run into this and you're scratching your head why the example doesn't work.

comment:14 by Ahmed Nassar, 7 months ago

Hi everyone,
Can I work on and address this ticket? Is it still relevant? I will be happy to work and submit my PR.
Thanks!

Note: See TracTickets for help on using tickets.

Download in other formats:

Issues