How to include external HTML fragments in AnQiCMS templates?

In building website templates for AnQiCMS, we often encounter some HTML code blocks that need to be reused, such as the website header, footer, sidebar navigation, ad spaces, or some general content modules.If you repeat writing this code in different template files each time, it is not only inefficient but also very麻烦 to find and update each file when you need to modify it.

To solve this problem, AnQiCMS provides powerful template functions, including the ability to introduce external HTML fragments, making the development of website templates more flexible and efficient.

核心功能：轻松引入外部HTML片段

AnQiCMS的模板系统基于类似Django的语法，它允许您使用EnglishincludeLabel, embed the content of an independent HTML file into another template file.The core value of this feature lies in 'reusability'. You can extract those common parts that need to be displayed on multiple pages, create an independent HTML file, and then simply reference it where needed.

usually, these reusable HTML fragment files are.htmlwith suffix, and it is recommended to store them in your template directory'spartial/subfolder. For example, you have a folder nameddefaultThe template, its root directory is/template/default/Then you can create a/template/default/partial/directory, specifically used to store these code snippets.

The most basic way of importing is very intuitive, like this:

{# 假设您的模板文件是 index.html #}

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

<main>
    <h1>欢迎来到我的网站</h1>
    <!-- 这里是页面特有的内容 -->
</main>

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

In the above example,header.htmlandfooter.htmlIt is two external HTML fragments. They may contain the website's logo, main navigation, copyright information, and other common elements.

A simplepartial/header.htmlIt may look like this:

<header class="site-header">
    <div class="container">
        <a href="/" class="logo">
            <img src="/static/images/logo.png" alt="网站Logo">
        </a>
        <nav class="main-nav">
            <ul>
                <li><a href="/">首页</a></li>
                <li><a href="/about">关于我们</a></li>
                <li><a href="/contact">联系我们</a></li>
            </ul>
        </nav>
    </div>
</header>

This way, no matter which page needs a page header, it only takes one line.{% include "partial/header.html" %}It can be done, greatly enhancing development efficiency and the convenience of later maintenance.

Advanced usage: passing data to the fragment

很多时候，被引入的HTML片段不仅仅是静态内容，它可能也需要显示一些动态信息。For example, a sidebar may need to display the title of the current page, or a generic card component may need to be filled with different data.includewhen labeling,withThe keyword is used to pass variables to the imported segment.

For example, you may have apartial/sidebar.htmlIt needs one.current_titleA variable to display the current page information:

<aside class="sidebar">
    <h3>当前页面</h3>
    <p>{{ current_title }}</p>
    <ul class="recent-posts">
        <!-- 这里可能还有其他动态内容，比如最新文章列表 -->
    </ul>
</aside>

In your main template file, you can do it like this:sidebar.htmlTo pass data:

{# 假设您的模板文件是 article_detail.html #}

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

<main>
    <h1>文章详情页</h1>
    <div class="content">
        <!-- 文章内容 -->
    </div>
</main>

{% include "partial/sidebar.html" with current_title="AnQiCMS模板开发指南" %}

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

You can also pass multiple variables, just separate them with spaces:

{% include "partial/product_card.html" with product_name="AnQiCMS企业版" price="￥999" discount="8折" %}

In some cases, you may want the introduced segment to only access the variables you explicitly pass, and not access other variables in the main template. In this case, you canwithafter addingonlyKeyword:

{% include "partial/ad_banner.html" with ad_id="promo_123" ad_type="image" only %}

usedonlyAfter,ad_banner.htmlonly usead_idandad_typeThese variables, while not affected by other variables in the main template, help maintain the independence of code snippets and avoid potential naming conflicts.

Handle non-existent template files

During development, you may occasionally encounter situations where the template file path is incorrect or the file has been deleted, which may cause the page to report errors. In order to improve the robustness of the template, you can useif_existskeywords.

When you useif_existsWhen the specified template file does not exist, AnQiCMS will gracefully ignore thisincludeThe statement will not cause the entire page to render fails. This is especially useful in some non-core, optional code snippets.

{# 尝试引入一个可能存在的广告位，如果不存在也不会报错 #}
{% include "partial/optional_ad.html" if_exists %}

<main>
    <h1>页面主内容</h1>
</main>

{# 尝试引入一个可能存在的推荐文章模块 #}
{% include "partial/recommended_articles.html" if_exists with category_id="1" %}

Use tips with **practice

  • Modular thinking:When designing templates, try to divide the page into logical, functionally independent modules, with each module corresponding to an HTML fragment.
  • Clear directory structure:Always recommend placing all reusable fragments in a unifiedpartial/directory and further divide according to function, for examplepartial/nav/main_menu.html,partial/widgets/search_box.html.
  • Avoid over nesting:Although it can be nested infinitelyincludeThe deep nesting may make the template structure complex, which is not conducive to understanding and debugging. Try to keep the fragments flat.
  • Use AppropriatelyextendsWithinclude: extendsTags are usually used to define the overall layout skeleton of the page (such asbase.html)，contains header, sidebar, main content area, and other large structures,includeThen used to fill in or insert specific subcomponents or content blocks within these structures. They complement each other to build an efficient template system.
  • Add comments to the segment:Add a brief comment at the beginning of complex fragment files to describe its function, required variables, etc., which is convenient for team collaboration and future maintenance.

By cleverly utilizing AnQiCMS'sincludeFunction, you can make the template development of the website more organized, easy to manage, and significantly improve the efficiency of development and maintenance.

Common Questions (FAQ)

1.includeandextendsWhat is the difference between tags?

extendsThe tag is used to implement template inheritance, it defines the overall structure or layout of a page, and allows child templates to overwrite specific "blocks".block). Usually, a page will onlyextendsAn English parent template.includeThe tag is used to insert an independent HTML snippet into any template (including parent and child templates).It can be understood as copying and pasting a small code file to the current position.extendsIt defines the "shape" of the page.includeIt is the "content block" filling the page.

2. Can I use AnQiCMS tags and variables in the HTML fragments I introduce?

Yes, absolutely. The template system of AnQiCMS will pass the context of the current template (all available variables and tags) to theincludefragment. This means you can inincludethe fragment can use various tags provided by AnQiCMS (such asarchiveList/system) and variables passed to the fragment or inherited from the parent template.

3. The HTML fragment file introduced must be placed inpartial/the directory?

It is not required, it is a recommended **practice. You can place the HTML fragment files in any subfolder of the template directory, as long asincludeThe path provided in the label is the correct path relative to the current template directory. For example, if your snippet ismy_components/widget.htmlyou can write{% include "my_components/widget.html" %}But in order to maintain the clarity of the project structure and facilitate management, it is strongly recommended to classify commonly used segments uniformly.partial/the directory.