How to define and use macro functions to create reusable code blocks in AnQiCMS templates?

As an experienced CMS website operation person, I know that the template function of the content management system is crucial for improving the efficiency of website operation and the quality of content display.AnQiCMS's powerful Django template engine syntax provides us with flexible content presentation capabilities, and the Macro function feature is an essential tool for code reuse, simplifying template structure, and improving development and maintenance efficiency.

During the process of content creation and publication, we often encounter some repetitive code snippets, such as the display format of article lists, the layout of product cards, and the specific structure of navigation menus.If copying code blocks every time, it not only increases the size of the template file and reduces readability, but also brings huge workloads and error risks in later modifications.The appearance of macro functions is to solve this pain point, it allows us to encapsulate these reusable code logic, and use them flexibly in templates like calling a function.

AnQiCMS Template Engine and Macro Function

AnQiCMS uses a template engine syntax similar to Django, which makes it very flexible and easy to use in template creation.The macro function as one of its auxiliary tags is essentially a template code snippet with parameters, it has an independent scope, and only handles the parameters passed in. This is similar toincludeThe tags are different,includeThe tag inherits and uses all the context variables of the current template, while the macro function is more focused on its own received parameters, making the macro function more modular and independent.

Define reusable code blocks: macro function syntax

Macro functions are passed through{% macro macro_name(参数列表) %} ... {% endmacro %}to define its structure.macro_nameis the name you give to the macro function, and参数列表The variables required by the macro function at runtime, which will be visible and used within the macro function.The logic inside the macro function can be any valid template code, including HTML structure, other tags, variable output, etc.

For example, we often need to display a brief summary of articles at different locations on a website, which may include title, link, description, and publication date. We can define a macro function for this:

{% macro render_article_item(article) %}
<li class="article-item">
    <a href="{{ article.Link }}" class="article-link">
        <h5 class="article-title">{{ article.Title }}</h5>
    </a>
    <p class="article-description">{{ article.Description|truncatechars:100 }}</p> {# 截取前100字符 #}
    <span class="article-date">{{ stampToDate(article.CreatedTime, "2006-01-02") }}</span>
</li>
{% endmacro %}

in thisrender_article_itemIn the macro function,articleIt is a parameter passed in, representing a specific article data object. Inside the macro function, it accessesarticlethe object'sLink/Title/DescriptionandCreatedTimeProperties such as, to build the HTML structure of the article list item. We also usedtruncatecharsThe filter extracted the description text and usedstampToDateThe function formatted the timestamp, all of these are powerful features provided by the AnQiCMS template engine.

Effectively use macro functions in the template.

After defining the macro function, we can call it through{{ macro_name(参数值) }}the syntax in the template.

Using the macro function in the same template file

If the macro function is defined in the current template file, it can be called anywhere in the file as needed. This applies to some local code blocks that are used multiple times within the current template.

{# 假设render_article_item宏函数已在当前文件顶部定义 #}

<h2>最新文章</h2>
{% archiveList latest_articles with type="list" limit="5" %}
    <ul class="latest-articles-list">
        {% for article in latest_articles %}
            {{ render_article_item(article) }} {# 直接调用宏函数并传入文章对象 #}
        {% endfor %}
    </ul>
{% empty %}
    <p>暂时没有最新文章。</p>
{% endarchiveList %}

Import and use macro functions across template files

It is recommended to define macro functions in independent template files for better management and organization, usually these files are stored in a subdirectory of the template directory, for examplepartial/macros/. This can achieve the global reuse of macro functions and avoid the main template file from becoming too large.

Suppose we created a file namedmacros/common_macros.htmlfile, where multiple general macro functions are defined, such as:

File:templates/your_template/macros/common_macros.html

{# templates/your_template/macros/common_macros.html #}

{% macro render_article_item(article) %}
<li class="article-item">
    <a href="{{ article.Link }}" class="article-link">
        <h5 class="article-title">{{ article.Title }}</h5>
    </a>
    <p class="article-description">{{ article.Description|truncatechars:100 }}</p>
    <span class="article-date">{{ stampToDate(article.CreatedTime, "2006-01-02") }}</span>
</li>
{% endmacro %}

{% macro render_product_card(product) %}
<div class="product-card">
    <img src="{{ product.Thumb }}" alt="{{ product.Title }}">
    <h3><a href="{{ product.Link }}">{{ product.Title }}</a></h3>
    <p class="product-price">${{ product.Price | floatformat:2 }}</p> {# 格式化价格为两位小数 #}
    <button class="add-to-cart">加入购物车</button>
</div>
{% endmacro %}

Now, in any template file that needs to use these macro functions (such asindex.htmlordetail.html), we can useimporttags to import them.importThe syntax of the tag is{% import "文件路径" macro_name1, macro_name2 as alias_name, ... %}. Among them,asKeywords allow us to set an alias for imported macro functions to avoid naming conflicts or to use a more concise name.

File:templates/your_template/index.html

`twig {# templates/your_template/index.html #}

{% import “macros/common_macros.html” render_article_item, render_product_card as product_card_renderer %}

{% extends "base.html" %} {# Assume the page inherits from base.html #}

{% block content %}

<section class="latest-news">
    <h2>最新资讯</h2>
    {% archiveList latest_articles with type="list" moduleId="1" limit="3" %} {# 假设文章模型ID为1 #}
        <ul class="latest-articles-list">
            {% for article in latest_articles %}
                {{ render_article_item(article) }} {# 调用导入的文章宏函数 #}
            {% endfor %}
        </ul>
    {% empty %}
        <p>暂无最新资讯。</p>
    {% endarchiveList %}
</section>

<section class="featured-products">
    <h2>热门产品</h2>
    <div class="featured-products-grid">
        {% archiveList featured_products with type="list" moduleId="2" limit="4" %} {# 假设产品模型ID为2 #}
            {% for product in featured_products %}