How to customize the document list template for a specific category?

As a website operator who deeply understands 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 the key step to achieve this goal.AnQiCMS provides a flexible template mechanism that allows you to present a unique list layout according to the characteristics of specific categories.

AnQiCMS template mechanism overview

AnQiCMS uses a syntax similar to the Django template engine, with.htmlas the template file suffix, and stores them uniformly in the site's/templateUnder the directory. Variables in the template are enclosed in double curly braces{{变量}}defined, while conditional judgment, loop control, and other logical tags use single curly braces and percentage signs{% 标签 %}This design concept makes the template structure clear, easy to understand and customize

In AnQiCMS, templates are usually processed throughextendsInherits a basic skeleton template (for examplebase.htmlorbash.html), to ensure consistency of the page structure and in differentblockRegional implementation of content differentiation. This inheritance relationship greatly enhances the reusability and maintenance efficiency of the template.

Two methods for customizing document list templates under specific categories.

In AnQiCMS, you can achieve customization of document list templates for specific categories in two main ways, each with its own focus, and you can choose to use them according to your specific needs.

Method one: automatically apply the template through naming conventions

A smart template naming convention mechanism is built into AnQiCMS, allowing you to create custom templates for specific category lists, the system will automatically recognize and apply according to the agreed filename.

The specific naming format is:{模型table}/list-{分类id}.html

To adopt this method, you need to complete the following steps:

1. 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, the model table name is usuallyarticle. You can see the 'model table name' or 'URL alias' of each model in the 'Content Model' management interface of AnQiCMS.
2. Get the category ID ({分类id})In AnQiCMS backend, go to the 'Document Category' management interface to find the specific category you want to customize. Each category will have a unique number ID.
3. Create a template fileIn the directory of the template theme you are currently 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 your article model table name isarticleand the target category ID is10then the template file path will bearticle/list-10.html.

Once the file is created and placed in the correct location, AnQiCMS will automatically load and apply when the user accesses the category list page with ID 10article/list-10.htmlThis template. This method is suitable for scenarios where deep customization is needed for a few important categories, as it directly associates with the category ID, achieving one-to-one precise matching.

Method two: Set a custom template through the background category settings

AnQiCMS also provides the flexibility to manually specify custom template files for each category in the background.This method provides greater freedom in file names and is convenient for unified management in the background.

The operation steps are as follows:

1. Prepare the custom template fileIn your template theme directory, you can create a custom template file, for example, you can name itspecial_category_list.html, and place it in sucharticle/directory, forming a patharticle/special_category_list.htmlOr, to better organize, you can also place it in other custom paths, as long as the path is relative to the root directory of the template theme.
2. Edit category settings: Log in to the AnQiCMS backend, navigate to the "Content Management" section under the "Document Category" page. Find the specific category you want to customize, click the "Edit" button.
3. Specify "Classification Template"In the 'Other Parameters' section of the category editing page, you will find an input box named 'Category Template'.Enter the relative path and filename of your custom template file here.For example, if the file you create isarticle/special_category_list.htmlEnter herearticle/special_category_list.html.

After filling and saving, when the user visits the list page of this category, AnQiCMS will give priority to the custom template specified in the background.The advantage of this method is that the filename is not limited by the category ID, is more descriptive, and can be centrally managed and adjusted through the back-end 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 the content of a custom template

In any 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 obtain 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 the template inherits frombase.html,{% block title %}and{% block content %}Then rewritten the corresponding content area of the basic 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, andarchiveListThe tag is responsible for retrieving the document list under the category and thentype="page"the parameter enables pagination. Finally,paginationthe tag generates the page navigation.

**Practice and Precautions

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, and that the filename or path set in the background is accurate.
• Template inheritanceUse well{% extends %}and{% block %}Tags, this helps keep the code tidy, modular, and reduce maintenance costs.Place 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 usageFamiliarize yourself with the various template tags provided by AnQiCMS (such asarchiveList,categoryDetail,pagination,tdkThey are the key to acquiring and displaying data. Be sure to refer to the official document for tag usage instructions to ensure that the parameters are correct.
• Cache cleaning: After modifying the template file, the front-end page may not update immediately.This is usually due to system cache or browser cache.Please try to perform the "Update Cache" operation in the AnQiCMS background and clear the browser cache (Ctrl+F5) to ensure that your changes take effect.
• Error checking: If the page displays an error, first check the server error logs and the AnQiCMS background log records, as they usually provide valuable clues.Template syntax errors may also cause the page to fail to render normally.

By using the above method, you can create a unique document list display for the specific category of the AnQiCMS website, thereby enhancing the level of content operation and user experience.

Frequently Asked 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 reason for this?

This is usually caused by several 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}.htmlCompletely match. Even a case error may cause the system to fail to recognize it.
• AnQiCMS cache is not updatedAfter modifying or adding template files, AnQiCMS may have page cache.Please log in to the backend, click the 'Update Cache' feature, then try to clear the browser cache (Ctrl+F5) and visit the page.
• Template syntax errorIf there is a syntax error in the custom template file (such as unclosed tags, misspelled variable names, etc.), the system may not be able to parse the template correctly, causing the page to report an error or fall back to the default template.Please check the server error log for detailed error information.

Can I get information about other categories or documents outside the current category in the custom category list template?

Completely. The template tag design of AnQiCMS is highly flexible. You can continue to use it in your custom category list template.categoryListLabel to retrieve other category lists (for example, display sibling categories or subcategories in the sidebar), and can also be usedarchiveListTag to get popular documents, recommended documents, and other categories, just specify the corresponding tags in the tag.moduleId/categoryId/flagParameters can be. For example,{% categoryList subCategories with parentId=currentCategory.Id %}You can get the subcategories of the current category.

3. How should CSS and JavaScript files be referenced in custom templates?

It is recommended to use{% system with name="TemplateUrl" %}Tag 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 benefit of doing this is 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, the system will automatically adapt, enhancing the versatility of the template