{% extends "/documentation-base.html" %} {% block title %}Djula Documentation{% endblock %} {% block style %} {% endblock style %} {% block body %} {# kludge until block.super is implemented #} {% block prepend-to-documentation1 %} {% endblock %} {% filter link-tags-to-definitions|link-variables-to-documentation|link-comments-to-documentation %}

Djula Documentation Quick Reference

  1. Variables
  2. Filters
  3. Tags
  4. Template Inheritance
  5. How Djula is different from the Django templating language
{# kludge until block.super is implemented #} {% block prepend-to-documentation2 %} {% endblock %}

Djula Documentation

This is all based on the Django templating language, if you are familiar it then Djula templates will be a breeze. In fact most of the text on this page was directly copied from The Django template language: for template authors. For a list of how Djula is different in from the Django templating language click here

Variables

Variables look like this: {% templatetag openvariable %} variable {% templatetag closevariable%}. When the template engine encounters a variable, it evaluates that variable and replaces it with the result.

Use a dot (.) to access attributes of a variable or index of a list. {% templatetag openvariable %} user.name {% templatetag closevariable%} will be replaced with the name attribute of the user object (Lisp hackers: this is a plist lookup). {% templatetag openvariable %} users.1 {% templatetag closevariable%} will be replaced with the first user object of the list users. You can use multiple dots with a variable, so {% templatetag openvariable %} users.1.name {% templatetag closevariable%} will be replaced with the name attribute of the first user object of the list users.

Filters

You can modify variables for display by using filters.

Filters look like this: {% templatetag openvariable %} name|lowercase {% templatetag closevariable %}. This displays the value of the {% templatetag openvariable %} name {% templatetag closevariable %} after being filtered through the lowercase filter, which converts text to lowercase. Use a pipe (|) to apply a filter.

Filters can be "chained." The output of one filter is applied to the next. {% templatetag openvariable %} name|lowercase|urlencode {% templatetag closevariable %} displays name after being lowercased and url-encoded.

Some filters take arguments. A filter argument looks like this: {% templatetag openvariable %} bio|truncatewords:30 {% templatetag closevariable %}. This will display the first 30 words of the bio variable.

Filter arguments that contain spaces must be quoted; for example, to join a list with commas and spaced you’d use {% templatetag openvariable %} list|join:"," {% templatetag closevariable %}.

The Known Filter Reference below describes all the filters Djula currently knows about. You can create your own filters, too, if you know how to write Common Lisp code

Known Filters

Tags

Tags look like this: {% templatetag openblock %} tag {% templatetag closeblock %}. Tags are more complex than variables: Some create text in the output, some control flow by performing loops or logic, and some load external information into the template to be used by later variables.

Some tags require beginning and ending tags (i.e. {% templatetag openblock %} tag {% templatetag closeblock %} ... tag contents ... {% templatetag openblock %} endtag {% templatetag closeblock %}). The known tag reference below describes all the tags Djula knows about. You can create your own tags, too, if you know how to write Common Lisp code.

Known Tags

Comments

Anything between {% templatetag opencomment %} and {% templatetag closecomment %} is commented out and will not appear in the browser.

So this:

Hello{% templatetag opencomment %} this is a comment {% templatetag closecomment %}
will be displayed by the template as:
Hello

Template Inheritance

The most powerful — and thus the most complex — part of Djula’s template engine is template inheritance. Template inheritance allows you to build a base "skeleton" template that contains all the common elements of your site and defines blocks that child templates can override.

It’s easiest to understand template inheritance by starting with an example:


   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
       "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
       <link rel="stylesheet" href="style.css" />
       <title>{% templatetag openblock %} block title {% templatetag closeblock %}My amazing site{% templatetag openblock %} endblock {% templatetag closeblock %}</title>
   </head>
   
   <body>
       <div id="sidebar">
           {% templatetag openblock %} block sidebar {% templatetag closeblock %}
           <ul>
               <li><a href="/">Home</a></li>
               <li><a href="/blog/">Blog</a></li>
           </ul>
           {% templatetag openblock %} endblock {% templatetag closeblock %}
       </div>
   
       <div id="content">
           {% templatetag openblock %} block content {% templatetag closeblock %}{% templatetag openblock %} endblock {% templatetag closeblock %}
       </div>
   </body>
   </html>

This template, which we’ll call base.html, defines a simple HTML skeleton document that you might use for a simple two-column page. It’s the job of "child" templates to fill the empty blocks with content.

In this example, the {% templatetag openblock %} block {% templatetag closeblock %} tag defines three blocks that child templates can fill in. All the block tag does is to tell the template engine that a child template may override those portions of the template.

A child template might look like this:

   {% templatetag openblock %} extends "base.html" {% templatetag closeblock %}
   
   {% templatetag openblock %} block title {% templatetag closeblock %}My amazing blog{% templatetag openblock %} endblock {% templatetag closeblock %}
   
   {% templatetag openblock %} block content {% templatetag closeblock %}
   {% templatetag openblock %} for entry in blog_entries {% templatetag closeblock %}
       <h2>{% templatetag openvariable %} entry.title {% templatetag closevariable %}</h2>
       <p>{% templatetag openvariable %} entry.body {% templatetag closevariable %}</p>
   {% templatetag openblock %} endfor {% templatetag closeblock %}
   {% templatetag openblock %} endblock {% templatetag closeblock %}

The {% templatetag openblock %} extends {% templatetag closeblock %} tag is the key here. It tells the template engine that this template "extends" another template. When the template system evaluates this template, first it locates the parent — in this case, base.html.

At that point, the template engine will notice the three {% templatetag openblock %} block {% templatetag closeblock %} tags in base.html and replace those blocks with the contents of the child template. Depending on the value of blog_entries, the output might look like:

   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
       "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
       <link rel="stylesheet" href="style.css" />
       <title>My amazing blog</title>
   </head>
   
   <body>
       <div id="sidebar">
           <ul>
               <li><a href="/">Home</a></li>
               <li><a href="/blog/">Blog</a></li>
           </ul>
       </div>
   
       <div id="content">
           <h2>Entry one</h2>
           <p>This is my first entry.</p>
   
           <h2>Entry two</h2>
           <p>This is my second entry.</p>
       </div>
   </body>
   </html>

Note that since the child template didn’t define the sidebar block, the value from the parent template is used instead. Content within a {% templatetag openblock %} block {% templatetag closeblock %} tag in a parent template is always used as a fallback.

You can use as many levels of inheritance as needed. One common way of using inheritance is the following three-level approach:

Create a base.html template that holds the main look-and-feel of your site.

Create a base_SECTIONNAME.html template for each "section" of your site. For example, base_news.html, base_sports.html. These templates all extend base.html and include section-specific styles/design.

Create individual templates for each type of page, such as a news article or blog entry. These templates extend the appropriate section template.

This approach maximizes code reuse and makes it easy to add items to shared content areas, such as section-wide navigation.

Here are some tips for working with inheritance:

If you use {% templatetag openblock %} extends {% templatetag closeblock %} in a template, it must be the first template tag in that template. Template inheritance won’t work, otherwise.

More {% templatetag openblock %} block {% templatetag closeblock %} tags in your base templates are better. Remember, child templates don’t have to define all parent blocks, so you can fill in reasonable defaults in a number of blocks, then only define the ones you need later. It’s better to have more hooks than fewer hooks.

If you find yourself duplicating content in a number of templates, it probably means you should move that content to a {% templatetag openblock %} block {% templatetag closeblock %} in a parent template.

If you need to get the content of the block from the parent template, the {% templatetag openvariable %} block.super {% templatetag closevariable %} variable will do the trick. This is useful if you want to add to the contents of a parent block instead of completely overriding it. Data inserted using {% templatetag openvariable %} block.super {% templatetag closevariable %} will not be automatically escaped (see the next section), since it was already escaped, if necessary, in the parent template.

For extra readability, you can optionally give a name to your {% templatetag openblock %} endblock {% templatetag closeblock %} tag. For example:


   {% templatetag openblock %} block content {% templatetag closeblock %}
   ...
   {% templatetag openblock %} endblock content {% templatetag closeblock %}

In larger templates, this technique helps you see which {% templatetag openblock %} block {% templatetag closeblock %} tags are being closed.

Finally, note that you can’t define multiple {% templatetag openblock %} block {% templatetag closeblock %} tags with the same name in the same template. This limitation exists because a block tag works in “both” directions. That is, a block tag doesn’t just provide a hole to fill — it also defines the content that fills the hole in the parent. If there were two similarly-named {% templatetag openblock %} block {% templatetag closeblock %} tags in a template, that template’s parent wouldn’t know which one of the blocks’ content to use.

Known Tag Reference

Known Filter Reference

How Djula is different from the Django templating language

...under construction...

Big differences

New Features

Missing

New Tags

Tags That Are Different From Their Django Equivalents

New Filters

Filters That Are Different From Their Django Equivalents

{% endfilter %} {% endblock body %}