Opened 5 years ago
Last modified 4 years ago
#27106 assigned Cleanup/optimization
Document which template filters can be used in Python code (and how)
Reported by: | Baptiste Mispelon | Owned by: | Burhan Khalid |
---|---|---|---|
Component: | Documentation | Version: | 1.10 |
Severity: | Normal | Keywords: | |
Cc: | Triage Stage: | Accepted | |
Has patch: | yes | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | yes |
Easy pickings: | no | UI/UX: | no |
Description
The Django template language ships with a lot of filters. Usually they're implemented as Python functions and can be imported and used in your own code.
However this particular usage is not documented (take the example of the various truncate*
filters [1]).
I think it would be useful to know:
1) Which template filters can be used as functions;
2) Where to import them from and how to use them;
3) If there are limitations/gotchas related to using them.
[1] https://docs.djangoproject.com/en/1.10/ref/templates/builtins/#truncatechars
Change History (7)
comment:1 Changed 5 years ago by
Triage Stage: | Unreviewed → Accepted |
---|
comment:2 Changed 5 years ago by
Yes, generally speaking Django template filters should be thin wrappers about utility functions. This makes it easy to use the underlying plain function in Jinja2 templates.
comment:3 Changed 4 years ago by
Owner: | changed from nobody to Burhan Khalid |
---|---|
Status: | new → assigned |
I'll work a PR for this, where I'll link to the relevant django.utils.*
documentation for those filters that are pure wrappers for other functions.
comment:4 Changed 4 years ago by
Has patch: | set |
---|
https://github.com/django/django/pull/7519
There was some documentation missing for some of the utils functions, which I added to the relevant sections in order to ensure Sphinx internal references were linked correctly.
comment:5 Changed 4 years ago by
Patch needs improvement: | set |
---|
comment:6 Changed 4 years ago by
Patch needs improvement: | unset |
---|
comment:7 Changed 4 years ago by
Patch needs improvement: | set |
---|
While I think I've imported from
django.template.defaultfilters
in some of my own projects, I'm not sure that promoting that pattern as a public API is a good idea. Some of the filters use functions fromdjango.utils.*
, e.g. theslugify
filter usesdjango.utils.text.slugify
. I don't mind linking to those utility functions from the template tag documentation.