As a website operator who is well-versed in the operation of AnQiCMS, I understand your needs for personalized content display and user experience optimization.The document list template under the custom category is a key step to achieve this goal.AnQiCMS provides a flexible template mechanism, allowing you to present a unique list layout according to the characteristics of specific category content.
AnQiCMS's template mechanism overview
AnQiCMS uses a syntax similar to Django's template engine,.htmlAs a template file suffix, and put them all in the site's/templatedirectory. Variables in the template are represented by double curly braces{{变量}}Definition, while logical tags such as condition judgment and loop control use single curly braces and percent signs{% 标签 %}This design concept makes the template structure clear, easy to understand, and customizable.
In AnQiCMS, templates are usually passed throughextendsa basic skeleton template (such asbase.htmlorbash.html) to ensure consistency of the page structure, and across differentblockArea implementation of content differentiation. This inheritance relationship greatly enhances the reusability and maintenance efficiency of the template.
Two methods for customizing the document list template under a specific category
In AnQiCMS, you can customize the document list template for specific categories in two main ways. These methods have different focuses and can be chosen according to your specific needs.
方法一：通过命名约定自动应用模板
AnQiCMS built-in a set of intelligent template naming conventions, allowing you to create custom templates for specific category lists. The system will automatically identify and apply according to the agreed file names.
The specific naming format is:{模型table}/list-{分类id}.html
To use this method, you need to complete the following steps:
- Determine the model table name (
{模型table})Each content model in AnQiCMS has a corresponding table name. For example, if you want to customize a category list of the 'article' model, its model table name is usuallyarticle。You can view the "Model Table Name" or "URL Alias" of each model in the "Content Model" management interface of AnQiCMS. - Get the category ID (
{分类id})In AnQiCMS backend, find the specific category you want to customize in the 'Document Category' management interface. Each category will have a unique numeric ID. - Create template fileIn the directory of the current template theme you are using (for example
/template/default), find or create the corresponding model folder (for examplearticle/), and then create a folder namedlist-{分类id}.htmlThe file. For example, if the table name of your article model isarticle, and the target category ID is10, then the template file path will bearticle/list-10.html.
Once the file is created and placed in the correct location, when the user accesses the category list page with ID 10, AnQiCMS will automatically load and applyarticle/list-10.htmlThis template. This method is suitable for scenarios that require deep customization for a few important categories, as it directly associates with the category ID, achieving one-to-one precise matching.
Method two: Specify a custom template through background category settings
AnQiCMS also provides the flexibility to manually specify custom template files for each category in the backend.This method provides greater freedom in filenames and is convenient for unified management in the background.
The operation steps are as follows:
- Prepare a custom template fileIn your template theme directory, you can create a custom template file, for example, you can name it
special_category_list.html, and place it in sucharticle/directory, forming a patharticle/special_category_list.htmlOr, for better organization, you can also place it in other custom paths. Just make sure the path is relative to the root directory of the template theme. - Edit category settingsLogin to the AnQiCMS backend, navigate to the "Document Category" page under "Content Management". Find the specific category you want to customize and click the "Edit" button.
- Specify "Classification Template"In the 'Other Parameters' section of the category editing page, you will find an input box named 'Category Template'.Here, enter the relative path and filename of your custom template file.
article/special_category_list.htmland you can fill it in herearticle/special_category_list.html.
After filling in and saving, when the user accesses the list page of this category, AnQiCMS will prioritize using the custom template you specified in the background.The advantages of this method are that the filename is not restricted by the category ID, which is more descriptive, and can be centrally managed and adjusted through the backend interface.At the same time, if the template file does not exist, AnQiCMS will fallback to the default list template to prevent the page from not opening.
Create content for a custom template
No matter which way you choose, the core content of the custom template file is similar.It needs to include the page structure and use AnQiCMS template tags to dynamically retrieve and display data.
The content of a typical classification list template is roughly as follows:
{% extends "base.html" %} {# 继承您的基础模板 #}
{% block title %}
<title>{% tdk with name="Title" siteName=true %}</title> {# 使用TDK标签获取当前页面标题 #}
{% endblock %}
{% block content %}
<div class="category-list-header">
{# 获取当前分类的详细信息 #}
{% categoryDetail currentCategory with name="Title" %}
<h1>{{ currentCategory }}</h1>
{% categoryDetail categoryDesc with name="Description" %}
<p>{{ categoryDesc }}</p>
{# 如果分类有Banner图，可以这样显示 #}
{% categoryDetail bannerImages with name="Images" %}
{% if bannerImages %}
{% set pageBanner = bannerImages[0] %}
<div class="category-banner" style="background-image: url({{pageBanner}});"></div>
{% endif %}
</div>
<div class="document-list-container">
{# 使用 archiveList 标签获取当前分类下的文档列表，并启用分页 #}
{% archiveList archives with type="page" limit="10" %}
{% for item in archives %}
<div class="document-item">
<a href="{{item.Link}}">
{% if item.Thumb %}<img src="{{item.Thumb}}" alt="{{item.Title}}">{% endif %}
<h2>{{item.Title}}</h2>
<p>{{item.Description}}</p>
<div class="meta">
<span>发布日期: {{stampToDate(item.CreatedTime, "2006-01-02")}}</span>
<span>浏览量: {{item.Views}}</span>
</div>
</a>
</div>
{% empty %}
<p>该分类下暂无文档。</p>
{% endfor %}
{% endarchiveList %}
</div>
<div class="pagination-area">
{# 使用 pagination 标签展示分页导航 #}
{% pagination pages with show="5" %}
<nav>
<ul>
{% if pages.FirstPage %}<li class="{% if pages.FirstPage.IsCurrent %}active{% endif %}"><a href="{{pages.FirstPage.Link}}">{{pages.FirstPage.Name}}</a></li>{% endif %}
{% if pages.PrevPage %}<li class="prev"><a href="{{pages.PrevPage.Link}}">{{pages.PrevPage.Name}}</a></li>{% endif %}
{% for item in pages.Pages %}<li class="{% if item.IsCurrent %}active{% endif %}"><a href="{{item.Link}}">{{item.Name}}</a></li>{% endfor %}
{% if pages.NextPage %}<li class="next"><a href="{{pages.NextPage.Link}}">{{pages.NextPage.Name}}</a></li>{% endif %}
{% if pages.LastPage %}<li class="{% if pages.LastPage.IsCurrent %}active{% endif %}"><a href="{{pages.LastPage.Link}}">{{pages.LastPage.Name}}</a></li>{% endif %}
</ul>
</nav>
{% endpagination %}
</div>
{% endblock %}
In the above code example,{% extends "base.html" %}Declared that the template inherits frombase.html,{% block title %}and{% block content %}Rewrote the corresponding content area of the base template.tdkThe tag is used to get the SEO title,categoryDetailThe tag is used to get the title, description, and other information of the current category, whilearchiveListThe tag is responsible for obtaining the document list under the category and generating the page number navigation.type="page"The parameter enables pagination function. Finally,paginationThe tag generates the page navigation.
**Practical Tips and Considerations
When customizing the template, please pay attention to the following points:
- Path and NamingEnsure that your custom template file is located in the current template theme directory being used, and the file name or background settings path is accurate and correct.
- Template InheritanceMake good use of it
{% extends %}and{% block %}Tags, which help to keep the code tidy, modular, and reduce maintenance costs.Put the common structure of the page in a basic template and then overwrite the parts that need to change in the specific page template. - Tag usage：Familiar with various template tags provided by AnQiCMS (such as
archiveList,categoryDetail,pagination,tdkThey are the keys to obtaining and displaying data. Be sure to refer to the official documentation for tag usage instructions to ensure the parameters are correct. - Cache cleaning
- Error checkingIf the page displays an error, first check the server error logs and the log records of AnQiCMS backend, which usually provide valuable clues.Template syntax errors may also cause the page to fail to render normally.
Through the above method, you can create a unique document list display for the specific category of AnQiCMS website, thereby enhancing the refinement of content operation and the user experience.
Common Questions (FAQ)
1. I created a custom template file, but after selecting it in the background or placing it according to the naming convention, the page still displays the default template content, or the page reports an error. What is the cause of this?
This is usually caused by the following reasons:
- Incorrect file path or file namePlease carefully check whether the custom template file is located in the currently enabled template theme directory, and whether the filename matches the backend settings or naming conventions (such as
{模型table}/list-{分类id}.html完全匹配。即使是大小写错误也可能导致系统无法识别。 - AnQiCMS cache not updatedIn case of modifying or adding template files, AnQiCMS may have page cache.Please log in to the back-end, click the 'Update Cache' feature, and then try clearing the browser cache (Ctrl+F5) before accessing the page.
- Template syntax errorIf there are syntax errors in the custom template file (such as unclosed tags, incorrect variable names, etc.), the system may not be able to parse the template correctly, resulting in page errors or falling back to the default template.Please check the server error log for detailed error information.
Can I get information about other categories or documents other than the current category in the custom category list template?
It is absolutely fine. The template tag design of AnQiCMS is highly flexible. You can continue to use it in your custom category list template.categoryListLabel to get other category lists (for example, display sibling categories or subcategories in the sidebar), and can also be usedarchiveListTags can be used to access popular documents and recommended documents in other categories, just specify the corresponding tags.moduleId/categoryId/flagparameters. For example,{% categoryList subCategories with parentId=currentCategory.Id %}can obtain the subcategories of the current category.
3. How should CSS and JavaScript files be referenced in custom templates?
When referencing CSS and JavaScript files in custom templates, it is recommended to use{% system with name="TemplateUrl" %}Label to get the static resource root path of the current template theme. For example, if your CSS file is located/template/您的主题名/static/css/style.css, you can use it in the template:<link href="{% system with name="TemplateUrl" %}/static/css/style.css" rel="stylesheet">The benefits of doing this are that, even if you change the template theme name, as long as the static resource structure remains unchanged, the reference path does not need to be modified, and the system will automatically adapt, enhancing the universality of the template