{%- from 'seo_schema_base.jinja' import render_seo -%} {%- if seo -%} {{- render_seo(seo, page_type | default("details"), breadcrumbs | default(none), list_breadcrumbs | default(none)) -}} {%- endif -%}
Menu
{%- from 'seo_schema_base.jinja' import render_seo -%} {%- if seo -%} {{- render_seo(seo, page_type | default("details"), breadcrumbs | default(none), list_breadcrumbs | default(none)) -}} {%- endif -%}

Jinja Blocks

A Comprehensive Guide to Jinja Blocks

The Jinja

tag is the foundation of template inheritance, a powerful feature that allows you to create a base layout and then extend or modify specific parts of it in child templates. Blocks act as both placeholders in a parent template and as containers for content in a child template.

The Concept of Template Inheritance

Imagine you're building a website with a consistent look and feel—a header, a navigation bar, and a footer that appear on every page. Instead of copying and pasting this boilerplate code into every single HTML file, you can create a single

) that defines this structure. Within this base template, you use

tags as placeholders for the content that will be unique to each page. A child template then

this base template and provides the specific content to fill these blocks. This approach significantly reduces code duplication, makes your templates easier to manage, and ensures a consistent design across your site.

Defining Blocks in the Base Template

In your base template, you define blocks with the

tag. The content inside the block tag serves as the default content. If a child template doesn't override a specific block, the default content will be rendered. For example, in a

template, you might have blocks for the page title and the main content:

text
<!DOCTYPE html>
<html data-translate="true">
<head data-translate="true">
    <title data-translate="true">{% block title %}My Website{% endblock %}</title>
</head>
<body data-translate="true">
    <div id="content" data-translate="true">
        {% block content %}{% endblock %}
    </div>
</body>
</html>

Here, we have a

block with a default value of "My Website" and a

block that is empty by default.

Overriding Blocks in Child Templates

To use this base template, a child template must start with the

tag. This tells Jinja that the child template inherits its structure from

. The child template can then override any of the blocks defined in the parent by using a

tag with the same name. The content inside the block in the child template will replace the content of the corresponding block in the parent. Here's an example of a child template that extends our

text
{% extends "base.html" %}

{% block title %}About Us{% endblock %}

{% block content %}
    <h1 data-translate="true">About Us</h1>
    <p data-translate="true">This is the content for the About Us page.</p>
{% endblock %}

When this child template is rendered, Jinja will use the layout from

but will inject "About Us" into the

block and the

tags into the

block.

Accessing the Parent Block's Content

Sometimes, you don't want to completely replace the parent block's content; you want to add to it. The

function inside a block allows you to render the content from the block in the parent template. This is particularly useful for things like adding a page-specific title to a generic site name or appending new content to a base stylesheet or script block.

text
{% extends "base.html" %}

{% block title %}{{ super() }} | My Page Title{% endblock %}

{% block content %}
    <p data-translate="true">This content appears after the parent's content.</p>
    {{ super() }}
{% endblock %}

In this example, the

block will render "My Website | My Page Title". The

block would render "This content appears after the parent's content." followed by whatever was in the

block of

Important Considerations for Blocks

  • extendsis First: The{% extends ... %}tag must be the very first line of a child template. Nothing else, not even a comment, can precede it.
  • No Duplicate Block Names: You cannot define multiple blocks with the same name within a single template. A block acts as a unique placeholder and a unique content container, so its name must be unique.
  • Blocks vs. Includes: Whileincludeis for embedding a template's content inline,blockis specifically for inheritance. Blocks are placeholders that are filled by child templates, while includes are simple injections of content. You cannot pass block content to an included file.

In summary, blocks are the core of Jinja's template inheritance. They provide a structural and elegant way to manage complex template layouts, promoting code reuse and making it simple to maintain a consistent user interface across your entire application.