How to reuse common HTML fragments in a template by using the `include` tag or define reusable code blocks by `macro`?

In the development and maintenance of website templates, we often encounter the need to reuse HTML code snippets or logical structures.If you copy and paste every time, it is not only inefficient, but also once you need to modify it, you have to repeat the operation in multiple places, which is easy to make mistakes.AnQi CMS knows this, it provides a template engine that follows the syntax of Django, throughincludeTags andmacroMacro function, allowing us to easily implement code reuse, greatly enhancing the maintainability and development efficiency of the template.

Reuse common HTML fragments: includeTag

Imagine that the top navigation bar and bottom copyright statement of our website appear on almost every page.If I had to write all this HTML code every time, it would be a nightmare.Secure CMS ofincludeThe tag is exactly the tool to solve this kind of problem. It allows us to embed an entire HTML file into another template file, like a puzzle.These common parts are usually referred to as "code snippets", such as headers, footers, sidebars, etc., which can be stored in the template directory.partial/In the directory, convenient for unified management and reference.

The simplest way to use it is to directly specify the file path to include. For example, we have one stored inpartialThe header file in the folderheader.htmlWe can introduce it like this in the main template:

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

Sometimes, the files we introduce may not be necessary for every page, or they may be optional components. In this case,includelabel'sif_existsThe parameter comes into play. With this parameter added, if the specified file does not exist, the system will not report an error but will silently skip the import operation, which is very useful for building flexible and variable page structures:

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

What's more powerful is,includeLabels can also allow us to pass specific data when introducing common segments. This is done bywithParameter implementation. For example, we hope that the common header can dynamically display the page title and keywords, but this information may differ on different pages. We can do it like this towardsheader.htmlPass data:

{% include "partial/header.html" with title="这是声明给header使用的title" keywords="这是声明给header使用的keywords" %}

Inheader.htmlInside, we can access these values as if we were using ordinary variables, through{{title}}and{{keywords}}Just separate multiple variables with spaces if we need to pass more than one.

Moreover, if we only want to letincludeThe template uses the explicitly specified variables, rather than inheriting all the context variables of the current template, and can be usedonlyParameters. This helps to keep the code clear, avoiding unnecessary variable pollution:

{% include "partial/header.html" with title="我的页面标题" keywords="SEO关键词" only %}

This meansheader.htmlCan only access intitleandkeywordsThese two variables, and cannot access any other variables in the main template.

In practical applications,includeThe tag is very suitable for reusing those areas with relatively fixed structures and slightly variable content, such as website navigation bars, footers, sidebars, and common advertising spaces.In this way, we can divide complex pages into multiple components, each responsible for its own content, thereby improving the readability and maintainability of the template.

Define reusable code blocks:macroMacro function

If we sayincludeTags are like bringing a ready-made block from somewhere, thenmacroMacro functions are like molds for making building blocks. They allow us to define reusable code blocks that can accept parameters and dynamically generate HTML content based on the parameters.macroThe function is more like a function in programming languages, with its own independent scope, handling only the passed parameters, which makes it very efficient in dealing with repeated, structurally similar but content-wise different elements.

Define a macro function is very intuitive, it ends with{% macro 宏名称(参数列表) %}and ends with{% endmacro %}. For example, if we often need to display the summary information of articles on the page, we can define a macro namedarchive_item:

{% macro archive_item(archive) %}
<li class="article-item">
    <a href="/archive/{{archive.Id}}" class="link">
        <h5 class="title">{{archive.Title}}</h5>
    </a>
</li>
{% endmacro %}

Where this macro needs to be used, we just need to pass the corresponding article data as we would call a function, for example, in an article list:

{% for item in archives %}
    {{ archive_item(item) }}
{% endfor %}

This way, each article list item will be sorted according toarchive_itemThe structure defined by macros is rendered.

To better organize template files, we can also store macro functions in separate template files (for examplearchive.helper), and then use them in other templates throughimportLabel import and use. This helps keep the main template concise and manage macro functions in categories:

{% import "archive.helper" as my_macros %}

After import, we can accessmy_macros.archive_item(item)in this form to call macros. Ifarchive.helperContaining multiple macros, we can also import them all at once, even set aliases for them, for convenience and differentiation.

macroMacro functions are particularly suitable for those that require high customization,