[Django] #35790: Deprecate content outside of {% block %} tags when {% extends %} is used

[Django]

#35790: Deprecate content outside of {% block %} tags when {% extends %} is used
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Type:
| Cleanup/optimization
Status: new | Component: Template
| system
Version: dev | Severity: Normal
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Currently, content outside of `{% block %}` tags in an extending template
is silently discarded. This could be a source of bugs, where written
content may appear to be rendered at first glance, but isn't.

I propose we deprecate allowing non-whitespace text nodes outside of `{%
block %}` tags, when `{% extends %}` is used. I don't think we can
disallow tags because they might be tags like `{% load %}` or `{% comment
%}` or a custom tag with other side effects.

For example, take this base template `egg.html`:

{{{
{% block yolk %}
hi
{% endblock yolk %}
}}}

And an extending template, `chicken.html`:

{{{
{% extends 'egg.html' %}

<title>Chicken egg</title>

{% block yolk %}
yellow
{% endblock yolk %}
}}}

The `<title>` content is silently discarded:

{{{
In [1]: from django.template import loader

In [2]: loader.get_template("chicken.html")
Out[2]: <django.template.backends.django.Template at 0x17431a950>

In [3]: loader.get_template("chicken.html").render()
Out[3]: '\nyellow\n\n'
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/35790>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#35790: Deprecate content outside of {% block %} tags when {% extends %} is used

--------------------------------------+------------------------------------
Reporter: Adam Johnson | Owner: (none)

Type: Cleanup/optimization | Status: new
Component: Template system | Version: dev

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

--------------------------------------+------------------------------------
Changes (by Sarah Boyce):

* stage: Unreviewed => Accepted

--
Ticket URL: <https://code.djangoproject.com/ticket/35790#comment:1>

[Django]

#35790: Deprecate content outside of {% block %} tags when {% extends %} is used

-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner: Sanjeev
Type: | Holla S
Cleanup/optimization | Status: assigned

Component: Template system | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Sanjeev Holla S):

* cc: Sanjeev Holla S (added)
* owner: (none) => Sanjeev Holla S
* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/35790#comment:2>

[Django]

#35790: Deprecate content outside of {% block %} tags when {% extends %} is used
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner: Sanjeev
Type: | Holla S
Cleanup/optimization | Status: assigned
Component: Template system | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Sanjeev Holla S):

Hello

So whenever a non-whitespace text nodes are used outside a {% block %}
tag, a deprication warning needs to be added right? (only when the
templates are extended from a base template)
--
Ticket URL: <https://code.djangoproject.com/ticket/35790#comment:3>

[Django]

#35790: Deprecate content outside of {% block %} tags when {% extends %} is used
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner: Sanjeev
Type: | Holla S
Cleanup/optimization | Status: assigned
Component: Template system | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Carlton Gibson):

I use such content quite regularly, for scratchpads and documentation. It
seems a bit mean to force that inside a comment, but I guess that would be
doable 🤔

> … a custom tag with other side effects.

Like a partialdef tag for example.
--
Ticket URL: <https://code.djangoproject.com/ticket/35790#comment:4>

[Django]

#35790: Deprecate content outside of {% block %} tags when {% extends %} is used
-------------------------------------+-------------------------------------

Reporter: Adam Johnson | Owner: Yogya
Type: | Chugh

Cleanup/optimization | Status: assigned
Component: Template system | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Yogya Chugh ):

* owner: Sanjeev Holla S => Yogya Chugh

--
Ticket URL: <https://code.djangoproject.com/ticket/35790#comment:5>

[Django]

#35790: Deprecate content outside of {% block %} tags when {% extends %} is used
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner: Yogya
Type: | Chugh
Cleanup/optimization | Status: assigned
Component: Template system | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Yogya Chugh ):

I couldn't find any changes for quite a while now and is assigning this to
myself ! If it's an issue, please do tell
--
Ticket URL: <https://code.djangoproject.com/ticket/35790#comment:6>

[Django]

#35790: Deprecate content outside of {% block %} tags when {% extends %} is used
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner: Yogya
Type: | Chugh
Cleanup/optimization | Status: assigned
Component: Template system | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Yogya Chugh ):

* has_patch: 0 => 1

Comment:

[https://github.com/django/django/pull/19302 PR]
--
Ticket URL: <https://code.djangoproject.com/ticket/35790#comment:7>

[Django]

#35790: Deprecate content outside of {% block %} tags when {% extends %} is used
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner: Yogya
Type: | Chugh
Cleanup/optimization | Status: assigned
Component: Template system | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce):

* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/35790#comment:8>

[Django]

#35790: Deprecate content outside of {% block %} tags when {% extends %} is used
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner: Yogya
Type: | Chugh
Cleanup/optimization | Status: assigned
Component: Template system | Version: dev
Severity: Normal | Resolution:

Keywords: | Triage Stage: Ready for
| checkin

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Yogya Chugh ):

* needs_better_patch: 1 => 0
* stage: Accepted => Ready for checkin

--
Ticket URL: <https://code.djangoproject.com/ticket/35790#comment:9>

[Django]

#35790: Deprecate content outside of {% block %} tags when {% extends %} is used
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner: Yogya
Type: | Chugh
Cleanup/optimization | Status: assigned
Component: Template system | Version: dev
Severity: Normal | Resolution:

Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Natalia Bidart):

* stage: Ready for checkin => Accepted

Comment:

Hello Yoga Chugh, thank you for your contribution but please note that
"Ready for Checkin" can only be set by a PR reviewer, and it can't be the
PR author. To get re-reviews, it's enough to unset (like you did) the
"patch needs improvement" flag.
--
Ticket URL: <https://code.djangoproject.com/ticket/35790#comment:10>

[Django]

#35790: Deprecate content outside of {% block %} tags when {% extends %} is used
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner: Yogya
Type: | Chugh
Cleanup/optimization | Status: assigned
Component: Template system | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Yogya Chugh ):

Sorry about that! I’ll keep it in mind going forward.
--
Ticket URL: <https://code.djangoproject.com/ticket/35790#comment:11>

[Django]

#35790: Deprecate content outside of {% block %} tags when {% extends %} is used
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner: Yogya
Type: | Chugh
Cleanup/optimization | Status: assigned
Component: Template system | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Arne):

* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/35790#comment:12>

[Django]

#35790: Deprecate content outside of {% block %} tags when {% extends %} is used
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner: Yogya
Type: | Chugh
Cleanup/optimization | Status: assigned
Component: Template system | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Chris Adams):

Hi folks. I'm reviewing this ticket with [Tom
Hall](https://github.com/[]tomhall2020), and there's a couple of questions
this brings up if you switch to raising the warning when there is a text
node outside of a block.

When we take the example below, it's reasonable that you get a warning,
and helpful to see why text `<title>Chicken egg</title>` is being silently
ignored. No problems here.

{{{

{% extends 'egg.html' %}

<title>Chicken egg</title>

{% block yolk %}
yellow
{% endblock yolk %}
}}}

There's a few other cases though.

What about where code is *not* really intended to be displayed after the
template has been rendered?

As Carlton suggested, any code like this would now be getting deprecation
errors.

{{{

{% extends 'egg.html' %}

<!-- commented out code -->
<!-- <title>Chicken egg</title> -->

{% block yolk %}
yellow
{% endblock yolk %}
}}}

Also, because we're still allowing custom tags outside a block, this would
sail through without any deprecation errors or clue to why the text in
`{{ chicken_egg_title }}`isn't appearing, because there's no real way to
discriminate between allowed and disallowed tags:

{{{

{% extends 'egg.html' %}

{{ chicken_egg_title }}

{% block yolk %}
yellow
{% endblock yolk %}
}}}

Is this the intention?

If it isn't, I wonder if it might make sense to have this as part of the
check framework, that you can switch on, rather than either forcing a
change.

Django extensions has something conceptually similar, with their
[validate_templates management command](https://django-
extensions.readthedocs.io/en/latest/validate_templates.html). Would this
be an alternative worth considering instead?
--
Ticket URL: <https://code.djangoproject.com/ticket/35790#comment:13>

[Django]

#35790: Deprecate content outside of {% block %} tags when {% extends %} is used
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner: Yogya
Type: | Chugh
Cleanup/optimization | Status: assigned
Component: Template system | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Yogya Chugh ):

Hello Chris!
Yes, the html comments and the variable node turn out to be a problem as
warning should not be raised.
Therefore, I have opened a discussion on the forum for the same
[https://forum.djangoproject.com/t/warning-for-text-outside-block-tag-
after-extends-tag/40693/ Here].
--
Ticket URL: <https://code.djangoproject.com/ticket/35790#comment:14>

[Django]

#35790: Deprecate content outside of {% block %} tags when {% extends %} is used
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner: Yogya
Type: | Chugh

Cleanup/optimization | Status: closed

Component: Template system | Version: dev

Severity: Normal | Resolution: wontfix

Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Natalia Bidart):

* resolution: => wontfix
* status: assigned => closed

Comment:

Replying to [comment:14 Yogya Chugh ]:

> Hello Chris!
> Yes, the html comments and the variable node turn out to be a problem as
warning should not be raised.
> Therefore, I have opened a discussion on the forum for the same
[https://forum.djangoproject.com/t/warning-for-text-outside-block-tag-
after-extends-tag/40693/ Here].

Thank you, Yogya, for your work so far and for starting the discussion on
the forum. Your post was right on target and really reflected the Django
community's spirit of collaborative decision-making. Based on the feedback
there, I think the right outcome here is to close the ticket as `wontfix`.
That said, your contribution and the thoughtful process you followed are
genuinely appreciated. We hope to see more contributions from you!
--
Ticket URL: <https://code.djangoproject.com/ticket/35790#comment:15>

[Django]

#35790: Deprecate content outside of {% block %} tags when {% extends %} is used
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner: Yogya
Type: | Chugh
Cleanup/optimization | Status: closed
Component: Template system | Version: dev
Severity: Normal | Resolution: wontfix
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Yogya Chugh ):

Thank you! Nothing lost — I learned some good stuff through this. On the
lookout for my next ticket!
--
Ticket URL: <https://code.djangoproject.com/ticket/35790#comment:16>