Django template filters, tags, simple_tags, and inclusion_tags

Question

This is more of a general question about the distinctions between these four different kinds of django tags. I just read the documentation page on template tags: http://docs.djangoproject.com/en/dev/howto/custom-template-tags/

But I'm finding it difficult to know when I should use one variation over another. For example, what can a template tag do that a simple_tag cannot? Is a filter limited to manipulating strings only and is that why the documentation says that template tags are more powerful because they can "do anything"?

Here is my perception of the distinctions:

• template filters: only operate on strings and return strings. No access to models?
• template tags: access to anything you can access in a view, compiled into nodes with a specified render function (it seems like the only advantage is that you can add variables to the context?)
• simple_tags: take strings and template variables and returns a string, you are passed the value of the template variable rather than the variable itself (when would you ever want the variable itself over the value?)
• inclusion tags: allow you to render arbitrary extra templates

Can someone give an example outlining when I would want to use one of these over another?

Thanks.

Answer 1

Template filters can operate on any object (and at most two at once). They're just functions that take one or two arguments. e.g.

# filter implementation @filter def myfilter(arg1, arg2):     ....  # usage in template {{ arg1|myfilter:arg2 }} 

They are limited in that they cannot access the template context, and can only accept a limited number of arguments.

Use case: You want to use modify one of the variables in the context slightly before printing it.

Template tags can change the way the rest of the template is parsed, and have access to anything in the context in which they are used. They're very powerful. For example I wrote a template tag that subclasses {% extends %} and allows a template to extend different templates based on the current User.

You can easily recognise template tags when they are used, because they around surrounded in {% and %}.

Use case: You want to perform some logic that requires Python code and access to the template context.

Inclusion tags are still template tags, but Django provides some helpers (i.e. the @inclusion_tag decorator) to make it easy to write template tags of this kind.

Use case: You want to render one template into another. For example you may have an advertisement on your site that you want to use in different places. It might not be possible to use template inheritance to achieve what you want, so rather than copy/paste the HTML for the ad multiple times, you would write an inclusion tag.

The reason why you would use an inclusion tag over the existing {% include %} template tag, is that you may want to render the template with a different context to the one you are in. Perhaps you need to do some database queries, to select the correct ad to display. This is not possible with {% include %}.

Simple tags like inclusion tags, simple tags are still template tags but they have limited functionality and are written in a simplified manner. They allow you to write a template tag that accepts any number of arguments (e.g. {% mytag "some str" arg2 arg3 %} etc) and require you to only implement a function that can accept these arguments (and optionally a context variable to give you access to the template context.

Essentially they're an upgrade from template filters, because instead of accepting only 1 or 2 arguments, you can accept as many as you like (and you can also access the template context).