What are the application scenarios of AnQiCMS template macro functions (macro) and include tags?

In AnQiCMS template development, in order to improve code reuse and reduce maintenance costs, we often use some powerful template features, among which the 'macro function (macro)' and 'Include tag' are two powerful assistants.They each have unique advantages and application scenarios. Understanding and appropriately using them can make template development twice as fast and build efficient, easy-to-maintain websites.

Macro: Encapsulates reusable dynamic logic

Macros functions in template development are like functions in programming languages.We can define a reusable code snippet and specify its parameters.When needed, just 'call' it and pass the corresponding parameters, it will render different content based on the data passed in.Macros have their own context, which means they only focus on the parameters passed in, do not accidentally modify or depend on external variables, making the code more robust and predictable.

In AnQiCMS, the application scenarios of macro functions are very extensive, especially suitable for those UI components with similar structures but dynamic content.

Application scenarios:

• Dynamic list item rendering:Imagine a website with common lists such as articles, product lists, user comments, and so on.Each list item's HTML structure may be very similar (for example, they all contain titles, descriptions, links, and images), but the specific data displayed by each item is completely different.article_item(article)Receiving onearticleAn object is passed as a parameter. When iterating over article data, you only need to call this macro function, passing in the current article's data, to generate the corresponding list item HTML. This is useful for handling things likearchiveList/categoryList/pageListThis tag returns data very efficiently. For example, in the document.tag-tags.mdIt shows how to define and usearchive_detail(archive)macros to render article list items.
• The encapsulation of complex UI components:When a smaller UI unit, such as a comment section header with user avatar and nickname, or a statistics display module, whose rendering logic includes complex conditional judgments or data processing, encapsulating it as a macro function can effectively reduce code redundancy and improve readability.
• Configurable general module:If the website has a general module that needs to adjust the rendering based on different parameters (such as display quantity, whether to display thumbnails, sorting method, etc.), for example, "Latest Articles RecommendationBy using macro functions, these parameters can be received to achieve flexible configuration and reuse, without the need to write a new HTML for each configuration.
• Extracted to a separate file for management:AnQiCMS allows the definition of macro functions to be stored in a separate template file (such asarchive.helper）Among them. When the main template needs to use these macros, it can be done throughimportLabel introduction. This method helps to keep the main template tidy and allows macro function definition files to focus on encapsulating reusable logic, enhancing the maintainability of the template structure.

Include tag: Include static or semi-static page fragments

The Include tag has a relatively direct function, it is used to insert the content of another template file directly into the current position. You can understand it as a simple text replacement operation: the template engine will embed the content of the specified file unchanged intoincludeThe location of the tag. The file being imported can access all variables of the current template, and it can alsowithThe keyword can receive specified variables, and can even be usedonlyKeyword limits access to specified variables only.

In the AnQiCMS template structure,includeTags are the basis for constructing the page skeleton and realizing modular layout.

Application scenarios:

• Website common structure:This isincludeThe most classic usage of the label.The website's header (header), footer, sidebar (aside), global navigation menu, etc., these contents are fixed or change very little throughout the website.bash.html(Headers, footers, and other common parts) andpartial/The catalog (code snippets), is designed toincludeDesign. Divide these common parts into independent files, and then throughincludeIntroducing tags on all pages can greatly improve development efficiency and ensure the consistency of the overall website style.
• Common static or semi-static code snippets:For example, a unified breadcrumb navigation (tag-breadcrumb.mdTags can generate data, but the rendering of HTML structure can be usedincludeEncapsulation), website copyright statement, unified CSS or JavaScript inclusion blocks, fixed advertisement placement code, or contact information obtained from the backend settings (tag-contact.mdLabel data retrieval) and system information (tag-system.mdThe rendering module of label data retrieval). These contents usually do not change much, throughincludeIntroduction can facilitate management and reuse.
• Modular page layout:For complex pages, different areas (such as the "Product Parameters" area and the "Customer Reviews" area on the product detail page) can be divided into independent template files. Then, they can be used in the main template.includeLabel these modules as needed. This allows each module to be developed and maintained independently, improving the modularization and readability of the page.

How to choose: Macro function vs Include tag

The focus is on understanding macro functions and Include tags in AnQiCMS template development:

• SelectIncludeWhen:You need to insert a relatively fixed HTML structure, or a complete, independent page fragment.The content mainly comes from the file itself, rather than generated dynamically through parameters.StructuredandFile combinationFor example, the header and footer usually change little, directlyincludeJust do it.
• SelectMacroWhen:You need to encapsulate a reusable rendering logic, this logic needs to receive different data or configuration parameters to generate different HTML outputs. It is more towardsfunctionalizationandDynamically generatedFor example, each item in the article list, although the structure is fixed, the content changes with the article, usingmacropassing in article data to render is very appropriate.

In actual development, both are not exclusive, but are often used together. You canincludea file containing multiple macro definitions, and then call these macros in the main template. Or, aincludewithin the file, may also call othermacroto render the dynamic part inside. This combination is used