armstrong.core.arm_layout 1.4.0

Cheat sheet

{% load layout_helpers %}

{% render_model model_obj "template_name" %}

<!-- otherwise render_model behaves exactly like {% include ... %} -->
{% render_model model_obj "template_name" with additional="data" %}
{% render_model model_obj "template_name" with isolated="context" only %}

<!-- shortcut to call render_model on a list of model objects -->
{% render_list list_of_models "template_name" %}

<!-- or more flexible looping -->
{% render_iter list_of_models %}
    {% render_next "big" %}
    {% render_next "small" %}
    {% render_next "big" %}
    {% render_remainder "small" %}
{% endrender_iter %}

In depth

To load the template tags, add the following line (generally at the top of your template):

{% load layout_helpers %}

Now you can use the render_model template tag to display a given model like this:

{% render_model some_model "full_page" %}

some_model is a variable in your template that is a model instance and the string "full_page" is the name of your “layout”. render_model looks for a template named layout/<app_label>/<model>/<layout>.html to determine what to use to display your model instance. Going one step further, it is smart enough to walk through the inheritance of the model to determine if there are any parent models that have the layout that can be used. For example, if some_model was an instance of armstrong.apps.articles.models.Article that inherits from armstrong.apps.content.models.Content, render_model looks for the following templates, in this order:

["layout/articles/article/full_page.html",
 "layout/content/content/full_page.html", ]

You have access to the entire template context inside the full_page.html template. You also have a new variable called object which represents the model instance that you provided to render_model. That variable is only available inside the layout template and temporarily overrides any other context variable called object. Aside from the flexibility of looking up a template based on model inheritance, this tag works just like {% include %}. You can add to the context using with extra="param" or isolate the context using only. Once render_model is finished, it restores the original context.

layout_helpers provides two other helper methods for easily rendering multiple models without having to manually loop through them. You can render an entire list of models using the same template:

{% render_list list_of_models "preview" %}

Or have finer control with a block tag that lets you step through each model instance specifying the template each time and then rendering all the rest with a common template:

{% render_iter list_of_models %}
    {% render_next "preview" %}
    {% render_next "preview" %}
    {% render_next "preview" %}
    {% render_remainder "headline" %}
{% endrender_iter %}

Of course you could do the same thing another way:

{% render_list list_of_models[:3] "preview" %}
{% render_list list_of_models[3:] "headline" %}

A limitation of these loop helpers is they cannot add or limit the context using with or only as render_model can. You could however wrap the tags in a {% with need="this" and="that" %} ... {% endwith %} block. See the with documentation.