Code

Opened 11 months ago

Last modified 11 months ago

#20435 assigned Cleanup/optimization

Reorder template tag documentation.

Reported by: jonathanslenders Owned by: danielquinn
Component: Documentation Version: master
Severity: Normal Keywords:
Cc: timograham@… Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
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.

Attachments (0)

Change History (5)

comment:1 Changed 11 months ago by aaugustin

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted
  • Version set to master

That proposal makes sense to me.

comment:2 Changed 11 months ago by zerok

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 11 months ago by danielquinn

  • Owner changed from nobody to danielquinn
  • Status changed from new to assigned

comment:4 Changed 11 months ago by danielquinn

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 11 months ago by timo

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

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

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as assigned
The owner will be changed from danielquinn to anonymous. Next status will be 'assigned'
The ticket will be disowned. Next status will be 'new'
as The resolution will be set. Next status will be 'closed'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.