Django Template Tags and Filters Advanced custom tags using Node
Example
Sometimes what you want to do is just too complex for a filter or a simple_tag. Fow this you will need to create a compilation function and a renderer.
In this example we will create a template tag verbose_name with the following syntax:
| Example | Description |
|---|---|
{% verbose_name obj %} | Verbose name of a model |
{% verbose_name obj 'status' %} | Verbose name of the field "status" |
{% verbose_name obj plural %} | Verbose name plural of a model |
{% verbose_name obj plural capfirst %} | Capitalized verbose name plural of a model |
{% verbose_name obj 'foo' capfirst %} | Capitalized verbose name of a field |
{% verbose_name obj field_name %} | Verbose name of a field from a variable |
{% verbose_name obj 'foo'|add:'_bar' %} | Verbose name of a field "foo_bar" |
The reason why we can't do this with a simple tag is that plural and capfirst are neither variables nor strings, they are "keywords". We could obviously decide to pass them as strings 'plural' and 'capfirst', but it may conflict with fields with these names. Would {% verbose_name obj 'plural' %} mean "verbose name plural of obj" or "verbose name of obj.plural"?
First let's create the compilation function:
@register.tag(name='verbose_name')
def do_verbose_name(parser, token):
"""
- parser: the Parser object. We will use it to parse tokens into
nodes such as variables, strings, ...
- token: the Token object. We will use it to iterate each token
of the template tag.
"""
# Split tokens within spaces (except spaces inside quotes)
tokens = token.split_contents()
tag_name = tokens[0]
try:
# each token is a string so we need to parse it to get the actual
# variable instead of the variable name as a string.
model = parser.compile_filter(tokens[1])
except IndexError:
raise TemplateSyntaxError(
"'{}' tag requires at least 1 argument.".format(tag_name))
field_name = None
flags = {
'plural': False,
'capfirst': False,
}
bits = tokens[2:]
for bit in bits:
if bit in flags.keys():
# here we don't need `parser.compile_filter` because we expect
# 'plural' and 'capfirst' flags to be actual strings.
if flags[bit]:
raise TemplateSyntaxError(
"'{}' tag only accept one occurrence of '{}' flag".format(
tag_name, bit)
)
flags[bit] = True
continue
if field_name:
raise TemplateSyntaxError((
"'{}' tag only accept one field name at most. {} is the second "
"field name encountered."
).format(tag_name, bit)
field_name = parser.compile_filter(bit)
# VerboseNameNode is our renderer which code is given right below
return VerboseNameNode(model, field_name, **flags)
And now the renderer:
class VerboseNameNode(Node):
def __init__(self, model, field_name=None, **flags):
self.model = model
self.field_name = field_name
self.plural = flags.get('plural', False)
self.capfirst = flags.get('capfirst', False)
def get_field_verbose_name(self):
if self.plural:
raise ValueError("Plural is not supported for fields verbose name.")
return self.model._meta.get_field(self.field_name).verbose_name
def get_model_verbose_name(self):
if self.plural:
return self.model._meta.verbose_name_plural
else:
return self.model._meta.verbose_name
def render(self, context):
"""This is the main function, it will be called to render the tag.
As you can see it takes context, but we don't need it here.
For instance, an advanced version of this template tag could look for an
`object` or `object_list` in the context if `self.model` is not provided.
"""
if self.field_name:
verbose_name = self.get_field_verbose_name()
else:
verbose_name = self.get_model_verbose_name()
if self.capfirst:
verbose_name = verbose_name.capitalize()
return verbose_name
