Opened 4 years ago

Closed 2 years ago

#20435 closed Cleanup/optimization (fixed)

Reorder template tag documentation.

Reported by: jonathanslenders Owned by: Daniel Roseman
Component: Documentation Version: master
Severity: Normal Keywords:
Cc: timograham@… Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

Right now, the documentation for creation of custom template tags, using a (parser, token)-function, is mentioned above the creation of simple template tags.
It would be great to revert this order, and make clear that when possible a simple tag is recommended. (Not only for readability.)

Why?:
The ability of creating custom template tags using (parser, token) is great, but it's a lot harder or impossible to predict the behaviour or the change the template render engine if we ever have to in the future. Making sure that people are using as much as possible the built-in Node classes, would do for a nice abstract syntax tree in moste cases.

https://docs.djangoproject.com/en/dev/howto/custom-template-tags/

See this ticket #20434 for related info.

Change History (8)

comment:1 Changed 4 years ago by Aymeric Augustin

Triage Stage: UnreviewedAccepted
Version: master

That proposal makes sense to me.

comment:2 Changed 4 years ago by Horst Gutmann

I definitely agree. We should encourage people to put far more logic into template tags and filters than in the templates themselves. Having the most complicated approach being mentioned first, doesn't help.

comment:3 Changed 4 years ago by Daniel Quinn

Owner: changed from nobody to Daniel Quinn
Status: newassigned

comment:4 Changed 4 years ago by Daniel Quinn

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

Basically I broke the whole tags section up into "Simple" and "Advanced", placing the simple stuff first.

comment:5 Changed 4 years ago by Tim Graham

Cc: timograham@… added
Has patch: set
Patch needs improvement: set

Existing pull request doesn't merge cleanly due to some recent commits.

comment:6 Changed 2 years ago by Daniel Roseman

Owner: changed from Daniel Quinn to Daniel Roseman

comment:7 Changed 2 years ago by Daniel Roseman

Patch needs improvement: unset

comment:8 Changed 2 years ago by Julien Phalip <jphalip@…>

Resolution: fixed
Status: assignedclosed

In 524e71c9c20da57722b22b978d87690379ca4ade:

Fixed #20435 -- Reordered the custom template tags docs.

Introduced the various shortcuts before explaining the more complex
parser/render functionality.

Also removed non-decorator syntax: it's been years since Django
supported a Python version without decorators.

Note: See TracTickets for help on using tickets.
Back to Top