How to use the `include` tag in AnQiCMS templates, efficiently reuse and display common page header, footer and other modules?
When building a website, we often encounter such a scenario: modules such as the website header (Header), footer (Footer), sidebar (Sidebar), and navigation menu appear almost on every page.These modules are not only similar in content, but also need to maintain consistency in their structure and style.If you repeat the same code on each page, it is not only inefficient, but also a nightmare of maintenance if you need to modify it later.
Luckyly, AnQiCMS (AnQiCMS) understands the importance of template reuse and provides powerful and flexibleincludetags, making everything simple and efficient. ThroughincludeLabel, we can isolate these common modules into separate files, then easily reference them wherever needed, thereby greatly enhancing development efficiency, reducing maintenance costs, and ensuring the consistency of the overall website style.
includeThe core value of the label
includeThe core concept of the tag is 'write once, use anywhere'.It allows developers to extract a block of independent template code (such as the HTML structure of the header and footer) and save it as a separate template file.When other templates need this part of the code, just useincludeThe tag points to the file, and the system will insert this part of the code into the specified position when rendering the page.
This reuse pattern brings multiple benefits:
- Improve development efficiency:No need to copy code, just a simple line of tag can introduce a complex module.
- Reduce maintenance costs:Any modification to the public module only needs to be made in one place, and all pages referencing it will automatically update.
- Keep the code tidy:The page template only contains core content and necessary information.
includeThe statement is clear and easy to read. - Ensure visual consistency:Ensures the unified appearance and functionality of common elements on different pages of the website.
includeBasic usage of tags
In the AnQi CMS template system,includeThe label usage is very intuitive. Suppose we have already saved the common header content of the website aspartial/header.html, and the common footer content aspartial/footer.htmlThey are usually located in the root directory of the current template theme (for example)template/default/partial/Then, in any page template (such as)index.html/detail.htmlWe can refer to them in this way:
{% include "partial/header.html" %}
<!-- 这里是当前页面的主要内容 -->
{% include "partial/footer.html" %}
When the page is accessed, Anqicms will automatically find and loadpartial/header.htmlandpartial/footer.htmlthe content and then seamlessly present it in the corresponding position on the current page.
More flexible usage: pass variables
It is simply a container for files, which is sometimes not enough to meet all needs.For example, the header of a website may need to display the title of the current page, or the copyright information of the footer may need to be dynamically adjusted for different pages. At this time,includelabel'swithKeywords come into play. They allow us to pass specific variables to the included template.
Suppose ourpartial/header.htmlcontains a{{ pageTitle }}variable to display the page title:
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>{{ pageTitle }} - 你的网站名称</title>
<!-- 其他头部信息 -->
</head>
<body>
<header>
<h1>{{ pageTitle }}</h1>
<!-- 导航等 -->
</header>
<main>
Then, in the referenceheader.htmlon the page, we can pass it like thispageTitleVariable:
{% include "partial/header.html" with pageTitle="安企CMS文章详情" %}
<!-- 文章详情内容 -->
{% include "partial/footer.html" %}
Thus,partial/header.htmlwhen rendering,{{ pageTitle }}it will be replaced with "AnQi CMS article details". You can also pass multiple variables at the same time, just separate them with spaces:
{% include "partial/header.html" with pageTitle="安企CMS文章详情" keywords="安企CMS, 模板, 详情" %}
Control variable scope:onlyKeyword
By default, useincludeThe label-introduced template inherits all variables from the parent template. This is convenient in most cases, but sometimes we may want the included template to use the variables passed throughwithExplicitly pass the variable, without inheriting any other variables from the parent template, to avoid potential variable conflicts or unnecessary complexity. At this point, you can useonlyA keyword to limit the scope of variables:
{% include "partial/header.html" with pageTitle="安企CMS文章详情" only %}
By addingonly,partial/header.htmltoOnlyCan accesspageTitleThis variable, while not accessing other variables defined in the current page template. This helps maintain the modularity and predictability of the module.
Robustness consideration: Handling non-existent template
In some cases, you may be uncertain aboutincludeWhether the template file exists or if a module is optional. If enforcedincludeA file does not exist, the system may report an error. To avoid this situation, you can useif_existsKeyword:
{% include "partial/sidebar.html" if_exists %}
Ifpartial/sidebar.htmlA file exists, it will be introduced normally; if it does not exist, then theincludeThe statement will be ignored, the page rendering will not be affected, and no error will occur. This makes your template more robust when facing incomplete or optional modules.
Practical suggestions with **practice
In order to give full play toincludethe advantages of tags, here are some practical suggestions:
- The conventionally accepted directory structure:It is recommended to place all reusable code snippets (such as headers, footers, navigation, sidebars, comment sections, breadcrumbs, etc.) in the current theme directory.
partial/In the subdirectory. This helps to keep the organization structure of the template files clear, convenient for search and management. - Fine-grained splitting:Do not be afraid to further divide large public modules into smaller, manageable pieces. For example, a complex header can be divided into several smaller modules such as the "logo area", "main navigation", and "user login status", and then continue
header.htmlinincludeThey. - Document your module:For complex or with specific parameters
includeModule, it is best to add comments inside the file to describe its function and required variables, which is convenient for other developers to understand and use.
includeTags are an extremely useful and flexible feature in AnQi CMS template development.It encourages modular design, significantly improves the reusability of templates, making the construction and maintenance of websites easier and more efficient.Master and make good use of this tool, your secure CMS website template will have more maintainability and scalability.
Frequently Asked Questions (FAQ)
includeTags andextendsWhat are the differences between tags?includeThe tag is used to insert the content of a template file (usually a small piece, such as header, footer, or navigation) into a specific location in another template, similar to code reuse. It isincludeThe template can access variables from the parent template and also pass its own variables. AndwithThe tag is used for template inheritance, it defines a basic layout (parent template) that contains usingextendsThe tag is used for template inheritance, it defines a basic layout (parent template) that contains usingblockThe area defined by the tag. Subtemplates can overwrite theseblockThe area to fill in specific content, but its overall structure and most of the content are inherited from the parent template.extendsIt must be the first tag in the sub-template and the structure of the sub-template is completely dependent on the definition of the parent template.Can I
includeUse which variables in the template thatBy default,includeThe template inherits all variables of the parent template. This means that any variables defined in the parent template can be used directly in the template being included.Furthermore, you can also usewithThe keyword explicitly points to theincludeThe template passes new variables, which can be used directly in the included template. If theonlykeyword is alsoincludethe template will only accept variables passed throughwithPassing the variable without inheriting any other variables from the parent template.includeIs the template path in the tag relative or absolute? How to specify?includeThe path is relative to the root directory of the current template theme file. For example, if your current template theme directory is/template/default/, and you want to include the file is/template/default/partial/header.html, you can beincludeLabel should be written as"partial/header.html"The Anqi CMS template system will resolve these relative paths based on the currently enabled template theme, so there is no need to specify the full absolute path.