As an experienced AnQi CMS website operator, I am well aware of the importance of a clear and efficient template structure for content management and website maintenance. In AnQi CMS, the template engine provides various auxiliary tags to help us better organize and reuse template code, among whichinclude/extendsandmacroThey are the three great tools for building flexible template architecture. They each have different responsibilities, but they serve together to enhance the maintainability and development efficiency of the template.
Modular content reuse: includeTag
includeThe main function of the tag is to embed the content of another template file in a template file.Imagine that your website has a universal header (header), footer (footer), or sidebar (aside) that appears on almost every page.If you copy the code every time, it is not only繁琐, but also once it needs to be modified, you have to change all pages one by one, which is time-consuming and laborious and easy to make mistakes.
ByincludeLabel, we can isolate these common modules into independent template files such aspartial/header.htmlThen simply introduce them in the page where they need to be displayed.By default, the template that is introduced will inherit all variables from the current main template.If you need to pass specific data to the template being imported, you can usewithParameters; if you want it to use only specific variables without inheriting the entire context of the main template, you can useonlyLimit the parameters. This promotes the modularization of the code, making the common content reusable and greatly simplifying the daily maintenance and update of the website.When a public component needs to be adjusted, we only need to modify a file, and all the pages that reference it will be synchronized updated.
Define the page skeleton:extendsTag
extendsTags are the foundation for building a template inheritance system, allowing us to define a basic layout (or "master template"), which other templates can then extend and fill out based on.This is like designing a master slide template when making a presentation, where all other slides inherit its basic style and layout, only filling in specific content.
In AnQi CMS, we will create a likebase.htmlSuch a basic template, which includes the overall structure of the website, such as<html>/<head>/<body>tags, as well as fixed areas such as headers, footers, and main navigation. Within these fixed areas, we useblockThe tag defines an area that can be overwritten or filled by a sub-template (for example{% block title %}or{% block content %}). A sub-template declares it inherits from{% extends 'base.html' %}, then it can use the same namedbase.html.blockLabel to override or append the corresponding content defined in the parent template. If the child template does not override someblock, it will retain the default content of the parent template.
It should be noted that,extendsThe tag must be the first tag in the sub-template, which clarifies the inheritance relationship.extendsThe advantage lies in its mandatory uniformity of the overall layout and style of the website, ensuring visual consistency, while also making it exceptionally simple to create new pages, as we only need to focus on the unique content of the page without having to rewrite the entire page structure.
Encapsulate dynamic components:macroTag
macroTags are more focused on defining parameterizable, reusable code snippets or functions, which are similar to functions in programming languages.macroAllow us to encapsulate a piece of HTML structure with specific logic and parameters, and then call it multiple times at any position in the template. Each time, different parameters are passed in to render different content.
For example, if your website has a list of articles, each article has the same display style, but the content (title, link, abstract, etc.) is different, then you can encapsulate the rendering logic of a single article into amacro. DefinemacroWhen, we will specify a name and a series of parameters (for example{% macro archive_detail(archive) %}...{% endmacro %}). When needed, we pass the data object as if calling a function (for example{{ archive_detail(item) }}). And withincludeThe difference is,macroIt has a more strict scope, which only accepts explicitly passed parameters, thus providing better encapsulation and isolation, reducing the possibility of variable conflicts. Moreover,macroCan be saved to a separate file (for examplearchive.helperThen proceedimportTags can be imported and used as needed in other templates
Comprehensive application and differentiation
Understanding the roles of these three tags, we can organize the template structure of AnQi CMS more effectively:
extendsUsed to build the macro layout of the website, determining the overall structure of the page.includeUsed to insert independent, general content segments in a fixed layout, such as page headers, footers, side navigation, etc., which usually do not change much or change little.macroThese are used to create dynamic, parameterizable UI components, such as article cards, product list items, form input boxes, etc., whose display logic is fixed, but the displayed data is variable.
In actual development, they often work together. A basic template (extends) defines the page layout, which may include multiple imported common parts (include)，while the page content area may call multiplemacroRender data lists or complex components. By reasonably utilizing these three elements, we can build a clear, efficient, maintainable, and scalable Anqin CMS template system.
Frequently Asked Questions (FAQ)
1. When should I choose to useincludeinstead ofmacro?
SelectincludeIt is usually to reuse those relatively fixed and unchanged HTML fragments, such as the website navigation bar, footer copyright information, or a purely static ad block that does not depend on external variables.includeIt inherits the entire context of the parent template, and it is also very convenient if the fragment needs a small amount of variables from the parent template. AndmacroIt is more suitable for creating dynamic components that need to accept different parameters to render different content, it provides stricter parameter isolation, avoids global variable pollution, and makes component reuse safer and more controllable.
2.extendslabel'sblockwithincludeWhat are the differences between tags?
extendsin the labelblockIt is used to define an area that can be filled or overwritten by a sub-template, focusing on the 'holes' or placeholders of the overall page layout. Sub-templates rewrite theseblockCome to inject your own specific content, thereby forming a complete page. AndincludeThis is an instruction that directly inserts the content of another template file at the current position, as if it were 'copy and paste' a piece of code.extendsIt defines the inheritance hierarchy and structure of the template, andincludesimply insert a content snippet without involving inheritance.
3. Can I call another onemacroin it?macroorincludeCan I call a file?
Yes,macroIt has certain flexibility. You can call onemacroThe definition internally calls another already defined or importedmacroThis helps to build more complex nested components. Similarly, you can also inmacroinincludeother template files, as long as they areincludethe file does not depend onmacroThe variable can be passed implicitly. But remembermacroscope feature, any variable not passed through parameters, inmacroInternally, they are invisible unless they are globally accessible context variables.