The mystery of AnQiCMS template inheritance:{% extends %}Does the blank line before the tag really affect the child template?

In website content operation and development, efficiency and maintainability are our core pursuits.AnQiCMS (AnQiCMS) relies on its high-performance architecture based on the Go language and flexible template system, becoming a powerful assistant for many small and medium-sized enterprises and content operation teams.The AnQi CMS adopts a syntax similar to the Django template engine, making template creation both powerful and easy to learn.Among them, template inheritance is undoubtedly a powerful tool to improve development efficiency and ensure consistency of the site style.

However, when using this powerful feature, a seemingly trivial detail often confuses developers: in sub-templates,{% extends %}If there is a blank line or any other content before the tag, will it affect the normal inheritance of the template? Put it straightforwardly:Yes, it will have a great impact!

Understand the template inheritance mechanism of AnQiCMS

Let's briefly review the working principle of template inheritance in AnQiCMS.Imagine that your website has a unified layout, including header, footer, sidebar, and other fixed elements, with only the content area in the middle changing according to different pages.At this point, template inheritance comes into play.

We will create a "master" or "skeleton" template (usually namedbase.htmlIn this template, define the overall structure of the website and use{% block 块名 %}{% endblock %}such tags to mark those areas that can be overridden or extended by child templates.

For example, a basicbase.htmlIt might look like this:

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>{% block title %}我的AnQiCMS网站{% endblock %}</title>
    <link rel="stylesheet" href="/public/static/css/style.css">
</head>
<body>
    <header>{% include 'partial/header.html' %}</header>
    <main>
        {% block content %}
            <!-- 这里是默认内容，子模板可以覆盖 -->
        {% endblock %}
    </main>
    <footer>{% include 'partial/footer.html' %}</footer>
</body>
</html>

Then, the child template can go through{% extends 'base.html' %}The tag can 'inherit' this master, and then fill in or override the master based on its own needs.blockArea. For example, a sub-template for an article detail page might be written like this: 

{% extends 'base.html' %}

{% block title %}文章标题 - 我的AnQiCMS网站{% endblock %}

{% block content %}
    <h1>{{ archive.Title }}</h1>
    <div class="article-body">{{ archive.Content|safe }}</div>
{% endblock %}

This mechanism greatly improves the reusability of templates, reduces duplicate code, and also keeps the visual style and structure of the website highly consistent.

Core rule:{% extends %}Must be the first tag

Now, return to the question at the beginning of our article. According to the explicit instructions of the AnQiCMS official template development document, there is a golden rule that must be strictly adhered to:

“Note: If you use the tag in a template,{% extends %}it must be the first tag in the template. In any other case, template inheritance will not work.”

This means, in the sub-template file,{% extends '母版文件名' %}This line of code must be the first line of the file, and there should be no content before it, including seemingly harmless blank lines, spaces, tabs, or even HTML comments.

Why is there such a rule?

This is a convention in the design of the template engine. When the AnQiCMS template parser reads a file, it expects to see it at the very beginning of the file.{% extends %}A tag to identify that this is a child template inherited from another template. If the parser reads to{% extends %}Before encountering any other character (including invisible whitespace characters), it will consider the file to be an independent template that does not inherit, and thus ignore{% extends %}The directive causes the template inheritance mechanism to fail.

Error example (❌):

{# 这是一个空行，或者任何其他内容 #}
{% extends 'base.html' %}

{% block content %}
    <h1>文章标题</h1>
{% endblock %}

In the above code,{% extends 'base.html' %}A blank line before the tag will directly cause the template inheritance to fail. The child template will not load correctly.base.htmlstructure.

Correct example (✅):

{% extends 'base.html' %}

{% block content %}
    <h1>文章标题</h1>
{% endblock %}

Only when{% extends %}When the tag is the first visible content in the file, AnQiCMS can correctly parse and execute template inheritance.

It is not just blank lines: any "extra" content will break inheritance

Please note that the "blank line" mentioned here does not refer to the newline character specifically. Any character{% extends %}before the tag, including:

  • Spaces or tabs:Even several invisible spaces are recognized as content by the template engine.
  • HTML comments:such as<!-- 这是注释 -->It is also content.
  • Other template tags:any other{% ... %}or{{ ... }}.
  • any text content:even just some ordinary text.

these extra contents will{% extends %}The tag is no longer the first item in the file, thus breaking the template inheritance. The consequences may include the child template failing to render correctly, blank page display, and even system errors in some cases.

Suggestions in actual operation and **practice

As a content operator or developer of AnQiCMS, in order to avoid such problems, we have some suggestions:

  1. Develop a habit:When creating a sub-template file, be sure to{% extends '母版文件路径' %}place the tag on the first line of the file. Do not have any characters before or after it. This is the simplest and most effective precaution.
  2. Please check the beginning of the file:If you encounter a problem with template inheritance not working, the first step is to check the first line of the child template file. You can confirm this by using the 'Show whitespace characters' feature in a text editor (such as VS Code, Sublime Text) or by directly viewing the page source.{% extends %}Are you really at the beginning of the file.
  3. Using the editor's automatic formatting feature:Many modern code editors have automatic formatting features, but be careful, as these features may sometimes add some whitespace characters at the beginning of the file without you noticing.Suggest to manually check the file header after saving.
  4. Make good use of-Remove blank lines:AnQiCMS template engine also provides-symbols to control the blank lines around the tags (see referencetag-remove.md) For example,{%- if condition %}or{{ variable -%}}.Please note that this feature is used to controlthe internal logic of the tagordata outputthe blank lines generated, not for solving{% extends %}the tag must be a rigid rule on the first line of the file.For{% extends %}The rule is rigid: it must be at the very beginning and have no decorations.

Summary

In the template development of AnQiCMS,{% extends %}Any blank lines or content before the label will cause the template inheritance to fail.This is not a Bug, but a strict regulation made by the template engine to ensure parsing efficiency and structural consistency.Master this core rule and develop good coding habits, it will help you use the powerful template features of AnQiCMS more smoothly and efficiently, building a stable and elegant website.

Frequently Asked Questions (FAQ)

Q1: If{% extends %}Will it also fail if there is an HTML comment before the tag?

A1: I will. AnQiCMS template engine is parsing{% extends %}When a tag is encountered, it will strictly check whether it is the first 'visible' content in the file. Even HTML comments are not considered blank in the template engine, and they will prevent{% extends %}It is recognized as the first label, resulting in inheritance failure. Remember,Any non-empty characteris not allowed to appear in front of it.

Q2: Why does AnQiCMS have such strict regulations? Are other template engines like this?

A2: This strictness is usually to ensure the efficiency and consistency of template parsing. Template