===========
Reuse Parts
===========

Jinja allows to move often used parts into external files.

This is an addition to the `template inheritance`_ system.


Predefined Blocks
=================

You can predefine blocks for later usage using the tag ``{% prepare %}``::

    {% prepare "box" %}
    <div id="box">this is the default box</div>
    {% endprepare %}

    {% prepare "dialog" accepting title, content %}
    <div id="dialog">
      <h1>{{ title|escapexml }}</h1>
      {% if content" %}
      <div class="text">{{ content }}</div>
      {% endif %}
    </div>
    {% endprepare %}

You can now display that block everywhere on the same file as long as
the block was prepared above the first usage::

    <ul>
    {% for user in users %}
      <li>{{ user.username }}
      {% if user.description %}
        {% call dialog, "User Details", user.description %}
      {% endif %}</li>
    {% endfor %}
    </ul>

    {% call "box" %}


Include Files
=============

You can use ``{% include %}`` to include files which are loadable by the 
current loader. That means you include it like you would extend from it::

    <h1>Hello World</h1>
    <div id="intro">
      {% include "parts/introtext" %}
    </div>


Requiring Files
===============

``{% require %}`` works like ``{% include %}`` but doesn't return the
output. This can be useful for loading `Predefined Blocks`_ or if you want to
write the rendered file into a variable::

    {% require "myblocks" %}
    {% require "parts/introtext" as introtext %}
    <h1>Hello World</h1>
    {% call "divbox", "intro", introtext %}

The first require will load "myblocks" and return nothing, the second one
will load "parts/introtext" and save the output in a variable "introtext".

Additionally require will only load blocks one time which means fastens up
jinja a lot when using the same included file on more than one page.


.. _template inheritance: inheritance.txt