How to use AnqiCMS template include tag to introduce common code fragments and achieve page structure reuse?
In website content management, we often encounter situations where we need to display the same content blocks, such as headers, footers, sidebars, or navigation menus, on multiple pages.If you copy and paste this code every time, it is not only inefficient, but also face the繁琐 of repeated operations in multiple files when you need to modify it.If this continues, the maintenance and update of the website content will become extremely difficult, and it may even lead to inconsistent experiences.
幸运的是，AnqiCMS（AnqiCMS）为我们提供了一个优雅的解决方案，其核心就是它模板引擎中的include 标签。通过巧妙地运用includeLabel, we can easily implement the introduction of common code snippets and the reuse of page structures, thereby greatly enhancing the development and maintenance efficiency of the website.
Get to knowincludeThe core role of tags
includeThe essence of a tag is to allow you to include another independent HTML file or code snippet within a template file.This is like building a Lego model where you don't have to build the same part from scratch every time, but can assemble some common components in advance and use them directly when needed.partial/in the folder, for example, the header can bepartial/header.htmlThe footer can bepartial/footer.html.
The benefits of doing this are obvious:
- code centralized management: All public code needs to be written once and stored in one place.
- Maintenance is convenient and efficientWhen the public part needs to be adjusted, only one file needs to be modified, and all pages that refer to it will be synchronized for updates, avoiding omissions and inconsistencies.
- Clear and readable structure：Split the page into independent logic blocks to make the template structure clearer, easier to understand and manage.
Flexible applicationinclude：From basic introduction to dynamic content
UseincludeThe tag is very intuitive, the most basic usage is to specify the file path to be imported, for example:
{% include "partial/header.html" %}
{% include "partial/sidebar.html" %}
{% include "partial/footer.html" %}
Thus,header.html/sidebar.htmlandfooter.htmlThe content will be "embedded" into the current template file.
However, simply static introduction is sometimes not enough to meet complex needs.We may want the same header fragment to display different titles on different pages, or the sidebar to load different content based on the current page type.includeTag provided.withandonlyThe parameters come into play.
By
withPassing variablesBy default, the
includeThe template fragment will inherit all variables from the current template environment. But if you want to pass some specific data to the imported fragment, you can usewithParameters. This allows you to make common fragments more dynamic and general.For example, a universal header fragment may need to display a dynamic page title and keywords:
{% include "partial/header.html" with title="当前页面标题" keywords="SEO关键词" %}and in the
partial/header.htmlIn, you can use these passed variables like this:<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <title>{{title}} - {% system with name="SiteName" %}</title> <meta name="keywords" content="{{keywords}}"> <!-- 其他页头内容 --> </head> <body>By
withWe can provide customized data for each introduced segment flexibly, without modifying the segment itself.Use
onlyControl variable scopeAlthough inheriting all variables is convenient, in some cases, we may want to be
includeonly access the fragment throughwithClearly pass the variable without inheriting other variables from the current template environment.This helps to avoid potential variable conflicts or unnecessary dependencies, making the segment more independent and controllable.withadded after the parameteronly:{% include "partial/header.html" with title="当前页面标题" keywords="SEO关键词" only %}Now,
partial/header.htmlAccess will be restricted totitleandkeywordsThese two variables, while unable to access any other variables defined in the current page.Utilize
if_existsElegantly handle the non-existent segment.Sometimes, the template snippet you introduce may not be necessary for every page, or you may not be sure whether a snippet has been created during the development process.Directly including a non-existent file will cause the template to render an error.
if_existsparameters:{% include "partial/optional_ad_section.html" if_exists %}If
partial/optional_ad_section.htmlThe file exists, it will be imported; if it does not exist, the Anqi CMS will silently ignore thisincludecommand without throwing an error, ensuring the normal rendering of the page.
Advanced modular management:extendsandmacro
exceptincludeLabel, the Anqi CMS template system also providesextendsandmacroLabels, they have different focuses on code reuse, together building a powerful template system
extendsTag: If said thatincludeIs "insert part", thenextendsIt is "inherit skeleton".extendsUsed to define the overall layout of the page or "master", usually containing the page's HTML structure, general CSS/JS references, and some placeholders (block），供子模板填充具体内容。例如，你可以定义一个base.html作为所有页面的基础布局，其中定义了header/content/footeretcblockarea.macroTag:macroIt is more like a 'function' in programming language.It allows you to define small, reusable HTML code blocks with parameters.macro会比includeMore flexibility. For example, one used to render an article list item.macroCan receive an article object as a parameter and generate the corresponding HTML accordingly.
By usingincludeUsed for independent code snippets,extendsUsed for overall page layout, as well as,macroUsed for parameterized repeated structures, we can organize website templates neatly, maximize code reusability, and focus on high-quality content creation and website operations.These templates provided by Anqi CMS make website maintenance more efficient and intelligent.
Frequently Asked Questions (FAQ)
Q1:includeTags andextendsWhat is the difference between tags, and how should I choose?
A:includeThe tag is used to "insert" another template fragment at any position in the current template, just like pasting a picture onto a canvas. It is suitable for reusing independent, functional code blocks, such as navigation menus, sidebar widgets, etc. AndextendsThe tag is used to define the overall layout or "skeleton" of the page, it must be the first tag in the template file, allowing sub-templates to "inherit" and fill in the definitions in the parent template.blockArea. Simply put,extendsIt is a top-down structural inheritance, defining what should be here,includeIs a horizontal component insertion, defining 'Here is something needed'. When you want to reuse the overall page layoutextends, when you want to reuse a small piece of codeinclude.
Q2: Can I use the current page's data (such as the document title) in the template snippet I introduced?
A: Yes. By default, you canincludeThe template fragment introduced by the tag will automatically inherit all variables from the current template environment. This means that inheader.htmlyou can directly access the current page's{{archive.Title}}Or{{category.Description}}data is present, assuming that these variables exist in the current template context. If you want to control more precisely which variables can be accessed, you can usewithandonlyParameters to specify or limit.
Q3: If I want toincludePass some variables dynamically into the template snippet without wanting it to access all the variables of the current page, what should I do?
A: You can usewithparameters to pass specific variables, andwiththen addonlykeywords. For example:{% include "partial/my_component.html" with item_id=123 item_name="示例" only %}Thus,my_component.htmlthe template can only accessitem_idanditem_nameThese variables, without inheriting any other variables from the current main template, thus achieving stricter scope control and modularization.