How `categoryList` and `archiveList` work together to display the latest few documents under each category?

As an experienced website operations expert, I know the power of a content management system (CMS), not only in the perfection of its backend functions, but also in the flexibility of front-end content display.AnQiCMS (AnQi CMS) is just such an outstanding tool, based on the high-performance architecture of the Go language, with its concise and efficient template tag system, it allows us to easily handle all kinds of complex content display needs.

Today, let's delve into the two core tags of AnQiCMS -categoryListandarchiveList——How to cleverly collaborate to help us accurately display the latest few documents under each category of the website, thereby greatly enriching the page content and enhancing the user experience.

1. Understanding Foundation: Category List TagscategoryList

In AnQiCMS,categoryListTags are a powerful tool for managing and displaying the structure of a website's categories. They allow us to retrieve category information under specific content models, whether it's articles, products, or other custom models, and can be flexibly called through them.

When we usecategoryListWhen, you can specify some key parameters to control its behavior, such as:

• moduleId: Tell the system which content model (such as article model ID 1, product model ID 2) we want to get the category for.
• parentId: Used to build the category hierarchy,parentId="0"Indicates retrieving all top-level categories, while specifying a category ID can retrieve its subcategories.
• limit: Limits the number of categories returned, such as displaying only the first 10 categories.

This tag will return an array of category objects that contain information such as category ID (Id), category title (Title), category link (Link), whether there is a subcategory (HasChildren) and other key information. This information will serve as the bridge for us to obtain documents under categories later on.

2. Content Core: Document List LabelarchiveList

With categories, it is naturally necessary to display the specific content under the category.archiveListTags are the core tools used in AnQiCMS to retrieve document lists (or called archives, such as articles, products, etc.).It can meet the needs of various scenarios from conventional lists, related documents to pagination display.

archiveListIts strength is also reflected in its rich parameter configuration, among which are those closely related to today's topic:

• categoryId: This is a connectioncategoryListThe key, through this parameter, we can specify which category of documents to retrieve.
• limit: Controls how many documents to display under each category, for example, 'the latest 5 articles.'
• order: Determines the document sorting method. To achieve 'latest' display, we usually useorder="id desc"(Sorted by document ID in descending order, i.e., the latest released at the top) ororder="createdTime desc"(Sorted by creation time in descending order). If you want to display popular documents, you can useorder="views desc"(Sorted by views in descending order).
• typeIn order to display a fixed number of documents on unclassified list pages (such as the homepage or a specific module), we generally willtypeis set to"list".

archiveListIt will return an array of document object, each containing the document ID(Id），Title（Title), link (Link), the abstract. (Description），release time（CreatedTime）as well as the thumbnail （Thumb)and other useful information.

3. Collaborative work: Display the latest document under each category

Now, we willcategoryListandarchiveListThese tags cleverly combine to achieve our goal: displaying the latest few documents under each category.

The core idea is:First usecategoryListIterate through all categories that need to be displayed, and then, within each iteration of the loop, nest another loop usingarchiveListand thencategoryIdbind it dynamically to the current category ID and setlimitandorderThe parameter is used to retrieve the latest documents in a specified quantity.

Let's understand this process through a specific template code example:

{# 外层：使用 categoryList 获取指定模型下的所有顶级分类 #}
{% categoryList categories with moduleId="1" parentId="0" %}
    {# 遍历每个获取到的分类 #}
    {% for category in categories %}
        <section class="category-block">
            <h3>
                <a href="{{ category.Link }}">{{ category.Title }}</a>
                <small>（共 {{ category.ArchiveCount }} 篇文章）</small>
            </h3>
            <ul class="latest-articles-list">
                {# 内层：嵌套使用 archiveList 获取当前分类下的最新文档 #}
                {# categoryId 动态绑定为当前分类的 Id #}
                {# limit 限制只显示最新的 5 篇文章 #}
                {# order="id desc" 确保按 ID 降序，即最新发布在前 #}
                {% archiveList archives with type="list" categoryId=category.Id limit="5" order="id desc" %}
                    {# 遍历当前分类下的每篇最新文档 #}
                    {% for article in archives %}
                        <li>
                            <a href="{{ article.Link }}">{{ article.Title }}</a>
                            <span class="publish-date">{{ stampToDate(article.CreatedTime, "2006-01-02") }}</span>
                        </li>
                    {% empty %}
                        {# 如果该分类下没有文档，则显示友好提示 #}
                        <li class="no-content">该分类下暂时没有文档发布。</li>
                    {% endfor %}
                {% endarchiveList %}
            </ul>
        </section>
    {% endfor %}
{% endcategoryList %}

Code analysis:

1. {% categoryList categories with moduleId="1" parentId="0" %}This line of code will retrieve the article model(moduleId="1") Under all top-level categories (parentId="0"), and store the results incategoriesthe variable.
2. {% for category in categories %}: We start traversing these top-level categories, each loop,categoryvariables represent an independent category object.
3. <h3><a href="{{ category.Link }}">{{ category.Title }}</a></h3>Here shows the current category title and link, convenient for users to click and view more content.
4. {% archiveList archives with type="list" categoryId=category.Id limit="5" order="id desc" %}This is the key to realizing the core function. Here,categoryIdis dynamically set to the currentcategoryofId.limit="5"Tell the system that we only need the latest 5 documents, andorder="id desc"which ensures that these documents are arranged in the order from new to old.type="list"Then we ensure that we are getting a fixed number of lists, not data for pagination.
5. {% for article in archives %}: We continue to iterate through the latest documents obtained under the current category.
6. <li><a href="{{ article.Link }}">{{ article.Title }}</a>...</li>: Display the title, link, and usage of each documentstampToDateThe formatted publish date after the filter.
7. {% empty %}: It is a very practical tag, whenarchiveList(or any for loop) when no documents are retrieved,emptyThe content in the block will be displayed. This can effectively avoid blank areas on the page, providing a better user experience.

By using this nested calling method, we can present the latest dynamic of each category in a structured and beautiful way on the homepage of the website, a specific topic page, or any page that needs to aggregate multiple categories of content, greatly enhancing the information density and attractiveness of the website.

4. The actual scenario and application value

ThiscategoryListwitharchiveListCollaborative work mode is widely used in the operation of actual websites:

• Dynamic area on the homepage of the websiteIt is easy to build modules such as 'Latest News', 'Product Updates', 'Industry Dynamics', etc., each corresponding to a category and displaying the latest information under that category.
• Topic page aggregation: A special page created for a specific topic, which can aggregate the latest content of multiple related categories, allowing users to obtain the information they need in one-stop.
• Sidebar content recommendationIn the category list page sidebar, you can display documents under the current category such as 'most popular clicks' or 'newest releases' to guide users to deeper browsing.

This flexible content combination ability not only meets the diverse display needs of content operators, but also optimizes the website's SEO structure, increases internal links, and ultimately improves the user's browsing experience and the professionalism of the website.

5. Frequently Asked Questions (FAQ)

Q1: How do I display the latest documents for a specific category instead of all categories?

A1:If you only need to display the latest documents under a specific category without traversing all categories, you can directly omit the outer layercategoryListtag, used alonearchiveListFor example, to display the latest 5 documents under the category with ID 10, you can write it like this:

<ul class="single-category-latest">
    {% archiveList archives with type="list" categoryId="10" limit="5" order="id desc" %}
        {% for article in archives %}
            <li><a href="{{ article.Link }}">{{ article.Title }}</a></li>
        {% empty %}
            <li class="no-content">该分类下暂无最新文档。</li>
        {% endfor %}
    {% endarchiveList %}
</ul>

Q2:archiveListoforderParameter, excluding:id descWhat are some commonly used sorting methods?

A2: orderThe parameters are very flexible, you can choose different sorting fields and order according to your needs:

• id desc: Sort by document ID in descending order, which is usually equivalent to the most recently released (by default, the ID is incremented).
• createdTime desc: Arrange documents in descending order of creation time, which is also a commonly used method to obtain the latest documents.
• views desc: Arrange documents in descending order of views, used to display popular or most popular documents.
• sort desc: Sort by the custom sorting field in descending order. If the backend has set a custom sorting value for the document, it can be sorted by this value.You can choose the most suitable sorting method according to your actual needs.

Q3: What will be displayed on the page if there are no documents under a certain category? How can blank areas be avoided?

A3:As shown in the example article, whenarchiveList(or otherforThe AnQiCMS template engine does not find any documents matching the conditions in the loop{% empty %}tags come into play. In{% for ... %}and{% endfor %}You can add between them{% empty %}Please place the prompt information after the loop content is empty.This can effectively avoid the appearance of a large blank area on the page, providing a more friendly user experience, for example: 'There are no latest documents under this category.'Or 'Content is being updated, please wait!'