How to reuse common HTML fragments through the `include` tag or define reusable code blocks through `macro` in templates?

In the development and maintenance of website templates, we often encounter the need to reuse HTML code snippets or logical structures.If you always copy and paste, it is not only inefficient, but also if you need to make changes, you have to repeat the operation in multiple places, which is very prone to errors.includeTags andmacroMacro function, allowing us to easily achieve code reuse, greatly improving the maintainability and development efficiency of templates.

Reuse common HTML fragments:includetags

Imagine, the top navigation bar and bottom copyright statement of our website almost appear on every page.If you have to write all this HTML code every time, it's a nightmare.includeLabels are the tools to solve such problems.It allows us to embed an entire HTML file into another template file, like a puzzle.partial/In the catalog, it is 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 a storage inpartialThe header file in the folderheader.htmlWe can introduce it in the main template like this:

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

Sometimes, the files we introduce may not be necessary for every page, or it is an optional component. In this case,includeTagsif_existsParameters come into play. After adding this parameter, 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 varied page structures:

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

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

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

Inheader.htmlInside, we can use it like a regular variable, through{{title}}and{{keywords}}to access these values. If we need to pass multiple variables, just separate them with spaces.

In addition, if we only want toincludeThe template coming in uses the variables we explicitly specify, not inheriting all the context variables of the current template, and can be usedonlyParameters. This helps maintain the clarity of the code and avoid unnecessary variable pollution:

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

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

In practical applications,includeThe label is very suitable for reusing those areas with relatively fixed structures and slightly varying content, such as website navigation bars, footers, sidebars, and general advertising positions, etc.Through this method, we can break down complex pages into multiple components, with each component 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 picking up a ready-made block and using it,macroMacros 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 functionality is more like a function in programming languages, having its own scope, and dealing only with the parameters passed in. This makes it very efficient when dealing with repeated, structurally similar but content-wise different elements.

Define a macro function is very intuitive, it starts with{% macro 宏名称(参数列表) %}Start, with{% endmacro %}. For example, if we often need to display the thumbnail 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 %}

At the place where this macro needs to be used, we just need to pass the corresponding article data as if calling a function, for example, in an article list:

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

In this way, each item in the article list will be sorted according toarchive_item宏定义的结构进行渲染.

为了更好地组织模板文件，我们还可以将宏函数保存在独立的模板文件中（例如.archive.helper），然后在其他模板中通过importLabel import and use. This helps to keep the main template concise and classify the macro functions.

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

After import, we can accessmy_macros.archive_item(item)in this manner to call the macros. Ifarchive.helperContains multiple macros, we can also import them all at once, and even set aliases for them, which is convenient for use and differentiation.

macroMacro functions are especially suitable for those that require high levels of customization,