Enhancing templates¶

Boxes¶

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 %}
    or
{% 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:

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

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.

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.