Enhancing templates

Since Ella is a regular Django application, even it’s templates are just plain Django templates. Therefore we just refer you to other sources to learn more about the templating language and it’s best practices, we will try to focus just on ella-specific parts.


First change we will make is abstract the rendering of the object listing on category homepage and archive. To do this, ella provides a Box for individual objects. It’s primary use is as a templatetag. Boxes can be rendered for objects accessible through a variable or through a database lookup:

{% box <box_name> for <object> %}{% endbox %}
{% box <box_name> for <app.model> with <field> <value> %}{% endbox %}

What {% box %} does is a little more then fancy include - it retrieves the object, find the appropriate template and renders that. Boxes are usually used throughout an Ella site to provide maximum flexibility in rendering objects and also for embedding objects into rich text fields stored in the database (in text of an article for example). Some applications (Positions for example) also use boxes to represent objects.

To create our first box, we just need to create a template called box/listing.html containing:

    <a href="{{ object.get_absolute_url }}">{{ object.title }}</a>
    {{ object.description|safe }}

And change page/category.html to use the box instead of manually specifying the output:

<h1>Welcome to category {{ category.title }}</h1>
<p>{{ category.description }}</p>

{% for listing in listings %}
    {% box listing for listing.target %}{% endbox %}
{% endfor %}

Overriding templates

In last step we created a few templates that should suffice for an entire site based on Ella. In real life you probably wouldn’t want every category and every object to share the same template. Ella provides a simple mechanism to target your templates more directly.

Let’s say that we want to create a specific template for rendering articles, just create a template called page/content_type/articles.article/object.html and you are done - next time you visit some article’s URL, this template will get rendered instead of your page/object.html. This template would be a good place to render the text of an article for example:

{% extends "page/object.html" %}
{% block content %}
    {{ object.content.content|safe }}
{% endblock %}

Now if you just define the appropriate block in your page/object.html:

<h1>{{ object.title }}</h1>
<p>Published on {{ placement.publish_from|date }} in category: <a href="{{ category.get_absolute_url }}">{{ category }}</a></p>
{{ object.description|safe }}
{% block content %}{% endblock %}

You should be able to see your article’s text on the web.

Another way you can override your templates is based on Category. For example if you want to create a custom template for your root category (and your root category’s slug is ella-blog), just create one called page/category/ella-blog/category.html:

<h1>Welcome to site {{ category.site }}</h1>
<p>{{ category.description }}</p>

{% for listing in listings %}
    {% box listing for listing.target %}{% endbox %}
{% endfor %}

You will be greeted into the site and not your root category next time you visit the root of your blog. Just create any subcategory to check it will remain unaffected.

You can use the same simple mechanism (creating new templates) to cange the look of your boxes for individual objects as well.


For more detailed explanation of all the possible template names, have a look at views and templatetags documentation.

Now you have a working site and all necessary tools to built a fancy ella-powered website, in next step we will show you how we think it’s best to layout your newly created application for easy deployment and maintenance.

Table Of Contents

Previous topic

Basic templates

Next topic

Deploying your Ella application

This Page