When it is necessary to dynamically generate HTML structures based on data, can the `macro` tag effectively simplify template logic?

In an AnQiCMS (AnQiCMS) that pursues an efficient, customizable Go language content management system, the flexibility and maintainability of the template level have always been the focus of developers and operators.Especially when facing the need to dynamically generate complex HTML structures based on background data, we often ponder how to effectively simplify template logic while ensuring rich and diverse content, and avoid code redundancy?Today, let's delve deeply into a powerful auxiliary tag in AnQi CMS -macroLook to see if it can become a 'Swiss Army knife' for simplifying template logic in dynamic HTML structure generation.

macroTag: The 'functional' tool in the template.

In AnQi CMS template design philosophy, we have retained many advantages of Django template engine, providing an intuitive and easy-to-use tag system. Among which,macroTags are like small functions in the world of templates, allowing you to define a reusable code snippet that can be called like a function, pass parameters, and generate specific HTML output.

Imagine when your website needs to display a list of products, article cards, or user comments, these elements may appear repeatedly on multiple pages of the website (such as the homepage, category page, search results page).If you copy code blocks every time, it's not only inefficient, but also once you need to modify the style or structure of an element, you have to adjust it manually in all places, which is undoubtedly a nightmare for operation and maintenance. AndmacroThe introduction of tags is to solve such pain points.

macroHow to simplify the structure of dynamic HTML?

1. Implement the DRY principle of 'define once, use everywhere': macroThe core value lies in its code reusability. You can encapsulate the HTML structure of a specific UI component in amacroIn, for example, an article card that includes images, title, introduction, and link. ThismacroIt will accept an 'article object' as a parameter. After that, whenever you need to display an article card on any page, just call thismacroPass the corresponding article data and you're done. This is like defining a function when programming, abstracting out common logic, which greatly reduces the repetitive code in template files.

   For example, we can define one for rendering article list itemsmacro:

   {% macro article_item(article) %}
   <div class="article-card">
       <a href="{{ article.Link }}">
           {% if article.Thumb %}
               <img src="{{ article.Thumb }}" alt="{{ article.Title }}">
           {% endif %}
           <h3>{{ article.Title }}</h3>
           <p>{{ article.Description|truncatechars:100 }}</p>
           <span>发布日期: {{ stampToDate(article.CreatedTime, "2006-01-02") }}</span>
       </a>
   </div>
   {% endmacro %}
   

   Then, on different pages, it can be simply called:

   {% for post in archives %}
       {{ article_item(post) }}
   {% endfor %}
   

   Compared to repeating the above long HTML in each loop, doesn't it feel cleaner immediately?

2. Enhance the readability and maintainability of the template:When a page needs to dynamically generate multiple different types of HTML structures, the main template file tends to become bloated and difficult to understand. BymacroWe can abstract these complex substructures, allowing the main template to focus on the overall layout and data flow, while delegating the specific UI rendering logic tomacroThis makes the template structure clearer, making it easier for developers to understand the function of each part and convenient for subsequent maintenance and debugging.When the UI or data structure changes, it is usually only necessary to modify one placemacroDefinition, all references to it will be synchronized and updated, which greatly reduces the maintenance cost.

3. Promote the thinking of componentized development: macroLabels encourage us to view UI as independent, composite components. For example, in addition to article cards, you might also need a "comment display"macroor a "product specifications table"macroThis component-based thinking mode not only helps keep the template code neat, but also provides a better bridge for collaboration between frontend development and backend templates.

4. Limited scope brings higher encapsulation:withincludeThe tag is different,macroHas a more strict scope. It can only access data passed through parameters and cannot directly access global variables defined outside of it.This 'isolation' feature, although it may require you to manually pass more parameters in some cases, but it can effectively avoid naming conflicts and unnecessary side effects, makingmacroMore independent, controllable, and easier to unit test (if the template engine supports it).It forces you to think about what data each UI component truly needs, thereby designing more robust and less coupled templates.

How to organize and use bettermacro?

In order to give full play tomacroThe advantage, especially in large projects, is that a good organizational structure is crucial. The template engine of Anqi CMS supports the ability tomacrodefined in independent auxiliary files, and throughimportLabel it into the template you need to use.

You can create a similarpartials/macros.htmlfile to centrally manage all reusablemacro.

{# partials/macros.html 文件内容 #}
{% macro article_item(article) %}
    <div class="article-card">
        <a href="{{ article.Link }}">
            {% if article.Thumb %}
                <img src="{{ article.Thumb }}" alt="{{ article.Title }}">
            {% endif %}
            <h3>{{ article.Title }}</h3>
            <p>{{ article.Description|truncatechars:100 }}</p>
            <span>发布日期: {{ stampToDate(article.CreatedTime, "2006-01-02") }}</span>
        </a>
    </div>
{% endmacro %}

{% macro product_card(product) %}
    <div class="product-item">
        <a href="{{ product.Link }}">
            <img src="{{ product.Logo }}" alt="{{ product.Title }}">
            <h4>{{ product.Title }}</h4>
            <span class="price">¥{{ product.Price }}</span>
        </a>
    </div>
{% endmacro %}

Then in the main template file (for exampleindex.htmlorlist.html), import and use as needed:

{# index.html 文件内容 #}
{% import "partials/macros.html" as ui %} {# 将所有macro导入到ui命名空间下 #}

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <title>我的网站 - {% tdk with name="Title" siteName=true %}</title>
</head>
<body>
    <header>...</header>
    <main>
        <h2>最新文章</h2>
        <section class="latest-articles">
            {% archiveList articles with type="list" moduleId=1 limit=5 %}
                {% for item in articles %}
                    {{ ui.article_item(item) }} {# 使用ui命名空间下的macro #}
                {% empty %}
                    <p>暂无文章。</p>
                {% endfor %}
            {% endarchiveList %}
        </section>

        <h2>热门产品</h2>
        <section class="hot-products">
            {% archiveList products with type="list" moduleId=2 limit=4 %}
                {% for item in products %}
                    {{ ui.product_card(item) }} {# 使用ui命名空间下的macro #}
                {% empty %}
                    <p>暂无产品。</p>
                {% endfor %}
            {% endarchiveList %}
        </section>
    </main>
    <footer>...</footer>
</body>
</html>

Byas uiTo import macro definition namespace, it can avoid naming conflicts between different macro files, further enhancing the organization and maintainability of template code.

Summary

There is no doubt that when it is necessary to dynamically generate HTML structures based on data, Anqi CMS'smacroThe tag is an extremely effective and elegant solution. It encapsulates repetitive UI logic into reusable “functions”, significantly simplifying template logic and improving code neatness, readability, and maintainability.For users of Anqi CMS who pursue efficient content management and excellent user experience, proficiency in usingmacroTags can undoubtedly make your template development more efficient, building websites that are easier to manage and more flexible.

Frequently Asked Questions (FAQ)

1. macroTags andincludeWhat are the differences between tags? macroThe tag is more like a function with parameters, it has its own local scope, and can only access data passed through parameters. This makesmacroThe encapsulation is stronger, more suitable for rendering independent, variable parameter UI components, andincludeIt is more like simply copying and pasting the content of a template file (or its fragment) at the current position, it will inherit all the context variables of the current template. Therefore,includeIt is usually used to introduce static or general modules that do not require parameters, such as page headers, footers, and so on, whilemacroit is more suitable for dynamic and configurable UI elements.

2. Can ImacroAre you calling other Anqi CMS template tags or filters?Of course you can.macroIt is a complete template context, you can use various built-in tags provided by Anqi CMS, such asif/for), data tags such assystem/contact/categoryDetail) as well as rich filters. For example, in the article card