# Auxiliary Templates

As the complexity of your templating project grows, it can be helpful to refactor common pieces into auxiliary templates so they can be reused. The `{% include %}` and `{% extends %}` tags support two very different approaches to this, described below.

## Loading Auxiliary Templates

When your main template makes reference to auxiliary templates, you’ll need to specify how the templating engine can find these auxiliary templates. This is achieved using a template loader (see `help("loader")`).

There are different types of loader, but `path_loader()` is the most commonly used. This allows you to specify the directory where auxiliary templates are stored in files.

Imagine you have a main template that uses nested template inheritance (`content` inherits from `blog_post.html`, which in turns inherits from `base.html`). You might store these two auxiliary templates in a templates directory:

    /path/to/templates/
    |-- base.html
    |-- blog_post.html

When rendering the main template, you create the loader object as part of the engine configuration:

    config <- jinjar_config(loader = path_loader("path", "to", "templates"))
    output <- render(content, !!!data, .config = config)

## Template Inclusion

The `include` tag can be used to include an auxiliary template and return the rendered contents of that file into the main document. Included templates have access to the same variables as the main template.

By default, an error is raised if the included template cannot be found. You can ignore these errors by setting the `ignore_missing_files` argument in `jinjar_config()`.

As an example, we create an auxiliary file `header.html` with contents:

    <!DOCTYPE html>
    <html lang="en">
    <head>
        <title>My webpage</title>
    </head>

and an auxiliary file `footer.html` with contents:

    </html>

And then the main template is rendered as:

    {% include "header.html" %}
    <body>
    Body
    </body>
    {% include "footer.html" %}

    <!DOCTYPE html>
    <html lang="en">
    <head>
        <title>My webpage</title>
    </head>

    <body>
    Body
    </body>
    </html>

## Template Inheritance

Template inheritance allows you to build a base “skeleton” template that contains all the common elements of your document and defines blocks that child templates can override. This is a very powerful technique.

As an example, consider the following base template stored in `base.html`:

    <!DOCTYPE html>
    <html>
    <head>
      {% block head -%}
      <link rel="stylesheet" href="style.css" />
      <title>{% block title %}{% endblock %} - My Webpage</title>
      {% endblock %}
    </head>
    <body>
      <div id="content">{% block content %}{% endblock %}</div>
    </body>
    </html>

This base template declares three `{% block %}` tags that child templates can fill in: `head`, `title` and `content`. Note that the base template itself defines some content for the `head` block – we’ll show how a child template can use this below.

A child template uses the `{% extends %}` tag to declare which parent template it builds upon. This should be the first tag in the child template, so the templating engine knows it must locate the parent template when rendering.

Building upon the base template example above, a child template might look like this:

    {% extends "base.html" %}
    {% block title %}Index{% endblock %}
    {% block head %}
      {{ super() }}
      <style type="text/css">
        .important { color: #336699; }
      </style>
    {% endblock %}
    {% block content %}
      <h1>Index</h1>
      <p class="important">
        Welcome to my blog!
      </p>
    {% endblock %}

    <!DOCTYPE html>
    <html>
    <head>

      <link rel="stylesheet" href="style.css" />
      <title>Index - My Webpage</title>

      <style type="text/css">
        .important { color: #336699; }
      </style>

    </head>
    <body>
      <div id="content">
      <h1>Index</h1>
      <p class="important">
        Welcome to my blog!
      </p>
    </div>
    </body>
    </html>

This child template defines the three blocks declared by the parent template: `head`, `title` and `content`. In the case of the `head` block, it uses `{{ super() }}` to render the contents of the `head` block defined by the parent template. If we were using nested `extends` tags, we could pass an argument to skip levels in the inheritance tree (e.g. `{{ super(2) }}`).