Now that you understand a bit more about the internals of the template system, let\u2019s look at how to extend the system with custom code. Most template customization comes in the form of custom template tags and\/or filters. Although the Django template language comes with many built-in tags and filters, you\u2019ll probably assemble your own libraries of tags and filters that fit your own needs. Fortunately, it\u2019s quite easy to define your own functionality.<\/p>\n
Creating a Template Library<\/strong> – Whether you\u2019re writing custom tags or filters, the first thing to do is to create a template library<\/strong> \u2014 a small bit of infrastructure Django can hook into. Creating a template library is a two-step process:<\/p>\n books\/ __init__.py models.py templatetags\/ views.py<\/p>\n Create two empty files in the templatetags directory: an __init__.py file (to indicate to Python that this is a package containing Python code) and a file that will contain your custom tag\/filter definitions. The name of the latter file is what you\u2019ll use to load the tags later. For example, if your custom tags\/filters are in a file called poll_extras.py, you\u2019d write the following in a template:<\/p>\n {% load poll_extras %}<\/p>\n The {% load %} tag looks at your INSTALLED_APPS setting and only allows the loading of template libraries within installed Django applications. This is a security feature; it allows you to host Python code for many template libraries on a single computer without enabling access to all of them for every Django installation.<\/p>\n If you write a template library that isn\u2019t tied to any particular models\/views, it\u2019s valid and quite normal to have a Django application package that contains only a templatetags package. There\u2019s no limit on how many modules you put in the templatetags package. Just keep in mind that a {% load %} statement will load tags\/filters for the given Python module name, not the name of the application. Once you\u2019ve created that Python module, you\u2019ll just have to write a bit of Python code, depending on whether you\u2019re writing filters or tags.<\/p>\n To be a valid tag library, the module must contain a module-level variable named register that is a template.Library instance. This template.Library instance is the data structure in which all the tags and filters are registered. So, near the top of your module, insert the following:<\/p>\n from django import template<\/p>\n register = template.Library()<\/p>\n Note<\/strong> – For a good number of examples, read the source code for Django\u2019s default filters and tags. They\u2019re in django\/template\/defaultfilters.py and django\/template\/defaulttags.py, respectively. Some applications in django.contrib also contain template libraries. Once you\u2019ve created this register variable, you\u2019ll use it to create template filters and tags.<\/p>\n Writing Custom Template Filters<\/strong> – Custom filters are just Python functions that take one or two arguments:<\/p>\n For example, in the filter {{ var|foo:”bar” }}, the filter foo would be passed the contents of the variable var and the argument “bar”. Filter functions should always return something. They shouldn\u2019t raise exceptions, and they should fail silently. If there\u2019s an error, they should return either the original input or an empty string, whichever makes more sense. Here\u2019s an example filter definition:<\/p>\n def cut(value, arg): “Removes all values of arg from the given string” return value.replace(arg, ”)<\/p>\n And here\u2019s an example of how that filter would be used:<\/p>\n {{ somevariable|cut:”0″ }}<\/p>\n Most filters don\u2019t take arguments. In this case, just leave the argument out of your function:<\/p>\n def lower(value): # Only one argument. “Converts a string into all lowercase” return value.lower()<\/p>\n When you\u2019ve written your filter definition, you need to register it with your Library instance, to make it available to Django\u2019s template language:<\/p>\n register.filter(‘cut’, cut)register.filter(‘lower’, lower)<\/p>\n The Library.filter() method takes two arguments:<\/p>\n If you\u2019re using Python 2.4 or above, you can use register.filter() as a decorator instead:<\/p>\n @register.filter(name=’cut’)def cut(value, arg): return value.replace(arg, ”) @register.filterdef lower(value): return value.lower()<\/p>\n If you leave off the name argument, as in the second example, Django will use the function\u2019s name as the filter name. Here, then, is a complete template library example, supplying the cut filter:<\/p>\n from django import template register = template.Library()@register.filter(name=’cut’)def cut(value, arg): return value.replace(arg, ”)<\/p>\n Writing Custom Template Tags<\/strong> – Tags are more complex than filters, because tags can do nearly<\/p>\n anything.Chapter 4 describes how the template system works in a two-step process: compiling and rendering. To define a custom template tag, you need to tell Django how to manage both steps when it gets to your tag. When Django compiles a template, it splits the raw template text into nodes<\/em>. Each node is an instance of django.template.Node and has a render() method. Thus, a compiled template is simply a list of Node objects.<\/p>\n When you call render() on a compiled template, the template calls render() on each Node in its node list, with the given context. The results are all concatenated together to form the output of the template. Thus, to define a custom template tag, you specify how the raw template tag is converted into a Node (the compilation function) and what the node\u2019s render() method does.<\/p>\n Writing the Compilation Function<\/strong> – For each template tag it encounters, the template parser calls a Python function with the tag contents and the parser object itself. This function is responsible for returning a Node instance based on the contents of the tag.<\/p>\n For example, let\u2019s write a template tag, {% current_time %}, that displays the current date\/time, formatted according to a parameter given in the tag, in strftime syntax (see http:\/\/www.djangoproject.com\/r\/python\/strftime\/). It\u2019s a good idea to decide the tag syntax before anything else. In our case, let\u2019s say the tag should be used like this:<\/p>\n <p>The time is {% current_time “%Y-%m-%d %I:%M %p” %}.<\/p><\/p>\n Note<\/strong> – Yes, this template tag is redundant\u2014Django\u2019s default {% now %} tag does the same task with simpler syntax. This template tag is presented here just for example purposes. The parser for this function should grab the parameter and create a Node object:<\/p>\n from django import template def do_current_time(parser, token): try: # split_contents() knows not to split quoted strings. tag_name, format_string = token.split_contents() except ValueError: msg = ‘%r tag requires a single argument’ % token.contents[0] raise template.TemplateSyntaxError(msg) return CurrentTimeNode(format_string[1:-1])<\/p>\n There\u2019s actually a lot going here:<\/p>\n Writing the Template Node<\/strong> – The second step in writing custom tags is to define a Node subclass that has a render() method. Continuing the preceding example, we need to define CurrentTimeNode:<\/p>\n import datetime class CurrentTimeNode(template.Node): def __init__(self, format_string): self.format_string = format_string def render(self, context): now = datetime.datetime.now() return now.strftime(self.format_string)<\/p>\n These two functions (__init__ and render) map directly to the two steps in template processing (compilation and rendering). Thus, the initialization function only needs to store the format string for later use, and the render() function does the real work.Like template filters, these rendering functions should fail silently instead of raising errors. The only time that template tags are allowed to raise errors is at compilation time.<\/p>\n Registering the Tag<\/strong> – Finally, you need to register the tag with your module\u2019s Library instance. Registering custom tags is very similar to registering custom filters (as explained above). Just instantiate a template.Library instance and call its tag() method. For example:<\/p>\n register.tag(‘current_time’, do_current_time)<\/p>\n The tag() method takes two arguments:<\/p>\n As with filter registration, it is also possible to use register.tag as a decorator in Python 2.4 and above:<\/p>\n @register.tag(name=”current_time”)def do_current_time(parser, token): # … @register.tagdef shout(parser, token): # …<\/p>\n If you leave off the name argument, as in the second example, Django will use the function\u2019s name as the tag name.<\/p>\n Setting a Variable in the Context<\/strong> – The previous section\u2019s example simply returned a value. Often it\u2019s useful to set template variables instead of returning values. That way, template authors can just use the variables that your template tags set. To set a variable in the context, use dictionary assignment on the context object in the render() method. Here\u2019s an updated version of CurrentTimeNode that sets a template variable, current_time, instead of returning it:<\/p>\n class CurrentTimeNode2(template.Node): def __init__(self, format_string): self.format_string = format_string def render(self, context): now = datetime.datetime.now() context[‘current_time’] = now.strftime(self.format_string) return ”<\/p>\n Note that render() returns an empty string. render() should always return a string, so if all the template tag does is set a variable, render() should return an empty string. Here\u2019s how you\u2019d use this new version of the tag:<\/p>\n {% current_time2 “%Y-%M-%d %I:%M %p” %}<p>The time is {{ current_time }}.<\/p><\/p>\n But there\u2019s a problem with CurrentTimeNode2: the variable name current_time is hard-coded. This means you\u2019ll need to make sure your template doesn\u2019t use {{ current_time }} anywhere else, because {% current_time2 %} will blindly overwrite that variable\u2019s value. A cleaner solution is to make the template tag specify the name of the variable to be set, like so:<\/p>\n {% get_current_time “%Y-%M-%d %I:%M %p” as my_current_time %}<p>The current time is {{ my_current_time }}.<\/p><\/p>\n To do so, you\u2019ll need to refactor both the compilation function and the Node class, as follows:<\/p>\n import re class CurrentTimeNode3(template.Node): def __init__(self, format_string, var_name): self.format_string = format_string self.var_name = var_name def render(self, context): now = datetime.datetime.now() context[self.var_name] = now.strftime(self.format_string) return ”<\/p>\n def do_current_time(parser, token): # This version uses a regular expression to parse tag contents. try: # Splitting by None == splitting by spaces. tag_name, arg = token.contents.split(None, 1) except ValueError: msg = ‘%r tag requires arguments’ % token.contents[0] raise template.TemplateSyntaxError(msg) m = re.search(r'(.*?) as (\\w+)’, arg) if m: fmt, var_name = m.groups() else: msg = ‘%r tag had invalid arguments’ % tag_name raise template.TemplateSyntaxError(msg) if not (fmt[0] == fmt[-1] and fmt[0] in (‘”‘, “‘”)): msg = “%r tag’s argument should be in quotes” % tag_name raise template.TemplateSyntaxError(msg) return CurrentTimeNode3(fmt[1:-1], var_name)<\/p>\n Now do_current_time() passes the format string and the variable name to CurrentTimeNode3.<\/p>\n Parsing Until Another Block Tag<\/u> – Template tags can work as blocks containing other tags (think {% if %}, {% for %}, etc.). To create a template tag like this, use parser.parse() in your compilation function. Here\u2019s how the standard {% comment %} tag is implemented:<\/p>\n def do_comment(parser, token): nodelist = parser.parse((‘endcomment’,)) parser.delete_first_token() return CommentNode() class CommentNode(template.Node): def render(self, context): return ”<\/p>\n parser.parse() takes a tuple of names of block tags to parse until. It returns an instance of django.template.NodeList, which is a list of all Node objects that the parser encountered before<\/em> it encountered any of the tags named in the tuple. So in the preceding example, nodelist is a list of all nodes between {% comment %} and {% endcomment %}, not counting {% comment %} and {% endcomment %} themselves.<\/p>\n After parser.parse() is called, the parser hasn\u2019t yet \u201cconsumed\u201d the {% endcomment %} tag, so the code needs to explicitly call parser.delete_first_token() to prevent that tag from being processed twice. Then CommentNode.render() simply returns an empty string. Anything between {% comment %} and {% endcomment %} is ignored.<\/p>\n Parsing Until Another Block Tag and Saving Contents<\/u> – In the previous example, do_comment() discarded everything between {% comment %} and {% endcomment %}. It\u2019s also possible to do something with the code between block tags instead. For example, here\u2019s a custom template tag, {% upper %}, that capitalizes everything between itself and {% endupper %}:<\/p>\n {% upper %}<\/p>\n This will appear in uppercase, {{ your_name }}.<\/p>\n {% endupper %}<\/p>\n As in the previous example, we\u2019ll use parser.parse(). This time, we pass the resulting nodelist to Node:<\/p>\n @register.tag<\/p>\n def do_upper(parser, token):<\/p>\n nodelist = parser.parse((‘endupper’,))<\/p>\n parser.delete_first_token()<\/p>\n return UpperNode(nodelist)<\/p>\n class UpperNode(template.Node):<\/p>\n def __init__(self, nodelist):<\/p>\n self.nodelist = nodelist<\/p>\n def render(self, context):<\/p>\n output = self.nodelist.render(context)<\/p>\n return output.upper()<\/p>\n The only new concept here is self.nodelist.render(context) in UpperNode.render(). This simply calls render() on each Node in the node list. For more examples of complex rendering, see the source code for {% if %}, {% for %}, {% ifequal %}, and {% ifchanged %}. They live in django\/template\/defaulttags.py.<\/p>\n Shortcut for Simple Tags<\/strong> – Many template tags take a single argument\u2014a string or a template variable reference\u2014and return a string after doing some processing based solely on the input argument and some external information. For example, the current_time tag we wrote earlier is of this variety. We give it a format string, and it returns the time as a string. To ease the creation of these types of tags, Django provides a helper function, simple_tag. This function, which is a method of django.template.Library, takes a function that accepts one argument, wraps it in a render function and the other necessary bits mentioned previously, and registers it with the template system. Our earlier current_time function could thus be written like this:<\/p>\n def current_time(format_string):<\/p>\n return datetime.datetime.now().strftime(format_string)<\/p>\n register.simple_tag(current_time)<\/p>\n In Python 2.4, the decorator syntax also works:<\/p>\n @register.simple_tag<\/p>\n def current_time(token):<\/p>\n …<\/p>\n A couple of things to notice about the simple_tag helper function are as follows:<\/p>\n Inclusion Tags<\/strong> – Another common template tag is the type that displays some data by rendering another<\/em> template. For example, Django\u2019s admin interface uses custom template tags to display the buttons along the bottom of the \u201cadd\/change\u201d form pages. Those buttons always look the same, but the link targets change depending on the object being edited. They\u2019re a perfect case for using a small template that is filled with details from the current object. These sorts of tags are called inclusion tags<\/em>. Writing inclusion tags is probably best demonstrated by example. Let\u2019s write a tag that produces a list of choices for a simple multiple-choice Poll object. We\u2019ll use the tag like this:<\/p>\n {% show_results poll %}<\/p>\n The result will be something like this:<\/p>\n <ul><\/p>\n <li>First choice<\/li><\/p>\n <li>Second choice<\/li><\/p>\n <li>Third choice<\/li><\/p>\n <\/ul><\/p>\n First, we define the function that takes the argument and produces a dictionary of data for the result. Notice that we need to return only a dictionary, not anything more complex. This will be used as the context for the template fragment:<\/p>\n def show_books_for_author(author):<\/p>\n books = author.book_set.all()<\/p>\n return {‘books’: books}<\/p>\n Next, we create the template used to render the tag\u2019s output. Following our example, the template is very simple:<\/p>\n <ul><\/p>\n {% for book in books %}<\/p>\n <li> {{ book }} <\/li><\/p>\n {% endfor %}<\/p>\n <\/ul><\/p>\n Finally, we create and register the inclusion tag by calling the inclusion_tag() method on a Library object. Following our example, if the preceding template is in a file called polls\/result_snippet.html, we register the tag like this:<\/p>\n register.inclusion_tag(‘books\/books_for_author.html’)(show_books_for_author)<\/p>\n As always, Python 2.4 decorator syntax works as well, so we could have instead written this:<\/p>\n @register.inclusion_tag(‘books\/books_for_author.html’)<\/p>\n def show_books_for_author(show_books_for_author):<\/p>\n …<\/p>\n Sometimes, your inclusion tags need access to values from the parent template\u2019s context. To solve this, Django provides a takes_context option for inclusion tags. If you specify takes_context in creating a template tag, the tag will have no required arguments, and the underlying Python function will have one argument: the template context as of when the tag was called.<\/p>\n For example, say you\u2019re writing an inclusion tag that will always be used in a context that contains home_link and home_title variables that point back to the main page. Here\u2019s what the Python function would look like:<\/p>\n @register.inclusion_tag(‘link.html’, takes_context=True)<\/p>\n def jump_link(context):<\/p>\n return {<\/p>\n ‘link’: context[‘home_link’],<\/p>\n ‘title’: context[‘home_title’],<\/p>\n }<\/p>\n\n
\n
\n
\n
\n
\n