How does the `macro` function in AnQiCMS templates help me reduce redundant rendering logic?

In Anqi CMS template development, improving efficiency and maintaining code cleanliness is the goal of every developer.web pages often contain many regions with similar structures but different contents, such as each article card in the article list, the various characteristics of the product details page, or each link item in the navigation menu.If you keep writing similar rendering logic over and over, not only will it take a lot of time and effort, but you may also face the dilemma of having to make repetitive changes in multiple places. 幸运的是，AnQiCMS强大的模板系统提供了macroThe macro function, which can effectively help us solve this problem, greatly reduces the repetitive rendering logic.

What ismacroWhat is the macro function?

In simple terms,macroMacros are like reusable "gadgets" or "subroutines" you define in a template.It allows you to encapsulate a segment of HTML code with specific logic and structure, and can be called like a function to pass different data parameters, thereby rendering dynamic and expected content.The template engine syntax of AnQiCMS is similar to Django, and it is very easy for developers to get started with it,macroIt is a reflection of its flexible and powerful functions.

withincludeTags (used to include static or general template fragments) differ,macroMacro functions are more focused onencapsulation of dynamic content and logicIt can accept parameters and generate different content based on these parameters, making it particularly efficient in handling scenarios with high repetition but varying details each time.

Why to usemacroWhat is the macro function?

applymacroMacro functions, which can bring significant advantages in many aspects:

  1. Reduce duplicate code:This is the most direct benefit. Defining repeated template structures as macros avoids pasting the same code block in multiple places, greatly reducing the volume of template files.
  2. Improve development efficiency:Once a macro is defined, it can be quickly invoked anywhere, saving time on rewriting and debugging similar code.
  3. Simplify the template structure:The main template code will become more concise and readable. Complex rendering logic is encapsulated in macros, and the main template only needs to focus on calling macros and passing data, with clearer logical levels.
  4. Easy to maintain and update:When you need to modify the display logic or style of a general UI component, you only need to modify the macro definition once, and all the places calling the macro will be automatically updated, avoiding omissions and inconsistencies.
  5. Ensure consistency:Ensure that all elements using the same macro on the website maintain a unified structure and basic style, enhancing user experience and brand image.

AnQiCMS inmacroUsage method

MastermacroThe usage is not complex, mainly divided into definition and invocation two steps.

1. DefinitionmacroMacro function

You can define one in any template file.macro. Usually, we define commonly used macro functions in a separate file (for example_macros.htmlorhelpers.html), to keep the main template clean. DefinitionmacroThe basic syntax is as follows:

{% macro macro_name(参数1, 参数2, ...) %}
    {# 宏函数内部的渲染逻辑，可以使用传入的参数 #}
    <div class="some-element">
        <h2>{{ 参数1.title }}</h2>
        <p>{{ 参数2.description }}</p>
        {# 更多逻辑 #}
    </div>
{% endmacro %}

For example, we want to render a uniform card style for each article on the website, which can be defined as followsarchive_cardmacro:

{# 文件名: _macros.html #}
{% macro archive_card(item) %}
    <div class="article-card">
        <a href="{{ item.Link }}">
            {% if item.Thumb %}
                <img src="{{ item.Thumb }}" alt="{{ item.Title }}" class="card-thumbnail">
            {% endif %}
            <h3 class="card-title">{{ item.Title }}</h3>
        </a>
        <p class="card-description">{{ item.Description|truncatechars:100 }}</p>
        <div class="card-meta">
            <span>{{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
            <span>阅读量：{{ item.Views }}</span>
        </div>
    </div>
{% endmacro %}

Thisarchive_cardThe macro accepts a name calleditemThe parameter, which is usually an article object, includes the title, link, thumbnail, description, creation time, and reading volume of the article.

2. CallmacroMacro function

After defining the macro, you can call it in other template files. If the macro is defined in the current file, you can call it directly; if it is defined in other files, you need to first throughimportLabel import.

Call within the same file:

{# 假设 archive_card 宏定义在此文件的上方 #}
{% for archive in archives %}
    {{ archive_card(archive) }}
{% endfor %}

Import and call external macros:

This is usually the recommended approach, as it promotes the modularization of templates.

First, make sure your macro function (such as the one defined above) is saved in a separate template file, such asarchive_cardThen, in your main template file (for exampletemplates/partials/my_macros.html.

tag it in:index.htmlorcategory_list.htmlUse it inimport: 

{# 文件名: index.html #}
{% import "partials/my_macros.html" as my_macros %}

{# 现在你可以通过 my_macros.archive_card 来调用宏了 #}
<div class="article-list">
    {% archiveList archives with type="page" limit="10" %}
        {% for archive in archives %}
            {{ my_macros.archive_card(archive) }}
        {% empty %}
            <p>目前没有文章。</p>
        {% endfor %}
    {% endarchiveList %}
</div>

Byas my_macrosWe have given an alias to the imported macro filemy_macrosSo, when callingarchive_cardyou need to write it asmy_macros.archive_card(archive)You can also directly import the macro function, or give an alias to the imported macro function:

{# 导入单个宏函数 #}
{% import "partials/my_macros.html" archive_card %}
{{ archive_card(archive) }}

{# 导入并给宏函数起别名 #}
{% import "partials/my_macros.html" archive_card as custom_card %}
{{ custom_card(archive) }}

{# 导入多个宏函数并起别名 #}
{% import "partials/my_macros.html" archive_card, other_macro as om %}
{{ archive_card(archive) }}
{{ om(data) }}

BymacroThe actual value brought

Master and applymacroMacros are not just about writing less code. They can elevate template development to a more efficient and structured level.In the operation of actual websites, this means you can respond faster to design changes, make it easier to test and deploy new features, and ensure the visual and functional consistency of the various modules of the website.Whether it is to deal with SEO details adjustment, or to fine-tune the UI interface,macroCan make you twice the work with half the effort.

In short, the Anqi CMS'smacroMacros are a powerful tool that encourages the modularization and reusability of templates, ultimately helping us build high-quality websites that are easier to manage, maintain, and scale.

Frequently Asked Questions (FAQ)

  1. macromacro functions andincludeWhat are the differences between tags? macroMacros can accept parameters and dynamically render content based on the parameters passed in, serving a similar function to programming languages in