How to ensure that the template file is included when using the `include` tag to avoid page errors?

As an experienced website operations expert, I know how important it is to modularize and reuse templates when building and maintaining a website.AnQiCMS (AnQiCMS) relies on its efficient architecture based on the Go language and a Django-like template engine, providing great flexibility for content display. Among them,includeTags are one of the core functions for implementing template reuse. However, powerful tools also need to be used carefully, otherwise they may bring unexpected "surprises" to the website - such as page errors caused by the introduction of non-existent template files.

Today, let's delve deeper into the use of Anqi CMS.includeHow to elegantly ensure that the template file is included when using tags, thus avoiding page errors and keeping your website running smoothly.

includeThe charm and potential risks of tags

In the template design of AnQi CMS,includeThe tag plays a crucial role. It allows us to extract common page elements, such as headers, footers, sidebars, or any reusable code snippets, into independent template files.This way, we do not need to repeat the same code on each page, which not only improves development efficiency but also makes the template structure clearer and easier to maintain.

For example, in yourindex.htmlIn the main template, you might introduce the common header and footer like this:

{% include "partial/header.html" %}

<div class="main-content">
    <!-- 页面核心内容 -->
</div>

{% include "partial/footer.html" %}

This approach is indeed efficient, but it also hides a potential risk: if some of theincludetemplate files, for example,partial/header.htmlThe file could not be found due to reasons such as incorrect deletion, naming errors, or improper path configuration. When AnQi CMS attempts to load the file, it will throw an error, which may cause the page content to fail to render partially, or in severe cases, display a server 500 error, affecting user experience and potentially exposing server information.As a website operator, of course, we hope such situations can be effectively avoided.

An elegant solution:if_existsModifier

幸运的是，AnQi CMS的模板引擎（Pongo2，兼容Django语法）为include标签提供了一个非常实用的修饰符——if_existsThe addition of this modifier completely solves the problem of the file not existing when importing.

When you areincludeadd aif_existsWhen, Anqi CMS tries to load the template file, it will first check if the file exists.

• If the file existsit will load and render the template content as usual.
• If the file does not existit will silently skip this one.includeThe operation will not cause an error and will not affect the normal rendering of other parts of the page.

This is like giving you.includeOperation has added an intelligent protection layer, even if a file loss occurs, the website can still run normally, but it is just missing the content of the module that was skipped.

Useif_existsThe syntax of the modifier is very simple, just need to inincludeadd to the template path of the tagif_existsand it is done:

{% include "partial/header.html" if_exists %}

Now, even ifpartial/header.htmlthe page will not crash because the file does not exist.

Application scenarios and **practice

if_existsModifiers are very useful in many situations, especially when dealing with optional, conditionally dynamic, or user-defined template fragments:

1. Optional Page Modulesuch as a side ad slot on a website, a user-defined module, or a notification bar that appears only during specific events.These module template files may not always exist, or may not be displayed on some pages.

   {# 引入一个可能存在的广告组件，如果文件不存在则不显示 #}
   {% include "widgets/ad_banner.html" if_exists %}
   

2. User-defined Template FileIf your website allows advanced users to upload or specify custom template files (such as custom article detail page layouts), then when introducing these user-specified templates, useif_existsIt can ensure that even if the user uploads a wrong filename or the file is deleted, it will not cause the entire website to crash.

3. Development and testing environmentIn the process of development, you may still be building a module, and the template file has not been completed. Useif_existsto avoid being hindered by the incompleteincludeand debugging other parts.

Combine variable passing (with) and scope control (only)

includeThe strength of labels lies in their ability to pass variables and control scope.if_existsThese features can be used well together.

• withPassing variables: When you introduce a template that requires some specific data, you can usewithkeyword to pass variables.

  
  {# 引入侧边栏，并传递当前文章的ID和相关分类数据 #}
  {% include "partial/sidebar.html" if_exists with currentPostId=archive.Id categories=categoryList %}
  

• onlyScope limitationIf you want the template to use only the variables you explicitly pass and not inherit all context variables from the parent template, you can useonlyThis helps avoid variable name conflicts and improve the modularity.

  
  {# 引入一个简单的版权信息模块，只传递年份变量，不暴露其他复杂数据 #}
  {% include "common/copyright.html" if_exists with currentYear=nowYear only %}
  

Complete example: build a robust page structure

Let's take a combination look at itif_exists/withandonlyAn example of the page structure, showing how to build a flexible and robust template:

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>{% tdk with name="Title" siteName=true %}</title>
    <meta name="keywords" content="{% tdk with name="Keywords" %}">
    <meta name="description" content="{% tdk with name="Description" %}">
    <link rel="stylesheet" href="{% system with name="TemplateUrl" %}/css/main.css">
    {# 如果有自定义的头部样式，尝试引入，不存在也不会报错 #}
    {% include "custom/head_styles.html" if_exists %}
</head>
<body>
    {# 页面头部，无论如何都应尝试引入，但避免致命错误 #}
    {% include "partial/header.html" if_exists with siteName=system.SiteName %}

    <div class="container">
        <div class="main-content">
            <!-- 核心内容区域，例如文章详情 -->
            {% if archive %} {# 确保是文章详情页 #}
                <article>
                    <h1>{{ archive.Title }}</h1>
                    <div class="article-meta">
                        <span>发布于 {{ stampToDate(archive.CreatedTime, "2006-01-02") }}</span>
                        <span>浏览量：{{ archive.Views }}</span>
                    </div>
                    <div class="article-body">
                        {{ archive.Content|safe }}
                    </div>
                    {# 相关文章模块，可能是可选的，或只有在有数据时才显示 #}
                    {% include "modules/related_articles.html" if_exists with currentArchiveId=archive.Id only %}
                </article>
            {% else %}
                {# 非文章详情页或内容不存在时的备用显示 #}
                <p>内容加载失败或页面不存在。</p>
            {% endif %}
        </div>

        <aside class="sidebar">
            {# 侧边栏的通用组件，即使文件不存在也不影响主内容 #}
            {% include "partial/sidebar_categories.html" if_exists %}
            {% include "partial/sidebar_hot_posts.html" if_exists %}
        </aside>
    </div>

    {# 页面底部，同样采用 if_exists 确保网站稳定性 #}
    {% include "partial/footer.html" if_exists with copyright=system.SiteCopyright %}

    <script src="{% system with name="TemplateUrl" %}/js/main.js"></script>
    {# 引入自定义的JS，如果文件不存在则跳过 #}
    {% include "custom/body_scripts.html" if_exists %}
</body>
</html>

Summary

In the template development of AnQi CMS,includeLabel combinationif_existsModifiers provide a powerful and safe way to build modular templates.It not only ensures the stability of the website, avoids page errors caused by missing files, but also enhances the flexibility and maintainability of template design.Reasonably using this feature will enable your safety CMS website to show excellent robustness and user experience in the face of various operation challenges.

Frequently Asked Questions (FAQ)

Q1:if_existsand beforeincludeUsed outside{% if ... %}What is the difference in judging whether the file exists?

A1: if_existsIsincludeThe built-in modifier of the tag, which tries to load the fileBeforePerform an existence check. If the file does not exist,includethe operation will be skipped directly, no errors or logs will be generated.